Commit ee443996 authored by Eric Van Hensbergen's avatar Eric Van Hensbergen Committed by Eric Van Hensbergen

9p: Documentation updates

The kernel-doc comments of much of the 9p system have been in disarray since
reorganization.  This patch fixes those problems, adds additional documentation
and a template book which collects the 9p information.
Signed-off-by: default avatarEric Van Hensbergen <ericvh@gmail.com>
parent b32a09db
......@@ -22,6 +22,21 @@
#include <linux/list.h>
/**
* struct v9fs_dentry - 9p private data stored in dentry d_fsdata
* @lock: protects the fidlist
* @fidlist: list of FIDs currently associated with this dentry
*
* This structure defines the 9p private data associated with
* a particular dentry. In particular, this private data is used
* to lookup which 9P FID handle should be used for a particular VFS
* operation. FID handles are associated with dentries instead of
* inodes in order to more closely map functionality to the Plan 9
* expected behavior for FID reclaimation and tracking.
*
* See Also: Mapping FIDs to Linux VFS model in
* Design and Implementation of the Linux 9P File System documentation
*/
struct v9fs_dentry {
spinlock_t lock; /* protect fidlist */
struct list_head fidlist;
......
......@@ -71,7 +71,6 @@ static match_table_t tokens = {
/**
* v9fs_parse_options - parse mount options into session structure
* @options: options string passed from mount
* @v9ses: existing v9fs session information
*
*/
......@@ -256,9 +255,12 @@ void v9fs_session_close(struct v9fs_session_info *v9ses)
}
/**
* v9fs_session_cancel - mark transport as disconnected
* and cancel all pending requests.
* v9fs_session_cancel - terminate a session
* @v9ses: session to terminate
*
* mark transport as disconnected and cancel all pending requests.
*/
void v9fs_session_cancel(struct v9fs_session_info *v9ses) {
P9_DPRINTK(P9_DEBUG_ERROR, "cancel session %p\n", v9ses);
p9_client_disconnect(v9ses->clnt);
......
......@@ -21,18 +21,69 @@
*
*/
/*
* Session structure provides information for an opened session
*
*/
/**
* enum p9_session_flags - option flags for each 9P session
* @V9FS_EXTENDED: whether or not to use 9P2000.u extensions
* @V9FS_ACCESS_SINGLE: only the mounting user can access the hierarchy
* @V9FS_ACCESS_USER: a new attach will be issued for every user (default)
* @V9FS_ACCESS_ANY: use a single attach for all users
* @V9FS_ACCESS_MASK: bit mask of different ACCESS options
*
* Session flags reflect options selected by users at mount time
*/
enum p9_session_flags {
V9FS_EXTENDED = 0x01,
V9FS_ACCESS_SINGLE = 0x02,
V9FS_ACCESS_USER = 0x04,
V9FS_ACCESS_ANY = 0x06,
V9FS_ACCESS_MASK = 0x06,
};
/* possible values of ->cache */
/**
* enum p9_cache_modes - user specified cache preferences
* @CACHE_NONE: do not cache data, dentries, or directory contents (default)
* @CACHE_LOOSE: cache data, dentries, and directory contents w/no consistency
*
* eventually support loose, tight, time, session, default always none
*/
enum p9_cache_modes {
CACHE_NONE,
CACHE_LOOSE,
};
/**
* struct v9fs_session_info - per-instance session information
* @flags: session options of type &p9_session_flags
* @nodev: set to 1 to disable device mapping
* @debug: debug level
* @afid: authentication handle
* @cache: cache mode of type &p9_cache_modes
* @options: copy of options string given by user
* @uname: string user name to mount hierarchy as
* @aname: mount specifier for remote hierarchy
* @maxdata: maximum data to be sent/recvd per protocol message
* @dfltuid: default numeric userid to mount hierarchy as
* @dfltgid: default numeric groupid to mount hierarchy as
* @uid: if %V9FS_ACCESS_SINGLE, the numeric uid which mounted the hierarchy
* @clnt: reference to 9P network client instantiated for this session
* @debugfs_dir: reference to debugfs_dir which can be used for add'l debug
*
* This structure holds state for each session instance established during
* a sys_mount() .
*
* Bugs: there seems to be a lot of state which could be condensed and/or
* removed.
*/
struct v9fs_session_info {
/* options */
unsigned char flags; /* session flags */
unsigned char nodev; /* set to 1 if no disable device mapping */
unsigned short debug; /* debug level */
unsigned int afid; /* authentication fid */
unsigned int cache; /* cache mode */
unsigned char flags;
unsigned char nodev;
unsigned short debug;
unsigned int afid;
unsigned int cache;
char *options; /* copy of mount options */
char *uname; /* user name to mount as */
......@@ -45,22 +96,6 @@ struct v9fs_session_info {
struct dentry *debugfs_dir;
};
/* session flags */
enum {
V9FS_EXTENDED = 0x01, /* 9P2000.u */
V9FS_ACCESS_MASK = 0x06, /* access mask */
V9FS_ACCESS_SINGLE = 0x02, /* only one user can access the files */
V9FS_ACCESS_USER = 0x04, /* attache per user */
V9FS_ACCESS_ANY = 0x06, /* use the same attach for all users */
};
/* possible values of ->cache */
/* eventually support loose, tight, time, session, default always none */
enum {
CACHE_NONE, /* default */
CACHE_LOOSE, /* no consistency */
};
extern struct dentry *v9fs_debugfs_root;
struct p9_fid *v9fs_session_init(struct v9fs_session_info *, const char *,
......
......@@ -43,7 +43,7 @@
/**
* v9fs_vfs_readpage - read an entire page in from 9P
*
* @file: file being read
* @filp: file being read
* @page: structure to page
*
*/
......
......@@ -60,7 +60,7 @@ static inline int dt_type(struct p9_stat *mistat)
/**
* v9fs_dir_readdir - read a directory
* @filep: opened file structure
* @filp: opened file structure
* @dirent: directory structure ???
* @filldir: function to populate directory structure ???
*
......
......@@ -90,10 +90,11 @@ int v9fs_file_open(struct inode *inode, struct file *file)
/**
* v9fs_file_lock - lock a file (or directory)
* @inode: inode to be opened
* @file: file being opened
* @filp: file to be locked
* @cmd: lock command
* @fl: file lock structure
*
* XXX - this looks like a local only lock, we should extend into 9P
* Bugs: this looks like a local only lock, we should extend into 9P
* by using open exclusive
*/
......@@ -118,7 +119,7 @@ static int v9fs_file_lock(struct file *filp, int cmd, struct file_lock *fl)
/**
* v9fs_file_read - read from a file
* @filep: file pointer to read
* @filp: file pointer to read
* @data: data buffer to read data into
* @count: size of buffer
* @offset: offset at which to read data
......@@ -142,7 +143,7 @@ v9fs_file_read(struct file *filp, char __user * data, size_t count,
/**
* v9fs_file_write - write to a file
* @filep: file pointer to write
* @filp: file pointer to write
* @data: data buffer to write data from
* @count: size of buffer
* @offset: offset at which to write data
......
......@@ -129,6 +129,12 @@ static int p9mode2unixmode(struct v9fs_session_info *v9ses, int mode)
return res;
}
/**
* v9fs_uflags2omode- convert posix open flags to plan 9 mode bits
* @uflags: flags to convert
*
*/
int v9fs_uflags2omode(int uflags)
{
int ret;
......@@ -312,6 +318,14 @@ error:
}
*/
/**
* v9fs_inode_from_fid - populate an inode by issuing a attribute request
* @v9ses: session information
* @fid: fid to issue attribute request for
* @sb: superblock on which to create inode
*
*/
static struct inode *
v9fs_inode_from_fid(struct v9fs_session_info *v9ses, struct p9_fid *fid,
struct super_block *sb)
......@@ -384,9 +398,12 @@ v9fs_open_created(struct inode *inode, struct file *file)
/**
* v9fs_create - Create a file
* @v9ses: session information
* @dir: directory that dentry is being created in
* @dentry: dentry that is being created
* @perm: create permissions
* @mode: open mode
* @extension: 9p2000.u extension string to support devices, etc.
*
*/
static struct p9_fid *
......@@ -461,7 +478,7 @@ error:
/**
* v9fs_vfs_create - VFS hook to create files
* @inode: directory inode that is being created
* @dir: directory inode that is being created
* @dentry: dentry that is being deleted
* @mode: create permissions
* @nd: path information
......@@ -519,7 +536,7 @@ error:
/**
* v9fs_vfs_mkdir - VFS mkdir hook to create a directory
* @inode: inode that is being unlinked
* @dir: inode that is being unlinked
* @dentry: dentry that is being unlinked
* @mode: mode for new directory
*
......@@ -703,9 +720,9 @@ done:
/**
* v9fs_vfs_getattr - retrieve file metadata
* @mnt - mount information
* @dentry - file to get attributes on
* @stat - metadata structure to populate
* @mnt: mount information
* @dentry: file to get attributes on
* @stat: metadata structure to populate
*
*/
......@@ -928,7 +945,7 @@ done:
/**
* v9fs_vfs_readlink - read a symlink's location
* @dentry: dentry for symlink
* @buf: buffer to load symlink location into
* @buffer: buffer to load symlink location into
* @buflen: length of buffer
*
*/
......@@ -996,10 +1013,12 @@ static void *v9fs_vfs_follow_link(struct dentry *dentry, struct nameidata *nd)
* v9fs_vfs_put_link - release a symlink path
* @dentry: dentry for symlink
* @nd: nameidata
* @p: unused
*
*/
static void v9fs_vfs_put_link(struct dentry *dentry, struct nameidata *nd, void *p)
static void
v9fs_vfs_put_link(struct dentry *dentry, struct nameidata *nd, void *p)
{
char *s = nd_get_link(nd);
......@@ -1008,6 +1027,15 @@ static void v9fs_vfs_put_link(struct dentry *dentry, struct nameidata *nd, void
__putname(s);
}
/**
* v9fs_vfs_mkspecial - create a special file
* @dir: inode to create special file in
* @dentry: dentry to create
* @mode: mode to create special file
* @extension: 9p2000.u format extension string representing special file
*
*/
static int v9fs_vfs_mkspecial(struct inode *dir, struct dentry *dentry,
int mode, const char *extension)
{
......@@ -1037,7 +1065,7 @@ static int v9fs_vfs_mkspecial(struct inode *dir, struct dentry *dentry,
* @dentry: dentry for symlink
* @symname: symlink data
*
* See 9P2000.u RFC for more information
* See Also: 9P2000.u RFC for more information
*
*/
......@@ -1058,10 +1086,6 @@ v9fs_vfs_symlink(struct inode *dir, struct dentry *dentry, const char *symname)
*
*/
/* XXX - lots of code dup'd from symlink and creates,
* figure out a better reuse strategy
*/
static int
v9fs_vfs_link(struct dentry *old_dentry, struct inode *dir,
struct dentry *dentry)
......@@ -1098,7 +1122,7 @@ clunk_fid:
* @dir: inode destination for new link
* @dentry: dentry for file
* @mode: mode for creation
* @dev_t: device associated with special file
* @rdev: device associated with special file
*
*/
......
......@@ -75,6 +75,7 @@ static int v9fs_set_super(struct super_block *s, void *data)
* v9fs_fill_super - populate superblock with info
* @sb: superblock
* @v9ses: session information
* @flags: flags propagated from v9fs_get_sb()
*
*/
......
......@@ -29,14 +29,31 @@
#ifdef CONFIG_NET_9P_DEBUG
#define P9_DEBUG_ERROR (1<<0)
#define P9_DEBUG_9P (1<<2)
#define P9_DEBUG_VFS (1<<3)
#define P9_DEBUG_CONV (1<<4)
#define P9_DEBUG_MUX (1<<5)
#define P9_DEBUG_TRANS (1<<6)
#define P9_DEBUG_SLABS (1<<7)
#define P9_DEBUG_FCALL (1<<8)
/**
* enum p9_debug_flags - bits for mount time debug parameter
* @P9_DEBUG_ERROR: more verbose error messages including original error string
* @P9_DEBUG_9P: 9P protocol tracing
* @P9_DEBUG_VFS: VFS API tracing
* @P9_DEBUG_CONV: protocol conversion tracing
* @P9_DEBUG_MUX: trace management of concurrent transactions
* @P9_DEBUG_TRANS: transport tracing
* @P9_DEBUG_SLABS: memory management tracing
* @P9_DEBUG_FCALL: verbose dump of protocol messages
*
* These flags are passed at mount time to turn on various levels of
* verbosity and tracing which will be output to the system logs.
*/
enum p9_debug_flags {
P9_DEBUG_ERROR = (1<<0),
P9_DEBUG_9P = (1<<2),
P9_DEBUG_VFS = (1<<3),
P9_DEBUG_CONV = (1<<4),
P9_DEBUG_MUX = (1<<5),
P9_DEBUG_TRANS = (1<<6),
P9_DEBUG_SLABS = (1<<7),
P9_DEBUG_FCALL = (1<<8),
};
extern unsigned int p9_debug_level;
......@@ -62,9 +79,47 @@ do { \
format , __FUNCTION__, task_pid_nr(current), ## arg); \
} while (0)
/**
* enum p9_msg_t - 9P message types
* @P9_TVERSION: version handshake request
* @P9_RVERSION: version handshake response
* @P9_TAUTH: request to establish authentication channel
* @P9_RAUTH: response with authentication information
* @P9_TATTACH: establish user access to file service
* @P9_RATTACH: response with top level handle to file hierarchy
* @P9_TERROR: not used
* @P9_RERROR: response for any failed request
* @P9_TFLUSH: request to abort a previous request
* @P9_RFLUSH: response when previous request has been cancelled
* @P9_TWALK: descend a directory hierarchy
* @P9_RWALK: response with new handle for position within hierarchy
* @P9_TOPEN: prepare a handle for I/O on an existing file
* @P9_ROPEN: response with file access information
* @P9_TCREATE: prepare a handle for I/O on a new file
* @P9_RCREATE: response with file access information
* @P9_TREAD: request to transfer data from a file or directory
* @P9_RREAD: response with data requested
* @P9_TWRITE: reuqest to transfer data to a file
* @P9_RWRITE: response with out much data was transfered to file
* @P9_TCLUNK: forget about a handle to an entity within the file system
* @P9_RCLUNK: response when server has forgotten about the handle
* @P9_TREMOVE: request to remove an entity from the hierarchy
* @P9_RREMOVE: response when server has removed the entity
* @P9_TSTAT: request file entity attributes
* @P9_RSTAT: response with file entity attributes
* @P9_TWSTAT: request to update file entity attributes
* @P9_RWSTAT: response when file entity attributes are updated
*
* There are 14 basic operations in 9P2000, paired as
* requests and responses. The one special case is ERROR
* as there is no @P9_TERROR request for clients to transmit to
* the server, but the server may respond to any other request
* with an @P9_RERROR.
*
* See Also: http://plan9.bell-labs.com/sys/man/5/INDEX.html
*/
/* Message Types */
enum {
enum p9_msg_t {
P9_TVERSION = 100,
P9_RVERSION,
P9_TAUTH = 102,
......@@ -95,30 +150,71 @@ enum {
P9_RWSTAT,
};
/* open modes */
enum {
/**
* enum p9_open_mode_t - 9P open modes
* @P9_OREAD: open file for reading only
* @P9_OWRITE: open file for writing only
* @P9_ORDWR: open file for reading or writing
* @P9_OEXEC: open file for execution
* @P9_OTRUNC: truncate file to zero-length before opening it
* @P9_OREXEC: close the file when an exec(2) system call is made
* @P9_ORCLOSE: remove the file when the file is closed
* @P9_OAPPEND: open the file and seek to the end
* @P9_OEXCL: only create a file, do not open it
*
* 9P open modes differ slightly from Posix standard modes.
* In particular, there are extra modes which specify different
* semantic behaviors than may be available on standard Posix
* systems. For example, @P9_OREXEC and @P9_ORCLOSE are modes that
* most likely will not be issued from the Linux VFS client, but may
* be supported by servers.
*
* See Also: http://plan9.bell-labs.com/magic/man2html/2/open
*/
enum p9_open_mode_t {
P9_OREAD = 0x00,
P9_OWRITE = 0x01,
P9_ORDWR = 0x02,
P9_OEXEC = 0x03,
P9_OEXCL = 0x04,
P9_OTRUNC = 0x10,
P9_OREXEC = 0x20,
P9_ORCLOSE = 0x40,
P9_OAPPEND = 0x80,
};
/* permissions */
enum {
P9_OEXCL = 0x1000,
};
/**
* enum p9_perm_t - 9P permissions
* @P9_DMDIR: mode bite for directories
* @P9_DMAPPEND: mode bit for is append-only
* @P9_DMEXCL: mode bit for excluse use (only one open handle allowed)
* @P9_DMMOUNT: mode bite for mount points
* @P9_DMAUTH: mode bit for authentication file
* @P9_DMTMP: mode bit for non-backed-up files
* @P9_DMSYMLINK: mode bit for symbolic links (9P2000.u)
* @P9_DMLINK: mode bit for hard-link (9P2000.u)
* @P9_DMDEVICE: mode bit for device files (9P2000.u)
* @P9_DMNAMEDPIPE: mode bit for named pipe (9P2000.u)
* @P9_DMSOCKET: mode bit for socket (9P2000.u)
* @P9_DMSETUID: mode bit for setuid (9P2000.u)
* @P9_DMSETGID: mode bit for setgid (9P2000.u)
* @P9_DMSETVTX: mode bit for sticky bit (9P2000.u)
*
* 9P permissions differ slightly from Posix standard modes.
*
* See Also: http://plan9.bell-labs.com/magic/man2html/2/stat
*/
enum p9_perm_t {
P9_DMDIR = 0x80000000,
P9_DMAPPEND = 0x40000000,
P9_DMEXCL = 0x20000000,
P9_DMMOUNT = 0x10000000,
P9_DMAUTH = 0x08000000,
P9_DMTMP = 0x04000000,
/* 9P2000.u extensions */
P9_DMSYMLINK = 0x02000000,
P9_DMLINK = 0x01000000,
/* 9P2000.u extensions */
P9_DMDEVICE = 0x00800000,
P9_DMNAMEDPIPE = 0x00200000,
P9_DMSOCKET = 0x00100000,
......@@ -127,8 +223,26 @@ enum {
P9_DMSETVTX = 0x00010000,
};
/* qid.types */
enum {
/**
* enum p9_qid_t - QID types
* @P9_QTDIR: directory
* @P9_QTAPPEND: append-only
* @P9_QTEXCL: excluse use (only one open handle allowed)
* @P9_QTMOUNT: mount points
* @P9_QTAUTH: authentication file
* @P9_QTTMP: non-backed-up files
* @P9_QTSYMLINK: symbolic links (9P2000.u)
* @P9_QTLINK: hard-link (9P2000.u)
* @P9_QTFILE: normal files
*
* QID types are a subset of permissions - they are primarily
* used to differentiate semantics for a file system entity via
* a jump-table. Their value is also the most signifigant 16 bits
* of the permission_t
*
* See Also: http://plan9.bell-labs.com/magic/man2html/2/stat
*/
enum p9_qid_t {
P9_QTDIR = 0x80,
P9_QTAPPEND = 0x40,
P9_QTEXCL = 0x20,
......@@ -140,6 +254,7 @@ enum {
P9_QTFILE = 0x00,
};
/* 9P Magic Numbers */
#define P9_NOTAG (u16)(~0)
#define P9_NOFID (u32)(~0)
#define P9_MAXWELEM 16
......@@ -147,19 +262,69 @@ enum {
/* ample room for Twrite/Rread header */
#define P9_IOHDRSZ 24
/**
* struct p9_str - length prefixed string type
* @len: length of the string
* @str: the string
*
* The protocol uses length prefixed strings for all
* string data, so we replicate that for our internal
* string members.
*/
struct p9_str {
u16 len;
char *str;
};
/* qids are the unique ID for a file (like an inode */
/**
* struct p9_qid - file system entity information
* @type: 8-bit type &p9_qid_t
* @version: 16-bit monotonically incrementing version number
* @path: 64-bit per-server-unique ID for a file system element
*
* qids are identifiers used by 9P servers to track file system
* entities. The type is used to differentiate semantics for operations
* on the entity (ie. read means something different on a directory than
* on a file). The path provides a server unique index for an entity
* (roughly analogous to an inode number), while the version is updated
* every time a file is modified and can be used to maintain cache
* coherency between clients and serves.
* Servers will often differentiate purely synthetic entities by setting
* their version to 0, signaling that they should never be cached and
* should be accessed synchronously.
*
* See Also://plan9.bell-labs.com/magic/man2html/2/stat
*/
struct p9_qid {
u8 type;
u32 version;
u64 path;
};
/* Plan 9 file metadata (stat) structure */
/**
* struct p9_stat - file system metadata information
* @size: length prefix for this stat structure instance
* @type: the type of the server (equivilent to a major number)
* @dev: the sub-type of the server (equivilent to a minor number)
* @qid: unique id from the server of type &p9_qid
* @mode: Plan 9 format permissions of type &p9_perm_t
* @atime: Last access/read time
* @mtime: Last modify/write time
* @length: file length
* @name: last element of path (aka filename) in type &p9_str
* @uid: owner name in type &p9_str
* @gid: group owner in type &p9_str
* @muid: last modifier in type &p9_str
* @extension: area used to encode extended UNIX support in type &p9_str
* @n_uid: numeric user id of owner (part of 9p2000.u extension)
* @n_gid: numeric group id (part of 9p2000.u extension)
* @n_muid: numeric user id of laster modifier (part of 9p2000.u extension)
*
* See Also: http://plan9.bell-labs.com/magic/man2html/2/stat
*/
struct p9_stat {
u16 size;
u16 type;
......@@ -179,10 +344,14 @@ struct p9_stat {
u32 n_muid; /* 9p2000.u extensions */
};
/* file metadata (stat) structure used to create Twstat message
The is similar to p9_stat, but the strings don't point to
the same memory block and should be freed separately
*/
/*
* file metadata (stat) structure used to create Twstat message
* The is identical to &p9_stat, but the strings don't point to
* the same memory block and should be freed separately
*
* See Also: http://plan9.bell-labs.com/magic/man2html/2/stat
*/
struct p9_wstat {
u16 size;
u16 type;
......@@ -335,10 +504,20 @@ struct p9_twstat {
struct p9_rwstat {
};
/*
* fcall is the primary packet structure
*
*/
/**
* struct p9_fcall - primary packet structure
* @size: prefixed length of the structure
* @id: protocol operating identifier of type &p9_msg_t
* @tag: transaction id of the request
* @sdata: payload