linux-cifs.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some warnings from W=1
@ 2021-09-20 12:14 David Howells
  2021-09-20 12:37 ` Matthew Wilcox
                   ` (6 more replies)
  0 siblings, 7 replies; 8+ messages in thread
From: David Howells @ 2021-09-20 12:14 UTC (permalink / raw)
  To: linux-fsdevel
  Cc: Jeff Layton, Dominique Martinet, Marc Dionne, Steve French,
	Trond Myklebust, Anna Schumaker, Mauro Carvalho Chehab,
	v9fs-developer, linux-afs, linux-cifs, linux-nfs, linux-doc,
	dhowells, linux-kernel

Deal with some warnings generated from make W=1:

 (1) Add/remove/fix kerneldoc parameters descriptions.

 (2) afs_sillyrename() isn't an API functions, so remove the kerneldoc
     annotation.

 (3) The fscache object CREATE_OBJECT work state isn't used, so remove it.

 (4) Move __add_fid() from between v9fs_fid_add() and its comment.

 (5) 9p's caches_show() doesn't really make sense as an API function, show
     remove the kerneldoc annotation.  It's also not prefixed with 'v9fs_'.

 (6) Remove the kerneldoc annotation on cifs_match_ipdaddr() as it's not
     fully documented.

 (7) Turn cifs' rqst_page_get_length()'s banner comment into a kerneldoc
     comment.  It should probably be prefixed with "cifs_" though.

Signed-off-by: David Howells <dhowells@redhat.com>
cc: Jeff Layton <jlayton@kernel.org>
cc: Dominique Martinet <asmadeus@codewreck.org>
cc: Marc Dionne <marc.dionne@auristor.com>
cc: Steve French <sfrench@samba.org>
cc: Trond Myklebust <trond.myklebust@hammerspace.com>
cc: Anna Schumaker <anna.schumaker@netapp.com>
cc: Mauro Carvalho Chehab <mchehab@kernel.org>
cc: v9fs-developer@lists.sourceforge.net
cc: linux-afs@lists.infradead.org
cc: linux-cifs@vger.kernel.org
cc: linux-nfs@vger.kernel.org
cc: linux-fsdevel@vger.kernel.org
cc: linux-doc@vger.kernel.org
---

 fs/9p/fid.c            |   14 +++++++-------
 fs/9p/v9fs.c           |    8 +++-----
 fs/9p/vfs_addr.c       |   13 +++++++++----
 fs/9p/vfs_file.c       |   33 ++++++++++++---------------------
 fs/9p/vfs_inode.c      |   24 ++++++++++++++++--------
 fs/9p/vfs_inode_dotl.c |   11 +++++++++--
 fs/afs/dir_silly.c     |    4 ++--
 fs/cifs/connect.c      |   14 +++++++++++++-
 fs/cifs/misc.c         |   14 ++++++++++++--
 fs/fscache/object.c    |    2 +-
 fs/fscache/operation.c |    3 +++
 fs/nfs_common/grace.c  |    1 -
 12 files changed, 87 insertions(+), 54 deletions(-)

diff --git a/fs/9p/fid.c b/fs/9p/fid.c
index 9d9de62592be..b8863dd0de5c 100644
--- a/fs/9p/fid.c
+++ b/fs/9p/fid.c
@@ -19,18 +19,18 @@
 #include "v9fs_vfs.h"
 #include "fid.h"
 
+static inline void __add_fid(struct dentry *dentry, struct p9_fid *fid)
+{
+	hlist_add_head(&fid->dlist, (struct hlist_head *)&dentry->d_fsdata);
+}
+
+
 /**
  * v9fs_fid_add - add a fid to a dentry
  * @dentry: dentry that the fid is being added to
  * @fid: fid to add
  *
  */
