Commit d2fe9754 authored by Eric Biggers's avatar Eric Biggers
Browse files

fscrypt: fix all kerneldoc warnings 

Fix all kerneldoc warnings in fs/crypto/ and include/linux/fscrypt.h.
Most of these were due to missing documentation for function parameters.

Detected with:

    scripts/kernel-doc -v -none fs/crypto/*.{c,h} include/linux/fscrypt.h

This cleanup makes it possible to check new patches for kerneldoc
warnings without having to filter out all the existing ones.

For consistency, also adjust some function "brief descriptions" to
include the parentheses and to wrap at 80 characters.  (The latter
matches the checkpatch expectation.)

Link: https://lore.kernel.org/r/20200511191358.53096-2-ebiggers@kernel.org


Signed-off-by: default avatarEric Biggers <ebiggers@google.com>
parent 2ef96a5b

fs/crypto/crypto.c

+7 −2
Original line number Diff line number Diff line
@@ -54,6 +54,7 @@ struct page *fscrypt_alloc_bounce_page(gfp_t gfp_flags) 


/**

 * fscrypt_free_bounce_page() - free a ciphertext bounce page

 * @bounce_page: the bounce page to free, or NULL

 *

 * Free a bounce page that was allocated by fscrypt_encrypt_pagecache_blocks(),

 * or by fscrypt_alloc_bounce_page() directly.
@@ -132,7 +133,8 @@ int fscrypt_crypt_block(const struct inode *inode, fscrypt_direction_t rw, 
}



/**

 * fscrypt_encrypt_pagecache_blocks() - Encrypt filesystem blocks from a pagecache page

 * fscrypt_encrypt_pagecache_blocks() - Encrypt filesystem blocks from a

 *					pagecache page

 * @page:      The locked pagecache page containing the block(s) to encrypt

 * @len:       Total size of the block(s) to encrypt.  Must be a nonzero

 *		multiple of the filesystem's block size.
@@ -222,7 +224,8 @@ int fscrypt_encrypt_block_inplace(const struct inode *inode, struct page *page, 
EXPORT_SYMBOL(fscrypt_encrypt_block_inplace);



/**

 * fscrypt_decrypt_pagecache_blocks() - Decrypt filesystem blocks in a pagecache page

 * fscrypt_decrypt_pagecache_blocks() - Decrypt filesystem blocks in a

 *					pagecache page

 * @page:      The locked pagecache page containing the block(s) to decrypt

 * @len:       Total size of the block(s) to decrypt.  Must be a nonzero

 *		multiple of the filesystem's block size.
@@ -346,6 +349,8 @@ void fscrypt_msg(const struct inode *inode, const char *level, 


/**

 * fscrypt_init() - Set up for fs encryption.

 *

 * Return: 0 on success; -errno on failure

 */

static int __init fscrypt_init(void)

