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