Re: [PATCH 16/15] xfs: start documenting common units and tags used in tracepoints

[Dave Chinner <david@fromorbit.com>]

On Wed, Aug 18, 2021 at 08:07:28PM -0700, Darrick J. Wong wrote:
> From: Darrick J. Wong <djwong@kernel.org>
> 
> Because there are a lot of tracepoints that express numeric data with
> an associated unit and tag, document what they are to help everyone else
> keep these thigns straight.
> 
> Signed-off-by: Darrick J. Wong <djwong@kernel.org>

Thanks for adding this quickly. :)

> ---
>  fs/xfs/scrub/trace.h |    4 ++++
>  fs/xfs/xfs_trace.h   |   24 ++++++++++++++++++++++++
>  2 files changed, 28 insertions(+)
> 
> diff --git a/fs/xfs/scrub/trace.h b/fs/xfs/scrub/trace.h
> index e9b81b7645c1..20f34548bfe5 100644
> --- a/fs/xfs/scrub/trace.h
> +++ b/fs/xfs/scrub/trace.h
> @@ -2,6 +2,10 @@
>  /*
>   * Copyright (C) 2017 Oracle.  All Rights Reserved.
>   * Author: Darrick J. Wong <darrick.wong@oracle.com>
> + *
> + * NOTE: none of these tracepoints shall be considered a stable kernel ABI
> + * as they can change at any time.  See xfs_trace.h for documentation of
> + * specific units found in tracepoint output.
>   */
>  #undef TRACE_SYSTEM
>  #define TRACE_SYSTEM xfs_scrub
> diff --git a/fs/xfs/xfs_trace.h b/fs/xfs/xfs_trace.h
> index a72cd56afc8c..c46dd4fea3e3 100644
> --- a/fs/xfs/xfs_trace.h
> +++ b/fs/xfs/xfs_trace.h
> @@ -2,6 +2,30 @@
>  /*
>   * Copyright (c) 2009, Christoph Hellwig
>   * All Rights Reserved.
> + *
> + * NOTE: none of these tracepoints shall be considered a stable kernel ABI
> + * as they can change at any time.
> + *
> + * Current conventions for printing numbers measuring specific units:
> + *
> + * ino: filesystem inode number
> + * agino: per-AG inode number
> + * agno: allocation group number
> + * agbno: per-AG block number in fs blocks
> + * owner: reverse-mapping owner, usually inodes
> + * daddr: physical block number in 512b blocks
> + * startblock: physical block number for file mappings.  This is either a
> + *             segmented fsblock for data device mappings, or a rfsblock
> + *             for realtime device mappings
> + * fileoff: file offset, in fs blocks
> + * pos: file offset, in bytes
> + * forkoff: inode fork offset, in bytes
> + * icount: number of inode records

ireccount?

> + * disize: ondisk file size, in bytes
> + * isize: incore file size, in bytes
> + * fsbcount: number of blocks in an extent, in fs blocks
> + * bbcount: number of blocks in a physical extent, in 512b blocks
> + * bytecount: number of bytes
>   */
>  #undef TRACE_SYSTEM
>  #define TRACE_SYSTEM xfs

Only thing I'd add to this comment is that hexadecimal is the
preferred output format for all these types.

Cheers,

Dave.
-- 
Dave Chinner
david@fromorbit.com