-
-static inline void __add_fid(struct dentry *dentry, struct p9_fid *fid)
-{
-	hlist_add_head(&fid->dlist, (struct hlist_head *)&dentry->d_fsdata);
-}
-
 void v9fs_fid_add(struct dentry *dentry, struct p9_fid *fid)
 {
 	spin_lock(&dentry->d_lock);
@@ -67,7 +67,7 @@ static struct p9_fid *v9fs_fid_find_inode(struct inode *inode, kuid_t uid)
 
 /**
  * v9fs_open_fid_add - add an open fid to an inode
- * @dentry: inode that the fid is being added to
+ * @inode: inode that the fid is being added to
  * @fid: fid to add
  *
  */
diff --git a/fs/9p/v9fs.c b/fs/9p/v9fs.c
index cdb99507ef33..2e0fa7c932db 100644
--- a/fs/9p/v9fs.c
+++ b/fs/9p/v9fs.c
@@ -155,6 +155,7 @@ int v9fs_show_options(struct seq_file *m, struct dentry *root)
 /**
  * v9fs_parse_options - parse mount options into session structure
  * @v9ses: existing v9fs session information
+ * @opts: The mount option string
  *
  * Return 0 upon success, -ERRNO upon failure.
  */
@@ -542,12 +543,9 @@ extern int v9fs_error_init(void);
 static struct kobject *v9fs_kobj;
 
 #ifdef CONFIG_9P_FSCACHE
-/**
- * caches_show - list caches associated with a session
- *
- * Returns the size of buffer written.
+/*
+ * List caches associated with a session
  */
-
 static ssize_t caches_show(struct kobject *kobj,
 			   struct kobj_attribute *attr,
 			   char *buf)
diff --git a/fs/9p/vfs_addr.c b/fs/9p/vfs_addr.c
index fd45874b55db..1c3708720fb9 100644
--- a/fs/9p/vfs_addr.c
+++ b/fs/9p/vfs_addr.c
@@ -88,7 +88,7 @@ static const struct netfs_read_request_ops v9fs_req_ops = {
 
 /**
  * v9fs_vfs_readpage - read an entire page in from 9P
- * @filp: file being read
+ * @file: file being read
  * @page: structure to page
  *
  */
@@ -108,6 +108,8 @@ static void v9fs_vfs_readahead(struct readahead_control *ractl)
 
 /**
  * v9fs_release_page - release the private state associated with a page
+ * @page: The page to be released
+ * @gfp: The caller's allocation restrictions
  *
  * Returns 1 if the page can be released, false otherwise.
  */
@@ -128,9 +130,9 @@ static int v9fs_release_page(struct page *page, gfp_t gfp)
 
 /**
  * v9fs_invalidate_page - Invalidate a page completely or partially
- *
- * @page: structure to page
- * @offset: offset in the page
+ * @page: The page to be invalidated
+ * @offset: offset of the invalidated region
+ * @length: length of the invalidated region
  */
 
 static void v9fs_invalidate_page(struct page *page, unsigned int offset,
@@ -190,6 +192,8 @@ static int v9fs_vfs_writepage(struct page *page, struct writeback_control *wbc)
 
 /**
  * v9fs_launder_page - Writeback a dirty page
+ * @page: The page to be cleaned up
+ *
  * Returns 0 on success.
  */
 
@@ -209,6 +213,7 @@ static int v9fs_launder_page(struct page *page)
 /**
  * v9fs_direct_IO - 9P address space operation for direct I/O
  * @iocb: target I/O control block
+ * @iter: The data/buffer to use
  *
  * The presence of v9fs_direct_IO() in the address space ops vector
  * allowes open() O_DIRECT flags which would have failed otherwise.
diff --git a/fs/9p/vfs_file.c b/fs/9p/vfs_file.c
index 4b617d10cf28..170d4612a031 100644
--- a/fs/9p/vfs_file.c
+++ b/fs/9p/vfs_file.c
@@ -359,14 +359,11 @@ static int v9fs_file_flock_dotl(struct file *filp, int cmd,
 }
 
 /**
- * v9fs_file_read - read from a file
- * @filp: file pointer to read
- * @udata: user data buffer to read data into
- * @count: size of buffer
- * @offset: offset at which to read data
+ * v9fs_file_read_iter - read from a file
+ * @iocb: The operation parameters
+ * @to: The buffer to read into
  *
  */
-
 static ssize_t
 v9fs_file_read_iter(struct kiocb *iocb, struct iov_iter *to)
 {
@@ -388,11 +385,9 @@ v9fs_file_read_iter(struct kiocb *iocb, struct iov_iter *to)
 }
 
 /**
- * v9fs_file_write - write to a file
- * @filp: file pointer to write
- * @data: data buffer to write data from
- * @count: size of buffer
- * @offset: offset at which to write data
+ * v9fs_file_write_iter - write to a file
+ * @iocb: The operation parameters
+ * @from: The data to write
  *
  */
 static ssize_t
@@ -574,11 +569,9 @@ v9fs_vm_page_mkwrite(struct vm_fault *vmf)
 }
 
 /**
- * v9fs_mmap_file_read - read from a file
- * @filp: file pointer to read
- * @data: user data buffer to read data into
- * @count: size of buffer
- * @offset: offset at which to read data
+ * v9fs_mmap_file_read_iter - read from a file
+ * @iocb: The operation parameters
+ * @to: The buffer to read into
  *
  */
 static ssize_t
@@ -589,11 +582,9 @@ v9fs_mmap_file_read_iter(struct kiocb *iocb, struct iov_iter *to)
 }
 
 /**
- * v9fs_mmap_file_write - write to a file
- * @filp: file pointer to write
- * @data: data buffer to write data from
- * @count: size of buffer
- * @offset: offset at which to write data
+ * v9fs_mmap_file_write_iter - write to a file
+ * @iocb: The operation parameters
+ * @from: The data to write
  *
  */
 static ssize_t
diff --git a/fs/9p/vfs_inode.c b/fs/9p/vfs_inode.c
index 795706520b5e..08f48b70a741 100644
--- a/fs/9p/vfs_inode.c
+++ b/fs/9p/vfs_inode.c
@@ -218,7 +218,7 @@ v9fs_blank_wstat(struct p9_wstat *wstat)
 
 /**
  * v9fs_alloc_inode - helper function to allocate an inode
- *
+ * @sb: The superblock to allocate the inode from
  */
 struct inode *v9fs_alloc_inode(struct super_block *sb)
 {
@@ -238,7 +238,7 @@ struct inode *v9fs_alloc_inode(struct super_block *sb)
 
 /**
  * v9fs_free_inode - destroy an inode
- *
+ * @inode: The inode to be freed
  */
 
 void v9fs_free_inode(struct inode *inode)
@@ -343,7 +343,7 @@ int v9fs_init_inode(struct v9fs_session_info *v9ses,
  * v9fs_get_inode - helper function to setup an inode
  * @sb: superblock
  * @mode: mode to setup inode with
- *
+ * @rdev: The device numbers to set
  */
 
 struct inode *v9fs_get_inode(struct super_block *sb, umode_t mode, dev_t rdev)
@@ -369,7 +369,7 @@ struct inode *v9fs_get_inode(struct super_block *sb, umode_t mode, dev_t rdev)
 }
 
 /**
- * v9fs_clear_inode - release an inode
+ * v9fs_evict_inode - Remove an inode from the inode cache
  * @inode: inode to release
  *
  */
@@ -665,14 +665,15 @@ v9fs_create(struct v9fs_session_info *v9ses, struct inode *dir,
 
 /**
  * v9fs_vfs_create - VFS hook to create a regular file
+ * @mnt_userns: The user namespace of the mount
+ * @dir: The parent directory
+ * @dentry: The name of file to be created
+ * @mode: The UNIX file mode to set
+ * @excl: True if the file must not yet exist
  *
  * open(.., O_CREAT) is handled in v9fs_vfs_atomic_open().  This is only called
  * for mknod(2).
  *
- * @dir: directory inode that is being created
- * @dentry:  dentry that is being deleted
- * @mode: create permissions
- *
  */
 
 static int
@@ -696,6 +697,7 @@ v9fs_vfs_create(struct user_namespace *mnt_userns, struct inode *dir,
 
 /**
  * v9fs_vfs_mkdir - VFS mkdir hook to create a directory
+ * @mnt_userns: The user namespace of the mount
  * @dir:  inode that is being unlinked
  * @dentry: dentry that is being unlinked
  * @mode: mode for new directory
@@ -900,10 +902,12 @@ int v9fs_vfs_rmdir(struct inode *i, struct dentry *d)
 
 /**
  * v9fs_vfs_rename - VFS hook to rename an inode
+ * @mnt_userns: The user namespace of the mount
  * @old_dir:  old dir inode
  * @old_dentry: old dentry
  * @new_dir: new dir inode
  * @new_dentry: new dentry
+ * @flags: RENAME_* flags
  *
  */
 
@@ -1009,6 +1013,7 @@ v9fs_vfs_rename(struct user_namespace *mnt_userns, struct inode *old_dir,
 
 /**
  * v9fs_vfs_getattr - retrieve file metadata
+ * @mnt_userns: The user namespace of the mount
  * @path: Object to query
  * @stat: metadata structure to populate
  * @request_mask: Mask of STATX_xxx flags indicating the caller's interests
@@ -1050,6 +1055,7 @@ v9fs_vfs_getattr(struct user_namespace *mnt_userns, const struct path *path,
 
 /**
  * v9fs_vfs_setattr - set file metadata
+ * @mnt_userns: The user namespace of the mount
  * @dentry: file whose metadata to set
  * @iattr: metadata assignment structure
  *
@@ -1285,6 +1291,7 @@ static int v9fs_vfs_mkspecial(struct inode *dir, struct dentry *dentry,
 
 /**
  * v9fs_vfs_symlink - helper function to create symlinks
+ * @mnt_userns: The user namespace of the mount
  * @dir: directory inode containing symlink
  * @dentry: dentry for symlink
  * @symname: symlink data
@@ -1340,6 +1347,7 @@ v9fs_vfs_link(struct dentry *old_dentry, struct inode *dir,
 
 /**
  * v9fs_vfs_mknod - create a special file
+ * @mnt_userns: The user namespace of the mount
  * @dir: inode destination for new link
  * @dentry: dentry for file
  * @mode: mode for creation
diff --git a/fs/9p/vfs_inode_dotl.c b/fs/9p/vfs_inode_dotl.c
index e1c0240b51c0..01b9e1281a29 100644
--- a/fs/9p/vfs_inode_dotl.c
+++ b/fs/9p/vfs_inode_dotl.c
@@ -37,7 +37,10 @@ v9fs_vfs_mknod_dotl(struct user_namespace *mnt_userns, struct inode *dir,
 		    struct dentry *dentry, umode_t omode, dev_t rdev);
 
 /**
- * v9fs_get_fsgid_for_create - Helper function to get the gid for creating a
+ * v9fs_get_fsgid_for_create - Helper function to get the gid for a new object
+ * @dir_inode: The directory inode
+ *
+ * Helper function to get the gid for creating a
  * new file system object. This checks the S_ISGID to determine the owning
  * group of the new file system object.
  */
@@ -211,12 +214,13 @@ int v9fs_open_to_dotl_flags(int flags)
 
 /**
  * v9fs_vfs_create_dotl - VFS hook to create files for 9P2000.L protocol.
+ * @mnt_userns: The user namespace of the mount
  * @dir: directory inode that is being created
  * @dentry:  dentry that is being deleted
  * @omode: create permissions
+ * @excl: True if the file must not yet exist
  *
  */
-
 static int
 v9fs_vfs_create_dotl(struct user_namespace *mnt_userns, struct inode *dir,
 		     struct dentry *dentry, umode_t omode, bool excl)
@@ -361,6 +365,7 @@ v9fs_vfs_atomic_open_dotl(struct inode *dir, struct dentry *dentry,
 
 /**
  * v9fs_vfs_mkdir_dotl - VFS mkdir hook to create a directory
+ * @mnt_userns: The user namespace of the mount
  * @dir:  inode that is being unlinked
  * @dentry: dentry that is being unlinked
  * @omode: mode for new directory
@@ -537,6 +542,7 @@ static int v9fs_mapped_iattr_valid(int iattr_valid)
 
 /**
  * v9fs_vfs_setattr_dotl - set file metadata
+ * @mnt_userns: The user namespace of the mount
  * @dentry: file whose metadata to set
  * @iattr: metadata assignment structure
  *
@@ -816,6 +822,7 @@ v9fs_vfs_link_dotl(struct dentry *old_dentry, struct inode *dir,
 
 /**
  * v9fs_vfs_mknod_dotl - create a special file
+ * @mnt_userns: The user namespace of the mount
  * @dir: inode destination for new link
  * @dentry: dentry for file
  * @omode: mode for creation
diff --git a/fs/afs/dir_silly.c b/fs/afs/dir_silly.c
index dae9a57d7ec0..45cfd50a9521 100644
--- a/fs/afs/dir_silly.c
+++ b/fs/afs/dir_silly.c
@@ -86,8 +86,8 @@ static int afs_do_silly_rename(struct afs_vnode *dvnode, struct afs_vnode *vnode
 	return afs_do_sync_operation(op);
 }
 
-/**
- * afs_sillyrename - Perform a silly-rename of a dentry
+/*
+ * Perform silly-rename of a dentry.
  *
  * AFS is stateless and the server doesn't know when the client is holding a
  * file open.  To prevent application problems when a file is unlinked while
diff --git a/fs/cifs/connect.c b/fs/cifs/connect.c
index 0db344807ef1..a725377d662b 100644
--- a/fs/cifs/connect.c
+++ b/fs/cifs/connect.c
@@ -1090,7 +1090,7 @@ cifs_demultiplex_thread(void *p)
 	module_put_and_exit(0);
 }
 
-/**
+/*
  * Returns true if srcaddr isn't specified and rhs isn't specified, or
  * if srcaddr is specified and matches the IP address of the rhs argument
  */
@@ -1550,6 +1550,8 @@ static int match_session(struct cifs_ses *ses, struct smb3_fs_context *ctx)
 
 /**
  * cifs_setup_ipc - helper to setup the IPC tcon for the session
+ * @ses: The session being set up
+ * @ctx: The mount context
  *
  * A new IPC connection is made and stored in the session
  * tcon_ipc. The IPC tcon has the same lifetime as the session.
@@ -1605,6 +1607,7 @@ cifs_setup_ipc(struct cifs_ses *ses, struct smb3_fs_context *ctx)
 
 /**
  * cifs_free_ipc - helper to release the session IPC tcon
+ * @ses: The session being destroyed
  *
  * Needs to be called everytime a session is destroyed.
  *
@@ -1855,6 +1858,8 @@ cifs_set_cifscreds(struct smb3_fs_context *ctx __attribute__((unused)),
 
 /**
  * cifs_get_smb_ses - get a session matching @ctx data from @server
+ * @server: The server we want to use
+ * @ctx: The mount context
  *
  * This function assumes it is being called from cifs_mount() where we
  * already got a server reference (server refcount +1). See
@@ -2065,6 +2070,8 @@ cifs_put_tcon(struct cifs_tcon *tcon)
 
 /**
  * cifs_get_tcon - get a tcon matching @ctx data from @ses
+ * @ses: The session we're working in
+ * @ctx: The mount context.
  *
  * - tcon refcount is the number of mount points using the tcon.
  * - ses refcount is the number of tcon using the session.
@@ -3032,6 +3039,11 @@ build_unc_path_to_root(const struct smb3_fs_context *ctx,
 
 /**
  * expand_dfs_referral - Perform a dfs referral query and update the cifs_sb
+ * @xid: The operation ID
+ * @ses: The session we're working in
+ * @ctx: The mount context
+ * @cifs_sb: The superblock private data
+ * @ref_path: The referral path
  *
  * If a referral is found, cifs_sb->ctx->mount_options will be (re-)allocated
  * to a string containing updated options for the submount.  Otherwise it
diff --git a/fs/cifs/misc.c b/fs/cifs/misc.c
index 9469f1cf0b46..05225d13e3d4 100644
--- a/fs/cifs/misc.c
+++ b/fs/cifs/misc.c
@@ -591,6 +591,7 @@ void cifs_put_writer(struct cifsInodeInfo *cinode)
 
 /**
  * cifs_queue_oplock_break - queue the oplock break handler for cfile
+ * @cfile: The file to break the oplock on
  *
  * This function is called from the demultiplex thread when it
  * receives an oplock break for @cfile.
@@ -1029,6 +1030,9 @@ setup_aio_ctx_iter(struct cifs_aio_ctx *ctx, struct iov_iter *iter, int rw)
 
 /**
  * cifs_alloc_hash - allocate hash and hash context together
+ * @name: The name of the crypto hash algo
+ * @shash: Where to put the pointer to the hash algo
+ * @sdesc: Where to put the pointer to the hash descriptor
  *
  * The caller has to make sure @sdesc is initialized to either NULL or
  * a valid context. Both can be freed via cifs_free_hash().
@@ -1067,6 +1071,8 @@ cifs_alloc_hash(const char *name,
 
 /**
  * cifs_free_hash - free hash and hash context together
+ * @shash: Where to find the pointer to the hash algo
+ * @sdesc: Where to find the pointer to the hash descriptor
  *
  * Freeing a NULL hash or context is safe.
  */
@@ -1082,8 +1088,10 @@ cifs_free_hash(struct crypto_shash **shash, struct sdesc **sdesc)
 
 /**
  * rqst_page_get_length - obtain the length and offset for a page in smb_rqst
- * Input: rqst - a smb_rqst, page - a page index for rqst
- * Output: *len - the length for this page, *offset - the offset for this page
+ * @rqst: The request descriptor
+ * @page: The index of the page to query
+ * @len: Where to store the length for this page:
+ * @offset: Where to store the offset for this page
  */
 void rqst_page_get_length(struct smb_rqst *rqst, unsigned int page,
 				unsigned int *len, unsigned int *offset)
@@ -1116,6 +1124,8 @@ void extract_unc_hostname(const char *unc, const char **h, size_t *len)
 
 /**
  * copy_path_name - copy src path to dst, possibly truncating
+ * @dst: The destination buffer
+ * @src: The source name
  *
  * returns number of bytes written (including trailing nul)
  */
diff --git a/fs/fscache/object.c b/fs/fscache/object.c
index d7eab46dd826..86ad941726f7 100644
--- a/fs/fscache/object.c
+++ b/fs/fscache/object.c
@@ -77,7 +77,6 @@ static WORK_STATE(INIT_OBJECT,		"INIT", fscache_initialise_object);
 static WORK_STATE(PARENT_READY,		"PRDY", fscache_parent_ready);
 static WORK_STATE(ABORT_INIT,		"ABRT", fscache_abort_initialisation);
 static WORK_STATE(LOOK_UP_OBJECT,	"LOOK", fscache_look_up_object);
-static WORK_STATE(CREATE_OBJECT,	"CRTO", fscache_look_up_object);
 static WORK_STATE(OBJECT_AVAILABLE,	"AVBL", fscache_object_available);
 static WORK_STATE(JUMPSTART_DEPS,	"JUMP", fscache_jumpstart_dependents);
 
@@ -907,6 +906,7 @@ static void fscache_dequeue_object(struct fscache_object *object)
  * @object: The object to ask about
  * @data: The auxiliary data for the object
  * @datalen: The size of the auxiliary data
+ * @object_size: The size of the object according to the server.
  *
  * This function consults the netfs about the coherency state of an object.
  * The caller must be holding a ref on cookie->n_active (held by
diff --git a/fs/fscache/operation.c b/fs/fscache/operation.c
index 433877107700..e002cdfaf3cc 100644
--- a/fs/fscache/operation.c
+++ b/fs/fscache/operation.c
@@ -22,7 +22,10 @@ static void fscache_operation_dummy_cancel(struct fscache_operation *op)
 
 /**
  * fscache_operation_init - Do basic initialisation of an operation
+ * @cookie: The cookie to operate on
  * @op: The operation to initialise
+ * @processor: The function to perform the operation
+ * @cancel: A function to handle operation cancellation
  * @release: The release function to assign
  *
  * Do basic initialisation of an operation.  The caller must still set flags,
diff --git a/fs/nfs_common/grace.c b/fs/nfs_common/grace.c
index edec45831585..0a9b72685f98 100644
--- a/fs/nfs_common/grace.c
+++ b/fs/nfs_common/grace.c
@@ -42,7 +42,6 @@ EXPORT_SYMBOL_GPL(locks_start_grace);
 
 /**
  * locks_end_grace
- * @net: net namespace that this lock manager belongs to
  * @lm: who this grace period is for
  *
  * Call this function to state that the given lock manager is ready to



^ permalink raw reply related	[flat|nested] 8+ messages in thread

* Re: [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some warnings from W=1
  2021-09-20 12:14 [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some warnings from W=1 David Howells
@ 2021-09-20 12:37 ` Matthew Wilcox
  2021-09-20 12:47 ` David Howells
                   ` (5 subsequent siblings)
  6 siblings, 0 replies; 8+ messages in thread
From: Matthew Wilcox @ 2021-09-20 12:37 UTC (permalink / raw)
  To: David Howells
  Cc: linux-fsdevel, Jeff Layton, Dominique Martinet, Marc Dionne,
	Steve French, Trond Myklebust, Anna Schumaker,
	Mauro Carvalho Chehab, v9fs-developer, linux-afs, linux-cifs,
	linux-nfs, linux-doc, linux-kernel

On Mon, Sep 20, 2021 at 01:14:15PM +0100, David Howells wrote:
> +++ b/fs/9p/vfs_addr.c
> @@ -88,7 +88,7 @@ static const struct netfs_read_request_ops v9fs_req_ops = {
>  
>  /**
>   * v9fs_vfs_readpage - read an entire page in from 9P
> - * @filp: file being read
> + * @file: file being read
>   * @page: structure to page
>   *
>   */

This is an example of a weird pattern in filesystems.  Several of
them have kernel-doc for the implementation of various ->ops methods.
I don't necessarily believe we should delete the comments (although is
there any useful information in the above?), but I don't see the point
in the comment being kernel-doc.


^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some warnings from W=1
  2021-09-20 12:14 [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some warnings from W=1 David Howells
  2021-09-20 12:37 ` Matthew Wilcox
@ 2021-09-20 12:47 ` David Howells
  2021-09-20 13:02 ` Dominique Martinet
                   ` (4 subsequent siblings)
  6 siblings, 0 replies; 8+ messages in thread
From: David Howells @ 2021-09-20 12:47 UTC (permalink / raw)
  To: Matthew Wilcox
  Cc: dhowells, linux-fsdevel, Jeff Layton, Dominique Martinet,
	Marc Dionne, Steve French, Trond Myklebust, Anna Schumaker,
	Mauro Carvalho Chehab, v9fs-developer, linux-afs, linux-cifs,
	linux-nfs, linux-doc, linux-kernel

Matthew Wilcox <willy@infradead.org> wrote:

> > +++ b/fs/9p/vfs_addr.c
> > @@ -88,7 +88,7 @@ static const struct netfs_read_request_ops v9fs_req_ops = {
> >  
> >  /**
> >   * v9fs_vfs_readpage - read an entire page in from 9P
> > - * @filp: file being read
> > + * @file: file being read
> >   * @page: structure to page
> >   *
> >   */
> 
> This is an example of a weird pattern in filesystems.  Several of
> them have kernel-doc for the implementation of various ->ops methods.
> I don't necessarily believe we should delete the comments (although is
> there any useful information in the above?), but I don't see the point
> in the comment being kernel-doc.

Yeah - I would prefer to do that.  Only kdoc it if it's inter-(sub-)driver API
- and if it is, it must have a namespacing prefix so that it is obvious in
amongst a kernel-wide general index.

David


^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some warnings from W=1
  2021-09-20 12:14 [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some warnings from W=1 David Howells
  2021-09-20 12:37 ` Matthew Wilcox
  2021-09-20 12:47 ` David Howells
@ 2021-09-20 13:02 ` Dominique Martinet
  2021-09-20 17:59 ` Steve French
                   ` (3 subsequent siblings)
  6 siblings, 0 replies; 8+ messages in thread
From: Dominique Martinet @ 2021-09-20 13:02 UTC (permalink / raw)
  To: David Howells, Matthew Wilcox
  Cc: linux-fsdevel, Jeff Layton, Marc Dionne, Steve French,
	Trond Myklebust, Anna Schumaker, Mauro Carvalho Chehab,
	v9fs-developer, linux-afs, linux-cifs, linux-nfs, linux-doc,
	linux-kernel

David Howells wrote on Mon, Sep 20, 2021 at 01:14:15PM +0100:
> Deal with some warnings generated from make W=1:
> 
>  (1) Add/remove/fix kerneldoc parameters descriptions.
> 
>  (2) afs_sillyrename() isn't an API functions, so remove the kerneldoc
>      annotation.
> 
>  (3) The fscache object CREATE_OBJECT work state isn't used, so remove it.
> 
>  (4) Move __add_fid() from between v9fs_fid_add() and its comment.
> 
>  (5) 9p's caches_show() doesn't really make sense as an API function, show
>      remove the kerneldoc annotation.  It's also not prefixed with 'v9fs_'.

Happy with the 9p changes:
Reviewed-by: Dominique Martinet <asmadeus@codewreck.org>

Having all of these in a single commit makes it difficult to deal but I
don't expect any conflict on my end, so happy to have it go in your
fscache tree.

Matthew Wilcox wrote on Mon, Sep 20, 2021 at 01:37:46PM +0100:
> This is an example of a weird pattern in filesystems.  Several of
> them have kernel-doc for the implementation of various ->ops methods.
> I don't necessarily believe we should delete the comments (although is
> there any useful information in the above?), but I don't see the point
> in the comment being kernel-doc.

As far as I'm concerned this is just an "it's always been like this"
thing for me/9p, I wouldn't mind if it were all converted to normal
comments -- but now it's describing arguments by name having it as
kerneldoc has helped catch comments which didn't get updated when
function changed quite a few times in patches similar to this one so it
would only make sense if we remove obvious argument descriptions as well
in my opinion, and that's a bit of manual work.

-- 
Dominique



^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some warnings from W=1
  2021-09-20 12:14 [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some warnings from W=1 David Howells
                   ` (2 preceding siblings ...)
  2021-09-20 13:02 ` Dominique Martinet
@ 2021-09-20 17:59 ` Steve French
  2021-09-20 18:16 ` David Howells
                   ` (2 subsequent siblings)
  6 siblings, 0 replies; 8+ messages in thread
From: Steve French @ 2021-09-20 17:59 UTC (permalink / raw)
  To: David Howells
  Cc: linux-fsdevel, Jeff Layton, Dominique Martinet, Marc Dionne,
	Steve French, Trond Myklebust, Anna Schumaker,
	Mauro Carvalho Chehab, v9fs-developer, linux-afs, CIFS,
	linux-nfs, linux-doc, LKML

For the cifs ones in connect.c (and also ioctl.c), I had submitted a
patch in rc1 for these (haven't heard back on that) but did not submit
kerneldoc fixup for fs/cifs/misc.c.  They seem trivial and safe, do
you want to split those out and I can put them in?

commit 4c51de1e8f928a5b05248714d832d7d991ac319a
Author: Steve French <stfrench@microsoft.com>
Date:   Mon Sep 13 18:29:46 2021 -0500

    cifs: fix incorrect kernel doc comments

    Correct kernel-doc comments pointed out by the
    automated kernel test robot.

    Reported-by: kernel test robot <lkp@intel.com>

On Mon, Sep 20, 2021 at 9:39 AM David Howells <dhowells@redhat.com> wrote:
>
> Deal with some warnings generated from make W=1:
>
>  (1) Add/remove/fix kerneldoc parameters descriptions.
>
>  (2) afs_sillyrename() isn't an API functions, so remove the kerneldoc
>      annotation.
>
>  (3) The fscache object CREATE_OBJECT work state isn't used, so remove it.
>
>  (4) Move __add_fid() from between v9fs_fid_add() and its comment.
>
>  (5) 9p's caches_show() doesn't really make sense as an API function, show
>      remove the kerneldoc annotation.  It's also not prefixed with 'v9fs_'.
>
>  (6) Remove the kerneldoc annotation on cifs_match_ipdaddr() as it's not
>      fully documented.
>
>  (7) Turn cifs' rqst_page_get_length()'s banner comment into a kerneldoc
>      comment.  It should probably be prefixed with "cifs_" though.
>
> Signed-off-by: David Howells <dhowells@redhat.com>
> cc: Jeff Layton <jlayton@kernel.org>
> cc: Dominique Martinet <asmadeus@codewreck.org>
> cc: Marc Dionne <marc.dionne@auristor.com>
> cc: Steve French <sfrench@samba.org>
> cc: Trond Myklebust <trond.myklebust@hammerspace.com>
> cc: Anna Schumaker <anna.schumaker@netapp.com>
> cc: Mauro Carvalho Chehab <mchehab@kernel.org>
> cc: v9fs-developer@lists.sourceforge.net
> cc: linux-afs@lists.infradead.org
> cc: linux-cifs@vger.kernel.org
> cc: linux-nfs@vger.kernel.org
> cc: linux-fsdevel@vger.kernel.org
> cc: linux-doc@vger.kernel.org
> ---
>
>  fs/9p/fid.c            |   14 +++++++-------
>  fs/9p/v9fs.c           |    8 +++-----
>  fs/9p/vfs_addr.c       |   13 +++++++++----
>  fs/9p/vfs_file.c       |   33 ++++++++++++---------------------
>  fs/9p/vfs_inode.c      |   24 ++++++++++++++++--------
>  fs/9p/vfs_inode_dotl.c |   11 +++++++++--
>  fs/afs/dir_silly.c     |    4 ++--
>  fs/cifs/connect.c      |   14 +++++++++++++-
>  fs/cifs/misc.c         |   14 ++++++++++++--
>  fs/fscache/object.c    |    2 +-
>  fs/fscache/operation.c |    3 +++
>  fs/nfs_common/grace.c  |    1 -
>  12 files changed, 87 insertions(+), 54 deletions(-)
>
> diff --git a/fs/9p/fid.c b/fs/9p/fid.c
> index 9d9de62592be..b8863dd0de5c 100644
> --- a/fs/9p/fid.c
> +++ b/fs/9p/fid.c
> @@ -19,18 +19,18 @@
>  #include "v9fs_vfs.h"
>  #include "fid.h"
>
> +static inline void __add_fid(struct dentry *dentry, struct p9_fid *fid)
> +{
> +       hlist_add_head(&fid->dlist, (struct hlist_head *)&dentry->d_fsdata);
> +}
> +
> +
>  /**
>   * v9fs_fid_add - add a fid to a dentry
>   * @dentry: dentry that the fid is being added to
>   * @fid: fid to add
>   *
>   */
> -
> -static inline void __add_fid(struct dentry *dentry, struct p9_fid *fid)
> -{
> -       hlist_add_head(&fid->dlist, (struct hlist_head *)&dentry->d_fsdata);
> -}
> -
>  void v9fs_fid_add(struct dentry *dentry, struct p9_fid *fid)
>  {
>         spin_lock(&dentry->d_lock);
> @@ -67,7 +67,7 @@ static struct p9_fid *v9fs_fid_find_inode(struct inode *inode, kuid_t uid)
>
>  /**
>   * v9fs_open_fid_add - add an open fid to an inode
> - * @dentry: inode that the fid is being added to
> + * @inode: inode that the fid is being added to
>   * @fid: fid to add
>   *
>   */
> diff --git a/fs/9p/v9fs.c b/fs/9p/v9fs.c
> index cdb99507ef33..2e0fa7c932db 100644
> --- a/fs/9p/v9fs.c
> +++ b/fs/9p/v9fs.c
> @@ -155,6 +155,7 @@ int v9fs_show_options(struct seq_file *m, struct dentry *root)
>  /**
>   * v9fs_parse_options - parse mount options into session structure
>   * @v9ses: existing v9fs session information
> + * @opts: The mount option string
>   *
>   * Return 0 upon success, -ERRNO upon failure.
>   */
> @@ -542,12 +543,9 @@ extern int v9fs_error_init(void);
>  static struct kobject *v9fs_kobj;
>
>  #ifdef CONFIG_9P_FSCACHE
> -/**
> - * caches_show - list caches associated with a session
> - *
> - * Returns the size of buffer written.
> +/*
> + * List caches associated with a session
>   */
> -
>  static ssize_t caches_show(struct kobject *kobj,
>                            struct kobj_attribute *attr,
>                            char *buf)
> diff --git a/fs/9p/vfs_addr.c b/fs/9p/vfs_addr.c
> index fd45874b55db..1c3708720fb9 100644
> --- a/fs/9p/vfs_addr.c
> +++ b/fs/9p/vfs_addr.c
> @@ -88,7 +88,7 @@ static const struct netfs_read_request_ops v9fs_req_ops = {
>
>  /**
>   * v9fs_vfs_readpage - read an entire page in from 9P
> - * @filp: file being read
> + * @file: file being read
>   * @page: structure to page
>   *
>   */
> @@ -108,6 +108,8 @@ static void v9fs_vfs_readahead(struct readahead_control *ractl)
>
>  /**
>   * v9fs_release_page - release the private state associated with a page
> + * @page: The page to be released
> + * @gfp: The caller's allocation restrictions
>   *
>   * Returns 1 if the page can be released, false otherwise.
>   */
> @@ -128,9 +130,9 @@ static int v9fs_release_page(struct page *page, gfp_t gfp)
>
>  /**
>   * v9fs_invalidate_page - Invalidate a page completely or partially
> - *
> - * @page: structure to page
> - * @offset: offset in the page
> + * @page: The page to be invalidated
> + * @offset: offset of the invalidated region
> + * @length: length of the invalidated region
>   */
>
>  static void v9fs_invalidate_page(struct page *page, unsigned int offset,
> @@ -190,6 +192,8 @@ static int v9fs_vfs_writepage(struct page *page, struct writeback_control *wbc)
>
>  /**
>   * v9fs_launder_page - Writeback a dirty page
> + * @page: The page to be cleaned up
> + *
>   * Returns 0 on success.
>   */
>
> @@ -209,6 +213,7 @@ static int v9fs_launder_page(struct page *page)
>  /**
>   * v9fs_direct_IO - 9P address space operation for direct I/O
>   * @iocb: target I/O control block
> + * @iter: The data/buffer to use
>   *
>   * The presence of v9fs_direct_IO() in the address space ops vector
>   * allowes open() O_DIRECT flags which would have failed otherwise.
> diff --git a/fs/9p/vfs_file.c b/fs/9p/vfs_file.c
> index 4b617d10cf28..170d4612a031 100644
> --- a/fs/9p/vfs_file.c
> +++ b/fs/9p/vfs_file.c
> @@ -359,14 +359,11 @@ static int v9fs_file_flock_dotl(struct file *filp, int cmd,
>  }
>
>  /**
> - * v9fs_file_read - read from a file
> - * @filp: file pointer to read
> - * @udata: user data buffer to read data into
> - * @count: size of buffer
> - * @offset: offset at which to read data
> + * v9fs_file_read_iter - read from a file
> + * @iocb: The operation parameters
> + * @to: The buffer to read into
>   *
>   */
> -
>  static ssize_t
>  v9fs_file_read_iter(struct kiocb *iocb, struct iov_iter *to)
>  {
> @@ -388,11 +385,9 @@ v9fs_file_read_iter(struct kiocb *iocb, struct iov_iter *to)
>  }
>
>  /**
> - * v9fs_file_write - write to a file
> - * @filp: file pointer to write
> - * @data: data buffer to write data from
> - * @count: size of buffer
> - * @offset: offset at which to write data
> + * v9fs_file_write_iter - write to a file
> + * @iocb: The operation parameters
> + * @from: The data to write
>   *
>   */
>  static ssize_t
> @@ -574,11 +569,9 @@ v9fs_vm_page_mkwrite(struct vm_fault *vmf)
>  }
>
>  /**
> - * v9fs_mmap_file_read - read from a file
> - * @filp: file pointer to read
> - * @data: user data buffer to read data into
> - * @count: size of buffer
> - * @offset: offset at which to read data
> + * v9fs_mmap_file_read_iter - read from a file
> + * @iocb: The operation parameters
> + * @to: The buffer to read into
>   *
>   */
>  static ssize_t
> @@ -589,11 +582,9 @@ v9fs_mmap_file_read_iter(struct kiocb *iocb, struct iov_iter *to)
>  }
>
>  /**
> - * v9fs_mmap_file_write - write to a file
> - * @filp: file pointer to write
> - * @data: data buffer to write data from
> - * @count: size of buffer
> - * @offset: offset at which to write data
> + * v9fs_mmap_file_write_iter - write to a file
> + * @iocb: The operation parameters
> + * @from: The data to write
>   *
>   */
>  static ssize_t
> diff --git a/fs/9p/vfs_inode.c b/fs/9p/vfs_inode.c
> index 795706520b5e..08f48b70a741 100644
> --- a/fs/9p/vfs_inode.c
> +++ b/fs/9p/vfs_inode.c
> @@ -218,7 +218,7 @@ v9fs_blank_wstat(struct p9_wstat *wstat)
>
>  /**
>   * v9fs_alloc_inode - helper function to allocate an inode
> - *
> + * @sb: The superblock to allocate the inode from
>   */
>  struct inode *v9fs_alloc_inode(struct super_block *sb)
>  {
> @@ -238,7 +238,7 @@ struct inode *v9fs_alloc_inode(struct super_block *sb)
>
>  /**
>   * v9fs_free_inode - destroy an inode
> - *
> + * @inode: The inode to be freed
>   */
>
>  void v9fs_free_inode(struct inode *inode)
> @@ -343,7 +343,7 @@ int v9fs_init_inode(struct v9fs_session_info *v9ses,
>   * v9fs_get_inode - helper function to setup an inode
>   * @sb: superblock
>   * @mode: mode to setup inode with
> - *
> + * @rdev: The device numbers to set
>   */
>
>  struct inode *v9fs_get_inode(struct super_block *sb, umode_t mode, dev_t rdev)
> @@ -369,7 +369,7 @@ struct inode *v9fs_get_inode(struct super_block *sb, umode_t mode, dev_t rdev)
>  }
>
>  /**
> - * v9fs_clear_inode - release an inode
> + * v9fs_evict_inode - Remove an inode from the inode cache
>   * @inode: inode to release
>   *
>   */
> @@ -665,14 +665,15 @@ v9fs_create(struct v9fs_session_info *v9ses, struct inode *dir,
>
>  /**
>   * v9fs_vfs_create - VFS hook to create a regular file
> + * @mnt_userns: The user namespace of the mount
> + * @dir: The parent directory
> + * @dentry: The name of file to be created
> + * @mode: The UNIX file mode to set
> + * @excl: True if the file must not yet exist
>   *
>   * open(.., O_CREAT) is handled in v9fs_vfs_atomic_open().  This is only called
>   * for mknod(2).
>   *
> - * @dir: directory inode that is being created
> - * @dentry:  dentry that is being deleted
> - * @mode: create permissions
> - *
>   */
>
>  static int
> @@ -696,6 +697,7 @@ v9fs_vfs_create(struct user_namespace *mnt_userns, struct inode *dir,
>
>  /**
>   * v9fs_vfs_mkdir - VFS mkdir hook to create a directory
> + * @mnt_userns: The user namespace of the mount
>   * @dir:  inode that is being unlinked
>   * @dentry: dentry that is being unlinked
>   * @mode: mode for new directory
> @@ -900,10 +902,12 @@ int v9fs_vfs_rmdir(struct inode *i, struct dentry *d)
>
>  /**
>   * v9fs_vfs_rename - VFS hook to rename an inode
> + * @mnt_userns: The user namespace of the mount
>   * @old_dir:  old dir inode
>   * @old_dentry: old dentry
>   * @new_dir: new dir inode
>   * @new_dentry: new dentry
> + * @flags: RENAME_* flags
>   *
>   */
>
> @@ -1009,6 +1013,7 @@ v9fs_vfs_rename(struct user_namespace *mnt_userns, struct inode *old_dir,
>
>  /**
>   * v9fs_vfs_getattr - retrieve file metadata
> + * @mnt_userns: The user namespace of the mount
>   * @path: Object to query
>   * @stat: metadata structure to populate
>   * @request_mask: Mask of STATX_xxx flags indicating the caller's interests
> @@ -1050,6 +1055,7 @@ v9fs_vfs_getattr(struct user_namespace *mnt_userns, const struct path *path,
>
>  /**
>   * v9fs_vfs_setattr - set file metadata
> + * @mnt_userns: The user namespace of the mount
>   * @dentry: file whose metadata to set
>   * @iattr: metadata assignment structure
>   *
> @@ -1285,6 +1291,7 @@ static int v9fs_vfs_mkspecial(struct inode *dir, struct dentry *dentry,
>
>  /**
>   * v9fs_vfs_symlink - helper function to create symlinks
> + * @mnt_userns: The user namespace of the mount
>   * @dir: directory inode containing symlink
>   * @dentry: dentry for symlink
>   * @symname: symlink data
> @@ -1340,6 +1347,7 @@ v9fs_vfs_link(struct dentry *old_dentry, struct inode *dir,
>
>  /**
>   * v9fs_vfs_mknod - create a special file
> + * @mnt_userns: The user namespace of the mount
>   * @dir: inode destination for new link
>   * @dentry: dentry for file
>   * @mode: mode for creation
> diff --git a/fs/9p/vfs_inode_dotl.c b/fs/9p/vfs_inode_dotl.c
> index e1c0240b51c0..01b9e1281a29 100644
> --- a/fs/9p/vfs_inode_dotl.c
> +++ b/fs/9p/vfs_inode_dotl.c
> @@ -37,7 +37,10 @@ v9fs_vfs_mknod_dotl(struct user_namespace *mnt_userns, struct inode *dir,
>                     struct dentry *dentry, umode_t omode, dev_t rdev);
>
>  /**
> - * v9fs_get_fsgid_for_create - Helper function to get the gid for creating a
> + * v9fs_get_fsgid_for_create - Helper function to get the gid for a new object
> + * @dir_inode: The directory inode
> + *
> + * Helper function to get the gid for creating a
>   * new file system object. This checks the S_ISGID to determine the owning
>   * group of the new file system object.
>   */
> @@ -211,12 +214,13 @@ int v9fs_open_to_dotl_flags(int flags)
>
>  /**
>   * v9fs_vfs_create_dotl - VFS hook to create files for 9P2000.L protocol.
> + * @mnt_userns: The user namespace of the mount
>   * @dir: directory inode that is being created
>   * @dentry:  dentry that is being deleted
>   * @omode: create permissions
> + * @excl: True if the file must not yet exist
>   *
>   */
> -
>  static int
>  v9fs_vfs_create_dotl(struct user_namespace *mnt_userns, struct inode *dir,
>                      struct dentry *dentry, umode_t omode, bool excl)
> @@ -361,6 +365,7 @@ v9fs_vfs_atomic_open_dotl(struct inode *dir, struct dentry *dentry,
>
>  /**
>   * v9fs_vfs_mkdir_dotl - VFS mkdir hook to create a directory
> + * @mnt_userns: The user namespace of the mount
>   * @dir:  inode that is being unlinked
>   * @dentry: dentry that is being unlinked
>   * @omode: mode for new directory
> @@ -537,6 +542,7 @@ static int v9fs_mapped_iattr_valid(int iattr_valid)
>
>  /**
>   * v9fs_vfs_setattr_dotl - set file metadata
> + * @mnt_userns: The user namespace of the mount
>   * @dentry: file whose metadata to set
>   * @iattr: metadata assignment structure
>   *
> @@ -816,6 +822,7 @@ v9fs_vfs_link_dotl(struct dentry *old_dentry, struct inode *dir,
>
>  /**
>   * v9fs_vfs_mknod_dotl - create a special file
> + * @mnt_userns: The user namespace of the mount
>   * @dir: inode destination for new link
>   * @dentry: dentry for file
>   * @omode: mode for creation
> diff --git a/fs/afs/dir_silly.c b/fs/afs/dir_silly.c
> index dae9a57d7ec0..45cfd50a9521 100644
> --- a/fs/afs/dir_silly.c
> +++ b/fs/afs/dir_silly.c
> @@ -86,8 +86,8 @@ static int afs_do_silly_rename(struct afs_vnode *dvnode, struct afs_vnode *vnode
>         return afs_do_sync_operation(op);
>  }
>
> -/**
> - * afs_sillyrename - Perform a silly-rename of a dentry
> +/*
> + * Perform silly-rename of a dentry.
>   *
>   * AFS is stateless and the server doesn't know when the client is holding a
>   * file open.  To prevent application problems when a file is unlinked while
> diff --git a/fs/cifs/connect.c b/fs/cifs/connect.c
> index 0db344807ef1..a725377d662b 100644
> --- a/fs/cifs/connect.c
> +++ b/fs/cifs/connect.c
> @@ -1090,7 +1090,7 @@ cifs_demultiplex_thread(void *p)
>         module_put_and_exit(0);
>  }
>
> -/**
> +/*
>   * Returns true if srcaddr isn't specified and rhs isn't specified, or
>   * if srcaddr is specified and matches the IP address of the rhs argument
>   */
> @@ -1550,6 +1550,8 @@ static int match_session(struct cifs_ses *ses, struct smb3_fs_context *ctx)
>
>  /**
>   * cifs_setup_ipc - helper to setup the IPC tcon for the session
> + * @ses: The session being set up
> + * @ctx: The mount context
>   *
>   * A new IPC connection is made and stored in the session
>   * tcon_ipc. The IPC tcon has the same lifetime as the session.
> @@ -1605,6 +1607,7 @@ cifs_setup_ipc(struct cifs_ses *ses, struct smb3_fs_context *ctx)
>
>  /**
>   * cifs_free_ipc - helper to release the session IPC tcon
> + * @ses: The session being destroyed
>   *
>   * Needs to be called everytime a session is destroyed.
>   *
> @@ -1855,6 +1858,8 @@ cifs_set_cifscreds(struct smb3_fs_context *ctx __attribute__((unused)),
>
>  /**
>   * cifs_get_smb_ses - get a session matching @ctx data from @server
> + * @server: The server we want to use
> + * @ctx: The mount context
>   *
>   * This function assumes it is being called from cifs_mount() where we
>   * already got a server reference (server refcount +1). See
> @@ -2065,6 +2070,8 @@ cifs_put_tcon(struct cifs_tcon *tcon)
>
>  /**
>   * cifs_get_tcon - get a tcon matching @ctx data from @ses
> + * @ses: The session we're working in
> + * @ctx: The mount context.
>   *
>   * - tcon refcount is the number of mount points using the tcon.
>   * - ses refcount is the number of tcon using the session.
> @@ -3032,6 +3039,11 @@ build_unc_path_to_root(const struct smb3_fs_context *ctx,
>
>  /**
>   * expand_dfs_referral - Perform a dfs referral query and update the cifs_sb
> + * @xid: The operation ID
> + * @ses: The session we're working in
> + * @ctx: The mount context
> + * @cifs_sb: The superblock private data
> + * @ref_path: The referral path
>   *
>   * If a referral is found, cifs_sb->ctx->mount_options will be (re-)allocated
>   * to a string containing updated options for the submount.  Otherwise it
> diff --git a/fs/cifs/misc.c b/fs/cifs/misc.c
> index 9469f1cf0b46..05225d13e3d4 100644
> --- a/fs/cifs/misc.c
> +++ b/fs/cifs/misc.c
> @@ -591,6 +591,7 @@ void cifs_put_writer(struct cifsInodeInfo *cinode)
>
>  /**
>   * cifs_queue_oplock_break - queue the oplock break handler for cfile
> + * @cfile: The file to break the oplock on
>   *
>   * This function is called from the demultiplex thread when it
>   * receives an oplock break for @cfile.
> @@ -1029,6 +1030,9 @@ setup_aio_ctx_iter(struct cifs_aio_ctx *ctx, struct iov_iter *iter, int rw)
>
>  /**
>   * cifs_alloc_hash - allocate hash and hash context together
> + * @name: The name of the crypto hash algo
> + * @shash: Where to put the pointer to the hash algo
> + * @sdesc: Where to put the pointer to the hash descriptor
>   *
>   * The caller has to make sure @sdesc is initialized to either NULL or
>   * a valid context. Both can be freed via cifs_free_hash().
> @@ -1067,6 +1071,8 @@ cifs_alloc_hash(const char *name,
>
>  /**
>   * cifs_free_hash - free hash and hash context together
> + * @shash: Where to find the pointer to the hash algo
> + * @sdesc: Where to find the pointer to the hash descriptor
>   *
>   * Freeing a NULL hash or context is safe.
>   */
> @@ -1082,8 +1088,10 @@ cifs_free_hash(struct crypto_shash **shash, struct sdesc **sdesc)
>
>  /**
>   * rqst_page_get_length - obtain the length and offset for a page in smb_rqst
> - * Input: rqst - a smb_rqst, page - a page index for rqst
> - * Output: *len - the length for this page, *offset - the offset for this page
> + * @rqst: The request descriptor
> + * @page: The index of the page to query
> + * @len: Where to store the length for this page:
> + * @offset: Where to store the offset for this page
>   */
>  void rqst_page_get_length(struct smb_rqst *rqst, unsigned int page,
>                                 unsigned int *len, unsigned int *offset)
> @@ -1116,6 +1124,8 @@ void extract_unc_hostname(const char *unc, const char **h, size_t *len)
>
>  /**
>   * copy_path_name - copy src path to dst, possibly truncating
> + * @dst: The destination buffer
> + * @src: The source name
>   *
>   * returns number of bytes written (including trailing nul)
>   */
> diff --git a/fs/fscache/object.c b/fs/fscache/object.c
> index d7eab46dd826..86ad941726f7 100644
> --- a/fs/fscache/object.c
> +++ b/fs/fscache/object.c
> @@ -77,7 +77,6 @@ static WORK_STATE(INIT_OBJECT,                "INIT", fscache_initialise_object);
>  static WORK_STATE(PARENT_READY,                "PRDY", fscache_parent_ready);
>  static WORK_STATE(ABORT_INIT,          "ABRT", fscache_abort_initialisation);
>  static WORK_STATE(LOOK_UP_OBJECT,      "LOOK", fscache_look_up_object);
> -static WORK_STATE(CREATE_OBJECT,       "CRTO", fscache_look_up_object);
>  static WORK_STATE(OBJECT_AVAILABLE,    "AVBL", fscache_object_available);
>  static WORK_STATE(JUMPSTART_DEPS,      "JUMP", fscache_jumpstart_dependents);
>
> @@ -907,6 +906,7 @@ static void fscache_dequeue_object(struct fscache_object *object)
>   * @object: The object to ask about
>   * @data: The auxiliary data for the object
>   * @datalen: The size of the auxiliary data
> + * @object_size: The size of the object according to the server.
>   *
>   * This function consults the netfs about the coherency state of an object.
>   * The caller must be holding a ref on cookie->n_active (held by
> diff --git a/fs/fscache/operation.c b/fs/fscache/operation.c
> index 433877107700..e002cdfaf3cc 100644
> --- a/fs/fscache/operation.c
> +++ b/fs/fscache/operation.c
> @@ -22,7 +22,10 @@ static void fscache_operation_dummy_cancel(struct fscache_operation *op)
>
>  /**
>   * fscache_operation_init - Do basic initialisation of an operation
> + * @cookie: The cookie to operate on
>   * @op: The operation to initialise
> + * @processor: The function to perform the operation
> + * @cancel: A function to handle operation cancellation
>   * @release: The release function to assign
>   *
>   * Do basic initialisation of an operation.  The caller must still set flags,
> diff --git a/fs/nfs_common/grace.c b/fs/nfs_common/grace.c
> index edec45831585..0a9b72685f98 100644
> --- a/fs/nfs_common/grace.c
> +++ b/fs/nfs_common/grace.c
> @@ -42,7 +42,6 @@ EXPORT_SYMBOL_GPL(locks_start_grace);
>
>  /**
>   * locks_end_grace
> - * @net: net namespace that this lock manager belongs to
>   * @lm: who this grace period is for
>   *
>   * Call this function to state that the given lock manager is ready to
>
>


-- 
Thanks,

Steve

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some warnings from W=1
  2021-09-20 12:14 [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some warnings from W=1 David Howells
                   ` (3 preceding siblings ...)
  2021-09-20 17:59 ` Steve French
@ 2021-09-20 18:16 ` David Howells
  2021-09-23 19:08 ` Fwd: " Steve French
  2021-09-28  8:46 ` David Howells
  6 siblings, 0 replies; 8+ messages in thread
From: David Howells @ 2021-09-20 18:16 UTC (permalink / raw)
  To: Steve French
  Cc: dhowells, linux-fsdevel, Jeff Layton, Dominique Martinet,
	Marc Dionne, Steve French, Trond Myklebust, Anna Schumaker,
	Mauro Carvalho Chehab, v9fs-developer, linux-afs, CIFS,
	linux-nfs, linux-doc, LKML

Steve French <smfrench@gmail.com> wrote:

> For the cifs ones in connect.c (and also ioctl.c), I had submitted a
> patch in rc1 for these (haven't heard back on that) but did not submit
> kerneldoc fixup for fs/cifs/misc.c.  They seem trivial and safe, do
> you want to split those out and I can put them in?

I can, though the reason I did the patch is that the warnings are always
popping up in what I'm doing.  I can drop the patch from mine when I'm done, I
guess.

David


^ permalink raw reply	[flat|nested] 8+ messages in thread

* Fwd: [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some warnings from W=1
  2021-09-20 12:14 [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some warnings from W=1 David Howells
                   ` (4 preceding siblings ...)
  2021-09-20 18:16 ` David Howells
@ 2021-09-23 19:08 ` Steve French
  2021-09-28  8:46 ` David Howells
  6 siblings, 0 replies; 8+ messages in thread
From: Steve French @ 2021-09-23 19:08 UTC (permalink / raw)
  To: CIFS, David Howells

[-- Attachment #1: Type: text/plain, Size: 20882 bytes --]

Updated patch (just including the cifs change) to avoid merge conflicts.

Tentatively merged into cifs-2.6.git for-next

---------- Forwarded message ---------
From: David Howells <dhowells@redhat.com>
Date: Mon, Sep 20, 2021 at 9:39 AM
Subject: [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some
warnings from W=1
To: <linux-fsdevel@vger.kernel.org>
Cc: Jeff Layton <jlayton@kernel.org>, Dominique Martinet
<asmadeus@codewreck.org>, Marc Dionne <marc.dionne@auristor.com>,
Steve French <sfrench@samba.org>, Trond Myklebust
<trond.myklebust@hammerspace.com>, Anna Schumaker
<anna.schumaker@netapp.com>, Mauro Carvalho Chehab
<mchehab@kernel.org>, <v9fs-developer@lists.sourceforge.net>,
<linux-afs@lists.infradead.org>, <linux-cifs@vger.kernel.org>,
<linux-nfs@vger.kernel.org>, <linux-doc@vger.kernel.org>,
<dhowells@redhat.com>, <linux-kernel@vger.kernel.org>


Deal with some warnings generated from make W=1:

 (1) Add/remove/fix kerneldoc parameters descriptions.

 (2) afs_sillyrename() isn't an API functions, so remove the kerneldoc
     annotation.

 (3) The fscache object CREATE_OBJECT work state isn't used, so remove it.

 (4) Move __add_fid() from between v9fs_fid_add() and its comment.

 (5) 9p's caches_show() doesn't really make sense as an API function, show
     remove the kerneldoc annotation.  It's also not prefixed with 'v9fs_'.

 (6) Remove the kerneldoc annotation on cifs_match_ipdaddr() as it's not
     fully documented.

 (7) Turn cifs' rqst_page_get_length()'s banner comment into a kerneldoc
     comment.  It should probably be prefixed with "cifs_" though.

Signed-off-by: David Howells <dhowells@redhat.com>
cc: Jeff Layton <jlayton@kernel.org>
cc: Dominique Martinet <asmadeus@codewreck.org>
cc: Marc Dionne <marc.dionne@auristor.com>
cc: Steve French <sfrench@samba.org>
cc: Trond Myklebust <trond.myklebust@hammerspace.com>
cc: Anna Schumaker <anna.schumaker@netapp.com>
cc: Mauro Carvalho Chehab <mchehab@kernel.org>
cc: v9fs-developer@lists.sourceforge.net
cc: linux-afs@lists.infradead.org
cc: linux-cifs@vger.kernel.org
cc: linux-nfs@vger.kernel.org
cc: linux-fsdevel@vger.kernel.org
cc: linux-doc@vger.kernel.org
---

 fs/9p/fid.c            |   14 +++++++-------
 fs/9p/v9fs.c           |    8 +++-----
 fs/9p/vfs_addr.c       |   13 +++++++++----
 fs/9p/vfs_file.c       |   33 ++++++++++++---------------------
 fs/9p/vfs_inode.c      |   24 ++++++++++++++++--------
 fs/9p/vfs_inode_dotl.c |   11 +++++++++--
 fs/afs/dir_silly.c     |    4 ++--
 fs/cifs/connect.c      |   14 +++++++++++++-
 fs/cifs/misc.c         |   14 ++++++++++++--
 fs/fscache/object.c    |    2 +-
 fs/fscache/operation.c |    3 +++
 fs/nfs_common/grace.c  |    1 -
 12 files changed, 87 insertions(+), 54 deletions(-)

diff --git a/fs/9p/fid.c b/fs/9p/fid.c
index 9d9de62592be..b8863dd0de5c 100644
--- a/fs/9p/fid.c
+++ b/fs/9p/fid.c
@@ -19,18 +19,18 @@
 #include "v9fs_vfs.h"
 #include "fid.h"

+static inline void __add_fid(struct dentry *dentry, struct p9_fid *fid)
+{
+       hlist_add_head(&fid->dlist, (struct hlist_head *)&dentry->d_fsdata);
+}
+
+
 /**
  * v9fs_fid_add - add a fid to a dentry
  * @dentry: dentry that the fid is being added to
  * @fid: fid to add
  *
  */
-
-static inline void __add_fid(struct dentry *dentry, struct p9_fid *fid)
-{
-       hlist_add_head(&fid->dlist, (struct hlist_head *)&dentry->d_fsdata);
-}
-
 void v9fs_fid_add(struct dentry *dentry, struct p9_fid *fid)
 {
        spin_lock(&dentry->d_lock);
@@ -67,7 +67,7 @@ static struct p9_fid *v9fs_fid_find_inode(struct
inode *inode, kuid_t uid)

 /**
  * v9fs_open_fid_add - add an open fid to an inode
- * @dentry: inode that the fid is being added to
+ * @inode: inode that the fid is being added to
  * @fid: fid to add
  *
  */
diff --git a/fs/9p/v9fs.c b/fs/9p/v9fs.c
index cdb99507ef33..2e0fa7c932db 100644
--- a/fs/9p/v9fs.c
+++ b/fs/9p/v9fs.c
@@ -155,6 +155,7 @@ int v9fs_show_options(struct seq_file *m, struct
dentry *root)
 /**
  * v9fs_parse_options - parse mount options into session structure
  * @v9ses: existing v9fs session information
+ * @opts: The mount option string
  *
  * Return 0 upon success, -ERRNO upon failure.
  */
@@ -542,12 +543,9 @@ extern int v9fs_error_init(void);
 static struct kobject *v9fs_kobj;

 #ifdef CONFIG_9P_FSCACHE
-/**
- * caches_show - list caches associated with a session
- *
- * Returns the size of buffer written.
+/*
+ * List caches associated with a session
  */
-
 static ssize_t caches_show(struct kobject *kobj,
                           struct kobj_attribute *attr,
                           char *buf)
diff --git a/fs/9p/vfs_addr.c b/fs/9p/vfs_addr.c
index fd45874b55db..1c3708720fb9 100644
--- a/fs/9p/vfs_addr.c
+++ b/fs/9p/vfs_addr.c
@@ -88,7 +88,7 @@ static const struct netfs_read_request_ops v9fs_req_ops = {

 /**
  * v9fs_vfs_readpage - read an entire page in from 9P
- * @filp: file being read
+ * @file: file being read
  * @page: structure to page
  *
  */
@@ -108,6 +108,8 @@ static void v9fs_vfs_readahead(struct
readahead_control *ractl)

 /**
  * v9fs_release_page - release the private state associated with a page
+ * @page: The page to be released
+ * @gfp: The caller's allocation restrictions
  *
  * Returns 1 if the page can be released, false otherwise.
  */
@@ -128,9 +130,9 @@ static int v9fs_release_page(struct page *page, gfp_t gfp)

 /**
  * v9fs_invalidate_page - Invalidate a page completely or partially
- *
- * @page: structure to page
- * @offset: offset in the page
+ * @page: The page to be invalidated
+ * @offset: offset of the invalidated region
+ * @length: length of the invalidated region
  */

 static void v9fs_invalidate_page(struct page *page, unsigned int offset,
@@ -190,6 +192,8 @@ static int v9fs_vfs_writepage(struct page *page,
struct writeback_control *wbc)

 /**
  * v9fs_launder_page - Writeback a dirty page
+ * @page: The page to be cleaned up
+ *
  * Returns 0 on success.
  */

@@ -209,6 +213,7 @@ static int v9fs_launder_page(struct page *page)
 /**
  * v9fs_direct_IO - 9P address space operation for direct I/O
  * @iocb: target I/O control block
+ * @iter: The data/buffer to use
  *
  * The presence of v9fs_direct_IO() in the address space ops vector
  * allowes open() O_DIRECT flags which would have failed otherwise.
diff --git a/fs/9p/vfs_file.c b/fs/9p/vfs_file.c
index 4b617d10cf28..170d4612a031 100644
--- a/fs/9p/vfs_file.c
+++ b/fs/9p/vfs_file.c
@@ -359,14 +359,11 @@ static int v9fs_file_flock_dotl(struct file
*filp, int cmd,
 }

 /**
- * v9fs_file_read - read from a file
- * @filp: file pointer to read
- * @udata: user data buffer to read data into
- * @count: size of buffer
- * @offset: offset at which to read data
+ * v9fs_file_read_iter - read from a file
+ * @iocb: The operation parameters
+ * @to: The buffer to read into
  *
  */
-
 static ssize_t
 v9fs_file_read_iter(struct kiocb *iocb, struct iov_iter *to)
 {
@@ -388,11 +385,9 @@ v9fs_file_read_iter(struct kiocb *iocb, struct
iov_iter *to)
 }

 /**
- * v9fs_file_write - write to a file
- * @filp: file pointer to write
- * @data: data buffer to write data from
- * @count: size of buffer
- * @offset: offset at which to write data
+ * v9fs_file_write_iter - write to a file
+ * @iocb: The operation parameters
+ * @from: The data to write
  *
  */
 static ssize_t
@@ -574,11 +569,9 @@ v9fs_vm_page_mkwrite(struct vm_fault *vmf)
 }

 /**
- * v9fs_mmap_file_read - read from a file
- * @filp: file pointer to read
- * @data: user data buffer to read data into
- * @count: size of buffer
- * @offset: offset at which to read data
+ * v9fs_mmap_file_read_iter - read from a file
+ * @iocb: The operation parameters
+ * @to: The buffer to read into
  *
  */
 static ssize_t
@@ -589,11 +582,9 @@ v9fs_mmap_file_read_iter(struct kiocb *iocb,
struct iov_iter *to)
 }

 /**
- * v9fs_mmap_file_write - write to a file
- * @filp: file pointer to write
- * @data: data buffer to write data from
- * @count: size of buffer
- * @offset: offset at which to write data
+ * v9fs_mmap_file_write_iter - write to a file
+ * @iocb: The operation parameters
+ * @from: The data to write
  *
  */
 static ssize_t
diff --git a/fs/9p/vfs_inode.c b/fs/9p/vfs_inode.c
index 795706520b5e..08f48b70a741 100644
--- a/fs/9p/vfs_inode.c
+++ b/fs/9p/vfs_inode.c
@@ -218,7 +218,7 @@ v9fs_blank_wstat(struct p9_wstat *wstat)

 /**
  * v9fs_alloc_inode - helper function to allocate an inode
- *
+ * @sb: The superblock to allocate the inode from
  */
 struct inode *v9fs_alloc_inode(struct super_block *sb)
 {
@@ -238,7 +238,7 @@ struct inode *v9fs_alloc_inode(struct super_block *sb)

 /**
  * v9fs_free_inode - destroy an inode
- *
+ * @inode: The inode to be freed
  */

 void v9fs_free_inode(struct inode *inode)
@@ -343,7 +343,7 @@ int v9fs_init_inode(struct v9fs_session_info *v9ses,
  * v9fs_get_inode - helper function to setup an inode
  * @sb: superblock
  * @mode: mode to setup inode with
- *
+ * @rdev: The device numbers to set
  */

 struct inode *v9fs_get_inode(struct super_block *sb, umode_t mode, dev_t rdev)
@@ -369,7 +369,7 @@ struct inode *v9fs_get_inode(struct super_block
*sb, umode_t mode, dev_t rdev)
 }

 /**
- * v9fs_clear_inode - release an inode
+ * v9fs_evict_inode - Remove an inode from the inode cache
  * @inode: inode to release
  *
  */
@@ -665,14 +665,15 @@ v9fs_create(struct v9fs_session_info *v9ses,
struct inode *dir,

 /**
  * v9fs_vfs_create - VFS hook to create a regular file
+ * @mnt_userns: The user namespace of the mount
+ * @dir: The parent directory
+ * @dentry: The name of file to be created
+ * @mode: The UNIX file mode to set
+ * @excl: True if the file must not yet exist
  *
  * open(.., O_CREAT) is handled in v9fs_vfs_atomic_open().  This is only called
  * for mknod(2).
  *
- * @dir: directory inode that is being created
- * @dentry:  dentry that is being deleted
- * @mode: create permissions
- *
  */

 static int
@@ -696,6 +697,7 @@ v9fs_vfs_create(struct user_namespace *mnt_userns,
struct inode *dir,

 /**
  * v9fs_vfs_mkdir - VFS mkdir hook to create a directory
+ * @mnt_userns: The user namespace of the mount
  * @dir:  inode that is being unlinked
  * @dentry: dentry that is being unlinked
  * @mode: mode for new directory
@@ -900,10 +902,12 @@ int v9fs_vfs_rmdir(struct inode *i, struct dentry *d)

 /**
  * v9fs_vfs_rename - VFS hook to rename an inode
+ * @mnt_userns: The user namespace of the mount
  * @old_dir:  old dir inode
  * @old_dentry: old dentry
  * @new_dir: new dir inode
  * @new_dentry: new dentry
+ * @flags: RENAME_* flags
  *
  */

@@ -1009,6 +1013,7 @@ v9fs_vfs_rename(struct user_namespace
*mnt_userns, struct inode *old_dir,

 /**
  * v9fs_vfs_getattr - retrieve file metadata
+ * @mnt_userns: The user namespace of the mount
  * @path: Object to query
  * @stat: metadata structure to populate
  * @request_mask: Mask of STATX_xxx flags indicating the caller's interests
@@ -1050,6 +1055,7 @@ v9fs_vfs_getattr(struct user_namespace
*mnt_userns, const struct path *path,

 /**
  * v9fs_vfs_setattr - set file metadata
+ * @mnt_userns: The user namespace of the mount
  * @dentry: file whose metadata to set
  * @iattr: metadata assignment structure
  *
@@ -1285,6 +1291,7 @@ static int v9fs_vfs_mkspecial(struct inode *dir,
struct dentry *dentry,

 /**
  * v9fs_vfs_symlink - helper function to create symlinks
+ * @mnt_userns: The user namespace of the mount
  * @dir: directory inode containing symlink
  * @dentry: dentry for symlink
  * @symname: symlink data
@@ -1340,6 +1347,7 @@ v9fs_vfs_link(struct dentry *old_dentry, struct
inode *dir,

 /**
  * v9fs_vfs_mknod - create a special file
+ * @mnt_userns: The user namespace of the mount
  * @dir: inode destination for new link
  * @dentry: dentry for file
  * @mode: mode for creation
diff --git a/fs/9p/vfs_inode_dotl.c b/fs/9p/vfs_inode_dotl.c
index e1c0240b51c0..01b9e1281a29 100644
--- a/fs/9p/vfs_inode_dotl.c
+++ b/fs/9p/vfs_inode_dotl.c
@@ -37,7 +37,10 @@ v9fs_vfs_mknod_dotl(struct user_namespace
*mnt_userns, struct inode *dir,
                    struct dentry *dentry, umode_t omode, dev_t rdev);

 /**
- * v9fs_get_fsgid_for_create - Helper function to get the gid for creating a
+ * v9fs_get_fsgid_for_create - Helper function to get the gid for a new object
+ * @dir_inode: The directory inode
+ *
+ * Helper function to get the gid for creating a
  * new file system object. This checks the S_ISGID to determine the owning
  * group of the new file system object.
  */
@@ -211,12 +214,13 @@ int v9fs_open_to_dotl_flags(int flags)

 /**
  * v9fs_vfs_create_dotl - VFS hook to create files for 9P2000.L protocol.
+ * @mnt_userns: The user namespace of the mount
  * @dir: directory inode that is being created
  * @dentry:  dentry that is being deleted
  * @omode: create permissions
+ * @excl: True if the file must not yet exist
  *
  */
-
 static int
 v9fs_vfs_create_dotl(struct user_namespace *mnt_userns, struct inode *dir,
                     struct dentry *dentry, umode_t omode, bool excl)
@@ -361,6 +365,7 @@ v9fs_vfs_atomic_open_dotl(struct inode *dir,
struct dentry *dentry,

 /**
  * v9fs_vfs_mkdir_dotl - VFS mkdir hook to create a directory
+ * @mnt_userns: The user namespace of the mount
  * @dir:  inode that is being unlinked
  * @dentry: dentry that is being unlinked
  * @omode: mode for new directory
@@ -537,6 +542,7 @@ static int v9fs_mapped_iattr_valid(int iattr_valid)

 /**
  * v9fs_vfs_setattr_dotl - set file metadata
+ * @mnt_userns: The user namespace of the mount
  * @dentry: file whose metadata to set
  * @iattr: metadata assignment structure
  *
@@ -816,6 +822,7 @@ v9fs_vfs_link_dotl(struct dentry *old_dentry,
struct inode *dir,

 /**
  * v9fs_vfs_mknod_dotl - create a special file
+ * @mnt_userns: The user namespace of the mount
  * @dir: inode destination for new link
  * @dentry: dentry for file
  * @omode: mode for creation
diff --git a/fs/afs/dir_silly.c b/fs/afs/dir_silly.c
index dae9a57d7ec0..45cfd50a9521 100644
--- a/fs/afs/dir_silly.c
+++ b/fs/afs/dir_silly.c
@@ -86,8 +86,8 @@ static int afs_do_silly_rename(struct afs_vnode
*dvnode, struct afs_vnode *vnode
        return afs_do_sync_operation(op);
 }

-/**
- * afs_sillyrename - Perform a silly-rename of a dentry
+/*
+ * Perform silly-rename of a dentry.
  *
  * AFS is stateless and the server doesn't know when the client is holding a
  * file open.  To prevent application problems when a file is unlinked while
diff --git a/fs/cifs/connect.c b/fs/cifs/connect.c
index 0db344807ef1..a725377d662b 100644
--- a/fs/cifs/connect.c
+++ b/fs/cifs/connect.c
@@ -1090,7 +1090,7 @@ cifs_demultiplex_thread(void *p)
        module_put_and_exit(0);
 }

-/**
+/*
  * Returns true if srcaddr isn't specified and rhs isn't specified, or
  * if srcaddr is specified and matches the IP address of the rhs argument
  */
@@ -1550,6 +1550,8 @@ static int match_session(struct cifs_ses *ses,
struct smb3_fs_context *ctx)

 /**
  * cifs_setup_ipc - helper to setup the IPC tcon for the session
+ * @ses: The session being set up
+ * @ctx: The mount context
  *
  * A new IPC connection is made and stored in the session
  * tcon_ipc. The IPC tcon has the same lifetime as the session.
@@ -1605,6 +1607,7 @@ cifs_setup_ipc(struct cifs_ses *ses, struct
smb3_fs_context *ctx)

 /**
  * cifs_free_ipc - helper to release the session IPC tcon
+ * @ses: The session being destroyed
  *
  * Needs to be called everytime a session is destroyed.
  *
@@ -1855,6 +1858,8 @@ cifs_set_cifscreds(struct smb3_fs_context *ctx
__attribute__((unused)),

 /**
  * cifs_get_smb_ses - get a session matching @ctx data from @server
+ * @server: The server we want to use
+ * @ctx: The mount context
  *
  * This function assumes it is being called from cifs_mount() where we
  * already got a server reference (server refcount +1). See
@@ -2065,6 +2070,8 @@ cifs_put_tcon(struct cifs_tcon *tcon)

 /**
  * cifs_get_tcon - get a tcon matching @ctx data from @ses
+ * @ses: The session we're working in
+ * @ctx: The mount context.
  *
  * - tcon refcount is the number of mount points using the tcon.
  * - ses refcount is the number of tcon using the session.
@@ -3032,6 +3039,11 @@ build_unc_path_to_root(const struct smb3_fs_context *ctx,

 /**
  * expand_dfs_referral - Perform a dfs referral query and update the cifs_sb
+ * @xid: The operation ID
+ * @ses: The session we're working in
+ * @ctx: The mount context
+ * @cifs_sb: The superblock private data
+ * @ref_path: The referral path
  *
  * If a referral is found, cifs_sb->ctx->mount_options will be (re-)allocated
  * to a string containing updated options for the submount.  Otherwise it
diff --git a/fs/cifs/misc.c b/fs/cifs/misc.c
index 9469f1cf0b46..05225d13e3d4 100644
--- a/fs/cifs/misc.c
+++ b/fs/cifs/misc.c
@@ -591,6 +591,7 @@ void cifs_put_writer(struct cifsInodeInfo *cinode)

 /**
  * cifs_queue_oplock_break - queue the oplock break handler for cfile
+ * @cfile: The file to break the oplock on
  *
  * This function is called from the demultiplex thread when it
  * receives an oplock break for @cfile.
@@ -1029,6 +1030,9 @@ setup_aio_ctx_iter(struct cifs_aio_ctx *ctx,
struct iov_iter *iter, int rw)

 /**
  * cifs_alloc_hash - allocate hash and hash context together
+ * @name: The name of the crypto hash algo
+ * @shash: Where to put the pointer to the hash algo
+ * @sdesc: Where to put the pointer to the hash descriptor
  *
  * The caller has to make sure @sdesc is initialized to either NULL or
  * a valid context. Both can be freed via cifs_free_hash().
@@ -1067,6 +1071,8 @@ cifs_alloc_hash(const char *name,

 /**
  * cifs_free_hash - free hash and hash context together
+ * @shash: Where to find the pointer to the hash algo
+ * @sdesc: Where to find the pointer to the hash descriptor
  *
  * Freeing a NULL hash or context is safe.
  */
@@ -1082,8 +1088,10 @@ cifs_free_hash(struct crypto_shash **shash,
struct sdesc **sdesc)

 /**
  * rqst_page_get_length - obtain the length and offset for a page in smb_rqst
- * Input: rqst - a smb_rqst, page - a page index for rqst
- * Output: *len - the length for this page, *offset - the offset for this page
+ * @rqst: The request descriptor
+ * @page: The index of the page to query
+ * @len: Where to store the length for this page:
+ * @offset: Where to store the offset for this page
  */
 void rqst_page_get_length(struct smb_rqst *rqst, unsigned int page,
                                unsigned int *len, unsigned int *offset)
@@ -1116,6 +1124,8 @@ void extract_unc_hostname(const char *unc, const
char **h, size_t *len)

 /**
  * copy_path_name - copy src path to dst, possibly truncating
+ * @dst: The destination buffer
+ * @src: The source name
  *
  * returns number of bytes written (including trailing nul)
  */
diff --git a/fs/fscache/object.c b/fs/fscache/object.c
index d7eab46dd826..86ad941726f7 100644
--- a/fs/fscache/object.c
+++ b/fs/fscache/object.c
@@ -77,7 +77,6 @@ static WORK_STATE(INIT_OBJECT,
"INIT", fscache_initialise_object);
 static WORK_STATE(PARENT_READY,                "PRDY", fscache_parent_ready);
 static WORK_STATE(ABORT_INIT,          "ABRT", fscache_abort_initialisation);
 static WORK_STATE(LOOK_UP_OBJECT,      "LOOK", fscache_look_up_object);
-static WORK_STATE(CREATE_OBJECT,       "CRTO", fscache_look_up_object);
 static WORK_STATE(OBJECT_AVAILABLE,    "AVBL", fscache_object_available);
 static WORK_STATE(JUMPSTART_DEPS,      "JUMP", fscache_jumpstart_dependents);

@@ -907,6 +906,7 @@ static void fscache_dequeue_object(struct
fscache_object *object)
  * @object: The object to ask about
  * @data: The auxiliary data for the object
  * @datalen: The size of the auxiliary data
+ * @object_size: The size of the object according to the server.
  *
  * This function consults the netfs about the coherency state of an object.
  * The caller must be holding a ref on cookie->n_active (held by
diff --git a/fs/fscache/operation.c b/fs/fscache/operation.c
index 433877107700..e002cdfaf3cc 100644
--- a/fs/fscache/operation.c
+++ b/fs/fscache/operation.c
@@ -22,7 +22,10 @@ static void fscache_operation_dummy_cancel(struct
fscache_operation *op)

 /**
  * fscache_operation_init - Do basic initialisation of an operation
+ * @cookie: The cookie to operate on
  * @op: The operation to initialise
+ * @processor: The function to perform the operation
+ * @cancel: A function to handle operation cancellation
  * @release: The release function to assign
  *
  * Do basic initialisation of an operation.  The caller must still set flags,
diff --git a/fs/nfs_common/grace.c b/fs/nfs_common/grace.c
index edec45831585..0a9b72685f98 100644
--- a/fs/nfs_common/grace.c
+++ b/fs/nfs_common/grace.c
@@ -42,7 +42,6 @@ EXPORT_SYMBOL_GPL(locks_start_grace);

 /**
  * locks_end_grace
- * @net: net namespace that this lock manager belongs to
  * @lm: who this grace period is for
  *
  * Call this function to state that the given lock manager is ready to




-- 
Thanks,

Steve

[-- Attachment #2: 0001-cifs-Deal-with-some-warnings-from-W-1.patch --]
[-- Type: text/x-patch, Size: 2749 bytes --]

From 03ab9cb982b622239cc2542ce7617b98a9ea159e Mon Sep 17 00:00:00 2001
From: David Howells <dhowells@redhat.com>
Date: Mon, 20 Sep 2021 13:14:15 +0100
Subject: [PATCH] cifs: Deal with some warnings from W=1

Deal with some warnings generated from make W=1:

 (1) Add/remove/fix kerneldoc parameters descriptions.

 (2) Turn cifs' rqst_page_get_length()'s banner comment into a kerneldoc
     comment.  It should probably be prefixed with "cifs_" though.

Signed-off-by: David Howells <dhowells@redhat.com>
Signed-off-by: Steve French <stfrench@microsoft.com>
---
 fs/cifs/misc.c | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/fs/cifs/misc.c b/fs/cifs/misc.c
index 03da00eb7c04..f2916b51652a 100644
--- a/fs/cifs/misc.c
+++ b/fs/cifs/misc.c
@@ -590,6 +590,7 @@ void cifs_put_writer(struct cifsInodeInfo *cinode)
 
 /**
  * cifs_queue_oplock_break - queue the oplock break handler for cfile
+ * @cfile: The file to break the oplock on
  *
  * This function is called from the demultiplex thread when it
  * receives an oplock break for @cfile.
@@ -1065,6 +1066,9 @@ setup_aio_ctx_iter(struct cifs_aio_ctx *ctx, struct iov_iter *iter, int rw)
 
 /**
  * cifs_alloc_hash - allocate hash and hash context together
+ * @name: The name of the crypto hash algo
+ * @shash: Where to put the pointer to the hash algo
+ * @sdesc: Where to put the pointer to the hash descriptor
  *
  * The caller has to make sure @sdesc is initialized to either NULL or
  * a valid context. Both can be freed via cifs_free_hash().
@@ -1103,6 +1107,8 @@ cifs_alloc_hash(const char *name,
 
 /**
  * cifs_free_hash - free hash and hash context together
+ * @shash: Where to find the pointer to the hash algo
+ * @sdesc: Where to find the pointer to the hash descriptor
  *
  * Freeing a NULL hash or context is safe.
  */
@@ -1118,8 +1124,10 @@ cifs_free_hash(struct crypto_shash **shash, struct sdesc **sdesc)
 
 /**
  * rqst_page_get_length - obtain the length and offset for a page in smb_rqst
- * Input: rqst - a smb_rqst, page - a page index for rqst
- * Output: *len - the length for this page, *offset - the offset for this page
+ * @rqst: The request descriptor
+ * @page: The index of the page to query
+ * @len: Where to store the length for this page:
+ * @offset: Where to store the offset for this page
  */
 void rqst_page_get_length(struct smb_rqst *rqst, unsigned int page,
 				unsigned int *len, unsigned int *offset)
@@ -1152,6 +1160,8 @@ void extract_unc_hostname(const char *unc, const char **h, size_t *len)
 
 /**
  * copy_path_name - copy src path to dst, possibly truncating
+ * @dst: The destination buffer
+ * @src: The source name
  *
  * returns number of bytes written (including trailing nul)
  */
-- 
2.30.2


^ permalink raw reply related	[flat|nested] 8+ messages in thread

* Re: Fwd: [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some warnings from W=1
  2021-09-20 12:14 [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some warnings from W=1 David Howells
                   ` (5 preceding siblings ...)
  2021-09-23 19:08 ` Fwd: " Steve French
@ 2021-09-28  8:46 ` David Howells
  6 siblings, 0 replies; 8+ messages in thread
From: David Howells @ 2021-09-28  8:46 UTC (permalink / raw)
  To: Steve French; +Cc: dhowells, CIFS

Steve French <smfrench@gmail.com> wrote:

> Updated patch (just including the cifs change) to avoid merge conflicts.
> 
> Tentatively merged into cifs-2.6.git for-next

I see your W=1 changes got merged and all my cifs bits are now gone.

David


^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2021-09-28  8:46 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-09-20 12:14 [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some warnings from W=1 David Howells
2021-09-20 12:37 ` Matthew Wilcox
2021-09-20 12:47 ` David Howells
2021-09-20 13:02 ` Dominique Martinet
2021-09-20 17:59 ` Steve French
2021-09-20 18:16 ` David Howells
2021-09-23 19:08 ` Fwd: " Steve French
2021-09-28  8:46 ` David Howells

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).