diff mbox series

[04/10] man: document the new health reporting fields in various ioctls

Message ID 156757184781.1838441.4746750117807426676.stgit@magnolia (mailing list archive)
State Accepted
Headers show
Series xfsprogs-5.3: various fixes | expand

Commit Message

Darrick J. Wong Sept. 4, 2019, 4:37 a.m. UTC 
From: Darrick J. Wong <darrick.wong@oracle.com>

Update the manpages to conver the new health reporting fields in the
fs geometry, ag geometry, and bulkstat ioctls.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Reviewed-by: Dave Chinner <dchinner@redhat.com>
---
 man/man2/ioctl_xfs_ag_geometry.2   |   48 +++++++++++++++++++++++++++++++
 man/man2/ioctl_xfs_fsbulkstat.2    |   52 +++++++++++++++++++++++++++++++++
 man/man2/ioctl_xfs_fsop_geometry.2 |   56 +++++++++++++++++++++++++++++++++++-
 3 files changed, 154 insertions(+), 2 deletions(-)

Comments

Eric Sandeen Sept. 9, 2019, 7:19 p.m. UTC | #1 
On 9/3/19 11:37 PM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
> 
> Update the manpages to conver the new health reporting fields in the
> fs geometry, ag geometry, and bulkstat ioctls.
> 
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> Reviewed-by: Dave Chinner <dchinner@redhat.com>
> ---
>  man/man2/ioctl_xfs_ag_geometry.2   |   48 +++++++++++++++++++++++++++++++
>  man/man2/ioctl_xfs_fsbulkstat.2    |   52 +++++++++++++++++++++++++++++++++
>  man/man2/ioctl_xfs_fsop_geometry.2 |   56 +++++++++++++++++++++++++++++++++++-
>  3 files changed, 154 insertions(+), 2 deletions(-)
> 
> 
...

