From 73ab7e2e5d94bce22f45f4f8d3553451e3101ad1 Mon Sep 17 00:00:00 2001 From: Arshad Hussain Date: Mon, 6 Jan 2025 00:06:26 -0500 Subject: [PATCH] LU-9633 llite: Add kernel doc style for lustre/llite/*.c (Part 1) This patch converts existing functional comments to kernel doc style comments and removes '/**' for comments which is not meant to be a kernel-doc comment Tested with: /scrips/kernel-doc -v -none Pass criteria: No errors/warnings reported Test-Parameters: trivial Signed-off-by: Arshad Hussain Change-Id: I90643c70bc5ecfbcc90504da1a5b3b3ea67e3381 Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/57725 Reviewed-by: Oleg Drokin Reviewed-by: Andreas Dilger Reviewed-by: James Simmons Tested-by: jenkins Tested-by: Maloo --- lustre/llite/dcache.c | 23 ++++++- lustre/llite/dir.c | 79 ++++++++++++++++++------ lustre/llite/rw.c | 55 +++++++++++------ lustre/llite/statahead.c | 110 +++++++++++++++++++-------------- lustre/llite/super25.c | 15 ++++- lustre/llite/vvp_dev.c | 6 ++ lustre/llite/vvp_page.c | 13 ++-- lustre/llite/xattr_cache.c | 139 +++++++++++++++++++++++++++++------------- lustre/llite/xattr_security.c | 85 ++++++++++++++++++-------- 9 files changed, 363 insertions(+), 162 deletions(-) diff --git a/lustre/llite/dcache.c b/lustre/llite/dcache.c index a0e31fe..205920d 100644 --- a/lustre/llite/dcache.c +++ b/lustre/llite/dcache.c @@ -48,8 +48,15 @@ static void ll_release(struct dentry *de) EXIT; } -/* Compare if two dentries are the same. Don't match if the existing dentry - * is marked invalid. Returns 1 if different, 0 if the same. +/** + * ll_dcompare() - Compare if two dentries are the same. Don't match if the + * existing dentry is marked invalid. + * + * @parent: parent directory + * @dentry: directory which is being compared + * @len: length + * @str: name of directory being compared + * @name: name and length (struct qstr) of directory being compared * * This avoids a race where ll_lookup_it() instantiates a dentry, but we get * an AST before calling d_revalidate_it(). The dentry still exists (marked @@ -61,6 +68,10 @@ static void ll_release(struct dentry *de) * in ll_lookup_nd() at a time. So allow invalid dentries to match * while d_in_lookup(). We will be called again when the lookup * completes, and can give a different answer then. + * + * Return: + * * %0 - if the same + * * %1 - if different */ #if defined(HAVE_D_COMPARE_5ARGS) static int ll_dcompare(const struct dentry *parent, const struct dentry *dentry, @@ -98,11 +109,19 @@ static int ll_dcompare(const struct dentry *dentry, unsigned int len, } /** + * ll_ddelete() - Called when last reference to a dentry is dropped + * + * @de: directory which is being deleted + * * Called when last reference to a dentry is dropped and dcache wants to know * whether or not it should cache it: * - return 1 to delete the dentry immediately * - return 0 to cache the dentry * Should NOT be called with the dcache lock, see fs/dcache.c + * + * Return: + * * %0 - to cache the dentry + * * %1 - to delete the dentry immediately */ static int ll_ddelete(const struct dentry *de) { diff --git a/lustre/llite/dir.c b/lustre/llite/dir.c index ee4bf10..a081613 100644 --- a/lustre/llite/dir.c +++ b/lustre/llite/dir.c @@ -39,7 +39,9 @@ #include "llite_internal.h" -/* +/** + * ll_get_dir_page() - Get directory page for a given directory inode + * * (new) readdir implementation overview. * * Original lustre readdir implementation cached exact copy of raw directory @@ -120,6 +122,15 @@ * lu_dirpage for this integrated page will be adjusted. See * mdc_adjust_dirpages(). * + * + * @dir: pointer to the directory(inode) for which page is being fetched + * @op_data: pointer to the md operation structure + * @offset: Offset witchin page + * @partial_readdir_rc: Used only on partial reads + * + * Return: + * * %Success - pointer to the page structure + * * %Failure - Error pointer (pointed by rc) */ struct page *ll_get_dir_page(struct inode *dir, struct md_op_data *op_data, __u64 offset, int *partial_readdir_rc) @@ -402,16 +413,19 @@ out: RETURN(rc); } -/* - * Create striped directory with specified stripe(@lump) +/** + * ll_dir_setdirstripe() - Create striped directory with specified stripe(@lump) * - * \param[in] dparent the parent of the directory. - * \param[in] lump the specified stripes. - * \param[in] dirname the name of the directory. - * \param[in] mode the specified mode of the directory. + * @dparent: the parent of the directory. + * @lump: the specified stripes. + * @len: length of @lump + * @dirname: the name of the directory. + * @mode: the specified mode of the directory. + * @createonly: if true, setstripe create only, don't restripe if target exists * - * \retval =0 if striped directory is being created successfully. - * <0 if the creation is failed. + * Return: + * * %0 if striped directory is being created successfully or <0 if the + * creation is failed */ static int ll_dir_setdirstripe(struct dentry *dparent, struct lmv_user_md *lump, size_t len, const char *dirname, umode_t mode, @@ -814,7 +828,10 @@ out: return rc; } -/* +/** + * ll_dir_getstripe_default() - Get default layout (striping information) for + * directory + * * This function will be used to get default LOV/LMV/Default LMV * @valid will be used to indicate which stripe it will retrieve. * If the directory does not have its own default layout, then the @@ -823,7 +840,19 @@ out: * OBD_MD_DEFAULT_MEA Default LMV stripe EA * otherwise Default LOV EA. * Each time, it can only retrieve 1 stripe EA - **/ + * + * @inode: inode for which layout is to be get + * @plmm: Returns address of valid layout metadata (struct lov_mds_md) + * @plmm_size: Returns size of the layout metadata + * @request: Returns ptlrpc_request struct which gets the layout + * @root_request: Returns ptlrpc_request struct which get the layout (for root + * access) + * @valid: indicate which stripe it will retrieve + * + * Return: + * * %0: Success + * * %-ERRNO: Failure + */ int ll_dir_getstripe_default(struct inode *inode, void **plmm, int *plmm_size, struct ptlrpc_request **request, struct ptlrpc_request **root_request, @@ -856,14 +885,26 @@ int ll_dir_getstripe_default(struct inode *inode, void **plmm, int *plmm_size, RETURN(rc); } -/* +/** + * ll_dir_getstripe() - Wrapper function to ll_dir_get_default_layout + * * This function will be used to get default LOV/LMV/Default LMV * @valid will be used to indicate which stripe it will retrieve * OBD_MD_MEA LMV stripe EA * OBD_MD_DEFAULT_MEA Default LMV stripe EA * otherwise Default LOV EA. * Each time, it can only retrieve 1 stripe EA - **/ + * + * @inode: inode for which layout is to be get + * @plmm: Returns address of valid layout metadata (struct lov_mds_md) + * @plmm_size: Returns size of the layout metadata + * @request: Returns ptlrpc_request struct which gets the layout + * @valid: indicate which stripe it will retrieve + * + * Return: + * * %0: Success + * * %-ERRNO: Failure + */ int ll_dir_getstripe(struct inode *inode, void **plmm, int *plmm_size, struct ptlrpc_request **request, u64 valid) { @@ -914,7 +955,7 @@ int ll_get_mdt_idx(struct inode *inode) } /* - * Generic handler to do any pre-copy work. + * ll_ioc_copy_start() - Generic handler to do any pre-copy work. * * It sends a first hsm_progress (with extent length == 0) to coordinator as a * first information for it that real work has started. @@ -922,7 +963,8 @@ int ll_get_mdt_idx(struct inode *inode) * Moreover, for a ARCHIVE request, it will sample the file data version and * store it in \a copy. * - * \return 0 on success. + * Return: + * * %0 On success or <0 on failure */ static int ll_ioc_copy_start(struct super_block *sb, struct hsm_copy *copy) { @@ -990,7 +1032,7 @@ progress: } /* - * Generic handler to do any post-copy work. + * ll_ioc_copy_end() - Generic handler to do any post-copy work. * * It will send the last hsm_progress update to coordinator to inform it * that copy is finished and whether it was successful or not. @@ -1002,7 +1044,8 @@ progress: * - for RESTORE request, it will sample the file data version and send it to * coordinator which is useful if the file was imported as 'released'. * - * \return 0 on success. + * Return: + * * %0 On success or <0 on failure */ static int ll_ioc_copy_end(struct super_block *sb, struct hsm_copy *copy) { @@ -1407,7 +1450,7 @@ static int quotactl_iter_glb(struct list_head *quota_list, void *buffer, /* iterate the quota setting from QMT and all QSDs to get the quota information * for all users or groups - **/ + */ static int quotactl_iter(struct ll_sb_info *sbi, struct if_quotactl *qctl) { struct list_head iter_quota_glb_list; diff --git a/lustre/llite/rw.c b/lustre/llite/rw.c index 76cea8f..0f1221d 100644 --- a/lustre/llite/rw.c +++ b/lustre/llite/rw.c @@ -173,13 +173,19 @@ enum ll_ra_page_hint { WILLNEED /* this page is gurateed to be needed */ }; -/* - * Initiates read-ahead of a page with given index. +/** + * ll_read_ahead_page() - Initiates read-ahead of a page with given index. + * + * @env: execution environment for this thread + * @io: struct (cl_io) responsible for IO operation + * @queue: struct cl_page_list (list of pages (memory) used for read ahead IO) + * @index: offset withing page to read ahead + * @hint: see ll_ra_page_hint * - * \retval +ve: page was already uptodate so it will be skipped - * from being added; - * \retval -ve: page wasn't added to \a queue for error; - * \retval 0: page was added into \a queue for read ahead. + * Returns: + * * %0 if page was added into @queue for read ahead or <0 if page was not + * added to @queue for read ahead or >0 if page was already uptodate so it will + * be skipped from being added */ static int ll_read_ahead_page(const struct lu_env *env, struct cl_io *io, struct cl_page_list *queue, pgoff_t index, @@ -283,7 +289,8 @@ static inline int stride_io_mode(struct ll_readahead_state *ras) return ras->ras_consecutive_stride_requests > 1; } -/* The function calculates how many bytes will be read in +/* stride_byte_count() - The function calculates how many bytes will be read in + * * [off, off + length], in such stride IO area, * stride_offset = st_off, stride_lengh = st_len, * stride_bytes = st_bytes @@ -1250,6 +1257,16 @@ static void ras_detect_read_pattern(struct ll_readahead_state *ras, RAS_CDEBUG(ras); } +/** + * ll_ras_enter() - used to detect read pattern according to pos and count + * + * @f: pointer to open file (struct file) + * @pos: position where read is starting + * @bytes: length to be read + * + * Returns: + * * %void + */ void ll_ras_enter(struct file *f, loff_t pos, size_t bytes) { struct ll_file_data *lfd = f->private_data; @@ -1319,11 +1336,8 @@ static bool index_in_stride_window(struct ll_readahead_state *ras, return false; } -/* - * ll_ras_enter() is used to detect read pattern according to pos and count. - * - * ras_update() is used to detect cache miss and - * reset window or increase window accordingly +/* ras_update() is used to detect cache miss and reset window or increase + * window accordingly */ static void ras_update(struct ll_sb_info *sbi, struct inode *inode, struct ll_readahead_state *ras, pgoff_t index, @@ -1818,12 +1832,17 @@ int ll_io_read_page(const struct lu_env *env, struct cl_io *io, RETURN(rc); } -/* - * Possible return value: - * 0 no async readahead triggered and fast read could not be used. - * 1 no async readahead, but fast read could be used. - * 2 async readahead triggered and fast read could be used too. - * < 0 on error. +/** + * kickoff_async_readahead() - start asynchronous readahead + * + * @file: readahead for this open file + * @pages: size of read ahead (in pages) + * + * Returns: + * * %0 no async readahead triggered and fast read could not be used. + * * %1 no async readahead, but fast read could be used. + * * %2 async readahead triggered and fast read could be used too. + * * %-ENOMEM on error. */ static int kickoff_async_readahead(struct file *file, unsigned long pages) { diff --git a/lustre/llite/statahead.c b/lustre/llite/statahead.c index 0181374..64377d4 100644 --- a/lustre/llite/statahead.c +++ b/lustre/llite/statahead.c @@ -157,10 +157,18 @@ static inline int agl_list_empty(struct ll_statahead_info *sai) } /** + * sa_low_hit() - Return if hit ratio is low + * + * @sai: (ll_statahead_info struct) holds info about the SA process for a + * directory + * + * Low hit ratio is defined as: * (1) hit ratio less than 80% * or - * (2) consecutive miss more than 32 - * then means low hit. + * (2) consecutive miss more than 32, this means low hit. + * + * Returns: + * * %0 Hit ratio is not low, else if !0 then hit ratio is low */ static inline int sa_low_hit(struct ll_statahead_info *sai) { @@ -983,11 +991,17 @@ static int sa_lookup(struct inode *dir, struct sa_entry *entry) } /** - * async stat for file found in dcache, similar to .revalidate + * sa_revalidate() - async stat for file found in dcache (directory cache), + * similar to .revalidate + * + * @dir: inode struct for the @dir that contains file to be revalidated + * @entry: sa_entry structure (SA file state) + * @dentry: dentry struct for the @dentry that contains file to be revalidated * - * \retval 1 dentry valid, no RPC sent - * \retval 0 dentry invalid, will send async stat RPC - * \retval negative number upon error + * Returns: + * * %1 dentry valid, no RPC sent + * * %0 dentry invalid, will send async stat RPC + * * %-ERRNO negative number upon error */ static int sa_revalidate(struct inode *dir, struct sa_entry *entry, struct dentry *dentry) @@ -1936,16 +1950,18 @@ out_unlock: } /** - * revalidate @dentryp from statahead cache + * revalidate_statahead_dentry() - revalidate @dentryp from statahead cache * - * \param[in] dir parent directory - * \param[in] sai sai structure - * \param[out] dentryp pointer to dentry which will be revalidated - * \param[in] unplug unplug statahead window only (normally for negative - * dentry) - * \retval 1 on success, dentry is saved in @dentryp - * \retval 0 if revalidation failed (no proper lock on client) - * \retval negative number upon error + * @dir: parent directory + * @sai: sai structure + * @ctx: statahead context structure (cache info) + * @dentryp: pointer to dentry which will be revalidated + * @unplug: unplug statahead window only (normally for negative dentry) + * + * Returns: + * * %1 on success, dentry is saved in @dentryp + * * %0 if revalidation failed (no proper lock on client) + * * %-ERRNO upon error */ static int revalidate_statahead_dentry(struct inode *dir, struct ll_statahead_info *sai, @@ -2263,17 +2279,17 @@ static inline bool sa_pattern_shared_fname(struct ll_inode_info *lli) } /** - * start statahead thread + * start_statahead_thread() - start statahead thread + * + * @dir: parent directory + * @dentry: dentry that triggers statahead, normally the first dirent under @dir + * @agl: indicate whether AGL(Asynchronous Glimpse Lock) is needed * - * \param[in] dir parent directory - * \param[in] dentry dentry that triggers statahead, normally the first - * dirent under @dir - * \param[in] agl indicate whether AGL is needed - * \retval -EAGAIN on success, because when this function is - * called, it's already in lookup call, so client should - * do it itself instead of waiting for statahead thread - * to do it asynchronously. - * \retval negative number upon error + * Returns: + * * %-EAGAIN success, because when this function is called, it's already + * in lookup call, so client should do it itself instead of waiting for + * statahead thread to do it asynchronously. + * * %-ERRNO (other than -EAGAIN) on error */ static int start_statahead_thread(struct inode *dir, struct dentry *dentry, bool agl) @@ -2524,19 +2540,20 @@ static inline bool ll_statahead_started(struct inode *dir, bool agl) } /** - * statahead entry function, this is called when client getattr on a file, it - * will start statahead thread if this is the first dir entry, else revalidate - * dentry from statahead cache. + * ll_start_statahead() - statahead entry function, this is called when client * - * \param[in] dir parent directory - * \param[out] dentryp dentry to getattr - * \param[in] agl whether start the agl thread + * @dir: parent directory + * @dentry: dentry to getattr + * @agl: whether start the agl thread * - * \retval 1 on success - * \retval 0 revalidation from statahead cache failed, caller needs - * to getattr from server directly - * \retval negative number on error, caller often ignores this and - * then getattr from server + * this is called when client getattr on a file, it will start statahead thread + * if this is the first dir entry, else revalidate dentry from statahead cache. + * + * Returns: + * * %1 success + * * %0 revalidation from statahead cache failed, caller needs to getattr + * from server directly + * * <0 on error, caller often ignores this and then getattrfrom server */ int ll_start_statahead(struct inode *dir, struct dentry *dentry, bool agl) { @@ -2546,17 +2563,18 @@ int ll_start_statahead(struct inode *dir, struct dentry *dentry, bool agl) } /** - * revalidate dentry from statahead cache. + * ll_revalidate_statahead() - revalidate dentry from statahead cache. + * + * @dir: parent directory + * @dentryp: dentry to getattr + * @unplug: unplug statahead window only (normally for negative dentry) * - * \param[in] dir parent directory - * \param[out] dentryp dentry to getattr - * \param[in] unplug unplug statahead window only (normally for negative - * dentry) - * \retval 1 on success - * \retval 0 revalidation from statahead cache failed, caller needs - * to getattr from server directly - * \retval negative number on error, caller often ignores this and - * then getattr from server + * Returns: + * * %1 success + * * %0 revalidation from statahead cache failed, caller needs to getattr + * from server directly + * * <0 negative number on error, caller often ignores this and then getattr + * from server */ int ll_revalidate_statahead(struct inode *dir, struct dentry **dentryp, bool unplug) diff --git a/lustre/llite/super25.c b/lustre/llite/super25.c index 5eba351..5e892fc 100644 --- a/lustre/llite/super25.c +++ b/lustre/llite/super25.c @@ -93,11 +93,21 @@ const struct super_operations lustre_super_operations = { }; /** + * lustre_fill_super() - set up the superblock with lustre info + * + * @sb: setup superblock struct with lustre info + * @lmd2_data: data Mount options provided during mount + * (e.g. -o flock,abort_recov) + * @silent: + * * This is the entry point for the mount call into Lustre. * This is called when a client is mounted, and this is * where we start setting things up. * - * @lmd2data data Mount options (e.g. -o flock,abort_recov) + * Returns: + * * %0 Success + * * <0 Error + * */ static int lustre_fill_super(struct super_block *sb, void *lmd2_data, int silent) @@ -194,8 +204,7 @@ static void lustre_kill_super(struct super_block *sb) kill_anon_super(sb); } -/** Register the "lustre" fs type - */ +/* Register the "lustre" fs type */ static struct file_system_type lustre_fs_type = { .owner = THIS_MODULE, .name = "lustre", diff --git a/lustre/llite/vvp_dev.c b/lustre/llite/vvp_dev.c index 9b8b6bb..2509391 100644 --- a/lustre/llite/vvp_dev.c +++ b/lustre/llite/vvp_dev.c @@ -255,8 +255,14 @@ void (*vvp_folio_memcg_unlock)(struct folio *folio); #endif /** + * vvp_global_init() - init global resources required by the VVP layer + * * A mutex serializing calls to vvp_inode_fini() under extreme memory * pressure, when environments cannot be allocated. + * + * Returns: + * * %0 Success + * * <0 Failure */ int vvp_global_init(void) { diff --git a/lustre/llite/vvp_page.c b/lustre/llite/vvp_page.c index a994952..c0dfa4e 100644 --- a/lustre/llite/vvp_page.c +++ b/lustre/llite/vvp_page.c @@ -29,11 +29,8 @@ #include "llite_internal.h" #include "vvp_internal.h" -/***************************************************************************** - * - * Page operations. - * - */ +/* Page operations */ + static void vvp_page_discard(const struct lu_env *env, const struct cl_page_slice *slice, struct cl_io *unused) @@ -83,7 +80,11 @@ static void vvp_page_delete(const struct lu_env *env, } /** - * Handles page transfer errors at VM level. + * vvp_vmpage_error() - Handles page transfer errors at VM level. + * + * @inode: inode linked with vmpage(struct page) + * @vmpage: struct page that has error + * @ioret: type of error * * This takes inode as a separate argument, because inode on which error is to * be set can be different from \a vmpage inode in case of direct-io. diff --git a/lustre/llite/xattr_cache.c b/lustre/llite/xattr_cache.c index 1643f89..700e1a4 100644 --- a/lustre/llite/xattr_cache.c +++ b/lustre/llite/xattr_cache.c @@ -50,10 +50,15 @@ void ll_xattr_fini(void) lu_kmem_fini(xattr_caches); } -/* - * Initializes xattr cache for an inode. +/** + * ll_xattr_cache_init() - Initializes xattr cache for an inode. * * This initializes the xattr list and marks cache presence. + * + * @lli: lustre ll_inode_info struct (list of xattrs) + * + * Returns: + * * %void */ static void ll_xattr_cache_init(struct ll_inode_info *lli) { @@ -66,13 +71,18 @@ static void ll_xattr_cache_init(struct ll_inode_info *lli) } /** - * This looks for a specific extended attribute. + * ll_xattr_cache_find() - This looks for a specific extended attribute. + * + * @cache: Find in this list @xattr_name + * @xattr_name: xattr name to find + * @xattr: Return matched xattr attribute on success * * Find in @cache and return @xattr_name attribute in @xattr, * for the NULL @xattr_name return the first cached @xattr. * - * \retval 0 success - * \retval -ENODATA if not found + * Returns: + * * %0 success + * * %-ENODATA if not found */ static int ll_xattr_cache_find(struct list_head *cache, const char *xattr_name, @@ -98,13 +108,19 @@ static int ll_xattr_cache_find(struct list_head *cache, } /** - * This adds an xattr. + * ll_xattr_cache_add() - This adds an xattr. + * + * @cache: list of xattr for an inode (struct ll_xattr_entry) + * @xattr_name: name of xattr to be added to the cache list + * @xattr_val: value of xattr to be added to the cache list + * @xattr_val_len: length of xattr value * * Add @xattr_name attr with @xattr_val value and @xattr_val_len length, * - * \retval 0 success - * \retval -ENOMEM if no memory could be allocated for the cached attr - * \retval -EPROTO if duplicate xattr is being added + * Returns: + * * %0 success + * * %-ENOMEM if no memory could be allocated for the cached attr + * * %-EPROTO if duplicate xattr is being added */ static int ll_xattr_cache_add(struct list_head *cache, const char *xattr_name, @@ -166,12 +182,16 @@ err_name: } /** - * This removes an extended attribute from cache. + * ll_xattr_cache_del() - This removes an extended attribute from cache. + * + * @cache: list of xattr for an inode (struct ll_xattr_entry) + * @xattr_name: name of xattr to be deleted to the cache list * * Remove @xattr_name attribute from @cache. * - * \retval 0 success - * \retval -ENODATA if @xattr_name is not cached + * Returns: + * * %0 success + * * %-ENODATA if @xattr_name is not cached */ static int ll_xattr_cache_del(struct list_head *cache, const char *xattr_name) @@ -195,14 +215,18 @@ static int ll_xattr_cache_del(struct list_head *cache, } /** - * This iterates cached extended attributes. + * ll_xattr_cache_list() - This iterates cached extended attributes. + * + * @cache: list of xattr for an inode (struct ll_xattr_entry) + * @xld_buffer: buffer(space) to store xattrs + * @xld_size: size of @xld_buffer * - * Walk over cached attributes in @cache and - * fill in @xld_buffer or only calculate buffer - * size if @xld_buffer is NULL. + * Walk over cached attributes in @cache and fill in @xld_buffer or only + * calculate buffer size if @xld_buffer is NULL. * - * \retval >= 0 buffer list size - * \retval -ENODATA if the list cannot fit @xld_size buffer + * Returns: + * * >= 0 buffer list size + * * %-ENODATA if the list cannot fit @xld_size buffer */ static int ll_xattr_cache_list(struct list_head *cache, char *xld_buffer, @@ -234,10 +258,13 @@ static int ll_xattr_cache_list(struct list_head *cache, } /** - * Check if the xattr cache is initialized. + * ll_xattr_cache_valid() - Check if the xattr cache is initialized. * - * \retval 0 @cache is not initialized - * \retval 1 @cache is initialized + * @lli: lustre ll_inode_info struct (list of xattrs) + * + * Returns: + * * %0 @cache is not initialized + * * %1 @cache is initialized */ static int ll_xattr_cache_valid(struct ll_inode_info *lli) { @@ -245,10 +272,13 @@ static int ll_xattr_cache_valid(struct ll_inode_info *lli) } /** - * Check if the xattr cache is filled. + * ll_xattr_cache_filled() - Check if the xattr cache is filled. + * + * @lli: lustre ll_inode_info struct (list of xattrs) * - * \retval 0 @cache is not filled - * \retval 1 @cache is filled + * Returns: + * * %0 @cache is not filled + * * %1 @cache is filled */ static int ll_xattr_cache_filled(struct ll_inode_info *lli) { @@ -256,11 +286,14 @@ static int ll_xattr_cache_filled(struct ll_inode_info *lli) } /** - * This finalizes the xattr cache. + * ll_xattr_cache_destroy_locked() - This finalizes the xattr cache. + * + * @lli: lustre ll_inode_info struct (list of xattrs) * * Free all xattr memory. @lli is the inode info pointer. * - * \retval 0 no error occured + * Returns: + * * %0 no error occured */ static int ll_xattr_cache_destroy_locked(struct ll_inode_info *lli) { @@ -328,7 +361,11 @@ out_empty: } /** - * Match or enqueue a PR lock. + * ll_xattr_find_get_lock() - Match or enqueue a PR lock. + * + * @inode: Whose xattr is being accessed + * @oit: lookup_intent struct (info of lock request) + * @req: ptlrpc_request struct * * Find or request an LDLM lock with xattr data. * Since LDLM does not provide API for atomic match_or_enqueue, @@ -336,8 +373,9 @@ out_empty: * If successful, the function exits with a write lock held * on lli_xattrs_list_rwsem. * - * \retval 0 no error occured - * \retval -ENOMEM not enough memory + * Returns: + * * %0 no error occured + * * %-ENOMEM not enough memory */ static int ll_xattr_find_get_lock(struct inode *inode, struct lookup_intent *oit, @@ -400,15 +438,18 @@ out: } /** - * Refill the xattr cache. + * ll_xattr_cache_refill() - Refill the xattr cache. + * + * @inode: Whose xattr is being accessed * * Fetch and cache the whole of xattrs for @inode, thanks to the write lock * on lli_xattrs_list_rwsem obtained from ll_xattr_find_get_lock(). * If successful, this write lock is kept. * - * \retval 0 no error occured - * \retval -EPROTO network protocol error - * \retval -ENOMEM not enough memory for the cache + * Returns: + * * %0 no error occured + * * %-EPROTO network protocol error + * * %-ENOMEM not enough memory for the cache */ static int ll_xattr_cache_refill(struct inode *inode) { @@ -532,18 +573,26 @@ err_req: } /** - * Get an xattr value or list xattrs using the write-through cache. + * ll_xattr_cache_get() - Get an xattr value or list xattrs using the + * write-through cache. + * + * @inode: Whose xattr is being accessed + * @name: name of xattr to be get + * @buffer: buffer(space) to store xattrs + * @size: size of the @buffer + * @valid: Operations to be performed * * Get the xattr value (@valid has OBD_MD_FLXATTR set) of @name or * list xattr names (@valid has OBD_MD_FLXATTRLS set) for @inode. * The resulting value/list is stored in @buffer if the former * is not larger than @size. * - * \retval 0 no error occured - * \retval -EPROTO network protocol error - * \retval -ENOMEM not enough memory for the cache - * \retval -ERANGE the buffer is not large enough - * \retval -ENODATA no such attr or the list is empty + * Returns: + * * %0 no error occured + * * %-EPROTO network protocol error + * * %-ENOMEM not enough memory for the cache + * * %-ERANGE the buffer is not large enough + * * %-ENODATA no such attr or the list is empty */ int ll_xattr_cache_get(struct inode *inode, const char *name, @@ -623,13 +672,19 @@ out: } /** - * Insert an xattr value into the cache. + * ll_xattr_cache_insert() - Insert an xattr value into the cache. + * + * @inode: Whose xattr is being accessed + * @name: xattr name to be inserted + * @buffer: value to be inserted + * @size: size of the @buffer * * Add @name xattr with @buffer value and @size length for @inode. * Init cache for @inode if necessary. * - * \retval 0 success - * \retval < 0 from ll_xattr_cache_add(), except -EPROTO is ignored for + * Returns: + * * %0 success + * * <0 from ll_xattr_cache_add(), except -EPROTO is ignored for * LL_XATTR_NAME_ENCRYPTION_CONTEXT xattr */ int ll_xattr_cache_insert(struct inode *inode, diff --git a/lustre/llite/xattr_security.c b/lustre/llite/xattr_security.c index 73acdc0..fcc8c45 100644 --- a/lustre/llite/xattr_security.c +++ b/lustre/llite/xattr_security.c @@ -104,16 +104,21 @@ int ll_dentry_init_security(struct dentry *dentry, int mode, struct qstr *name, } /** - * A helper function for security_inode_init_security() + * ll_initxattrs() - A helper function for security_inode_init_security() * that takes care of setting xattrs * - * Get security context of @inode from @xattr_array, - * and put it in 'security.xxx' xattr of dentry - * stored in @fs_info. + * @inode: pointer to inode for which the security context is initialized + * @xattr_array: pointer to array of xattr structures, these structures are + * extended attribute to be set on the inode + * @fs_info: pointer to additional FS info (dentry linked with the inode) * - * \retval 0 success - * \retval -ENOMEM if no memory could be allocated for xattr name - * \retval < 0 failure to set xattr + * Get security context of @inode from @xattr_array, and put it in + * 'security.xxx' xattr of dentry stored in @fs_info. + * + * Returns: + * * %0 success + * * %-ENOMEM if no memory could be allocated for xattr name + * * <0 failure to set xattr */ static int ll_initxattrs(struct inode *inode, const struct xattr *xattr_array, @@ -143,14 +148,19 @@ ll_initxattrs(struct inode *inode, const struct xattr *xattr_array, } /** - * Initializes security context + * ll_inode_init_security() - Initializes security context + * + * @dentry: dentry linked with the inode + * @inode: pointer to inode for which the security context is initialized + * @dir: inode struct of the directory, in which new inode to be created * - * Get security context of @inode in @dir, - * and put it in 'security.xxx' xattr of @dentry. + * Get security context of @inode in @dir, and put it in 'security.xxx' + * xattr of @dentry. * - * \retval 0 success, or SELinux is disabled - * \retval -ENOMEM if no memory could be allocated for xattr name - * \retval < 0 failure to get security context or set xattr + * Return: + * * %0 success, or SELinux is disabled + * * %-ENOMEM if no memory could be allocated for xattr name + * * <0 failure to get security context or set xattr */ int ll_inode_init_security(struct dentry *dentry, struct inode *inode, @@ -170,12 +180,17 @@ ll_inode_init_security(struct dentry *dentry, struct inode *inode, } /** - * Notify security context to the security layer + * ll_inode_notifysecctx() - Notify security context to the security layer + * + * @inode: pointer to inode for which the security context is notifyed + * @secctx: security context that will be set into inode + * @secctxlen: security context length * * Notify security context @secctx of inode @inode to the security layer. * - * \retval 0 success, or SELinux is disabled or not supported by the fs - * \retval < 0 failure to set the security context + * Returns: + * * %0 success, or SELinux is disabled or not supported by the fs + * * <0 failure to set the security context */ int ll_inode_notifysecctx(struct inode *inode, void *secctx, __u32 secctxlen) @@ -200,7 +215,7 @@ int ll_inode_notifysecctx(struct inode *inode, return rc; } -/** +/* * Free the security context xattr name used by policy */ void ll_secctx_name_free(struct ll_sb_info *sbi) @@ -211,11 +226,15 @@ void ll_secctx_name_free(struct ll_sb_info *sbi) } /** - * Get security context xattr name used by policy and save it. + * ll_secctx_name_store() - Get security context xattr name used by policy and + * save it. + * + * @in: pointer to inode for which the security context is retrieved * - * \retval > 0 length of xattr name - * \retval == 0 no LSM module registered supporting security contexts - * \retval <= 0 failure to get xattr name or xattr is not supported + * Returns: + * * %0 no LSM module registered supporting security contexts + * * >0 length of xattr name + * * <=0 failure to get xattr name or xattr is not supported */ int ll_secctx_name_store(struct inode *in) { @@ -269,10 +288,15 @@ err_free: } /** - * Retrieved file security context xattr name stored. + * ll_secctx_name_get() - Retrieved file security context xattr name stored. * - * \retval security context xattr name size stored. - * \retval 0 no xattr name stored. + * @sbi: Lustre superblock information struct (FS specific info: secturity + * context) + * @secctx_name: Returned security context xattr on success + * + * Returns: + * * %secctx_name security context xattr name size stored. + * * %0 no xattr name stored. */ __u32 ll_secctx_name_get(struct ll_sb_info *sbi, const char **secctx_name) { @@ -285,14 +309,21 @@ __u32 ll_secctx_name_get(struct ll_sb_info *sbi, const char **secctx_name) } /** - * Filter out xattr file security context if not managed by LSM + * ll_security_secctx_name_filter() - Filter out xattr file security context + * if not managed by LSM + * + * @sbi: Lustre superblock information struct (FS specific info: secturity + * context) + * @xattr_type: type of xattr being processed. (security-related xattrs) + * @suffix: xattr string that follows XATTR_SECURITY_PREFIX ("security.") * * This is done to improve performance for application that blindly try to get * file context (like "ls -l" for security.linux). * See LU-549 for more information. * - * \retval 0 xattr not filtered - * \retval -EOPNOTSUPP no enabled LSM security module supports the xattr + * Returns: + * * %0 xattr not filtered + * * %-EOPNOTSUPP no enabled LSM security module supports the xattr */ int ll_security_secctx_name_filter(struct ll_sb_info *sbi, int xattr_type, const char *suffix) -- 1.8.3.1