nilfs2: add comments for ioctls

Add comments for ioctls in fs/nilfs2/ioctl.c file and describe NILFS2
specific ioctls in Documentation/filesystems/nilfs2.txt.

Signed-off-by: Vyacheslav Dubeyko <[email protected]>
Reviewed-by: Ryusuke Konishi <[email protected]>
Cc: Wenliang Fan <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>
This commit is contained in:
Vyacheslav Dubeyko 2014-01-23 15:55:23 -08:00 • committed by Linus Torvalds
commit d623a9420c
2 changed files with 418 additions and 1 deletions

View file

@ -37,7 +37,26 @@
#include "sufile.h"
#include "dat.h"
/**
* nilfs_ioctl_wrap_copy - wrapping function of get/set metadata info
* @nilfs: nilfs object
* @argv: vector of arguments from userspace
* @dir: set of direction flags
* @dofunc: concrete function of get/set metadata info
*
* Description: nilfs_ioctl_wrap_copy() gets/sets metadata info by means of
* calling dofunc() function on the basis of @argv argument.
*
* Return Value: On success, 0 is returned and requested metadata info
* is copied into userspace. On error, one of the following
* negative error codes is returned.
*
* %-EINVAL - Invalid arguments from userspace.
*
* %-ENOMEM - Insufficient amount of memory available.
*
* %-EFAULT - Failure during execution of requested operation.
*/
static int nilfs_ioctl_wrap_copy(struct the_nilfs *nilfs,
struct nilfs_argv *argv, int dir,
ssize_t (*dofunc)(struct the_nilfs *,
@ -107,6 +126,9 @@ static int nilfs_ioctl_wrap_copy(struct the_nilfs *nilfs,
return ret;
}
/**
* nilfs_ioctl_getflags - ioctl to support lsattr
*/
static int nilfs_ioctl_getflags(struct inode *inode, void __user *argp)
{
unsigned int flags = NILFS_I(inode)->i_flags & FS_FL_USER_VISIBLE;
@ -114,6 +136,9 @@ static int nilfs_ioctl_getflags(struct inode *inode, void __user *argp)
return put_user(flags, (int __user *)argp);
}
/**
* nilfs_ioctl_setflags - ioctl to support chattr
*/
static int nilfs_ioctl_setflags(struct inode *inode, struct file *filp,
void __user *argp)
{
@ -166,11 +191,33 @@ out:
return ret;
}
/**
* nilfs_ioctl_getversion - get info about a file's version (generation number)
*/
static int nilfs_ioctl_getversion(struct inode *inode, void __user *argp)
{
return put_user(inode->i_generation, (int __user *)argp);
}
/**
* nilfs_ioctl_change_cpmode - change checkpoint mode (checkpoint/snapshot)
* @inode: inode object
* @filp: file object
* @cmd: ioctl's request code
* @argp: pointer on argument from userspace
*
* Description: nilfs_ioctl_change_cpmode() function changes mode of
* given checkpoint between checkpoint and snapshot state. This ioctl
* is used in chcp and mkcp utilities.
*
* Return Value: On success, 0 is returned and mode of a checkpoint is
* changed. On error, one of the following negative error codes
* is returned.
*
* %-EPERM - Operation not permitted.
*
* %-EFAULT - Failure during checkpoint mode changing.
*/
static int nilfs_ioctl_change_cpmode(struct inode *inode, struct file *filp,
unsigned int cmd, void __user *argp)
{
@ -206,6 +253,25 @@ out:
return ret;
}
/**
* nilfs_ioctl_delete_checkpoint - remove checkpoint
* @inode: inode object
* @filp: file object
* @cmd: ioctl's request code
* @argp: pointer on argument from userspace
*
* Description: nilfs_ioctl_delete_checkpoint() function removes
* checkpoint from NILFS2 file system. This ioctl is used in rmcp
* utility.
*
* Return Value: On success, 0 is returned and a checkpoint is
* removed. On error, one of the following negative error codes
* is returned.
*
* %-EPERM - Operation not permitted.
*
* %-EFAULT - Failure during checkpoint removing.
*/
static int
nilfs_ioctl_delete_checkpoint(struct inode *inode, struct file *filp,
unsigned int cmd, void __user *argp)
@ -237,6 +303,21 @@ out:
return ret;
}
/**
* nilfs_ioctl_do_get_cpinfo - callback method getting info about checkpoints
* @nilfs: nilfs object
* @posp: pointer on array of checkpoint's numbers
* @flags: checkpoint mode (checkpoint or snapshot)
* @buf: buffer for storing checkponts' info
* @size: size in bytes of one checkpoint info item in array
* @nmembs: number of checkpoints in array (numbers and infos)
*
* Description: nilfs_ioctl_do_get_cpinfo() function returns info about
* requested checkpoints. The NILFS_IOCTL_GET_CPINFO ioctl is used in
* lscp utility and by nilfs_cleanerd daemon.
*
* Return value: count of nilfs_cpinfo structures in output buffer.
*/
static ssize_t
nilfs_ioctl_do_get_cpinfo(struct the_nilfs *nilfs, __u64 *posp, int flags,
void *buf, size_t size, size_t nmembs)
@ -250,6 +331,27 @@ nilfs_ioctl_do_get_cpinfo(struct the_nilfs *nilfs, __u64 *posp, int flags,
return ret;
}
/**
* nilfs_ioctl_get_cpstat - get checkpoints statistics
* @inode: inode object
* @filp: file object
* @cmd: ioctl's request code
* @argp: pointer on argument from userspace
*
* Description: nilfs_ioctl_get_cpstat() returns information about checkpoints.
* The NILFS_IOCTL_GET_CPSTAT ioctl is used by lscp, rmcp utilities
* and by nilfs_cleanerd daemon.
*
* Return Value: On success, 0 is returned, and checkpoints information is
* copied into userspace pointer @argp. On error, one of the following
* negative error codes is returned.
*
* %-EIO - I/O error.
*
* %-ENOMEM - Insufficient amount of memory available.
*
* %-EFAULT - Failure during getting checkpoints statistics.
*/
static int nilfs_ioctl_get_cpstat(struct inode *inode, struct file *filp,
unsigned int cmd, void __user *argp)
{
@ -268,6 +370,21 @@ static int nilfs_ioctl_get_cpstat(struct inode *inode, struct file *filp,
return ret;
}
/**
* nilfs_ioctl_do_get_suinfo - callback method getting segment usage info
* @nilfs: nilfs object
* @posp: pointer on array of segment numbers
* @flags: *not used*
* @buf: buffer for storing suinfo array
* @size: size in bytes of one suinfo item in array
* @nmembs: count of segment numbers and suinfos in array
*
* Description: nilfs_ioctl_do_get_suinfo() function returns segment usage
* info about requested segments. The NILFS_IOCTL_GET_SUINFO ioctl is used
* in lssu, nilfs_resize utilities and by nilfs_cleanerd daemon.
*
* Return value: count of nilfs_suinfo structures in output buffer.
*/
static ssize_t
nilfs_ioctl_do_get_suinfo(struct the_nilfs *nilfs, __u64 *posp, int flags,
void *buf, size_t size, size_t nmembs)
@ -281,6 +398,27 @@ nilfs_ioctl_do_get_suinfo(struct the_nilfs *nilfs, __u64 *posp, int flags,
return ret;
}
/**
* nilfs_ioctl_get_sustat - get segment usage statistics
* @inode: inode object
* @filp: file object
* @cmd: ioctl's request code
* @argp: pointer on argument from userspace
*
* Description: nilfs_ioctl_get_sustat() returns segment usage statistics.
* The NILFS_IOCTL_GET_SUSTAT ioctl is used in lssu, nilfs_resize utilities
* and by nilfs_cleanerd daemon.
*
* Return Value: On success, 0 is returned, and segment usage information is
* copied into userspace pointer @argp. On error, one of the following
* negative error codes is returned.
*
* %-EIO - I/O error.
*
* %-ENOMEM - Insufficient amount of memory available.
*
* %-EFAULT - Failure during getting segment usage statistics.
*/
static int nilfs_ioctl_get_sustat(struct inode *inode, struct file *filp,
unsigned int cmd, void __user *argp)
{
@ -299,6 +437,21 @@ static int nilfs_ioctl_get_sustat(struct inode *inode, struct file *filp,
return ret;
}
/**
* nilfs_ioctl_do_get_vinfo - callback method getting virtual blocks info
* @nilfs: nilfs object
* @posp: *not used*
* @flags: *not used*
* @buf: buffer for storing array of nilfs_vinfo structures
* @size: size in bytes of one vinfo item in array
* @nmembs: count of vinfos in array
*
* Description: nilfs_ioctl_do_get_vinfo() function returns information
* on virtual block addresses. The NILFS_IOCTL_GET_VINFO ioctl is used
* by nilfs_cleanerd daemon.
*
* Return value: count of nilfs_vinfo structures in output buffer.
*/
static ssize_t
nilfs_ioctl_do_get_vinfo(struct the_nilfs *nilfs, __u64 *posp, int flags,
void *buf, size_t size, size_t nmembs)
@ -311,6 +464,21 @@ nilfs_ioctl_do_get_vinfo(struct the_nilfs *nilfs, __u64 *posp, int flags,
return ret;
}
/**
* nilfs_ioctl_do_get_bdescs - callback method getting disk block descriptors
* @nilfs: nilfs object
* @posp: *not used*
* @flags: *not used*
* @buf: buffer for storing array of nilfs_bdesc structures
* @size: size in bytes of one bdesc item in array
* @nmembs: count of bdescs in array
*
* Description: nilfs_ioctl_do_get_bdescs() function returns information
* about descriptors of disk block numbers. The NILFS_IOCTL_GET_BDESCS ioctl
* is used by nilfs_cleanerd daemon.
*
* Return value: count of nilfs_bdescs structures in output buffer.
*/
static ssize_t
nilfs_ioctl_do_get_bdescs(struct the_nilfs *nilfs, __u64 *posp, int flags,
void *buf, size_t size, size_t nmembs)
@ -337,6 +505,29 @@ nilfs_ioctl_do_get_bdescs(struct the_nilfs *nilfs, __u64 *posp, int flags,
return nmembs;
}
/**
* nilfs_ioctl_get_bdescs - get disk block descriptors
* @inode: inode object
* @filp: file object
* @cmd: ioctl's request code
* @argp: pointer on argument from userspace
*
* Description: nilfs_ioctl_do_get_bdescs() function returns information
* about descriptors of disk block numbers. The NILFS_IOCTL_GET_BDESCS ioctl
* is used by nilfs_cleanerd daemon.
*
* Return Value: On success, 0 is returned, and disk block descriptors are
* copied into userspace pointer @argp. On error, one of the following
* negative error codes is returned.
*
* %-EINVAL - Invalid arguments from userspace.
*
* %-EIO - I/O error.
*
* %-ENOMEM - Insufficient amount of memory available.
*
* %-EFAULT - Failure during getting disk block descriptors.
*/
static int nilfs_ioctl_get_bdescs(struct inode *inode, struct file *filp,
unsigned int cmd, void __user *argp)
{
@ -360,6 +551,26 @@ static int nilfs_ioctl_get_bdescs(struct inode *inode, struct file *filp,
return ret;
}
/**
* nilfs_ioctl_move_inode_block - prepare data/node block for moving by GC
* @inode: inode object
* @vdesc: descriptor of virtual block number
* @buffers: list of moving buffers
*
* Description: nilfs_ioctl_move_inode_block() function registers data/node
* buffer in the GC pagecache and submit read request.
*
* Return Value: On success, 0 is returned. On error, one of the following
* negative error codes is returned.
*
* %-EIO - I/O error.
*
* %-ENOMEM - Insufficient amount of memory available.
*
* %-ENOENT - Requested block doesn't exist.
*
* %-EEXIST - Blocks conflict is detected.
*/
static int nilfs_ioctl_move_inode_block(struct inode *inode,
struct nilfs_vdesc *vdesc,
struct list_head *buffers)
@ -405,6 +616,19 @@ static int nilfs_ioctl_move_inode_block(struct inode *inode,
return 0;
}
/**
* nilfs_ioctl_move_blocks - move valid inode's blocks during garbage collection
* @sb: superblock object
* @argv: vector of arguments from userspace
* @buf: array of nilfs_vdesc structures
*
* Description: nilfs_ioctl_move_blocks() function reads valid data/node
* blocks that garbage collector specified with the array of nilfs_vdesc
* structures and stores them into page caches of GC inodes.
*
* Return Value: Number of processed nilfs_vdesc structures or
* error code, otherwise.
*/
static int nilfs_ioctl_move_blocks(struct super_block *sb,
struct nilfs_argv *argv, void *buf)
{
@ -470,6 +694,25 @@ static int nilfs_ioctl_move_blocks(struct super_block *sb,
return ret;
}
/**
* nilfs_ioctl_delete_checkpoints - delete checkpoints
* @nilfs: nilfs object
* @argv: vector of arguments from userspace
* @buf: array of periods of checkpoints numbers
*
* Description: nilfs_ioctl_delete_checkpoints() function deletes checkpoints
* in the period from p_start to p_end, excluding p_end itself. The checkpoints
* which have been already deleted are ignored.
*
* Return Value: Number of processed nilfs_period structures or
* error code, otherwise.
*
* %-EIO - I/O error.
*
* %-ENOMEM - Insufficient amount of memory available.
*
* %-EINVAL - invalid checkpoints.
*/
static int nilfs_ioctl_delete_checkpoints(struct the_nilfs *nilfs,
struct nilfs_argv *argv, void *buf)
{
@ -487,6 +730,24 @@ static int nilfs_ioctl_delete_checkpoints(struct the_nilfs *nilfs,
return nmembs;
}
/**
* nilfs_ioctl_free_vblocknrs - free virtual block numbers
* @nilfs: nilfs object
* @argv: vector of arguments from userspace
* @buf: array of virtual block numbers
*
* Description: nilfs_ioctl_free_vblocknrs() function frees
* the virtual block numbers specified by @buf and @argv->v_nmembs.
*
* Return Value: Number of processed virtual block numbers or
* error code, otherwise.
*
* %-EIO - I/O error.
*
* %-ENOMEM - Insufficient amount of memory available.
*
* %-ENOENT - The virtual block number have not been allocated.
*/
static int nilfs_ioctl_free_vblocknrs(struct the_nilfs *nilfs,
struct nilfs_argv *argv, void *buf)
{
@ -498,6 +759,24 @@ static int nilfs_ioctl_free_vblocknrs(struct the_nilfs *nilfs,
return (ret < 0) ? ret : nmembs;
}
/**
* nilfs_ioctl_mark_blocks_dirty - mark blocks dirty
* @nilfs: nilfs object
* @argv: vector of arguments from userspace
* @buf: array of block descriptors
*
* Description: nilfs_ioctl_mark_blocks_dirty() function marks
* metadata file or data blocks as dirty.
*
* Return Value: Number of processed block descriptors or
* error code, otherwise.
*
* %-ENOMEM - Insufficient memory available.
*
* %-EIO - I/O error
*
* %-ENOENT - the specified block does not exist (hole block)
*/
static int nilfs_ioctl_mark_blocks_dirty(struct the_nilfs *nilfs,
struct nilfs_argv *argv, void *buf)
{
@ -579,6 +858,20 @@ int nilfs_ioctl_prepare_clean_segments(struct the_nilfs *nilfs,
return ret;
}
/**
* nilfs_ioctl_clean_segments - clean segments
* @inode: inode object
* @filp: file object
* @cmd: ioctl's request code
* @argp: pointer on argument from userspace
*
* Description: nilfs_ioctl_clean_segments() function makes garbage
* collection operation in the environment of requested parameters
* from userspace. The NILFS_IOCTL_CLEAN_SEGMENTS ioctl is used by
* nilfs_cleanerd daemon.
*
* Return Value: On success, 0 is returned or error code, otherwise.
*/
static int nilfs_ioctl_clean_segments(struct inode *inode, struct file *filp,
unsigned int cmd, void __user *argp)
{
@ -690,6 +983,33 @@ out:
return ret;
}
/**
* nilfs_ioctl_sync - make a checkpoint
* @inode: inode object
* @filp: file object
* @cmd: ioctl's request code
* @argp: pointer on argument from userspace
*
* Description: nilfs_ioctl_sync() function constructs a logical segment
* for checkpointing. This function guarantees that all modified data
* and metadata are written out to the device when it successfully
* returned.
*
* Return Value: On success, 0 is retured. On errors, one of the following
* negative error code is returned.
*
* %-EROFS - Read only filesystem.
*
* %-EIO - I/O error
*
* %-ENOSPC - No space left on device (only in a panic state).
*
* %-ERESTARTSYS - Interrupted.
*
* %-ENOMEM - Insufficient memory available.
*
* %-EFAULT - Failure during execution of requested operation.
*/
static int nilfs_ioctl_sync(struct inode *inode, struct file *filp,
unsigned int cmd, void __user *argp)
{
@ -718,6 +1038,14 @@ static int nilfs_ioctl_sync(struct inode *inode, struct file *filp,
return 0;
}
/**
* nilfs_ioctl_resize - resize NILFS2 volume
* @inode: inode object
* @filp: file object
* @argp: pointer on argument from userspace
*
* Return Value: On success, 0 is returned or error code, otherwise.
*/
static int nilfs_ioctl_resize(struct inode *inode, struct file *filp,
void __user *argp)
{
@ -743,6 +1071,17 @@ out:
return ret;
}
/**
* nilfs_ioctl_set_alloc_range - limit range of segments to be allocated
* @inode: inode object
* @argp: pointer on argument from userspace
*
* Decription: nilfs_ioctl_set_alloc_range() function defines lower limit
* of segments in bytes and upper limit of segments in bytes.
* The NILFS_IOCTL_SET_ALLOC_RANGE is used by nilfs_resize utility.
*
* Return Value: On success, 0 is returned or error code, otherwise.
*/
static int nilfs_ioctl_set_alloc_range(struct inode *inode, void __user *argp)
{
struct the_nilfs *nilfs = inode->i_sb->s_fs_info;
@ -775,6 +1114,28 @@ out:
return ret;
}
/**
* nilfs_ioctl_get_info - wrapping function of get metadata info
* @inode: inode object
* @filp: file object
* @cmd: ioctl's request code
* @argp: pointer on argument from userspace
* @membsz: size of an item in bytes
* @dofunc: concrete function of getting metadata info
*
* Description: nilfs_ioctl_get_info() gets metadata info by means of
* calling dofunc() function.
*
* Return Value: On success, 0 is returned and requested metadata info
* is copied into userspace. On error, one of the following
* negative error codes is returned.
*
* %-EINVAL - Invalid arguments from userspace.
*
* %-ENOMEM - Insufficient amount of memory available.
*
* %-EFAULT - Failure during execution of requested operation.
*/
static int nilfs_ioctl_get_info(struct inode *inode, struct file *filp,
unsigned int cmd, void __user *argp,
size_t membsz,