1.\" $NetBSD: puffs.4,v 1.5 2007/03/13 17:06:10 pooka Exp $ 2.\" 3.\" Copyright (c) 2006 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 December 1, 2006 27.Dt PUFFS 4 28.Os 29.Sh NAME 30.Nm puffs 31.Nd Pass-to-Userspace Framework File System 32.Sh SYNOPSIS 33.Cd "file-system PUFFS" 34.Sh DESCRIPTION 35.Em IMPORTANT NOTE! 36This document describes interfaces which are not yet guaranteed to be 37stable. 38In case you update your system sources, please recompile everything 39and fix complation errors. 40If your sources are out-of-sync, incorrect operation may result. 41.Pp 42.Nm 43provides a framework for creating file systems as userspace servers. 44The in-kernel VFS attachment is controlled through a special device 45node, 46.Pa /dev/puffs . 47This document describes the operations on the device. 48People looking to implement file systems should prefer using the 49system through the convenience library described in 50.Xr puffs 3 . 51Users wanting to access the device node directly should include 52the header 53.Pa sys/fs/puffs/puffs_msgif.h 54for relevant definitions. 55.Ss Mounting 56The 57.Nm 58device node should be opened once per file system instance (i.e. mount). 59The device itself is a cloning node, so the same node can be opened 60a practically unlimited number of times. 61Once the device is open, the file system can be mounted the normal 62way using the 63.Xr mount 2 64system call and using the argument structure to control mount options: 65.Bd -literal -offset indent 66struct puffs_args { 67 int pa_vers; 68 int pa_fd; 69 unsigned int pa_flags; 70 size_t pa_maxreqlen; 71 char pa_name[PUFFSNAMESIZE]; 72 uint8_t pa_vnopmask[PUFFS_VN_MAX]; 73}; 74.Ed 75.Pp 76The member 77.Va pa_vers 78is currently always 0 and ignored. 79The 80.Va pa_fd 81member is the file descriptor number from opening the device node. 82.Va pa_flags 83controls some operations specific to puffs: 84.Bl -tag -width "PUFFS_KFLAG_ALLOWCTL" 85.It Dv PUFFS_KFLAG_ALLOWCTL 86Allow file system fcntl and ioctl operations. 87Allowing these has security implications as the file system can 88technically read anything out of a calling processes address space. 89This flag may additionally be enforced by the kernel security policy. 90.It Dv PUFFS_KFLAG_NOCACHE 91Do not store data in the page cache. 92This causes operations to always consult the user server instead of 93consulting the page cache. 94This makes sense in situations where there is relatively little 95bulk data to be transferred and the user server does not want to take 96part in complex cache management routines in case the file system data 97can be modified through routes other than the file system interface. 98.It Dv PUFFS_KFLAG_ALLOPS 99Transport all vnode operations to the file system server instead of just 100the ones specified by 101.Va pa_vnopmask . 102.El 103.Pp 104The 105.Va pa_maxreqlen 106member signifies the length of the incoming data buffer in userspace. 107A good value is 108.Dv PUFFS_REQ_MAXSIZE , 109which is the maximum the kernel will use. 110A minimum value is also enforced, so the value of this field should 111be checked after the mount operation to determine the correct buffer 112size. 113During operation, in case request fetch is attempted with a buffer 114too short, the error 115.Er E2BIG 116will be returned. 117The file system type is give in 118.Va pa_name . 119It will always be prepended by "puffs:" by the kernel. 120Finally, the array 121.Va pa_vnopmask 122specifies which operations are supported by the file system server. 123The array is indexed with 124.Dv PUFFS_VN_FOO 125and 0 means vnode operation 126.Dv FOO 127is unimplemented while non-zero means an implemented operation. 128This array is ignored if 129.Dv PUFFS_KFLAG_ALLOPS 130is given. 131.Pp 132After a succesful mount system call, the the ioctl 133.Dv PUFFSSTARTOP 134must be issued through the open device node. 135The parameter for this ioctl is the following structure: 136.Bd -literal -offset indent 137struct puffs_startreq { 138 void *psr_cookie; 139 struct statvfs psr_sb; 140}; 141.Ed 142.Pp 143The member 144.Va psr_cookie 145should be set before calling. 146This signals the cookie value of the root node of the file system 147(see 148.Xr puffs 3 149for more details on cookie strategies). 150The value of 151.Va psr_sb 152should be filled with the same results as for a regular statvfs 153call. 154After successfully executing this operation the file system is 155active. 156.Ss Operation 157Operations must be queried from the kernel using the ioctl 158.Dv PUFFSGETOP , 159processed, and the results pushed back to the kernel using 160.Dv PUFFSPUTOP . 161Normally the system will block until an event is available for 162.Dv PUFFSGETOP , 163but it is possible to set the file descriptor into non-blocking 164mode, in which case 165.Er EWOULDBLOCK 166is returned if no event is available. 167Asynchoronous I/O calls (i.e., 168.Xr select 2 , 169.Xr poll 2 , 170and 171.Xr kevent 2 ) 172can be issued to be notified of events. 173.Pp 174As the argument both get and push use the following structure: 175.Bd -literal -offset indent 176struct puffs_req { 177 uint64_t preq_id; 178 uint8_t preq_opclass; 179 uint8_t preq_optype; 180 void *preq_cookie; 181 182 int preq_rv; 183 184 void *preq_aux; 185 size_t preq_auxlen; 186}; 187.Ed 188.Pp 189The member 190.Va preq_id 191is used as an identifier in the reply. 192It should not be modified during the processing of a 193.Dv PUFFSGETOP - 194.Dv PUFFSPUTOP 195sequence. 196The members 197.Va preq_opclass 198and 199.Va preq_optype 200identify the request; they also are used for typing the data 201pointed to by 202.Va preq_aux . 203Currently the mapping between these two is only documented in 204code in 205.Pa src/lib/libpuffs/puff.c:puffcall() . 206The handling of this will very likely change in the future towards 207a more automatic direction. 208The length of the buffer given to 209.Dv PUFFSGETOP 210is described by 211.Va preq_auxlen 212and will be modified by the kernel to indicate how much data 213actually was transmitted. 214This is for the benefit of calls such as write, which transmit a 215variable amount of data. 216Similarly, the user server should fill in the amount of data the 217kernel must copy for 218.Dv PUFFSPUTOP ; 219most of the time this will be constant for a given operation, but 220operations such as read want to adjust it dynamically. 221Finally, 222.Va preq_rv 223is used by the userspace server to fill in the success value of the 224operation in question. 225.Pp 226In case the macro 227.Fn PUFFSOP_WANTREPLY 228returns false for 229.Va preq_opclass , 230a return value is not wanted and 231.Dv PUFFSPUTOP 232should not be issued. 233.Pp 234Additionally, an operation of type 235.Dv PUFFSSIZEOP 236is supported, but it is only used by the ioctl and fcntl operations 237and will likely go away in the future. 238It is not described here. 239.Ss Termination 240The file system can be unmounted regularly using 241.Xr umount 8 . 242It will automatically be unmounted in case the userspace server is 243killed or the control file descriptor closed, but in this case the 244userspace server will not be separately requested to unmount itself 245and this may result in data loss. 246.Sh SEE ALSO 247.Xr ioctl 2 , 248.Xr mount 2 , 249.Xr puffs 3 , 250.Xr umount 8 251.Rs 252.%A Antti Kantee 253.%D March 2007 254.%J Proceedings of AsiaBSDCon 2007 255.%P pp. 29-42 256.%T puffs - Pass-to-Userspace Framework File System 257.Re 258.Sh HISTORY 259An unsupported experimental version of 260.Nm 261first appeared in 262.Nx 4.0 . 263.Sh AUTHORS 264.An Antti Kantee Aq pooka@iki.fi 265.Sh BUGS 266.Nm 267is currently more like a souffle than puff pastry. 268