doc/nnpfs.txt

   1
   2 NNPFS DOCUMENTATION
   3 =================
   4
   5 $Id$
   6
   7 This is not the truth, but close to.
   8
   9
  10 TODO
  11 #include <nnpfs/nnpfs_attr.h>
  12
  13
  14 LIMITATIONS and CONSTANTS
  15 =========================
  16
  17 You can install messages to nnpfs of max size ``NNPFS_MAX_MSG_SIZE''.
  18
  19 The kernel can at most hold rights of size ``MAXRIGHTS''.
  20
  21 A nnpfs handle have the size of ``MAXHANDLE'', and that is at least 16
  22 bytes.
  23
  24 The anonymous user had id ``NNPFS_ANONYMOUSID''.
  25
  26 The nnpfs-fh-open-handle has the size of ``CACHEHANDLESIZE'', and it
  27 is an opaque data-structure.
  28
  29 PAGS
  30 ====
  31
  32 Pags are a hack to separate processes of same UID to make them have
  33 different access-rights. Pags are saved over setuid(2)/initgroups(2)
  34 calls. Nnpfs uses a struct ``nnpfs_cred'' to pass over the UID and the pag.
  35
  36
  37 TOKENS
  38 ======
  39
  40 This section does not apply to 0.36 or older
  41
  42 Tokens describe what parts of the node are valid, and what rights npfs
  43 has on those parts.
  44
  45 Open token are requests to open a file, note that OPEN tokens are
  46 different from DATA token, OPEN are if there is right to open data.
  47 DATA is if there is data installed.
  48
  49 NNPFS_OPEN_R
  50 NNPFS_OPEN_W
  51
  52 NNPFS_OPEN_{R,W}_PRE must never be requested by nnpfs in messages to
  53 the userland daemon. The are installed into the kernel when the
  54 userland daemon allows async open.
  55
  56 NNPFS_OPEN_R_PRE
  57 NNPFS_OPEN_W_PRE
  58
  59 Async is used for OPEN when the kernel have a NNPFS_OPEN_{R,W}_PRE and
  60 wants to notify the user land daemon that it has opened the file.
  61
  62 NNPFS_ASYNC
  63
  64 Attribute token, apply to all attribute except size.
  65
  66 NNPFS_ATTR_R                   /* Attributes valid */
  67 NNPFS_ATTR_W                   /* Attributes valid and modifiable */
  68
  69 Tokens that apply to node data.
  70
  71 NNPFS_DATA_R                   /* Data valid */
  72 NNPFS_DATA_W                   /* Data valid and modifiable */
  73
  74 Token that apply to locking of node
  75
  76 NNPFS_LOCK_R                   /* Data Shared locks */
  77 NNPFS_LOCK_W                   /* Data Exclusive locks */
  78
  79 XXX How should invalid node modify above ?
  80
  81 XXX OPEN vs GETDATA should
  82 XXX Should it be LOOKUP and GETDATA ?
  83 XXX Do DATA really need to be _{R,W} ?
  84
  85
  86 MESSAGES
  87 ========
  88
  89 Are passed through the nnpfs device somehow.
  90
  91 Each message is prepended by a header including the 32-bit fields
  92 `size'', ``opcode'', ``sequence_num'', ``pad1'' (in that
  93 order). ``Size'' is the size of the WHOLE message. ``Opcode'' is the
  94 opcode (described below). ``sequence_num'' is a messages specific field
  95 that is used for replying the the sender of the message (if so is
  96 needed).
  97
  98 All messages (and the nnpfs_header) are padded to 64-bit boundary to
  99 avoid bit unaligned data in the kernel. The padding is called padN,
 100 where N is a number.
 101
 102 Note that the total size of the data sent to the kernel may consist
 103 of several messages for performance reasons. Each data blob sent to
 104 the kernel must contain complete messages, the nnpfs implementation
 105 does not do any de-fragmentation.
 106
 107 Nnpfs parses each individual message with the help of its size in
 108 the message header.
 109
 110 The following opcodes are defined (values from 0 to
 111 NNPFS_MSG_COUNT - 1):
 112
 113 The sender of the message is listed after the opcode name.
 114
 115 NNPFS_MSG_VERSION (user-land)
 116
 117         Probe the kernel module to send its nnpfs version.
 118         The kernel module returns an integer which
 119         identifies the capabilities of this nnpfs version.
 120
 121         The user-land process must use this to check if it can support
 122         this version. It must not use the nnpfs implementation when it
 123         doesn't support it.
 124
 125 NNPFS_MSG_WAKEUP (user-land|nnpfs)
 126
 127         Wake up a message with `seqnum', and pass on `error' as return
 128         value.
 129
 130 NNPFS_MSG_WAKEUP_DATA (user-land)
 131
 132         Wake up a kernel-thread with `seqnum', and pass on `error'
 133         as return value. Add also a data blob for generic use.
 134
 135         Data blob used for ??
 136
 137 NNPFS_MSG_GETROOT (nnpfs)
 138
 139         GETROOT is called to get the root-node with the ``cred''
 140
 141         Its only called from nnpfs to get the root-node, this might be
 142         several times per mount depending on file system.
 143
 144         User-Land answers with a NNPFS_MSG_INSTALLROOT
 145
 146 NNPFS_MSG_INSTALLROOT (user-land)
 147
 148         INSTALLROOT is called to insert a root node.
 149
 150         INSTALLROOT MUST only be called on the request of GETROOT.
 151
 152         The node to install is in ``node''.
 153
 154         The only return value of the message is the integer return value.
 155
 156         Multiple INSTALLROOT must be ignored by the nnpfs-implementation, and
 157         the return value EBUSY MUST be returned.
 158
 159 NNPFS_MSG_GETNODE (nnpfs)
 160
 161         GETNODE is called to get the node named ``named'' in the
 162         directory ``parent_handle'' with ``cred''.
 163
 164         While there is no error in the returning WAKEUP call and there
 165         is corresponding node in cache the nnpfs-implementation should
 166         loop until there is an error.
 167
 168 NNPFS_MSG_INSTALLNODE (user-land)
 169
 170         Insert the ``node'' of ``name'' in the directory ``parent_handle''
 171         into the cache.
 172
 173         The user-land MUST NOT install the ``node'' twice.
 174
 175         The nnpfs-implementation SHOULD NOT install same node several
 176         times in the same ``parent_handle'', that is if ``node'' has
 177         same parent and same name (observe that same handle can be
 178         installed several times in the case of hard-links).
 179
 180 NNPFS_MSG_GETATTR (nnpfs)
 181
 182         Get the attributes for the node described by ``handle'' that
 183         already have been installed by INSTALLNODE with the ``cred''.
 184
 185         The nnpfs-implementation should loop until there is an error,
 186         or the node is the cache with appropriate pag in the cred
 187         part of the node.
 188
 189 NNPFS_MSG_INSTALLATTR (user-land)
 190
 191         Should update the installed ``node's'' attribute.
 192
 193         If the node found in ``node.handle'' isn't in the installed
 194         the nnpfs-implementation SHOULD return ENOENT.
 195
 196         Note that it isn't an error if the node isn't in the
 197         nnpfs-cache since it might have been deleted from the
 198         nnpfs-cache before the message was sent to nnpfs (that is, the
 199         NNPFS_MSG_INVALIDNODE message is still in the queue to
 200         user-land).
 201
 202 NNPFS_MSG_GETDATA (nnpfs)
 203
 204         Get data for the node described in ``handle''. Otherwise same
 205         as GETATTR.
 206
 207 NNPFS_MSG_INSTALLDATA (user-land)
 208
 209         Install data for the node described by ``node.handle''. The
 210         vnode/inode that contains the data is pointed out by
 211         ``cache_handle'' if the underlying OS supports openfh/getfh.
 212
 213         The cache file is also pointed out by the name ``cache_name'',
 214         and that name is relative to the current working directory of
 215         the user-land process that did the installdata process.
 216
 217         In addition to the data, installdata also updates the
 218         attributes of the node.
 219
 220         If the ``flag & NNPFS_ID_HANDLE_VALID'' is not set,
 221         ``cache_name'' will be used instead.
 222
 223         If the ``flag & NNPFS_ID_INVALID_DNLC'' is set the
 224         nnpfs-implementation should flush all name cache related to this
 225         node. The nnpfs-implementation SHOULD check that this is a
 226         directory-node.
 227
 228 NNPFS_MSG_INACTIVENODE (nnpfs)
 229
 230         The message that nnpfs sends to the user-land daemon when
 231         ``handle'' no longer exists in the nnpfs-cache.
 232
 233         To tell what state the node is in ``flag'' is set to
 234         appropriate value. ``NNPFS_NOREFS'' tells the user-land daemon
 235         that the nnpfs still has the node cached but nothing is using it
 236         and it can be removed at any time. ``NNPFS_DELETE'' means that
 237         this node already has been dropped from the cache and can't be
 238         used anymore.
 239
 240 NNPFS_MSG_INVALIDNODE (user-land)
 241
 242         Used to hint the kernel that node described by ``handle''
 243         should be dropped from the nnpfs-cache. Doesn't mean that the
 244         node has to be dropped from the cache immediately, just that
 245         it should be deleted when it's no longer used.
 246
 247         This is typically used by user-land process need to propagates broken
 248         call-backs/oplocks to nnpfs.
 249
 250         The user-land MUST NOT remove the node from the cache until it
 251         receives a NNPFS_MSG_INACTIVENODE.
 252
 253 NNPFS_MSG_OPEN (nnpfs)
 254
 255         Passed to the user-land to inform that ``handle'' has been
 256         opened with ``cred'' to do what is described in ``tokens''.
 257
 258         Can be the same as NNPFS_MSG_GETDATA if no locking is implemented.
 259
 260 NNPFS_MSG_PUTDATA (nnpfs)
 261
 262         Syncs data associated to ``handle'' from nnpfs-cache to
 263         user-land. The associating ``cred.uid'' and ``cred.pag'' are
 264         sent along the data.
 265
 266         As a side effect, ``attr'' will contain the mtime of the node.
 267         and user-land may use that to update the modification time of
 268         the data.
 269
 270         The nature of the operation is described by ``flag''.
 271
 272         NNPFS_READ:    unused
 273         NNPFS_WRITE:   Data is expected to be written to user-land
 274         NNPFS_NOBLOCK: The operations is expected to be non-blocking (async)
 275         NNPFS_APPEND:  unused
 276         NNPFS_FSYNC:   Flag which can be used that it is expected that user-land
 277                      syncs the data to the next level (whatever that is).
 278
 279        enum { NNPFS_READ = 1, NNPFS_WRITE = 2, NNPFS_NONBLOCK = 4, NNPFS_APPEND = 8, NNPFS_FSYNC};
 280
 281 NNPFS_MSG_PUTATTR (nnpfs)
 282
 283         Syncs attributes (like times, mode bits and size) associated to
 284         ``handle'' from nnpfs-cache to user-land. The associating
 285         ``cred.uid'' and ``cred.pag'' are sent along the data.
 286
 287 /* Directory manipulating messages. */
 288
 289 NNPFS_MSG_CREATE (nnpfs)
 290
 291         Instructs user-land to create a new file node entry in
 292         ``parent_handle'' named ``name'' with the attributes in
 293         ``attr'' and authenticated with ``cred.uid'' and ``cred.pag''.
 294         ``mode''.
 295
 296 NNPFS_MSG_MKDIR (nnpfs)
 297
 298         Instructs user-land to create a new directory node entry in
 299         ``parent_handle'' named ``name'' with the attributes in
 300         ``attr'' and authenticated with ``cred.uid'' and ``cred.pag''.
 301
 302 NNPFS_MSG_LINK (nnpfs)
 303
 304         Instructs user-land to create a new "hard" link node entry in
 305         ``parent_handle'' named ``name'' using ``from_handle'' as the
 306         source with the attributes in ``attr'' and authenticated with
 307         ``cred.uid'' and ``cred.pag''.
 308
 309 NNPFS_MSG_SYMLINK (nnpfs)
 310
 311         Instructs user-land to create a new symbolic link node entry in
 312         ``parent_handle'' named ``name'' pointing on ``contents'' as
 313         the source with the attributes in ``attr'' and authenticated
 314         with ``cred.uid'' and ``cred.pag''.
 315
 316 NNPFS_MSG_REMOVE (nnpfs)
 317
 318         Instructs user-land to remove a file node in ``parent_handle''
 319         named ``name'' with the attributes in ``attr'' and
 320         authenticated with ``cred.uid'' and ``cred.pag''.
 321
 322 NNPFS_MSG_RMDIR (nnpfs)
 323
 324         Instructs user-land to remove a directory node in
 325         ``parent_handle'' named ``name'' with the attributes in
 326         ``attr'' and authenticated with ``cred.uid'' and ``cred.pag''.
 327
 328 NNPFS_MSG_RENAME (nnpfs)
 329
 330         Instructs user-land to rename a node in ``parent_handle'' named
 331         ``old_name'' to ``new_name'' authenticated with ``cred.uid''
 332         and ``cred.pag''.
 333
 334 NNPFS_MSG_PIOCTL (nnpfs)
 335
 336         If the nnpfs-cache manager get a pioctl and can not take care of
 337         it itself, it forwards it to user-land. Associated with the
 338         pioctl there are the ``opcode'' of the pioctl, a ``insize'',
 339         ``outsize'' and ``cred''.
 340
 341 NNPFS_MSG_WAKEUP_DATA (user-land)
 342
 343 NNPFS_MSG_UPDATEFID (user-land)
 344
 345 NNPFS_MSG_ADVLOCK (nnpfs/user-land)
 346
 347 NNPFS_MSG_GC_NODES (user-land)
 348
 349         NNPFS_MSG_GC_NODES is almost the equivalent of
 350         NNPFS_MSG_INVALIDNODE, with the difference that the node isn't
 351         invalid, its the the user-land process that wants to free it.
 352
 353 __END__;
 354
 355 /* NNPFS_MSG_OPEN */
 356 struct nnpfs_message_open {
 357   struct nnpfs_message_header header;
 358   struct nnpfs_cred cred;
 359   nnpfs_handle handle;
 360   u_int32_t tokens;
 361   u_int32_t pad1;
 362 };
 363
 364 /* NNPFS_MSG_PUTDATA */
 365 struct nnpfs_message_putdata {
 366   struct nnpfs_message_header header;
 367   nnpfs_handle handle;
 368   struct nnpfs_attr attr;               /* XXX ??? */
 369   struct nnpfs_cred cred;
 370   u_int32_t flag;
 371   u_int32_t pad1;
 372 };
 373
 374 /* NNPFS_MSG_PUTATTR */
 375 struct nnpfs_message_putattr {
 376   struct nnpfs_message_header header;
 377   nnpfs_handle handle;
 378   struct nnpfs_attr attr;
 379   struct nnpfs_cred cred;
 380 };
 381
 382 /* NNPFS_MSG_CREATE */
 383 struct nnpfs_message_create {
 384   struct nnpfs_message_header header;
 385   nnpfs_handle parent_handle;
 386   char name[256];               /* XXX */
 387   struct nnpfs_attr attr;
 388   u_int32_t mode;
 389   u_int32_t pad1;
 390   struct nnpfs_cred cred;
 391 };
 392
 393 /* NNPFS_MSG_MKDIR */
 394 struct nnpfs_message_mkdir {
 395   struct nnpfs_message_header header;
 396   nnpfs_handle parent_handle;
 397   char name[256];               /* XXX */
 398   struct nnpfs_attr attr;
 399   struct nnpfs_cred cred;
 400 };
 401
 402 /* NNPFS_MSG_LINK */
 403 struct nnpfs_message_link {
 404   struct nnpfs_message_header header;
 405   nnpfs_handle parent_handle;
 406   char name[256];               /* XXX */
 407   nnpfs_handle from_handle;
 408   struct nnpfs_cred cred;
 409 };
 410
 411 /* NNPFS_MSG_SYMLINK */
 412 struct nnpfs_message_symlink {
 413   struct nnpfs_message_header header;
 414   nnpfs_handle parent_handle;
 415   char name[256];               /* XXX */
 416   char contents[2048];          /* XXX */
 417   struct nnpfs_attr attr;
 418   struct nnpfs_cred cred;
 419 };
 420
 421 /* NNPFS_MSG_REMOVE */
 422 struct nnpfs_message_remove {
 423   struct nnpfs_message_header header;
 424   nnpfs_handle parent_handle;
 425   char name[256];               /* XXX */
 426   struct nnpfs_cred cred;
 427 };
 428
 429 /* NNPFS_MSG_RMDIR */
 430 struct nnpfs_message_rmdir {
 431   struct nnpfs_message_header header;
 432   nnpfs_handle parent_handle;
 433   char name[256];               /* XXX */
 434   struct nnpfs_cred cred;
 435 };
 436
 437 /* NNPFS_MSG_RENAME */
 438 struct nnpfs_message_rename {
 439   struct nnpfs_message_header header;
 440   nnpfs_handle old_parent_handle;
 441   char old_name[256];           /* XXX */
 442   nnpfs_handle new_parent_handle;
 443   char new_name[256];           /* XXX */
 444   struct nnpfs_cred cred;
 445 };
 446
 447 /* NNPFS_MSG_PIOCTL */
 448 struct nnpfs_message_pioctl {
 449   struct nnpfs_message_header header;
 450   u_int32_t opcode ;
 451   u_int32_t pad1;
 452   nnpfs_cred cred;
 453   u_int32_t insize;
 454   u_int32_t outsize;
 455   char msg[2048] ;    /* XXX */
 456   nnpfs_handle handle;
 457 };
 458
 459
 460 /* NNPFS_MESSAGE_WAKEUP_DATA */
 461 struct nnpfs_message_wakeup_data {
 462   struct nnpfs_message_header header;
 463   u_int32_t sleepers_sequence_num;      /* Where to send wakeup */
 464   u_int32_t error;                      /* Return value */
 465   u_int32_t len;
 466   u_int32_t pad1;
 467   char msg[2048] ;    /* XXX */
 468 };
 469
 470 /* NNPFS_MESSAGE_UPDATEFID */
 471 struct nnpfs_message_updatefid {
 472   struct nnpfs_message_header header;
 473   nnpfs_handle old_handle;
 474   nnpfs_handle new_handle;
 475 };
 476
 477 /* NNPFS_MESSAGE_ADVLOCK */
 478 struct nnpfs_message_advlock {
 479   struct nnpfs_message_header header;
 480   nnpfs_handle handle;
 481   struct nnpfs_cred cred;
 482   nnpfs_locktype_t locktype;
 483 #define NNPFS_WR_LOCK 1 /* Write lock */
 484 #define NNPFS_RD_LOCK 2 /* Read lock */
 485 #define NNPFS_UN_LOCK 3 /* Unlock */
 486 #define NNPFS_BR_LOCK 4 /* Break lock (inform that we don't want the lock) */
 487   nnpfs_lockid_t lockid;
 488 };
 489
 490 /* NNPFS_MESSAGE_GC_NODES */
 491 struct nnpfs_message_gc_nodes {
 492   struct nnpfs_message_header header;
 493 #define NNPFS_GC_NODES_MAX_HANDLE 50
 494   u_int32_t len;
 495   u_int32_t pad1;
 496   nnpfs_handle handle[NNPFS_GC_NODES_MAX_HANDLE];
 497 };
 498 #endif /* _xmsg_h */