> On Dec 7, 2021, at 5:35 PM, Bruce Fields <bfields@xxxxxxxxxxxx> wrote:
>
> On Tue, Dec 07, 2021 at 10:00:22PM +0000, Chuck Lever III wrote:
>> Thanks for clarifying! If you are feeling industrious, it would be nice
>> for this to be documented somewhere in the source code....
>
> I did that, then noticed I was duplicating a comment I'd already written
> elsewhere, so, how about the following?
>
> --b.
>
> From 2e3f00c5f29f033fd5db05ef713d0d9fa27d6db1 Mon Sep 17 00:00:00 2001
> From: "J. Bruce Fields" <bfields@xxxxxxxxxx>
> Date: Tue, 7 Dec 2021 17:32:21 -0500
> Subject: [PATCH] nfsd: improve stateid access bitmask documentation
>
> The use of the bitmaps is confusing. Add a cross-reference to make it
> easier to find the existing comment. Add an updated reference with URL
> to make it quicker to look up. And a bit more editorializing about the
> value of this.
>
> Signed-off-by: J. Bruce Fields <bfields@xxxxxxxxxx>
> ---
> fs/nfsd/nfs4state.c | 14 ++++++++++----
> fs/nfsd/state.h | 4 ++++
> 2 files changed, 14 insertions(+), 4 deletions(-)
>
> diff --git a/fs/nfsd/nfs4state.c b/fs/nfsd/nfs4state.c
> index 0031e006f4dc..f07fe7562d4d 100644
> --- a/fs/nfsd/nfs4state.c
> +++ b/fs/nfsd/nfs4state.c
> @@ -360,11 +360,13 @@ static const struct nfsd4_callback_ops nfsd4_cb_notify_lock_ops = {
> * st_{access,deny}_bmap field of the stateid, in order to track not
> * only what share bits are currently in force, but also what
> * combinations of share bits previous opens have used. This allows us
> - * to enforce the recommendation of rfc 3530 14.2.19 that the server
> - * return an error if the client attempt to downgrade to a combination
> - * of share bits not explicable by closing some of its previous opens.
> + * to enforce the recommendation in
> + * https://datatracker.ietf.org/doc/html/rfc7530#section-16.19.4 that
> + * the server return an error if the client attempt to downgrade to a
> + * combination of share bits not explicable by closing some of its
> + * previous opens.
> *
> - * XXX: This enforcement is actually incomplete, since we don't keep
> + * This enforcement is arguably incomplete, since we don't keep
> * track of access/deny bit combinations; so, e.g., we allow:
> *
> * OPEN allow read, deny write
> @@ -372,6 +374,10 @@ static const struct nfsd4_callback_ops nfsd4_cb_notify_lock_ops = {
> * DOWNGRADE allow read, deny none
> *
> * which we should reject.
> + *
> + * But you could also argue that what our current code is already
> + * overkill, since it only exists to return NFS4ERR_INVAL on incorrect
> + * client behavior.
Thanks for the patch! This sentence seems to have too many words.
> */
> static unsigned int
> bmap_to_share_mode(unsigned long bmap)
> diff --git a/fs/nfsd/state.h b/fs/nfsd/state.h
> index e73bdbb1634a..6eb3c7157214 100644
> --- a/fs/nfsd/state.h
> +++ b/fs/nfsd/state.h
> @@ -568,6 +568,10 @@ struct nfs4_ol_stateid {
> struct list_head st_locks;
> struct nfs4_stateowner *st_stateowner;
> struct nfs4_clnt_odstate *st_clnt_odstate;
> +/*
> + * These bitmasks use 3 separate bits for READ, ALLOW, and BOTH; see the
> + * comment above bmap_to_share_mode() for explanation:
> + */
> unsigned char st_access_bmap;
> unsigned char st_deny_bmap;
> struct nfs4_ol_stateid *st_openstp;
> --
> 2.33.1
>
--
Chuck Lever
