kernel: separate state for trace-deferred syscalls
[minix.git] / lib / libpuffs / puffs.3
blobabc276d87c74cf6728ef884130cbfb2befdc03ed
1 .\"     $NetBSD: puffs.3,v 1.42.4.2 2009/10/16 12:07:23 sborrill 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 September 6, 2008
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 .Fo puffs_dispatch_create
86 .Fa "struct puffs_usermount *pu" "struct puffs_framebuf *pb"
87 .Fa "struct puffs_cc **pccp"
88 .Fc
89 .Ft int
90 .Fn puffs_dispatch_exec .Fa "struct puffs_cc *pcc" "struct puffs_framebuf **pbp"
91 .Sh DESCRIPTION
92 .Nm
93 provides a framework for creating file systems as userspace servers.
94 Operations are transported from the kernel virtual file system layer
95 to the concrete implementation behind
96 .Nm ,
97 where they are processed and results are sent back to the kernel.
98 .Pp
99 It is possible to use
101 in two different ways.
102 Calling
103 .Fn puffs_mainloop
104 takes execution context away from the caller and automatically handles
105 all requests by using the callbacks.
106 By using
107 .Xr puffs_framebuf 3
108 in conjuction with
109 .Fn puffs_mainloop ,
110 it is possible to handle I/O to and from file descriptors.
111 This is suited e.g. for distributed file servers.
112 .Ss Library operation
113 Operations on the library always require a pointer to the opaque context
114 identifier,
115 .Va struct puffs_usermount .
116 It is obtained by calling
117 .Fn puffs_init .
120 operates using operation callbacks.
121 They can be initialized using the macro
122 .Fn PUFFSOP_SET pops fsname type opname ,
123 which will initialize the operation
124 .Fn puffs_type_opname
126 .Fa pops
128 .Fn fsname_type_opname .
129 All operations are initialized to a default state with the call
130 .Fn PUFFSOP_INIT pops .
131 All of the VFS routines are mandatory, but all of the node operations
132 with the exception of
133 .Fn puffs_node_lookup
134 are optional.
135 However, leaving operations blank will naturally have an effect on the
136 features available from the file system implementation.
137 .Bl -tag -width xxxx
138 .It Fn puffs_init pops mntfromname puffsname private flags
139 Initializes the library context.
140 .Ar pops
141 specifies the callback operations vector.
142 .Ar mntfromname
143 is device the file system is mounted from.
144 This can be for example a block device such as
145 .Pa /dev/wd0a
146 or, if the file system is pseudo file system, the
148 device name can be given by
149 .Dv _PATH_PUFFS .
150 This value is used for example in the first column of the output of
151 .Xr mount 8
153 .Xr df 1 .
154 .Ar puffsname
155 is the file system type.
156 It will always be prepended with the string "puffs|".
157 If possible, file server binaries should be named using the format
158 "mount_myfsnamehere" and this value should equal "myfsnamehere".
159 A file system specific context pointer can optionally be given in
160 .Ar private .
161 This can be retrieved by
162 .Fn puffs_getspecific .
163 Flags for
165 can be given via
166 .Fa pflags .
167 Currently the following flags are supported:
168 .Bl -tag -width "XPUFFS_KFLAG_LOOKUP_FULLPNBUF"
169 .It Dv PUFFS_KFLAG_NOCACHE_NAME
170 Do not enter pathname components into the name cache.
171 This means that every time the kernel does a lookup for a
172 componentname, the file server will be consulted.
173 .It Dv PUFFS_KFLAG_NOCACHE_PAGE
174 Do not use the page cache.
175 This means that all reads and writes to regular file are
176 propagated to the file server for handling.
177 This option makes a difference only for regular files.
178 .It Dv PUFFS_KFLAG_NOCACHE
179 An alias for both
180 .Dv PUFFS_KFLAG_NOCACHE_NAME
182 .Dv PUFFS_KFLAG_NOCACHE_PAGE .
183 .It Dv PUFFS_KFLAG_ALLOPS
184 This flag requests that all operations are sent to userspace.
185 Normally the kernel shortcircuits unimplemented operations.
186 This flag is mostly useful for debugging purposes.
187 .It Dv PUFFS_KFLAG_WTCACHE
188 Set the file system cache behavior as write-through.
189 This means that all writes are immediately issued to the file server
190 instead of being flushed in file system sync.
191 This is useful especially for distributed file systems.
192 .It Dv PUFFS_KFLAG_IAONDEMAND
193 Issue inactive only on demand.
194 If a file server defines the inactive method, call it only if the file
195 server has explicitly requested that inactive be called for the
196 node in question.
197 Once inactive has been called for a node, it will not be called
198 again unless the request to call inactive is reissued by the file server.
200 .Fn puffs_setback
202 .Xr puffs_ops 3
203 for more information.
204 .It Dv PUFFS_KFLAG_LOOKUP_FULLPNBUF
205 This flag affects only the parameter
206 .Ar pcn to
207 .Fn puffs_node_lookup .
208 If this flag is not given, only the next pathname component under
209 lookup is found from
210 .Ar pcn-\*[Gt]pcn_name .
211 If this flag is given, the full path the kernel was
212 asked to resolve can be found from there.
213 .It Dv PUFFS_FLAG_BUILDPATH
214 The framework will build a complete path name, which is supplied
215 with each operation and can be found from the
216 .Va pcn_po_full.po_path
217 field in a
218 .Vt struct puffs_cn .
219 The option assumes that the framework can map a cookie to a
220 .Vt struct puffs_node .
222 .Sx Cookies
223 for more information on cookie mapping.
225 .Xr puffs_path 3
226 for more information on library calls involving paths.
227 .It Dv PUFFS_FLAG_HASHPATH
228 Calculate a hash of the path into the path object field
229 .Va po_hash .
230 This hash value is used by
231 .Fn puffs_path_walkcmp
232 to avoid doing a full comparison for every path equal in length to
233 the one searched for.
234 Especially if the file system uses the abovementioned function, it
235 is a good idea to define this flag.
236 .It Dv PUFFS_FLAG_OPDUMP
237 This option makes the framework dump a textual representation of
238 each operation before executing it.
239 It is useful for debugging purposes.
243 The following functions can be used to query or modify the global
244 state of the file system.
245 Note, that all calls are not available at all times.
246 .Bl -tag -width xxxx
247 .It Fn puffs_getselectable "pu"
248 Returns a handle to do I/O multiplexing with:
249 .Xr select 2 ,
250 .Xr poll 2 ,
252 .Xr kqueue 2
253 are all examples of acceptable operations.
254 .It Fn puffs_setblockingmode "pu" "mode"
255 Sets the file system upstream access to blocking or non-blocking mode.
256 Acceptable values for the argument are
257 .Dv PUFFSDEV_BLOCK
259 .Dv PUFFSDEV_NONBLOCK .
261 This routine can be called only after calling
262 .Fn puffs_mount .
263 .It Fn puffs_getstate "pu"
264 Returns the state of the file system.
265 It is maintained by the framework and is mostly useful for the framework
266 itself.
267 Possible values are
268 .Dv PUFFS_STATE_BEFOREMOUNT ,
269 .Dv PUFFS_STATE_RUNNING ,
270 .Dv PUFFS_STATE_UNMOUNTING
272 .Dv PUFFS_STATE_UNMOUNTED .
273 .It Fn puffs_setstacksize "pu" "stacksize"
274 Sets the stack size used when running callbacks.
275 The default is
276 .Dv PUFFS_STACKSIZE_DEFAULT
277 bytes of stack space per request.
278 The minimum stacksize is architecture-dependent and can be specified
279 by using the opaque constant
280 .Dv PUFFS_STACKSIZE_MIN .
281 .It Fn puffs_setroot "pu" "node"
282 Sets the root node of mount
283 .Fa pu
285 .Fa "node" .
286 Setting the root node is currently required only if the path
287 framework is used, see
288 .Xr puffs_path 3 .
289 .It Fn puffs_setrootinfo pu vt vsize rdev
290 The default root node is a directory.
291 In case the file system wants something different, it can call this
292 function and set the type, size and possible device type to whatever
293 it wants.
294 This routine is independent of
295 .Fn puffs_setroot .
296 .It Fn puffs_getroot "pu"
297 Returns the root node set earlier.
298 .It Fn puffs_getspecific "pu"
299 Returns the
300 .Fa private
301 argument of
302 .Fn puffs_init .
303 .It Fn puffs_setspecific "pu" "private"
304 Can be used to set the specific data after the call to
305 .Fn puffs_init .
306 .It Fn puffs_setmaxreqlen "pu" "maxreqlen"
307 In case the file system desires a maximum buffer length different from
308 the default, the amount
309 .Fa maxreqlen
310 will be requested from the kernel when the file system is mounted.
312 It is legal to call this function only between
313 .Fn puffs_init
315 .Fn puffs_mount .
317 .Em NOTE
318 This does not currently work.
319 .It Fn puffs_getmaxreqlen "pu"
320 Returns the maximum request length the kernel will need for a single
321 request.
323 .Em NOTE
324 This does not currently work.
325 .It Fn puffs_setfhsize "pu" "fhsize" "flags"
326 Sets the desired file handle size.
327 This must be called if the file system wishes to support NFS exporting
328 file systems of the
329 .Fn fh*
330 family of function calls.
332 In case all nodes in the file system produce the same length file handle,
333 it must be supplied as
334 .Fa fhsize .
335 In this case, the file system may ignore the length parameters in the
336 file handle callback routines, as the kernel will always pass the
337 correct length buffer.
338 However, if the file handle size varies according to file, the argument
339 .Fa fhsize
340 defines the maximum size of a file handle for the file system.
341 In this case the file system must take care of the handle lengths by
342 itself in the file handle callbacks, see
343 .Xr puffs_ops 3
344 for more information.
345 Also, the flag
346 .Dv PUFFS_FHFLAG_DYNAMIC
347 must be provided in the argument
348 .Fa flags .
350 In case the file system wants to sanity check its file handle lengths
351 for the limits of NFS, it can supply
352 .Dv PUFFS_FHFLAG_NFSV2
354 .Dv PUFFS_FHFLAG_NFSV3
355 in the
356 .Fa flags
357 parameter.
358 It is especially important to note that these are not directly the
359 limits specified by the protocols, as the kernel uses some bytes from
360 the buffer space.
361 In case the file handles are too large, mount will return an error.
363 It is legal to call this function only between
364 .Fn puffs_init
366 .Fn puffs_mount .
367 .It Fn puffs_setncookiehash "pu" "ncookiehash"
368 The parameter
369 .Fa ncookiehash
370 controls the amount of hash buckets the kernel has for reverse lookups
371 from cookie to vnode.
372 Technically the default is enough, but a memory/time tradeoff can be
373 made by increasing this for file systems which know they will have
374 very many active files.
376 It is legal to call this function only between
377 .Fn puffs_init
379 .Fn puffs_mount .
382 After the correct setup for the library has been established and the
383 backend has been initialized the file system is made operational by calling
384 .Fn puffs_mount .
385 After this function returns the file system should start processing requests.
386 .Bl -tag -width xxxx
387 .It Fn puffs_mount pu dir mntflags root_cookie
388 .Ar pu
389 is the library context pointer from
390 .Fn puffs_init .
391 The argument
392 .Fa dir
393 signifies the mount point and
394 .Fa mntflags
395 is the flagset given to
396 .Xr mount 2 .
397 The value
398 .Ar root_cookie
399 will be used as the cookie for the file system root node.
401 .Ss Using the built-in eventloop
402 .Bl -tag -width xxxx
403 .It Fn puffs_ml_loop_fn pu
404 Loop function signature.
405 .It Fn puffs_ml_setloopfn pu lfn
406 Set loop function to
407 .Ar lfn .
408 This function is called once each time the event loop loops.
409 It is not a well-defined interval, but it can be made fairly regular
410 by setting the loop timeout by
411 .Fn puffs_ml_settimeout .
412 .It Fn puffs_ml_settimeout pu ts
413 Sets the loop timeout to
414 .Ar ts
415 or disables it if
416 .Ar ts
418 .Dv NULL .
419 This can be used to roughly control how often the loop callback
420 .Fn lfn
421 is called
422 .It Fn puffs_daemon pu nochdir noclose
423 Detach from the console like
424 .Fn daemon 3 .
425 This call synchronizes with
426 .Fn puffs_mount
427 and the foreground process does not exit before the file system mount
428 call has returned from the kernel.
429 .It Fn puffs_mainloop pu flags
430 Handle all requests automatically until the file system is unmounted.
431 It returns 0 if the file system was successfully unmounted or \-1 if it
432 was killed in action.
434 In case
435 .Xr puffs_framebuf 3
436 has been initialized, I/O from the relevant descriptors is processed
437 automatically by the eventloop.
438 .It Fn puffs_dispatch_create pu pb pccp
439 .It Fn puffs_dispatch_exec pcc pbp
440 In case the use of
441 .Fn puffs_mainloop
442 is not possible, requests may be dispatched manually.
443 However, as this is less efficient than using the mainloop,
444 it should never be the first preference.
446 Calling
447 .Fn puffs_dispatch_create
448 creates a dispatch request.
449 The argument
450 .Ar pb
451 should contains a valid request and upon success
452 .Ar pccp
453 will contain a valid request context.
454 This context is passed to
455 .Fn puffs_dispatch_exec
456 to execute the request.
457 If the request yielded before completing, the routine returns 0,
458 otherwise 1.
459 When the routine completes,
460 .Ar pcc
461 is made invalid and a pointer to the processed buffer is placed in
462 .Ar pbp .
463 It is the responsibility of the caller to send the response (if
464 necessary) and destroy the buffer.
467 .Xr puffs_cc 3
469 .Xr puffs_framebuf 3
470 for further information.
472 .Ss Cookies
473 Every file (regular file, directory, device node, ...) instance is
474 attached to the kernel using a cookie.
475 A cookie should uniquely map to a file during its lifetime.
476 If file instances are kept in memory, a simple strategy is to use
477 the virtual address of the structure describing the file.
478 The cookie can be recycled when
479 .Fn puffs_node_reclaim
480 is called for a node.
482 For some operations (such as building paths) the framework needs to map
483 the cookie to the framework-level structure describing a file,
484 .Vt struct puffs_node .
485 It is advisable to simply use the
486 .Vt struct puffs_node
487 address as a cookie and store file system specific data in the private
488 portion of
489 .Vt struct puffs_node .
490 The library assumes this by default.
491 If it is not desirable, the file system implementation can call
492 .Fn puffs_set_cookiemap
493 to provide an alternative cookie-to-node mapping function.
494 .Sh SEE ALSO
495 .Xr mount 2 ,
496 .Xr puffs_cc 3 ,
497 .Xr puffs_cred 3 ,
498 .Xr puffs_flush 3 ,
499 .Xr puffs_framebuf 3 ,
500 .Xr puffs_node 3 ,
501 .Xr puffs_ops 3 ,
502 .Xr puffs_path 3 ,
503 .Xr puffs_suspend 3 ,
504 .Xr refuse 3 ,
505 .Xr puffs 4
507 .%A Antti Kantee
508 .%D March 2007
509 .%J Proceedings of AsiaBSDCon 2007
510 .%P pp. 29-42
511 .%T puffs - Pass-to-Userspace Framework File System
514 .%A Antti Kantee
515 .%D September 2007
516 .%I Helsinki University of Technology
517 .%R Tech Report TKK-TKO-B157
518 .%T Using puffs for Implementing Client-Server Distributed File Systems
521 .%A Antti Kantee
522 .%A Alistair Crooks
523 .%D September 2007
524 .%J EuroBSDCon 2007
525 .%T ReFUSE: Userspace FUSE Reimplementation Using puffs
528 .%A Antti Kantee
529 .%D March 2008
530 .%J Proceedings of AsiaBSDCon 2008
531 .%P pp. 55-70
532 .%T Send and Receive of File System Protocols: Userspace Approach With puffs
534 .Sh HISTORY
535 An unsupported experimental version of
537 first appeared in
538 .Nx 4.0 .
539 A stable version appeared in
540 .Nx 5.0 .
541 .Sh AUTHORS
542 .An Antti Kantee Aq pooka@iki.fi