fscrypt: document struct fscrypt_operations

#define FSCRYPT_SET_CONTEXT_MAX_SIZE	40

#ifdef CONFIG_FS_ENCRYPTION

/*

 * fscrypt superblock flags

 * If set, the fscrypt bounce page pool won't be allocated (unless another

 * filesystem needs it).  Set this if the filesystem always uses its own bounce

 * pages for writes and therefore won't need the fscrypt bounce page pool.

 */

#define FS_CFLG_OWN_PAGES (1U << 1)

/*

 * crypto operations for filesystems

 */

/* Crypto operations for filesystems */

struct fscrypt_operations {

	/* Set of optional flags; see above for allowed flags */

	unsigned int flags;

	/*

	 * If set, this is a filesystem-specific key description prefix that

	 * will be accepted for "logon" keys for v1 fscrypt policies, in

	 * addition to the generic prefix "fscrypt:".  This functionality is

	 * deprecated, so new filesystems shouldn't set this field.

	 */

	const char *key_prefix;

	/*

	 * Get the fscrypt context of the given inode.

	 *

	 * @inode: the inode whose context to get

	 * @ctx: the buffer into which to get the context

	 * @len: length of the @ctx buffer in bytes

	 *

	 * Return: On success, returns the length of the context in bytes; this

	 *	   may be less than @len.  On failure, returns -ENODATA if the

	 *	   inode doesn't have a context, -ERANGE if the context is

	 *	   longer than @len, or another -errno code.

	 */

	int (*get_context)(struct inode *inode, void *ctx, size_t len);

	/*

	 * Set an fscrypt context on the given inode.

	 *

	 * @inode: the inode whose context to set.  The inode won't already have

	 *	   an fscrypt context.

	 * @ctx: the context to set

	 * @len: length of @ctx in bytes (at most FSCRYPT_SET_CONTEXT_MAX_SIZE)

	 * @fs_data: If called from fscrypt_set_context(), this will be the

	 *	     value the filesystem passed to fscrypt_set_context().

	 *	     Otherwise (i.e. when called from

	 *	     FS_IOC_SET_ENCRYPTION_POLICY) this will be NULL.

	 *

	 * i_rwsem will be held for write.

	 *

	 * Return: 0 on success, -errno on failure.

	 */

	int (*set_context)(struct inode *inode, const void *ctx, size_t len,

			   void *fs_data);

	/*

	 * Get the dummy fscrypt policy in use on the filesystem (if any).

	 *

	 * Filesystems only need to implement this function if they support the

	 * test_dummy_encryption mount option.

	 *

	 * Return: A pointer to the dummy fscrypt policy, if the filesystem is

	 *	   mounted with test_dummy_encryption; otherwise NULL.

	 */

	const union fscrypt_policy *(*get_dummy_policy)(struct super_block *sb);

	/*

	 * Check whether a directory is empty.  i_rwsem will be held for write.

	 */

	bool (*empty_dir)(struct inode *inode);

	/* The filesystem's maximum ciphertext filename length, in bytes */

	unsigned int max_namelen;

	/*

	 * Check whether the filesystem's inode numbers and UUID are stable,

	 * meaning that they will never be changed even by offline operations

	 * such as filesystem shrinking and therefore can be used in the

	 * encryption without the possibility of files becoming unreadable.

	 *

	 * Filesystems only need to implement this function if they want to

	 * support the FSCRYPT_POLICY_FLAG_IV_INO_LBLK_{32,64} flags.  These

	 * flags are designed to work around the limitations of UFS and eMMC

	 * inline crypto hardware, and they shouldn't be used in scenarios where

	 * such hardware isn't being used.

	 *

	 * Leaving this NULL is equivalent to always returning false.

	 */

	bool (*has_stable_inodes)(struct super_block *sb);

	/*

	 * Get the number of bits that the filesystem uses to represent inode

	 * numbers and file logical block numbers.

	 *

	 * By default, both of these are assumed to be 64-bit.  This function

	 * can be implemented to declare that either or both of these numbers is

	 * shorter, which may allow the use of the

	 * FSCRYPT_POLICY_FLAG_IV_INO_LBLK_{32,64} flags and/or the use of

	 * inline crypto hardware whose maximum DUN length is less than 64 bits

	 * (e.g., eMMC v5.2 spec compliant hardware).  This function only needs

	 * to be implemented if support for one of these features is needed.

	 */

	void (*get_ino_and_lblk_bits)(struct super_block *sb,

				      int *ino_bits_ret, int *lblk_bits_ret);

	/*

	 * Return the number of block devices to which the filesystem may write

	 * encrypted file contents.

	 *

	 * If the filesystem can use multiple block devices (other than block

	 * devices that aren't used for encrypted file contents, such as

	 * external journal devices), and wants to support inline encryption,

	 * then it must implement this function.  Otherwise it's not needed.

	 */

	int (*get_num_devices)(struct super_block *sb);

	/*

	 * If ->get_num_devices() returns a value greater than 1, then this

	 * function is called to get the array of request_queues that the

	 * filesystem is using -- one per block device.  (There may be duplicate

	 * entries in this array, as block devices can share a request_queue.)

	 */

	void (*get_devices)(struct super_block *sb,

			    struct request_queue **devs);

};