include/net/9p/9p.h

   1 /*
   2  * include/net/9p/9p.h
   3  *
   4  * 9P protocol definitions.
   5  *
   6  *  Copyright (C) 2005 by Latchesar Ionkov <lucho@ionkov.net>
   7  *  Copyright (C) 2004 by Eric Van Hensbergen <ericvh@gmail.com>
   8  *  Copyright (C) 2002 by Ron Minnich <rminnich@lanl.gov>
   9  *
  10  *  This program is free software; you can redistribute it and/or modify
  11  *  it under the terms of the GNU General Public License version 2
  12  *  as published by the Free Software Foundation.
  13  *
  14  *  This program is distributed in the hope that it will be useful,
  15  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  *  GNU General Public License for more details.
  18  *
  19  *  You should have received a copy of the GNU General Public License
  20  *  along with this program; if not, write to:
  21  *  Free Software Foundation
  22  *  51 Franklin Street, Fifth Floor
  23  *  Boston, MA  02111-1301  USA
  24  *
  25  */
  26
  27 #ifndef NET_9P_H
  28 #define NET_9P_H
  29
  30 #ifdef CONFIG_NET_9P_DEBUG
  31
  32 /**
  33  * enum p9_debug_flags - bits for mount time debug parameter
  34  * @P9_DEBUG_ERROR: more verbose error messages including original error string
  35  * @P9_DEBUG_9P: 9P protocol tracing
  36  * @P9_DEBUG_VFS: VFS API tracing
  37  * @P9_DEBUG_CONV: protocol conversion tracing
  38  * @P9_DEBUG_MUX: trace management of concurrent transactions
  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
  47 enum 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 };
  57
  58 extern unsigned int p9_debug_level;
  59
  60 #define P9_DPRINTK(level, format, arg...) \
  61 do {  \
  62         if ((p9_debug_level & level) == level) \
  63                 printk(KERN_NOTICE "-- %s (%d): " \
  64                 format , __func__, task_pid_nr(current) , ## arg); \
  65 } while (0)
  66
  67 #define PRINT_FCALL_ERROR(s, fcall) P9_DPRINTK(P9_DEBUG_ERROR,   \
  68         "%s: %.*s\n", s, fcall?fcall->params.rerror.error.len:0, \
  69         fcall?fcall->params.rerror.error.str:"");
  70
  71 #else
  72 #define P9_DPRINTK(level, format, arg...)  do { } while (0)
  73 #define PRINT_FCALL_ERROR(s, fcall) do { } while (0)
  74 #endif
  75
  76 #define P9_EPRINTK(level, format, arg...) \
  77 do { \
  78         printk(level "9p: %s (%d): " \
  79                 format , __func__, task_pid_nr(current), ## arg); \
  80 } while (0)
  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  */
 121
 122 enum p9_msg_t {
 123         P9_TVERSION = 100,
 124         P9_RVERSION,
 125         P9_TAUTH = 102,
 126         P9_RAUTH,
 127         P9_TATTACH = 104,
 128         P9_RATTACH,
 129         P9_TERROR = 106,
 130         P9_RERROR,
 131         P9_TFLUSH = 108,
 132         P9_RFLUSH,
 133         P9_TWALK = 110,
 134         P9_RWALK,
 135         P9_TOPEN = 112,
 136         P9_ROPEN,
 137         P9_TCREATE = 114,
 138         P9_RCREATE,
 139         P9_TREAD = 116,
 140         P9_RREAD,
 141         P9_TWRITE = 118,
 142         P9_RWRITE,
 143         P9_TCLUNK = 120,
 144         P9_RCLUNK,
 145         P9_TREMOVE = 122,
 146         P9_RREMOVE,
 147         P9_TSTAT = 124,
 148         P9_RSTAT,
 149         P9_TWSTAT = 126,
 150         P9_RWSTAT,
 151 };
 152
 153 /**
 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
 175 enum p9_open_mode_t {
 176         P9_OREAD = 0x00,
 177         P9_OWRITE = 0x01,
 178         P9_ORDWR = 0x02,
 179         P9_OEXEC = 0x03,
 180         P9_OTRUNC = 0x10,
 181         P9_OREXEC = 0x20,
 182         P9_ORCLOSE = 0x40,
 183         P9_OAPPEND = 0x80,
 184         P9_OEXCL = 0x1000,
 185 };
 186
 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  */
 208 enum p9_perm_t {
 209         P9_DMDIR = 0x80000000,
 210         P9_DMAPPEND = 0x40000000,
 211         P9_DMEXCL = 0x20000000,
 212         P9_DMMOUNT = 0x10000000,
 213         P9_DMAUTH = 0x08000000,
 214         P9_DMTMP = 0x04000000,
 215 /* 9P2000.u extensions */
 216         P9_DMSYMLINK = 0x02000000,
 217         P9_DMLINK = 0x01000000,
 218         P9_DMDEVICE = 0x00800000,
 219         P9_DMNAMEDPIPE = 0x00200000,
 220         P9_DMSOCKET = 0x00100000,
 221         P9_DMSETUID = 0x00080000,
 222         P9_DMSETGID = 0x00040000,
 223         P9_DMSETVTX = 0x00010000,
 224 };
 225
 226 /**
 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  */
 245 enum p9_qid_t {
 246         P9_QTDIR = 0x80,
 247         P9_QTAPPEND = 0x40,
 248         P9_QTEXCL = 0x20,
 249         P9_QTMOUNT = 0x10,
 250         P9_QTAUTH = 0x08,
 251         P9_QTTMP = 0x04,
 252         P9_QTSYMLINK = 0x02,
 253         P9_QTLINK = 0x01,
 254         P9_QTFILE = 0x00,
 255 };
 256
 257 /* 9P Magic Numbers */
 258 #define P9_NOTAG        (u16)(~0)
 259 #define P9_NOFID        (u32)(~0)
 260 #define P9_MAXWELEM     16
 261
 262 /* ample room for Twrite/Rread header */
 263 #define P9_IOHDRSZ      24
 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
 275 struct p9_str {
 276         u16 len;
 277         char *str;
 278 };
 279
 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
 300 struct p9_qid {
 301         u8 type;
 302         u32 version;
 303         u64 path;
 304 };
 305
 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
 328 struct p9_stat {
 329         u16 size;
 330         u16 type;
 331         u32 dev;
 332         struct p9_qid qid;
 333         u32 mode;
 334         u32 atime;
 335         u32 mtime;
 336         u64 length;
 337         struct p9_str name;
 338         struct p9_str uid;
 339         struct p9_str gid;
 340         struct p9_str muid;
 341         struct p9_str extension;        /* 9p2000.u extensions */
 342         u32 n_uid;                      /* 9p2000.u extensions */
 343         u32 n_gid;                      /* 9p2000.u extensions */
 344         u32 n_muid;                     /* 9p2000.u extensions */
 345 };
 346
 347 /*
 348  * file metadata (stat) structure used to create Twstat message
 349  * The is identical to &p9_stat, but the strings don't point to
 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
 355 struct p9_wstat {
 356         u16 size;
 357         u16 type;
 358         u32 dev;
 359         struct p9_qid qid;
 360         u32 mode;
 361         u32 atime;
 362         u32 mtime;
 363         u64 length;
 364         char *name;
 365         char *uid;
 366         char *gid;
 367         char *muid;
 368         char *extension;        /* 9p2000.u extensions */
 369         u32 n_uid;              /* 9p2000.u extensions */
 370         u32 n_gid;              /* 9p2000.u extensions */
 371         u32 n_muid;             /* 9p2000.u extensions */
 372 };
 373
 374 /* Structures for Protocol Operations */
 375 struct p9_tversion {
 376         u32 msize;
 377         struct p9_str version;
 378 };
 379
 380 struct p9_rversion {
 381         u32 msize;
 382         struct p9_str version;
 383 };
 384
 385 struct p9_tauth {
 386         u32 afid;
 387         struct p9_str uname;
 388         struct p9_str aname;
 389         u32 n_uname;            /* 9P2000.u extensions */
 390 };
 391
 392 struct p9_rauth {
 393         struct p9_qid qid;
 394 };
 395
 396 struct p9_rerror {
 397         struct p9_str error;
 398         u32 errno;              /* 9p2000.u extension */
 399 };
 400
 401 struct p9_tflush {
 402         u16 oldtag;
 403 };
 404
 405 struct p9_rflush {
 406 };
 407
 408 struct p9_tattach {
 409         u32 fid;
 410         u32 afid;
 411         struct p9_str uname;
 412         struct p9_str aname;
 413         u32 n_uname;            /* 9P2000.u extensions */
 414 };
 415
 416 struct p9_rattach {
 417         struct p9_qid qid;
 418 };
 419
 420 struct p9_twalk {
 421         u32 fid;
 422         u32 newfid;
 423         u16 nwname;
 424         struct p9_str wnames[16];
 425 };
 426
 427 struct p9_rwalk {
 428         u16 nwqid;
 429         struct p9_qid wqids[16];
 430 };
 431
 432 struct p9_topen {
 433         u32 fid;
 434         u8 mode;
 435 };
 436
 437 struct p9_ropen {
 438         struct p9_qid qid;
 439         u32 iounit;
 440 };
 441
 442 struct p9_tcreate {
 443         u32 fid;
 444         struct p9_str name;
 445         u32 perm;
 446         u8 mode;
 447         struct p9_str extension;
 448 };
 449
 450 struct p9_rcreate {
 451         struct p9_qid qid;
 452         u32 iounit;
 453 };
 454
 455 struct p9_tread {
 456         u32 fid;
 457         u64 offset;
 458         u32 count;
 459 };
 460
 461 struct p9_rread {
 462         u32 count;
 463         u8 *data;
 464 };
 465
 466 struct p9_twrite {
 467         u32 fid;
 468         u64 offset;
 469         u32 count;
 470         u8 *data;
 471 };
 472
 473 struct p9_rwrite {
 474         u32 count;
 475 };
 476
 477 struct p9_tclunk {
 478         u32 fid;
 479 };
 480
 481 struct p9_rclunk {
 482 };
 483
 484 struct p9_tremove {
 485         u32 fid;
 486 };
 487
 488 struct p9_rremove {
 489 };
 490
 491 struct p9_tstat {
 492         u32 fid;
 493 };
 494
 495 struct p9_rstat {
 496         struct p9_stat stat;
 497 };
 498
 499 struct p9_twstat {
 500         u32 fid;
 501         struct p9_stat stat;
 502 };
 503
 504 struct p9_rwstat {
 505 };
 506
 507 /**
 508  * struct p9_fcall - primary packet structure
 509  * @size: prefixed length of the structure
 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  */
 521
 522 struct p9_fcall {
 523         u32 size;
 524         u8 id;
 525         u16 tag;
 526         void *sdata;
 527
 528         union {
 529                 struct p9_tversion tversion;
 530                 struct p9_rversion rversion;
 531                 struct p9_tauth tauth;
 532                 struct p9_rauth rauth;
 533                 struct p9_rerror rerror;
 534                 struct p9_tflush tflush;
 535                 struct p9_rflush rflush;
 536                 struct p9_tattach tattach;
 537                 struct p9_rattach rattach;
 538                 struct p9_twalk twalk;
 539                 struct p9_rwalk rwalk;
 540                 struct p9_topen topen;
 541                 struct p9_ropen ropen;
 542                 struct p9_tcreate tcreate;
 543                 struct p9_rcreate rcreate;
 544                 struct p9_tread tread;
 545                 struct p9_rread rread;
 546                 struct p9_twrite twrite;
 547                 struct p9_rwrite rwrite;
 548                 struct p9_tclunk tclunk;
 549                 struct p9_rclunk rclunk;
 550                 struct p9_tremove tremove;
 551                 struct p9_rremove rremove;
 552                 struct p9_tstat tstat;
 553                 struct p9_rstat rstat;
 554                 struct p9_twstat twstat;
 555                 struct p9_rwstat rwstat;
 556         } params;
 557 };
 558
 559 struct p9_idpool;
 560
 561 int p9_deserialize_stat(void *buf, u32 buflen, struct p9_stat *stat,
 562         int dotu);
 563 int p9_deserialize_fcall(void *buf, u32 buflen, struct p9_fcall *fc, int dotu);
 564 void p9_set_tag(struct p9_fcall *fc, u16 tag);
 565 struct p9_fcall *p9_create_tversion(u32 msize, char *version);
 566 struct p9_fcall *p9_create_tattach(u32 fid, u32 afid, char *uname,
 567         char *aname, u32 n_uname, int dotu);
 568 struct p9_fcall *p9_create_tauth(u32 afid, char *uname, char *aname,
 569         u32 n_uname, int dotu);
 570 struct p9_fcall *p9_create_tflush(u16 oldtag);
 571 struct p9_fcall *p9_create_twalk(u32 fid, u32 newfid, u16 nwname,
 572         char **wnames);
 573 struct p9_fcall *p9_create_topen(u32 fid, u8 mode);
 574 struct p9_fcall *p9_create_tcreate(u32 fid, char *name, u32 perm, u8 mode,
 575         char *extension, int dotu);
 576 struct p9_fcall *p9_create_tread(u32 fid, u64 offset, u32 count);
 577 struct p9_fcall *p9_create_twrite(u32 fid, u64 offset, u32 count,
 578         const char *data);
 579 struct p9_fcall *p9_create_twrite_u(u32 fid, u64 offset, u32 count,
 580         const char __user *data);
 581 struct p9_fcall *p9_create_tclunk(u32 fid);
 582 struct p9_fcall *p9_create_tremove(u32 fid);
 583 struct p9_fcall *p9_create_tstat(u32 fid);
 584 struct p9_fcall *p9_create_twstat(u32 fid, struct p9_wstat *wstat,
 585         int dotu);
 586
 587 int p9_printfcall(char *buf, int buflen, struct p9_fcall *fc, int dotu);
 588 int p9_errstr2errno(char *errstr, int len);
 589
 590 struct p9_idpool *p9_idpool_create(void);
 591 void p9_idpool_destroy(struct p9_idpool *);
 592 int p9_idpool_get(struct p9_idpool *p);
 593 void p9_idpool_put(int id, struct p9_idpool *p);
 594 int p9_idpool_check(int id, struct p9_idpool *p);
 595
 596 int p9_error_init(void);
 597 int p9_errstr2errno(char *, int);
 598 int p9_trans_fd_init(void);
 599 void p9_trans_fd_exit(void);
 600 #endif /* NET_9P_H */