Fix some typos.
[dragonfly.git] / lib / libpuffs / puffs.3
1 .\"     $NetBSD: puffs.3,v 1.47 2010/01/12 18:42:38 pooka Exp $
2 .\"
3 .\" Copyright (c) 2006, 2007, 2008 Antti Kantee.  All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\"    notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\"    notice, this list of conditions and the following disclaimer in the
12 .\"    documentation and/or other materials provided with the distribution.
13 .\"
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24 .\" SUCH DAMAGE.
25 .\"
26 .Dd February 5, 2012
27 .Dt PUFFS 3
28 .Os
29 .Sh NAME
30 .Nm puffs
31 .Nd Pass-to-Userspace Framework File System development interface
32 .Sh LIBRARY
33 .Lb libpuffs
34 .Sh SYNOPSIS
35 .In puffs.h
36 .Ft struct puffs_usermount *
37 .Fo puffs_init
38 .Fa "struct puffs_ops *pops" "const char *mntfromname" "const char *puffsname"
39 .Fa "void *private" "uint32_t flags"
40 .Fc
41 .Ft int
42 .Fo puffs_mount
43 .Fa "struct puffs_usermount *pu" "const char *dir" "int mntflags"
44 .Fa "puffs_cookie_t root_cookie"
45 .Fc
46 .Ft int
47 .Fn puffs_getselectable "struct puffs_usermount *pu"
48 .Ft int
49 .Fn puffs_setblockingmode "struct puffs_usermount *pu" "int mode"
50 .Ft int
51 .Fn puffs_getstate "struct puffs_usermount *pu"
52 .Ft int
53 .Fn puffs_setstacksize "struct puffs_usermount *pu" "size_t stacksize"
54 .Ft void
55 .Fn puffs_setroot "struct puffs_usermount *pu" "struct puffs_node *node"
56 .Ft void
57 .Fo puffs_setrootinfo
58 .Fa "struct puffs_usermount *pu" "enum vtype vt" "vsize_t vsize" "dev_t rdev"
59 .Fc
60 .Ft struct puffs_node *
61 .Fn puffs_getroot "struct puffs_usermount *pu"
62 .Ft void *
63 .Fn puffs_getspecific "struct puffs_usermount *pu"
64 .Ft void
65 .Fn puffs_setspecific "struct puffs_usermount *pu" "void *private"
66 .Ft void
67 .Fn puffs_setmaxreqlen "struct puffs_usermount *pu" "size_t maxreqlen"
68 .Ft size_t
69 .Fn puffs_getmaxreqlen "struct puffs_usermount *pu"
70 .Ft void
71 .Fn puffs_setfhsize "struct puffs_usermount *pu" "size_t fhsize" "int flags"
72 .Ft void
73 .Fn puffs_setncookiehash "struct puffs_usermount *pu" "int nhashes"
74 .Ft void
75 .Fn puffs_ml_loop_fn "struct puffs_usermount *pu"
76 .Ft void
77 .Fn puffs_ml_setloopfn "struct puffs_usermount *pu" "puffs_ml_loop_fn lfn"
78 .Ft void
79 .Fn puffs_ml_settimeout "struct puffs_usermount *pu" "struct timespec *ts"
80 .Ft int
81 .Fn puffs_daemon "struct puffs_usermount *pu" "int nochdir" "int noclose"
82 .Ft int
83 .Fn puffs_mainloop "struct puffs_usermount *pu"
84 .Ft int
85 .Fn puffs_unmountonsignal "int sig" "bool ignoresig"
86 .Ft int
87 .Fo puffs_dispatch_create
88 .Fa "struct puffs_usermount *pu" "struct puffs_framebuf *pb"
89 .Fa "struct puffs_cc **pccp"
90 .Fc
91 .Ft int
92 .Fn puffs_dispatch_exec "struct puffs_cc *pcc" "struct puffs_framebuf **pbp"
93 .Sh DESCRIPTION
94 .Nm
95 provides a framework for creating file systems as userspace servers.
96 Operations are transported from the kernel virtual file system layer
97 to the concrete implementation behind
98 .Nm ,
99 where they are processed and results are sent back to the kernel.
100 .Pp
101 It is possible to use
102 .Nm
103 in two different ways.
104 Calling
105 .Fn puffs_mainloop
106 takes execution context away from the caller and automatically handles
107 all requests by using the callbacks.
108 By using
109 .Xr puffs_framebuf 3
110 in conjunction with
111 .Fn puffs_mainloop ,
112 it is possible to handle I/O to and from file descriptors.
113 This is suited e.g. for distributed file servers.
114 .Ss Library operation
115 Operations on the library always require a pointer to the opaque context
116 identifier,
117 .Va struct puffs_usermount .
118 It is obtained by calling
119 .Fn puffs_init .
120 .Pp
121 .Nm
122 operates using operation callbacks.
123 They can be initialized using the macro
124 .Fn PUFFSOP_SET pops fsname type opname ,
125 which will initialize the operation
126 .Fn puffs_type_opname
127 in
128 .Fa pops
129 to
130 .Fn fsname_type_opname .
131 All operations are initialized to a default state with the call
132 .Fn PUFFSOP_INIT pops .
133 All of the VFS routines are mandatory, but all of the node operations
134 with the exception of
135 .Fn puffs_node_lookup
136 are optional.
137 However, leaving operations blank will naturally have an effect on the
138 features available from the file system implementation.
139 .Bl -tag -width xxxx
140 .It Fn puffs_init pops mntfromname puffsname private flags
141 Initializes the library context.
142 .Ar pops
143 specifies the callback operations vector.
144 .Ar mntfromname
145 is device the file system is mounted from.
146 This can be for example a block device such as
147 .Pa /dev/wd0a
148 or, if the file system is pseudo file system, the
149 .Nm
150 device name can be given by
151 .Dv _PATH_PUFFS .
152 This value is used for example in the first column of the output of
153 .Xr mount 8
154 and
155 .Xr df 1 .
156 .Ar puffsname
157 is the file system type.
158 It will always be prepended with the string "puffs|".
159 If possible, file server binaries should be named using the format
160 "mount_myfsnamehere" and this value should equal "myfsnamehere".
161 A file system specific context pointer can optionally be given in
162 .Ar private .
163 This can be retrieved by
164 .Fn puffs_getspecific .
165 Flags for
166 .Nm
167 can be given via
168 .Fa pflags .
169 Currently the following flags are supported:
170 .Bl -tag -width "XPUFFS_KFLAG_LOOKUP_FULLPNBUF"
171 .It Dv PUFFS_KFLAG_NOCACHE_NAME
172 Do not enter pathname components into the name cache.
173 This means that every time the kernel does a lookup for a
174 componentname, the file server will be consulted.
175 .It Dv PUFFS_KFLAG_NOCACHE_PAGE
176 Do not use the page cache.
177 This means that all reads and writes to regular file are
178 propagated to the file server for handling.
179 This option makes a difference only for regular files.
180 .It Dv PUFFS_KFLAG_NOCACHE
181 An alias for both
182 .Dv PUFFS_KFLAG_NOCACHE_NAME
183 and
184 .Dv PUFFS_KFLAG_NOCACHE_PAGE .
185 .It Dv PUFFS_KFLAG_ALLOPS
186 This flag requests that all operations are sent to userspace.
187 Normally the kernel shortcircuits unimplemented operations.
188 This flag is mostly useful for debugging purposes.
189 .It Dv PUFFS_KFLAG_WTCACHE
190 Set the file system cache behavior as write-through.
191 This means that all writes are immediately issued to the file server
192 instead of being flushed in file system sync.
193 This is useful especially for distributed file systems.
194 .It Dv PUFFS_KFLAG_IAONDEMAND
195 Issue inactive only on demand.
196 If a file server defines the inactive method, call it only if the file
197 server has explicitly requested that inactive be called for the
198 node in question.
199 Once inactive has been called for a node, it will not be called
200 again unless the request to call inactive is reissued by the file server.
201 See
202 .Fn puffs_setback
203 in
204 .Xr puffs_ops 3
205 for more information.
206 .It Dv PUFFS_KFLAG_LOOKUP_FULLPNBUF
207 This flag affects only the parameter
208 .Ar pcn to
209 .Fn puffs_node_lookup .
210 If this flag is not given, only the next pathname component under
211 lookup is found from
212 .Ar pcn-\*[Gt]pcn_name .
213 If this flag is given, the full path the kernel was
214 asked to resolve can be found from there.
215 .It Dv PUFFS_FLAG_BUILDPATH
216 The framework will build a complete path name, which is supplied
217 with each operation and can be found from the
218 .Va pn_po.po_full_pcn
219 field in a
220 .Vt struct puffs_node .
221 The option assumes that the framework can map a cookie to a
222 .Vt struct puffs_node .
223 See
224 .Sx Cookies
225 for more information on cookie mapping.
226 See
227 .Xr puffs_path 3
228 for more information on library calls involving paths.
229 .It Dv PUFFS_FLAG_HASHPATH
230 Calculate a hash of the path into the path object field
231 .Va po_hash .
232 This hash value is used by
233 .Fn puffs_path_walkcmp
234 to avoid doing a full comparison for every path equal in length to
235 the one searched for.
236 Especially if the file system uses the abovementioned function, it
237 is a good idea to define this flag.
238 .It Dv PUFFS_FLAG_OPDUMP
239 This option makes the framework dump a textual representation of
240 each operation before executing it.
241 It is useful for debugging purposes.
242 .El
243 .El
244 .Pp
245 The following functions can be used to query or modify the global
246 state of the file system.
247 Note, that all calls are not available at all times.
248 .Bl -tag -width xxxx
249 .It Fn puffs_getselectable "pu"
250 Returns a handle to do I/O multiplexing with:
251 .Xr select 2 ,
252 .Xr poll 2 ,
253 and
254 .Xr kqueue 2
255 are all examples of acceptable operations.
256 .It Fn puffs_setblockingmode "pu" "mode"
257 Sets the file system upstream access to blocking or non-blocking mode.
258 Acceptable values for the argument are
259 .Dv PUFFSDEV_BLOCK
260 and
261 .Dv PUFFSDEV_NONBLOCK .
262 .Pp
263 This routine can be called only after calling
264 .Fn puffs_mount .
265 .It Fn puffs_getstate "pu"
266 Returns the state of the file system.
267 It is maintained by the framework and is mostly useful for the framework
268 itself.
269 Possible values are
270 .Dv PUFFS_STATE_BEFOREMOUNT ,
271 .Dv PUFFS_STATE_RUNNING ,
272 .Dv PUFFS_STATE_UNMOUNTING
273 and
274 .Dv PUFFS_STATE_UNMOUNTED .
275 .It Fn puffs_setstacksize "pu" "stacksize"
276 Sets the stack size used when running callbacks.
277 The default is
278 .Dv PUFFS_STACKSIZE_DEFAULT
279 bytes of stack space per request.
280 The minimum stacksize is architecture-dependent and can be specified
281 by using the opaque constant
282 .Dv PUFFS_STACKSIZE_MIN .
283 .It Fn puffs_setroot "pu" "node"
284 Sets the root node of mount
285 .Fa pu
286 to
287 .Fa "node" .
288 Setting the root node is currently required only if the path
289 framework is used, see
290 .Xr puffs_path 3 .
291 .It Fn puffs_setrootinfo pu vt vsize rdev
292 The default root node is a directory.
293 In case the file system wants something different, it can call this
294 function and set the type, size and possible device type to whatever
295 it wants.
296 This routine is independent of
297 .Fn puffs_setroot .
298 .It Fn puffs_getroot "pu"
299 Returns the root node set earlier.
300 .It Fn puffs_getspecific "pu"
301 Returns the
302 .Fa private
303 argument of
304 .Fn puffs_init .
305 .It Fn puffs_setspecific "pu" "private"
306 Can be used to set the specific data after the call to
307 .Fn puffs_init .
308 .It Fn puffs_setmaxreqlen "pu" "maxreqlen"
309 In case the file system desires a maximum buffer length different from
310 the default, the amount
311 .Fa maxreqlen
312 will be requested from the kernel when the file system is mounted.
313 .Pp
314 It is legal to call this function only between
315 .Fn puffs_init
316 and
317 .Fn puffs_mount .
318 .Pp
319 .Em NOTE
320 This does not currently work.
321 .It Fn puffs_getmaxreqlen "pu"
322 Returns the maximum request length the kernel will need for a single
323 request.
324 .Pp
325 .Em NOTE
326 This does not currently work.
327 .It Fn puffs_setfhsize "pu" "fhsize" "flags"
328 Sets the desired file handle size.
329 This must be called if the file system wishes to support NFS exporting
330 file systems of the
331 .Fn fh*
332 family of function calls.
333 .Pp
334 In case all nodes in the file system produce the same length file handle,
335 it must be supplied as
336 .Fa fhsize .
337 In this case, the file system may ignore the length parameters in the
338 file handle callback routines, as the kernel will always pass the
339 correct length buffer.
340 However, if the file handle size varies according to file, the argument
341 .Fa fhsize
342 defines the maximum size of a file handle for the file system.
343 In this case the file system must take care of the handle lengths by
344 itself in the file handle callbacks, see
345 .Xr puffs_ops 3
346 for more information.
347 Also, the flag
348 .Dv PUFFS_FHFLAG_DYNAMIC
349 must be provided in the argument
350 .Fa flags .
351 .Pp
352 In case the file system wants to sanity check its file handle lengths
353 for the limits of NFS, it can supply
354 .Dv PUFFS_FHFLAG_NFSV2
355 and
356 .Dv PUFFS_FHFLAG_NFSV3
357 in the
358 .Fa flags
359 parameter.
360 It is especially important to note that these are not directly the
361 limits specified by the protocols, as the kernel uses some bytes from
362 the buffer space.
363 In case the file handles are too large, mount will return an error.
364 .Pp
365 It is legal to call this function only between
366 .Fn puffs_init
367 and
368 .Fn puffs_mount .
369 .It Fn puffs_setncookiehash "pu" "ncookiehash"
370 The parameter
371 .Fa ncookiehash
372 controls the amount of hash buckets the kernel has for reverse lookups
373 from cookie to vnode.
374 Technically the default is enough, but a memory/time tradeoff can be
375 made by increasing this for file systems which know they will have
376 very many active files.
377 .Pp
378 It is legal to call this function only between
379 .Fn puffs_init
380 and
381 .Fn puffs_mount .
382 .El
383 .Pp
384 After the correct setup for the library has been established and the
385 backend has been initialized the file system is made operational by calling
386 .Fn puffs_mount .
387 After this function returns the file system should start processing requests.
388 .Bl -tag -width xxxx
389 .It Fn puffs_mount pu dir mntflags root_cookie
390 .Ar pu
391 is the library context pointer from
392 .Fn puffs_init .
393 The argument
394 .Fa dir
395 signifies the mount point and
396 .Fa mntflags
397 is the flagset given to
398 .Xr mount 2 .
399 The value
400 .Ar root_cookie
401 will be used as the cookie for the file system root node.
402 .El
403 .Ss Using the built-in eventloop
404 .Bl -tag -width xxxx
405 .It Fn puffs_ml_loop_fn pu
406 Loop function signature.
407 .It Fn puffs_ml_setloopfn pu lfn
408 Set loop function to
409 .Ar lfn .
410 This function is called once each time the event loop loops.
411 It is not a well-defined interval, but it can be made fairly regular
412 by setting the loop timeout by
413 .Fn puffs_ml_settimeout .
414 .It Fn puffs_ml_settimeout pu ts
415 Sets the loop timeout to
416 .Ar ts
417 or disables it if
418 .Ar ts
419 is
420 .Dv NULL .
421 This can be used to roughly control how often the loop callback
422 .Fn lfn
423 is called
424 .It Fn puffs_daemon pu nochdir noclose
425 Detach from the console like
426 .Fn daemon 3 .
427 This call synchronizes with
428 .Fn puffs_mount
429 and the foreground process does not exit before the file system mount
430 call has returned from the kernel.
431 Since this routine internally calls fork, it has to be called
432 .Em before
433 .Fn puffs_mount .
434 .It Fn puffs_mainloop pu flags
435 Handle all requests automatically until the file system is unmounted.
436 It returns 0 if the file system was successfully unmounted or \-1 if it
437 was killed in action.
438 .Pp
439 In case
440 .Xr puffs_framebuf 3
441 has been initialized, I/O from the relevant descriptors is processed
442 automatically by the eventloop.
443 .It Fn puffs_unmountonsignal signum ignoresig
444 Cause all file servers within the process to initiate unmount upon
445 receipt of signal
446 .Ar signum .
447 This works only for servers which call
448 .Fn puffs_mainloop
449 and must be called before any server within the process enters the mainloop.
450 The process signal handler is still called before starting the unmount
451 procedure.
452 The parameter
453 .Ar ignoresig
454 is provided as a convenience and tells if to install a signal handler
455 to ignore
456 .Ar sig
457 so that the process will not e.g. terminate based on the default action
458 before the file system unmount can be initiated.
459 .It Fn puffs_dispatch_create pu pb pccp
460 .It Fn puffs_dispatch_exec pcc pbp
461 In case the use of
462 .Fn puffs_mainloop
463 is not possible, requests may be dispatched manually.
464 However, as this is less efficient than using the mainloop,
465 it should never be the first preference.
466 .Pp
467 Calling
468 .Fn puffs_dispatch_create
469 creates a dispatch request.
470 The argument
471 .Ar pb
472 should contains a valid request and upon success
473 .Ar pccp
474 will contain a valid request context.
475 This context is passed to
476 .Fn puffs_dispatch_exec
477 to execute the request.
478 If the request yielded before completing, the routine returns 0,
479 otherwise 1.
480 When the routine completes,
481 .Ar pcc
482 is made invalid and a pointer to the processed buffer is placed in
483 .Ar pbp .
484 It is the responsibility of the caller to send the response (if
485 necessary) and destroy the buffer.
486 .Pp
487 See
488 .Xr puffs_cc 3
489 and
490 .Xr puffs_framebuf 3
491 for further information.
492 .El
493 .Ss Cookies
494 Every file (regular file, directory, device node, ...) instance is
495 attached to the kernel using a cookie.
496 A cookie should uniquely map to a file during its lifetime.
497 If file instances are kept in memory, a simple strategy is to use
498 the virtual address of the structure describing the file.
499 The cookie can be recycled when
500 .Fn puffs_node_reclaim
501 is called for a node.
502 .Pp
503 For some operations (such as building paths) the framework needs to map
504 the cookie to the framework-level structure describing a file,
505 .Vt struct puffs_node .
506 It is advisable to simply use the
507 .Vt struct puffs_node
508 address as a cookie and store file system specific data in the private
509 portion of
510 .Vt struct puffs_node .
511 The library assumes this by default.
512 If it is not desirable, the file system implementation can call
513 .Fn puffs_set_cookiemap
514 to provide an alternative cookie-to-node mapping function.
515 .Sh SEE ALSO
516 .Xr mount 2 ,
517 .Xr puffs_cc 3 ,
518 .Xr puffs_cred 3 ,
519 .Xr puffs_flush 3 ,
520 .Xr puffs_framebuf 3 ,
521 .Xr puffs_node 3 ,
522 .Xr puffs_ops 3 ,
523 .Xr puffs_path 3 ,
524 .\".Xr puffs_suspend 3 ,
525 .Xr refuse 3 ,
526 .Xr puffs 4
527 .Rs
528 .%A Antti Kantee
529 .%D March 2007
530 .%J Proceedings of AsiaBSDCon 2007
531 .%P pp. 29-42
532 .%T puffs - Pass-to-Userspace Framework File System
533 .Re
534 .Rs
535 .%A Antti Kantee
536 .%D September 2007
537 .%I Helsinki University of Technology
538 .%R Tech Report TKK-TKO-B157
539 .%T Using puffs for Implementing Client-Server Distributed File Systems
540 .Re
541 .Rs
542 .%A Antti Kantee
543 .%A Alistair Crooks
544 .%D September 2007
545 .%J EuroBSDCon 2007
546 .%T ReFUSE: Userspace FUSE Reimplementation Using puffs
547 .Re
548 .Rs
549 .%A Antti Kantee
550 .%D March 2008
551 .%J Proceedings of AsiaBSDCon 2008
552 .%P pp. 55-70
553 .%T Send and Receive of File System Protocols: Userspace Approach With puffs
554 .Re
555 .Sh HISTORY
556 An unsupported experimental version of
557 .Nm
558 first appeared in
559 .Nx 4.0 .
560 A stable version appeared in
561 .Nx 5.0 .
562 .Sh AUTHORS
563 .An Antti Kantee Aq pooka@iki.fi