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