{

fs/crypto/fname.c

+38 −14
Original line number Diff line number Diff line
@@ -18,7 +18,7 @@ 
#include <crypto/skcipher.h>

#include "fscrypt_private.h"



/**

/*

 * struct fscrypt_nokey_name - identifier for directory entry when key is absent

 *

 * When userspace lists an encrypted directory without access to the key, the
@@ -105,8 +105,11 @@ static inline bool fscrypt_is_dot_dotdot(const struct qstr *str) 


/**

 * fscrypt_fname_encrypt() - encrypt a filename

 *

 * The output buffer must be at least as large as the input buffer.

 * @inode: inode of the parent directory (for regular filenames)

 *	   or of the symlink (for symlink targets)

 * @iname: the filename to encrypt

 * @out: (output) the encrypted filename

 * @olen: size of the encrypted filename.  It must be at least @iname->len.

 *	  Any extra space is filled with NUL padding before encryption.

 *

 * Return: 0 on success, -errno on failure
@@ -157,8 +160,11 @@ int fscrypt_fname_encrypt(const struct inode *inode, const struct qstr *iname, 


/**

 * fname_decrypt() - decrypt a filename

 *

 * The caller must have allocated sufficient memory for the @oname string.

 * @inode: inode of the parent directory (for regular filenames)

 *	   or of the symlink (for symlink targets)

 * @iname: the encrypted filename to decrypt

 * @oname: (output) the decrypted filename.  The caller must have allocated

 *	   enough space for this, e.g. using fscrypt_fname_alloc_buffer().

 *

 * Return: 0 on success, -errno on failure

 */
@@ -206,7 +212,10 @@ static const char lookup_table[65] = 
#define BASE64_CHARS(nbytes)	DIV_ROUND_UP((nbytes) * 4, 3)



/**

 * base64_encode() -

 * base64_encode() - base64-encode some bytes

 * @src: the bytes to encode

 * @len: number of bytes to encode

 * @dst: (output) the base64-encoded string.  Not NUL-terminated.

 *

 * Encodes the input string using characters from the set [A-Za-z0-9+,].

 * The encoded string is roughly 4/3 times the size of the input string.
@@ -272,7 +281,12 @@ bool fscrypt_fname_encrypted_size(const struct inode *inode, u32 orig_len, 
}



/**

 * fscrypt_fname_alloc_buffer - allocate a buffer for presented filenames

 * fscrypt_fname_alloc_buffer() - allocate a buffer for presented filenames

 * @inode: inode of the parent directory (for regular filenames)

 *	   or of the symlink (for symlink targets)

 * @max_encrypted_len: maximum length of encrypted filenames the buffer will be

 *		       used to present

 * @crypto_str: (output) buffer to allocate

 *

 * Allocate a buffer that is large enough to hold any decrypted or encoded

 * filename (null-terminated), for the given maximum encrypted filename length.
@@ -297,9 +311,10 @@ int fscrypt_fname_alloc_buffer(const struct inode *inode, 
EXPORT_SYMBOL(fscrypt_fname_alloc_buffer);



/**

 * fscrypt_fname_free_buffer - free the buffer for presented filenames

 * fscrypt_fname_free_buffer() - free a buffer for presented filenames

 * @crypto_str: the buffer to free

 *

 * Free the buffer allocated by fscrypt_fname_alloc_buffer().

 * Free a buffer that was allocated by fscrypt_fname_alloc_buffer().

 */

void fscrypt_fname_free_buffer(struct fscrypt_str *crypto_str)

{
@@ -311,10 +326,19 @@ void fscrypt_fname_free_buffer(struct fscrypt_str *crypto_str) 
EXPORT_SYMBOL(fscrypt_fname_free_buffer);



/**

 * fscrypt_fname_disk_to_usr() - converts a filename from disk space to user

 * space

 *

 * The caller must have allocated sufficient memory for the @oname string.

 * fscrypt_fname_disk_to_usr() - convert an encrypted filename to

 *				 user-presentable form

 * @inode: inode of the parent directory (for regular filenames)

 *	   or of the symlink (for symlink targets)

 * @hash: first part of the name's dirhash, if applicable.  This only needs to

 *	  be provided if the filename is located in an indexed directory whose

 *	  encryption key may be unavailable.  Not needed for symlink targets.

 * @minor_hash: second part of the name's dirhash, if applicable

 * @iname: encrypted filename to convert.  May also be "." or "..", which

 *	   aren't actually encrypted.

 * @oname: output buffer for the user-presentable filename.  The caller must

 *	   have allocated enough space for this, e.g. using

 *	   fscrypt_fname_alloc_buffer().

 *

 * If the key is available, we'll decrypt the disk name.  Otherwise, we'll

 * encode it for presentation in fscrypt_nokey_name format.

fs/crypto/fscrypt_private.h

+2 −2
Original line number Diff line number Diff line
@@ -43,7 +43,7 @@ struct fscrypt_context_v2 { 
	u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];

};



/**

/*

 * fscrypt_context - the encryption context of an inode

 *

 * This is the on-disk equivalent of an fscrypt_policy, stored alongside each
@@ -157,7 +157,7 @@ fscrypt_policy_flags(const union fscrypt_policy *policy) 
	BUG();

}



/**

/*

 * For encrypted symlinks, the ciphertext length is stored at the beginning

 * of the string in little-endian format.

 */

fs/crypto/hooks.c

+2 −2
Original line number Diff line number Diff line
@@ -10,7 +10,7 @@ 
#include "fscrypt_private.h"



/**

 * fscrypt_file_open - prepare to open a possibly-encrypted regular file

 * fscrypt_file_open() - prepare to open a possibly-encrypted regular file

 * @inode: the inode being opened

 * @filp: the struct file being set up

 *
@@ -262,7 +262,7 @@ err_free_sd: 
EXPORT_SYMBOL_GPL(__fscrypt_encrypt_symlink);



/**

 * fscrypt_get_symlink - get the target of an encrypted symlink

 * fscrypt_get_symlink() - get the target of an encrypted symlink

 * @inode: the symlink inode

 * @caddr: the on-disk contents of the symlink

 * @max_size: size of @caddr buffer

fs/crypto/keysetup.c

+6 −3
Original line number Diff line number Diff line
@@ -475,7 +475,8 @@ out: 
EXPORT_SYMBOL(fscrypt_get_encryption_info);



/**

 * fscrypt_put_encryption_info - free most of an inode's fscrypt data

 * fscrypt_put_encryption_info() - free most of an inode's fscrypt data

 * @inode: an inode being evicted

 *

 * Free the inode's fscrypt_info.  Filesystems must call this when the inode is

 * being evicted.  An RCU grace period need not have elapsed yet.
@@ -488,7 +489,8 @@ void fscrypt_put_encryption_info(struct inode *inode) 
EXPORT_SYMBOL(fscrypt_put_encryption_info);



/**

 * fscrypt_free_inode - free an inode's fscrypt data requiring RCU delay

 * fscrypt_free_inode() - free an inode's fscrypt data requiring RCU delay

 * @inode: an inode being freed

 *

 * Free the inode's cached decrypted symlink target, if any.  Filesystems must

 * call this after an RCU grace period, just before they free the inode.
@@ -503,7 +505,8 @@ void fscrypt_free_inode(struct inode *inode) 
EXPORT_SYMBOL(fscrypt_free_inode);



/**

 * fscrypt_drop_inode - check whether the inode's master key has been removed

 * fscrypt_drop_inode() - check whether the inode's master key has been removed

 * @inode: an inode being considered for eviction

 *

 * Filesystems supporting fscrypt must call this from their ->drop_inode()

 * method so that encrypted inodes are evicted as soon as they're no longer in

CRA Git | Maintained and supported by SUSTech CRA and CCSE