aboutsummaryrefslogtreecommitdiffstats
path: root/include/net/9p
diff options
context:
space:
mode:
authorEric Van Hensbergen <ericvh@ericvh-desktop.(none)>2008-03-05 08:08:09 -0500
committerEric Van Hensbergen <ericvh@opteron.9grid.us>2008-05-14 20:23:25 -0400
commitee443996a35c1e04f210cafd43d5a98d41e46085 (patch)
tree58ee72b69a02d9dbb3a98e402a4561baba0eb9a8 /include/net/9p
parentb32a09db4fb9a87246ba4e7726a979ac4709ad97 (diff)
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: Eric Van Hensbergen <ericvh@gmail.com>
Diffstat (limited to 'include/net/9p')
-rw-r--r--include/net/9p/9p.h239
-rw-r--r--include/net/9p/client.h35
-rw-r--r--include/net/9p/transport.h43
3 files changed, 287 insertions, 30 deletions
diff --git a/include/net/9p/9p.h b/include/net/9p/9p.h
index 585eb4496990..7bfb2f2e423c 100644
--- a/include/net/9p/9p.h
+++ b/include/net/9p/9p.h
@@ -29,14 +29,31 @@
29 29
30#ifdef CONFIG_NET_9P_DEBUG 30#ifdef CONFIG_NET_9P_DEBUG
31 31
32#define P9_DEBUG_ERROR (1<<0) 32/**
33#define P9_DEBUG_9P (1<<2) 33 * enum p9_debug_flags - bits for mount time debug parameter
34#define P9_DEBUG_VFS (1<<3) 34 * @P9_DEBUG_ERROR: more verbose error messages including original error string
35#define P9_DEBUG_CONV (1<<4) 35 * @P9_DEBUG_9P: 9P protocol tracing
36#define P9_DEBUG_MUX (1<<5) 36 * @P9_DEBUG_VFS: VFS API tracing
37#define P9_DEBUG_TRANS (1<<6) 37 * @P9_DEBUG_CONV: protocol conversion tracing
38#define P9_DEBUG_SLABS (1<<7) 38 * @P9_DEBUG_MUX: trace management of concurrent transactions
39#define P9_DEBUG_FCALL (1<<8) 39 * @P9_DEBUG_TRANS: transport tracing
40 * @P9_DEBUG_SLABS: memory management tracing
41 * @P9_DEBUG_FCALL: verbose dump of protocol messages
42 *
43 * These flags are passed at mount time to turn on various levels of
44 * verbosity and tracing which will be output to the system logs.
45 */
46
47enum p9_debug_flags {
48 P9_DEBUG_ERROR = (1<<0),
49 P9_DEBUG_9P = (1<<2),
50 P9_DEBUG_VFS = (1<<3),
51 P9_DEBUG_CONV = (1<<4),
52 P9_DEBUG_MUX = (1<<5),
53 P9_DEBUG_TRANS = (1<<6),
54 P9_DEBUG_SLABS = (1<<7),
55 P9_DEBUG_FCALL = (1<<8),
56};
40 57
41extern unsigned int p9_debug_level; 58extern unsigned int p9_debug_level;
42 59
@@ -62,9 +79,47 @@ do { \
62 format , __FUNCTION__, task_pid_nr(current), ## arg); \ 79 format , __FUNCTION__, task_pid_nr(current), ## arg); \
63} while (0) 80} while (0)
64 81
82/**
83 * enum p9_msg_t - 9P message types
84 * @P9_TVERSION: version handshake request
85 * @P9_RVERSION: version handshake response
86 * @P9_TAUTH: request to establish authentication channel
87 * @P9_RAUTH: response with authentication information
88 * @P9_TATTACH: establish user access to file service
89 * @P9_RATTACH: response with top level handle to file hierarchy
90 * @P9_TERROR: not used
91 * @P9_RERROR: response for any failed request
92 * @P9_TFLUSH: request to abort a previous request
93 * @P9_RFLUSH: response when previous request has been cancelled
94 * @P9_TWALK: descend a directory hierarchy
95 * @P9_RWALK: response with new handle for position within hierarchy
96 * @P9_TOPEN: prepare a handle for I/O on an existing file
97 * @P9_ROPEN: response with file access information
98 * @P9_TCREATE: prepare a handle for I/O on a new file
99 * @P9_RCREATE: response with file access information
100 * @P9_TREAD: request to transfer data from a file or directory
101 * @P9_RREAD: response with data requested
102 * @P9_TWRITE: reuqest to transfer data to a file
103 * @P9_RWRITE: response with out much data was transfered to file
104 * @P9_TCLUNK: forget about a handle to an entity within the file system
105 * @P9_RCLUNK: response when server has forgotten about the handle
106 * @P9_TREMOVE: request to remove an entity from the hierarchy
107 * @P9_RREMOVE: response when server has removed the entity
108 * @P9_TSTAT: request file entity attributes
109 * @P9_RSTAT: response with file entity attributes
110 * @P9_TWSTAT: request to update file entity attributes
111 * @P9_RWSTAT: response when file entity attributes are updated
112 *
113 * There are 14 basic operations in 9P2000, paired as
114 * requests and responses. The one special case is ERROR
115 * as there is no @P9_TERROR request for clients to transmit to
116 * the server, but the server may respond to any other request
117 * with an @P9_RERROR.
118 *
119 * See Also: http://plan9.bell-labs.com/sys/man/5/INDEX.html
120 */
65 121
66/* Message Types */ 122enum p9_msg_t {
67enum {
68 P9_TVERSION = 100, 123 P9_TVERSION = 100,
69 P9_RVERSION, 124 P9_RVERSION,
70 P9_TAUTH = 102, 125 P9_TAUTH = 102,
@@ -95,30 +150,71 @@ enum {
95 P9_RWSTAT, 150 P9_RWSTAT,
96}; 151};
97 152
98/* open modes */ 153/**
99enum { 154 * enum p9_open_mode_t - 9P open modes
155 * @P9_OREAD: open file for reading only
156 * @P9_OWRITE: open file for writing only
157 * @P9_ORDWR: open file for reading or writing
158 * @P9_OEXEC: open file for execution
159 * @P9_OTRUNC: truncate file to zero-length before opening it
160 * @P9_OREXEC: close the file when an exec(2) system call is made
161 * @P9_ORCLOSE: remove the file when the file is closed
162 * @P9_OAPPEND: open the file and seek to the end
163 * @P9_OEXCL: only create a file, do not open it
164 *
165 * 9P open modes differ slightly from Posix standard modes.
166 * In particular, there are extra modes which specify different
167 * semantic behaviors than may be available on standard Posix
168 * systems. For example, @P9_OREXEC and @P9_ORCLOSE are modes that
169 * most likely will not be issued from the Linux VFS client, but may
170 * be supported by servers.
171 *
172 * See Also: http://plan9.bell-labs.com/magic/man2html/2/open
173 */
174
175enum p9_open_mode_t {
100 P9_OREAD = 0x00, 176 P9_OREAD = 0x00,
101 P9_OWRITE = 0x01, 177 P9_OWRITE = 0x01,
102 P9_ORDWR = 0x02, 178 P9_ORDWR = 0x02,
103 P9_OEXEC = 0x03, 179 P9_OEXEC = 0x03,
104 P9_OEXCL = 0x04,
105 P9_OTRUNC = 0x10, 180 P9_OTRUNC = 0x10,
106 P9_OREXEC = 0x20, 181 P9_OREXEC = 0x20,
107 P9_ORCLOSE = 0x40, 182 P9_ORCLOSE = 0x40,
108 P9_OAPPEND = 0x80, 183 P9_OAPPEND = 0x80,
109}; 184 P9_OEXCL = 0x1000,
110 185};
111/* permissions */ 186
112enum { 187/**
188 * enum p9_perm_t - 9P permissions
189 * @P9_DMDIR: mode bite for directories
190 * @P9_DMAPPEND: mode bit for is append-only
191 * @P9_DMEXCL: mode bit for excluse use (only one open handle allowed)
192 * @P9_DMMOUNT: mode bite for mount points
193 * @P9_DMAUTH: mode bit for authentication file
194 * @P9_DMTMP: mode bit for non-backed-up files
195 * @P9_DMSYMLINK: mode bit for symbolic links (9P2000.u)
196 * @P9_DMLINK: mode bit for hard-link (9P2000.u)
197 * @P9_DMDEVICE: mode bit for device files (9P2000.u)
198 * @P9_DMNAMEDPIPE: mode bit for named pipe (9P2000.u)
199 * @P9_DMSOCKET: mode bit for socket (9P2000.u)
200 * @P9_DMSETUID: mode bit for setuid (9P2000.u)
201 * @P9_DMSETGID: mode bit for setgid (9P2000.u)
202 * @P9_DMSETVTX: mode bit for sticky bit (9P2000.u)
203 *
204 * 9P permissions differ slightly from Posix standard modes.
205 *
206 * See Also: http://plan9.bell-labs.com/magic/man2html/2/stat
207 */
208enum p9_perm_t {
113 P9_DMDIR = 0x80000000, 209 P9_DMDIR = 0x80000000,
114 P9_DMAPPEND = 0x40000000, 210 P9_DMAPPEND = 0x40000000,
115 P9_DMEXCL = 0x20000000, 211 P9_DMEXCL = 0x20000000,
116 P9_DMMOUNT = 0x10000000, 212 P9_DMMOUNT = 0x10000000,
117 P9_DMAUTH = 0x08000000, 213 P9_DMAUTH = 0x08000000,
118 P9_DMTMP = 0x04000000, 214 P9_DMTMP = 0x04000000,
215/* 9P2000.u extensions */
119 P9_DMSYMLINK = 0x02000000, 216 P9_DMSYMLINK = 0x02000000,
120 P9_DMLINK = 0x01000000, 217 P9_DMLINK = 0x01000000,
121 /* 9P2000.u extensions */
122 P9_DMDEVICE = 0x00800000, 218 P9_DMDEVICE = 0x00800000,
123 P9_DMNAMEDPIPE = 0x00200000, 219 P9_DMNAMEDPIPE = 0x00200000,
124 P9_DMSOCKET = 0x00100000, 220 P9_DMSOCKET = 0x00100000,
@@ -127,8 +223,26 @@ enum {
127 P9_DMSETVTX = 0x00010000, 223 P9_DMSETVTX = 0x00010000,
128}; 224};
129 225
130/* qid.types */ 226/**
131enum { 227 * enum p9_qid_t - QID types
228 * @P9_QTDIR: directory
229 * @P9_QTAPPEND: append-only
230 * @P9_QTEXCL: excluse use (only one open handle allowed)
231 * @P9_QTMOUNT: mount points
232 * @P9_QTAUTH: authentication file
233 * @P9_QTTMP: non-backed-up files
234 * @P9_QTSYMLINK: symbolic links (9P2000.u)
235 * @P9_QTLINK: hard-link (9P2000.u)
236 * @P9_QTFILE: normal files
237 *
238 * QID types are a subset of permissions - they are primarily
239 * used to differentiate semantics for a file system entity via
240 * a jump-table. Their value is also the most signifigant 16 bits
241 * of the permission_t
242 *
243 * See Also: http://plan9.bell-labs.com/magic/man2html/2/stat
244 */
245enum p9_qid_t {
132 P9_QTDIR = 0x80, 246 P9_QTDIR = 0x80,
133 P9_QTAPPEND = 0x40, 247 P9_QTAPPEND = 0x40,
134 P9_QTEXCL = 0x20, 248 P9_QTEXCL = 0x20,
@@ -140,6 +254,7 @@ enum {
140 P9_QTFILE = 0x00, 254 P9_QTFILE = 0x00,
141}; 255};
142 256
257/* 9P Magic Numbers */
143#define P9_NOTAG (u16)(~0) 258#define P9_NOTAG (u16)(~0)
144#define P9_NOFID (u32)(~0) 259#define P9_NOFID (u32)(~0)
145#define P9_MAXWELEM 16 260#define P9_MAXWELEM 16
@@ -147,19 +262,69 @@ enum {
147/* ample room for Twrite/Rread header */ 262/* ample room for Twrite/Rread header */
148#define P9_IOHDRSZ 24 263#define P9_IOHDRSZ 24
149 264
265/**
266 * struct p9_str - length prefixed string type
267 * @len: length of the string
268 * @str: the string
269 *
270 * The protocol uses length prefixed strings for all
271 * string data, so we replicate that for our internal
272 * string members.
273 */
274
150struct p9_str { 275struct p9_str {
151 u16 len; 276 u16 len;
152 char *str; 277 char *str;
153}; 278};
154 279
155/* qids are the unique ID for a file (like an inode */ 280/**
281 * struct p9_qid - file system entity information
282 * @type: 8-bit type &p9_qid_t
283 * @version: 16-bit monotonically incrementing version number
284 * @path: 64-bit per-server-unique ID for a file system element
285 *
286 * qids are identifiers used by 9P servers to track file system
287 * entities. The type is used to differentiate semantics for operations
288 * on the entity (ie. read means something different on a directory than
289 * on a file). The path provides a server unique index for an entity
290 * (roughly analogous to an inode number), while the version is updated
291 * every time a file is modified and can be used to maintain cache
292 * coherency between clients and serves.
293 * Servers will often differentiate purely synthetic entities by setting
294 * their version to 0, signaling that they should never be cached and
295 * should be accessed synchronously.
296 *
297 * See Also://plan9.bell-labs.com/magic/man2html/2/stat
298 */
299
156struct p9_qid { 300struct p9_qid {
157 u8 type; 301 u8 type;
158 u32 version; 302 u32 version;
159 u64 path; 303 u64 path;
160}; 304};
161 305
162/* Plan 9 file metadata (stat) structure */ 306/**
307 * struct p9_stat - file system metadata information
308 * @size: length prefix for this stat structure instance
309 * @type: the type of the server (equivilent to a major number)
310 * @dev: the sub-type of the server (equivilent to a minor number)
311 * @qid: unique id from the server of type &p9_qid
312 * @mode: Plan 9 format permissions of type &p9_perm_t
313 * @atime: Last access/read time
314 * @mtime: Last modify/write time
315 * @length: file length
316 * @name: last element of path (aka filename) in type &p9_str
317 * @uid: owner name in type &p9_str
318 * @gid: group owner in type &p9_str
319 * @muid: last modifier in type &p9_str
320 * @extension: area used to encode extended UNIX support in type &p9_str
321 * @n_uid: numeric user id of owner (part of 9p2000.u extension)
322 * @n_gid: numeric group id (part of 9p2000.u extension)
323 * @n_muid: numeric user id of laster modifier (part of 9p2000.u extension)
324 *
325 * See Also: http://plan9.bell-labs.com/magic/man2html/2/stat
326 */
327
163struct p9_stat { 328struct p9_stat {
164 u16 size; 329 u16 size;
165 u16 type; 330 u16 type;
@@ -179,10 +344,14 @@ struct p9_stat {
179 u32 n_muid; /* 9p2000.u extensions */ 344 u32 n_muid; /* 9p2000.u extensions */
180}; 345};
181 346
182/* file metadata (stat) structure used to create Twstat message 347/*
183 The is similar to p9_stat, but the strings don't point to 348 * file metadata (stat) structure used to create Twstat message
184 the same memory block and should be freed separately 349 * The is identical to &p9_stat, but the strings don't point to
185*/ 350 * the same memory block and should be freed separately
351 *
352 * See Also: http://plan9.bell-labs.com/magic/man2html/2/stat
353 */
354
186struct p9_wstat { 355struct p9_wstat {
187 u16 size; 356 u16 size;
188 u16 type; 357 u16 type;
@@ -335,10 +504,20 @@ struct p9_twstat {
335struct p9_rwstat { 504struct p9_rwstat {
336}; 505};
337 506
338/* 507/**
339 * fcall is the primary packet structure 508 * struct p9_fcall - primary packet structure
340 * 509 * @size: prefixed length of the structure
341 */ 510 * @id: protocol operating identifier of type &p9_msg_t
511 * @tag: transaction id of the request
512 * @sdata: payload
513 * @params: per-operation parameters
514 *
515 * &p9_fcall represents the structure for all 9P RPC
516 * transactions. Requests are packaged into fcalls, and reponses
517 * must be extracted from them.
518 *
519 * See Also: http://plan9.bell-labs.com/magic/man2html/2/fcall
520 */
342 521
343struct p9_fcall { 522struct p9_fcall {
344 u32 size; 523 u32 size;
diff --git a/include/net/9p/client.h b/include/net/9p/client.h
index e52f93d9ac5f..c936dd14de41 100644
--- a/include/net/9p/client.h
+++ b/include/net/9p/client.h
@@ -26,6 +26,23 @@
26#ifndef NET_9P_CLIENT_H 26#ifndef NET_9P_CLIENT_H
27#define NET_9P_CLIENT_H 27#define NET_9P_CLIENT_H
28 28
29/**
30 * struct p9_client - per client instance state
31 * @lock: protect @fidlist
32 * @msize: maximum data size negotiated by protocol
33 * @dotu: extension flags negotiated by protocol
34 * @trans_mod: module API instantiated with this client
35 * @trans: tranport instance state and API
36 * @conn: connection state information used by trans_fd
37 * @fidpool: fid handle accounting for session
38 * @fidlist: List of active fid handles
39 *
40 * The client structure is used to keep track of various per-client
41 * state that has been instantiated.
42 *
43 * Bugs: duplicated data and potentially unnecessary elements.
44 */
45
29struct p9_client { 46struct p9_client {
30 spinlock_t lock; /* protect client structure */ 47 spinlock_t lock; /* protect client structure */
31 int msize; 48 int msize;
@@ -38,6 +55,24 @@ struct p9_client {
38 struct list_head fidlist; 55 struct list_head fidlist;
39}; 56};
40 57
58/**
59 * struct p9_fid - file system entity handle
60 * @clnt: back pointer to instantiating &p9_client
61 * @fid: numeric identifier for this handle
62 * @mode: current mode of this fid (enum?)
63 * @qid: the &p9_qid server identifier this handle points to
64 * @iounit: the server reported maximum transaction size for this file
65 * @uid: the numeric uid of the local user who owns this handle
66 * @aux: transport specific information (unused?)
67 * @rdir_fpos: tracks offset of file position when reading directory contents
68 * @rdir_pos: (unused?)
69 * @rdir_fcall: holds response of last directory read request
70 * @flist: per-client-instance fid tracking
71 * @dlist: per-dentry fid tracking
72 *
73 * TODO: This needs lots of explanation.
74 */
75
41struct p9_fid { 76struct p9_fid {
42 struct p9_client *clnt; 77 struct p9_client *clnt;
43 u32 fid; 78 u32 fid;
diff --git a/include/net/9p/transport.h b/include/net/9p/transport.h
index d2209ae9d18b..240e0de888c6 100644
--- a/include/net/9p/transport.h
+++ b/include/net/9p/transport.h
@@ -26,12 +26,40 @@
26#ifndef NET_9P_TRANSPORT_H 26#ifndef NET_9P_TRANSPORT_H
27#define NET_9P_TRANSPORT_H 27#define NET_9P_TRANSPORT_H
28 28
29/**
30 * enum p9_trans_status - different states of underlying transports
31 * @Connected: transport is connected and healthy
32 * @Disconnected: transport has been disconnected
33 * @Hung: transport is connected by wedged
34 *
35 * This enumeration details the various states a transport
36 * instatiation can be in.
37 */
38
29enum p9_trans_status { 39enum p9_trans_status {
30 Connected, 40 Connected,
31 Disconnected, 41 Disconnected,
32 Hung, 42 Hung,
33}; 43};
34 44
45/**
46 * struct p9_trans - per-transport state and API
47 * @status: transport &p9_trans_status
48 * @msize: negotiated maximum packet size (duplicate from client)
49 * @extended: negotiated protocol extensions (duplicate from client)
50 * @priv: transport private data
51 * @close: member function to disconnect and close the transport
52 * @rpc: member function to issue a request to the transport
53 *
54 * This is the basic API for a transport instance. It is used as
55 * a handle by the client to issue requests. This interface is currently
56 * in flux during reorganization.
57 *
58 * Bugs: there is lots of duplicated data here and its not clear that
59 * the member functions need to be per-instance versus per transport
60 * module.
61 */
62
35struct p9_trans { 63struct p9_trans {
36 enum p9_trans_status status; 64 enum p9_trans_status status;
37 int msize; 65 int msize;
@@ -42,6 +70,21 @@ struct p9_trans {
42 struct p9_fcall **rc); 70 struct p9_fcall **rc);
43}; 71};
44 72
73/**
74 * struct p9_trans_module - transport module interface
75 * @list: used to maintain a list of currently available transports
76 * @name: the human-readable name of the transport
77 * @maxsize: transport provided maximum packet size
78 * @def: set if this transport should be considered the default
79 * @create: member function to create a new connection on this transport
80 *
81 * This is the basic API for a transport module which is registered by the
82 * transport module with the 9P core network module and used by the client
83 * to instantiate a new connection on a transport.
84 *
85 * Bugs: the transport module list isn't protected.
86 */
87
45struct p9_trans_module { 88struct p9_trans_module {
46 struct list_head list; 89 struct list_head list;
47 char *name; /* name of transport */ 90 char *name; /* name of transport */