[PATCH] fsmap: fix documentation of FMR_OF_LAST

[PATCH] fsmap: fix documentation of FMR_OF_LAST

[Darrick J. Wong]

The FMR_OF_LAST flag is set on the last fsmap record being returned for
the dataset requested, contrary to what the header file says.  Fix the
docs to reflect the behavior of all fsmap implementations.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
 include/uapi/linux/fsmap.h |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/uapi/linux/fsmap.h b/include/uapi/linux/fsmap.h
index 7e8e5f0b..e5213c3 100644
--- a/include/uapi/linux/fsmap.h
+++ b/include/uapi/linux/fsmap.h
@@ -96,7 +96,7 @@ fsmap_advance(
 #define FMR_OF_EXTENT_MAP	0x4	/* segment = extent map */
 #define FMR_OF_SHARED		0x8	/* segment = shared with another file */
 #define FMR_OF_SPECIAL_OWNER	0x10	/* owner is a special value */
-#define FMR_OF_LAST		0x20	/* segment is the last in the FS */
+#define FMR_OF_LAST		0x20	/* segment is the last in the dataset */
 
 /* Each FS gets to define its own special owner codes. */
 #define FMR_OWNER(type, code)	(((__u64)type << 32) | \

Re: [PATCH] fsmap: fix documentation of FMR_OF_LAST

[Dave Chinner]

On Thu, Aug 31, 2017 at 01:49:18PM -0700, Darrick J. Wong wrote:
> The FMR_OF_LAST flag is set on the last fsmap record being returned for
> the dataset requested, contrary to what the header file says.  Fix the
> docs to reflect the behavior of all fsmap implementations.
> 
> Signed-off-by: Darrick J. Wong <darrick.wong-QHcLZuEGTsvQT0dZR+AlfA@public.gmane.org>
> ---
>  include/uapi/linux/fsmap.h |    2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/include/uapi/linux/fsmap.h b/include/uapi/linux/fsmap.h
> index 7e8e5f0b..e5213c3 100644
> --- a/include/uapi/linux/fsmap.h
> +++ b/include/uapi/linux/fsmap.h
> @@ -96,7 +96,7 @@ fsmap_advance(
>  #define FMR_OF_EXTENT_MAP	0x4	/* segment = extent map */
>  #define FMR_OF_SHARED		0x8	/* segment = shared with another file */
>  #define FMR_OF_SPECIAL_OWNER	0x10	/* owner is a special value */
> -#define FMR_OF_LAST		0x20	/* segment is the last in the FS */
> +#define FMR_OF_LAST		0x20	/* segment is the last in the dataset */
>  
>  /* Each FS gets to define its own special owner codes. */
>  #define FMR_OWNER(type, code)	(((__u64)type << 32) | \

Looks fine.

Reviewed-by: Dave Chinner <dchinner-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>

-- 
Dave Chinner
david-FqsqvQoI3Ljby3iVrkZq2A@public.gmane.org

Re: [PATCH] fsmap: fix documentation of FMR_OF_LAST

[Christoph Hellwig]

On Thu, Aug 31, 2017 at 01:49:18PM -0700, Darrick J. Wong wrote:
> The FMR_OF_LAST flag is set on the last fsmap record being returned for
> the dataset requested, contrary to what the header file says.  Fix the
> docs to reflect the behavior of all fsmap implementations.

Hmm.  What's the point of the flag then given that you can trivially
deduce the last entry from fmh_entries?

Re: [PATCH] fsmap: fix documentation of FMR_OF_LAST

[Darrick J. Wong]

On Fri, Sep 01, 2017 at 01:09:04AM -0700, Christoph Hellwig wrote:
> On Thu, Aug 31, 2017 at 01:49:18PM -0700, Darrick J. Wong wrote:
> > The FMR_OF_LAST flag is set on the last fsmap record being returned for
> > the dataset requested, contrary to what the header file says.  Fix the
> > docs to reflect the behavior of all fsmap implementations.
> 
> Hmm.  What's the point of the flag then given that you can trivially
> deduce the last entry from fmh_entries?

fmh_entries is the number of records returned, not the number of records
in the dataset.  If, for example, you allocate space for 100 records and
perform a query for a block that has been reflinked 1000 times, the
dataset size is 1000 but fmh_entries is set to 100.  The lack of a LAST
flag on the 100th record tells you that there's more records to return.

If however you allocate space for 100 records and the block is reflinked
exactly 100 times, there's no way (without the flag) for userspace to
know that record 100 is the end of the dataset, so the only thing it can
do is to fsmap_advance() and try the query again, only to receive zero
results.  Granted I don't think fsmap queries are all /that/ expensive,
but it's trivial for the kernel to set the flag.

--D

> --
> To unsubscribe from this list: send the line "unsubscribe linux-xfs" in
> the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] fsmap: fix documentation of FMR_OF_LAST

[Christoph Hellwig]

On Fri, Sep 01, 2017 at 08:07:16AM -0700, Darrick J. Wong wrote:
> fmh_entries is the number of records returned, not the number of records
> in the dataset.  If, for example, you allocate space for 100 records and
> perform a query for a block that has been reflinked 1000 times, the
> dataset size is 1000 but fmh_entries is set to 100.  The lack of a LAST
> flag on the 100th record tells you that there's more records to return.
> 
> If however you allocate space for 100 records and the block is reflinked
> exactly 100 times, there's no way (without the flag) for userspace to
> know that record 100 is the end of the dataset, so the only thing it can
> do is to fsmap_advance() and try the query again, only to receive zero
> results.  Granted I don't think fsmap queries are all /that/ expensive,
> but it's trivial for the kernel to set the flag.

Oh, ok - it had to look up this defintion of dataset first.  With
that the explanation makes total sense:

Reviewed-by: Christoph Hellwig <hch@lst.de>