> diff --git a/man/man2/ioctl_xfs_fsbulkstat.2 b/man/man2/ioctl_xfs_fsbulkstat.2
> index a8b22dc4..3e13cfa8 100644
> --- a/man/man2/ioctl_xfs_fsbulkstat.2
> +++ b/man/man2/ioctl_xfs_fsbulkstat.2
> @@ -94,7 +94,9 @@ struct xfs_bstat {
>  	__u16             bs_projid_lo;
>  	__u16             bs_forkoff;
>  	__u16             bs_projid_hi;
> -	unsigned char     bs_pad[6];
> +	uint16_t          bs_sick;
> +	uint16_t          bs_checked;
> +	unsigned char     bs_pad[2];
>  	__u32             bs_cowextsize;
>  	__u32             bs_dmevmask;
>  	__u16             bs_dmstate;
> @@ -184,6 +186,54 @@ is unused on Linux.
>  .I bs_aextents
>  is the number of storage mappings associated with this file's extended
>  attributes.
> +.PP
> +The fields
> +.IR bs_sick " and " bs_checked
> +indicate the relative health of various allocation group metadata:


This should probably say "inode metadata?" 

I can fix that on the way in, the rest looks ok

Reviewed-by: Eric Sandeen <sandeen@redhat.com>
Darrick J. Wong Sept. 16, 2019, 3:17 p.m. UTC | #2 
On Mon, Sep 09, 2019 at 02:19:42PM -0500, Eric Sandeen wrote:
> On 9/3/19 11:37 PM, Darrick J. Wong wrote:
> > From: Darrick J. Wong <darrick.wong@oracle.com>
> > 
> > Update the manpages to conver the new health reporting fields in the
> > fs geometry, ag geometry, and bulkstat ioctls.
> > 
> > Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> > Reviewed-by: Dave Chinner <dchinner@redhat.com>
> > ---
> >  man/man2/ioctl_xfs_ag_geometry.2   |   48 +++++++++++++++++++++++++++++++
> >  man/man2/ioctl_xfs_fsbulkstat.2    |   52 +++++++++++++++++++++++++++++++++
> >  man/man2/ioctl_xfs_fsop_geometry.2 |   56 +++++++++++++++++++++++++++++++++++-
> >  3 files changed, 154 insertions(+), 2 deletions(-)
> > 
> > 
> ...
> 
> > diff --git a/man/man2/ioctl_xfs_fsbulkstat.2 b/man/man2/ioctl_xfs_fsbulkstat.2
> > index a8b22dc4..3e13cfa8 100644
> > --- a/man/man2/ioctl_xfs_fsbulkstat.2
> > +++ b/man/man2/ioctl_xfs_fsbulkstat.2
> > @@ -94,7 +94,9 @@ struct xfs_bstat {
> >  	__u16             bs_projid_lo;
> >  	__u16             bs_forkoff;
> >  	__u16             bs_projid_hi;
> > -	unsigned char     bs_pad[6];
> > +	uint16_t          bs_sick;
> > +	uint16_t          bs_checked;
> > +	unsigned char     bs_pad[2];
> >  	__u32             bs_cowextsize;
> >  	__u32             bs_dmevmask;
> >  	__u16             bs_dmstate;
> > @@ -184,6 +186,54 @@ is unused on Linux.
> >  .I bs_aextents
> >  is the number of storage mappings associated with this file's extended
> >  attributes.
> > +.PP
> > +The fields
> > +.IR bs_sick " and " bs_checked
> > +indicate the relative health of various allocation group metadata:
> 
> 
> This should probably say "inode metadata?" 

Yes it should have, thanks for fixing that.

--D

> I can fix that on the way in, the rest looks ok
> 
> Reviewed-by: Eric Sandeen <sandeen@redhat.com>
>
diff mbox series

Patch

diff --git a/man/man2/ioctl_xfs_ag_geometry.2 b/man/man2/ioctl_xfs_ag_geometry.2
index ddd54265..80ebcb76 100644
--- a/man/man2/ioctl_xfs_ag_geometry.2
+++ b/man/man2/ioctl_xfs_ag_geometry.2
@@ -57,6 +57,54 @@  Currently no flags are defined, so this field must be zero.
 .TP
 .IR ag_reserved
 All reserved fields will be set to zero on return.
+.PP
+The fields
+.IR ag_sick " and " ag_checked
+indicate the relative health of various allocation group metadata:
+.IP \[bu] 2
+If a given sick flag is set in
+.IR ag_sick ,
+then that piece of metadata has been observed to be damaged.
+The same bit will be set in
+.IR ag_checked .
+.IP \[bu]
+If a given sick flag is set in
+.I ag_checked
+and is not set in
+.IR ag_sick ,
+then that piece of metadata has been checked and is not faulty.
+.IP \[bu]
+If a given sick flag is not set in
+.IR ag_checked ,
+then no conclusion can be made.
+.PP
+The following flags apply to these fields:
+.RS 0.4i
+.TP
+.B XFS_AG_GEOM_SICK_SB
+Allocation group superblock.
+.TP
+.B XFS_AG_GEOM_SICK_AGF
+Free space header.
+.TP
+.B XFS_AG_GEOM_SICK_AGFL
+Free space reserve list.
+.TP
+.B XFS_AG_GEOM_SICK_AGI
+Inode header.
+.TP
+.BR XFS_AG_GEOM_SICK_BNOBT " or " XFS_AG_GEOM_SICK_CNTBT
+Free space btrees.
+.TP
+.BR XFS_AG_GEOM_SICK_INOBT " or " XFS_AG_GEOM_SICK_FINOBT
+Inode btrees.
+.TP
+.B XFS_AG_GEOM_SICK_RMAPBT
+Reverse mapping btree.
+.TP
+.B XFS_AG_GEOM_SICK_REFCNTBT
+Reference count btree.
+.RE
 .SH RETURN VALUE
 On error, \-1 is returned, and
 .I errno
diff --git a/man/man2/ioctl_xfs_fsbulkstat.2 b/man/man2/ioctl_xfs_fsbulkstat.2
index a8b22dc4..3e13cfa8 100644
--- a/man/man2/ioctl_xfs_fsbulkstat.2
+++ b/man/man2/ioctl_xfs_fsbulkstat.2
@@ -94,7 +94,9 @@  struct xfs_bstat {
 	__u16             bs_projid_lo;
 	__u16             bs_forkoff;
 	__u16             bs_projid_hi;
-	unsigned char     bs_pad[6];
+	uint16_t          bs_sick;
+	uint16_t          bs_checked;
+	unsigned char     bs_pad[2];
 	__u32             bs_cowextsize;
 	__u32             bs_dmevmask;
 	__u16             bs_dmstate;
@@ -184,6 +186,54 @@  is unused on Linux.
 .I bs_aextents
 is the number of storage mappings associated with this file's extended
 attributes.
+.PP
+The fields
+.IR bs_sick " and " bs_checked
+indicate the relative health of various allocation group metadata:
+.IP \[bu] 2
+If a given sick flag is set in
+.IR bs_sick ,
+then that piece of metadata has been observed to be damaged.
+The same bit should be set in
+.IR bs_checked .
+.IP \[bu]
+If a given sick flag is set in
+.I bs_checked
+but is not set in
+.IR bs_sick ,
+then that piece of metadata has been checked and is not faulty.
+.IP \[bu]
+If a given sick flag is not set in
+.IR bs_checked ,
+then no conclusion can be made.
+.PP
+The following flags apply to these fields:
+.RS 0.4i
+.TP
+.B XFS_BS_SICK_INODE
+The inode's record itself.
+.TP
+.B XFS_BS_SICK_BMBTD
+File data extent mappings.
+.TP
+.B XFS_BS_SICK_BMBTA
+Extended attribute extent mappings.
+.TP
+.B XFS_BS_SICK_BMBTC
+Copy on Write staging extent mappings.
+.TP
+.B XFS_BS_SICK_DIR
+Directory information.
+.TP
+.B XFS_BS_SICK_XATTR
+Extended attribute data.
+.TP
+.B XFS_BS_SICK_SYMLINK
+Symbolic link target.
+.TP
+.B XFS_BS_SICK_PARENT
+Parent pointers.
+.RE
 .SH RETURN VALUE
 On error, \-1 is returned, and
 .I errno
diff --git a/man/man2/ioctl_xfs_fsop_geometry.2 b/man/man2/ioctl_xfs_fsop_geometry.2
index 365bda8b..a35bbaeb 100644
--- a/man/man2/ioctl_xfs_fsop_geometry.2
+++ b/man/man2/ioctl_xfs_fsop_geometry.2
@@ -47,7 +47,9 @@  struct xfs_fsop_geom {
 	__u32         logsunit;
 	/* struct xfs_fsop_geom_v4 stops here. */
 
-	__u64         reserved[18];
+	__u32         sick;
+	__u32         checked;
+	__u64         reserved[17];
 };
 .fi
 .in
@@ -130,6 +132,13 @@  This field is meaningful only if the flag
 .B  XFS_FSOP_GEOM_FLAGS_LOGV2
 is set.
 .PP
+The fields
+.IR sick " and " checked
+indicate the relative health of various whole-filesystem metadata.
+Please see the section
+.B XFS METADATA HEALTH REPORTING
+for more details.
+.PP
 .I reserved
 is set to zero.
 .SH FILESYSTEM FEATURE FLAGS
@@ -203,6 +212,51 @@  Filesystem stores reverse mappings of blocks to owners.
 .B XFS_FSOP_GEOM_FLAGS_REFLINK
 Filesystem supports sharing blocks between files.
 .RE
+.SH XFS METADATA HEALTH REPORTING
+.PP
+The online filesystem checking utility scans metadata and records what it
+finds in the kernel incore state.
+The following scheme is used for userspace to read the incore health status
+of the filesystem:
+
+.IP \[bu] 2
+If a given sick flag is set in
+.IR sick ,
+then that piece of metadata has been observed to be damaged.
+The same bit should be set in
+.IR checked .
+.IP \[bu]
+If a given sick flag is set in
+.I checked
+but is not set in
+.IR sick ,
+then that piece of metadata has been checked and is not faulty.
+.IP \[bu]
+If a given sick flag is not set in
+.IR checked ,
+then no conclusion can be made.
+.PP
+The following flags apply to these fields:
+.RS 0.4i
+.TP
+.B XFS_FSOP_GEOM_SICK_COUNTERS
+Inode and space summary counters.
+.TP
+.B XFS_FSOP_GEOM_SICK_UQUOTA
+User quota information.
+.TP
+.B XFS_FSOP_GEOM_SICK_GQUOTA
+Group quota information.
+.TP
+.B XFS_FSOP_GEOM_SICK_PQUOTA
+Project quota information.
+.TP
+.B XFS_FSOP_GEOM_SICK_RT_BITMAP
+Free space bitmap for the realtime device.
+.TP
+.B XFS_FSOP_GEOM_SICK_RT_SUMMARY
+Free space summary for the realtime device.
+.RE
 
 .SH RETURN VALUE
 On error, \-1 is returned, and