1 .\" $NetBSD: puffs.3,v 1.42.4.2 2009/10/16 12:07:23 sborrill Exp $
3 .\" Copyright (c) 2006, 2007, 2008 Antti Kantee. All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
31 .Nd Pass-to-Userspace Framework File System development interface
36 .Ft struct puffs_usermount *
38 .Fa "struct puffs_ops *pops" "const char *mntfromname" "const char *puffsname"
39 .Fa "void *private" "uint32_t flags"
43 .Fa "struct puffs_usermount *pu" "const char *dir" "int mntflags"
44 .Fa "puffs_cookie_t root_cookie"
47 .Fn puffs_getselectable "struct puffs_usermount *pu"
49 .Fn puffs_setblockingmode "struct puffs_usermount *pu" "int mode"
51 .Fn puffs_getstate "struct puffs_usermount *pu"
53 .Fn puffs_setstacksize "struct puffs_usermount *pu" "size_t stacksize"
55 .Fn puffs_setroot "struct puffs_usermount *pu" "struct puffs_node *node"
58 .Fa "struct puffs_usermount *pu" "enum vtype vt" "vsize_t vsize" "dev_t rdev"
60 .Ft struct puffs_node *
61 .Fn puffs_getroot "struct puffs_usermount *pu"
63 .Fn puffs_getspecific "struct puffs_usermount *pu"
65 .Fn puffs_setspecific "struct puffs_usermount *pu" "void *private"
67 .Fn puffs_setmaxreqlen "struct puffs_usermount *pu" "size_t maxreqlen"
69 .Fn puffs_getmaxreqlen "struct puffs_usermount *pu"
71 .Fn puffs_setfhsize "struct puffs_usermount *pu" "size_t fhsize" "int flags"
73 .Fn puffs_setncookiehash "struct puffs_usermount *pu" "int nhashes"
75 .Fn puffs_ml_loop_fn "struct puffs_usermount *pu"
77 .Fn puffs_ml_setloopfn "struct puffs_usermount *pu" "puffs_ml_loop_fn lfn"
79 .Fn puffs_ml_settimeout "struct puffs_usermount *pu" "struct timespec *ts"
81 .Fn puffs_daemon "struct puffs_usermount *pu" "int nochdir" "int noclose"
83 .Fn puffs_mainloop "struct puffs_usermount *pu"
85 .Fo puffs_dispatch_create
86 .Fa "struct puffs_usermount *pu" "struct puffs_framebuf *pb"
87 .Fa "struct puffs_cc **pccp"
90 .Fn puffs_dispatch_exec .Fa "struct puffs_cc *pcc" "struct puffs_framebuf **pbp"
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
97 where they are processed and results are sent back to the kernel.
101 in two different ways.
104 takes execution context away from the caller and automatically handles
105 all requests by using the callbacks.
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
115 .Va struct puffs_usermount .
116 It is obtained by calling
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
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
135 However, leaving operations blank will naturally have an effect on the
136 features available from the file system implementation.
138 .It Fn puffs_init pops mntfromname puffsname private flags
139 Initializes the library context.
141 specifies the callback operations vector.
143 is device the file system is mounted from.
144 This can be for example a block device such as
146 or, if the file system is pseudo file system, the
148 device name can be given by
150 This value is used for example in the first column of the output of
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
161 This can be retrieved by
162 .Fn puffs_getspecific .
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
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
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.
203 for more information.
204 .It Dv PUFFS_KFLAG_LOOKUP_FULLPNBUF
205 This flag affects only the parameter
207 .Fn puffs_node_lookup .
208 If this flag is not given, only the next pathname component under
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
218 .Vt struct puffs_cn .
219 The option assumes that the framework can map a cookie to a
220 .Vt struct puffs_node .
223 for more information on cookie mapping.
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
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.
247 .It Fn puffs_getselectable "pu"
248 Returns a handle to do I/O multiplexing with:
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
259 .Dv PUFFSDEV_NONBLOCK .
261 This routine can be called only after calling
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
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.
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
286 Setting the root node is currently required only if the path
287 framework is used, see
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
294 This routine is independent of
296 .It Fn puffs_getroot "pu"
297 Returns the root node set earlier.
298 .It Fn puffs_getspecific "pu"
303 .It Fn puffs_setspecific "pu" "private"
304 Can be used to set the specific data after the call to
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
310 will be requested from the kernel when the file system is mounted.
312 It is legal to call this function only between
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
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
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
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
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
344 for more information.
346 .Dv PUFFS_FHFLAG_DYNAMIC
347 must be provided in the argument
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
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
361 In case the file handles are too large, mount will return an error.
363 It is legal to call this function only between
367 .It Fn puffs_setncookiehash "pu" "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
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
385 After this function returns the file system should start processing requests.
387 .It Fn puffs_mount pu dir mntflags root_cookie
389 is the library context pointer from
393 signifies the mount point and
395 is the flagset given to
399 will be used as the cookie for the file system root node.
401 .Ss Using the built-in eventloop
403 .It Fn puffs_ml_loop_fn pu
404 Loop function signature.
405 .It Fn puffs_ml_setloopfn pu 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
419 This can be used to roughly control how often the loop callback
422 .It Fn puffs_daemon pu nochdir noclose
423 Detach from the console like
425 This call synchronizes with
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.
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
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.
447 .Fn puffs_dispatch_create
448 creates a dispatch request.
451 should contains a valid request and upon success
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,
459 When the routine completes,
461 is made invalid and a pointer to the processed buffer is placed in
463 It is the responsibility of the caller to send the response (if
464 necessary) and destroy the buffer.
470 for further information.
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
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.
499 .Xr puffs_framebuf 3 ,
503 .Xr puffs_suspend 3 ,
509 .%J Proceedings of AsiaBSDCon 2007
511 .%T puffs - Pass-to-Userspace Framework File System
516 .%I Helsinki University of Technology
517 .%R Tech Report TKK-TKO-B157
518 .%T Using puffs for Implementing Client-Server Distributed File Systems
525 .%T ReFUSE: Userspace FUSE Reimplementation Using puffs
530 .%J Proceedings of AsiaBSDCon 2008
532 .%T Send and Receive of File System Protocols: Userspace Approach With puffs
535 An unsupported experimental version of
539 A stable version appeared in
542 .An Antti Kantee Aq pooka@iki.fi