NetBSD-5.0.2/share/man/man4/puffs.4
.\" $NetBSD: puffs.4,v 1.8 2008/04/13 16:02:33 pooka Exp $
.\"
.\" Copyright (c) 2006 Antti Kantee. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd December 1, 2006
.Dt PUFFS 4
.Os
.Sh NAME
.Nm puffs
.Nd Pass-to-Userspace Framework File System
.Sh SYNOPSIS
.Cd "file-system PUFFS"
.Cd "pseudo-device putter"
.Sh DESCRIPTION
.Em THIS DOCUMENT IS HOPELESSLY OUT OF DATE .
While some parts are still valid, please refer to the source
code for current reality.
.Pp
.Em IMPORTANT NOTE!
This document describes interfaces which are not yet guaranteed to be
stable.
In case you update your system sources, please recompile everything
and fix compilation errors.
If your sources are out-of-sync, incorrect operation may result.
.Pp
.Nm
provides a framework for creating file systems as userspace servers.
The in-kernel VFS attachment is controlled through a special device
node,
.Pa /dev/puffs .
This document describes the operations on the device.
People looking to implement file systems should prefer using the
system through the convenience library described in
.Xr puffs 3 .
Users wanting to access the device node directly should include
the header
.Pa sys/fs/puffs/puffs_msgif.h
for relevant definitions.
.Ss Mounting
The
.Nm
device node should be opened once per file system instance (i.e. mount).
The device itself is a cloning node, so the same node can be opened
a practically unlimited number of times.
Once the device is open, the file system can be mounted the normal
way using the
.Xr mount 2
system call and using the argument structure to control mount options:
.Bd -literal -offset indent
struct puffs_args {
int pa_vers;
int pa_fd;
unsigned int pa_flags;
size_t pa_maxreqlen;
char pa_name[PUFFSNAMESIZE];
uint8_t pa_vnopmask[PUFFS_VN_MAX];
};
.Ed
.Pp
The member
.Va pa_vers
is currently always 0 and ignored.
The
.Va pa_fd
member is the file descriptor number from opening the device node.
.Va pa_flags
controls some operations specific to puffs:
.Bl -tag -width "PUFFS_KFLAG_ALLOWCTL"
.It Dv PUFFS_KFLAG_ALLOWCTL
Allow file system fcntl and ioctl operations.
Allowing these has security implications as the file system can
technically read anything out of a calling processes address space.
This flag may additionally be enforced by the kernel security policy.
.It Dv PUFFS_KFLAG_NOCACHE
Do not store data in the page cache.
This causes operations to always consult the user server instead of
consulting the page cache.
This makes sense in situations where there is relatively little
bulk data to be transferred and the user server does not want to take
part in complex cache management routines in case the file system data
can be modified through routes other than the file system interface.
.It Dv PUFFS_KFLAG_ALLOPS
Transport all vnode operations to the file system server instead of just
the ones specified by
.Va pa_vnopmask .
.El
.Pp
The
.Va pa_maxreqlen
member signifies the length of the incoming data buffer in userspace.
A good value is
.Dv PUFFS_REQ_MAXSIZE ,
which is the maximum the kernel will use.
A minimum value is also enforced, so the value of this field should
be checked after the mount operation to determine the correct buffer
size.
During operation, in case request fetch is attempted with a buffer
too short, the error
.Er E2BIG
will be returned.
The file system type is give in
.Va pa_name .
It will always be prepended by "puffs:" by the kernel.
Finally, the array
.Va pa_vnopmask
specifies which operations are supported by the file system server.
The array is indexed with
.Dv PUFFS_VN_FOO
and 0 means vnode operation
.Dv FOO
is unimplemented while non-zero means an implemented operation.
This array is ignored if
.Dv PUFFS_KFLAG_ALLOPS
is given.
.Pp
After a successful mount system call, the the ioctl
.Dv PUFFSSTARTOP
must be issued through the open device node.
The parameter for this ioctl is the following structure:
.Bd -literal -offset indent
struct puffs_startreq {
void *psr_cookie;
struct statvfs psr_sb;
};
.Ed
.Pp
The member
.Va psr_cookie
should be set before calling.
This signals the cookie value of the root node of the file system
(see
.Xr puffs 3
for more details on cookie strategies).
The value of
.Va psr_sb
should be filled with the same results as for a regular statvfs
call.
After successfully executing this operation the file system is
active.
.Ss Operation
Operations must be queried from the kernel using the ioctl
.Dv PUFFSGETOP ,
processed, and the results pushed back to the kernel using
.Dv PUFFSPUTOP .
Normally the system will block until an event is available for
.Dv PUFFSGETOP ,
but it is possible to set the file descriptor into non-blocking
mode, in which case
.Er EWOULDBLOCK
is returned if no event is available.
Asynchronous I/O calls (i.e.,
.Xr select 2 ,
.Xr poll 2 ,
and
.Xr kevent 2 )
can be issued to be notified of events.
.Pp
As the argument both get and push use the following structure:
.Bd -literal -offset indent
struct puffs_req {
uint64_t preq_id;
uint8_t preq_opclass;
uint8_t preq_optype;
void *preq_cookie;
int preq_rv;
void *preq_aux;
size_t preq_auxlen;
};
.Ed
.Pp
The member
.Va preq_id
is used as an identifier in the reply.
It should not be modified during the processing of a
.Dv PUFFSGETOP -
.Dv PUFFSPUTOP
sequence.
The members
.Va preq_opclass
and
.Va preq_optype
identify the request; they also are used for typing the data
pointed to by
.Va preq_aux .
Currently the mapping between these two is only documented in
code in
.Pa src/lib/libpuffs/puff.c:puffcall() .
The handling of this will very likely change in the future towards
a more automatic direction.
The length of the buffer given to
.Dv PUFFSGETOP
is described by
.Va preq_auxlen
and will be modified by the kernel to indicate how much data
actually was transmitted.
This is for the benefit of calls such as write, which transmit a
variable amount of data.
Similarly, the user server should fill in the amount of data the
kernel must copy for
.Dv PUFFSPUTOP ;
most of the time this will be constant for a given operation, but
operations such as read want to adjust it dynamically.
Finally,
.Va preq_rv
is used by the userspace server to fill in the success value of the
operation in question.
.Pp
In case the macro
.Fn PUFFSOP_WANTREPLY
returns false for
.Va preq_opclass ,
a return value is not wanted and
.Dv PUFFSPUTOP
should not be issued.
.Pp
Additionally, an operation of type
.Dv PUFFSSIZEOP
is supported, but it is only used by the ioctl and fcntl operations
and will likely go away in the future.
It is not described here.
.Ss Termination
The file system can be unmounted regularly using
.Xr umount 8 .
It will automatically be unmounted in case the userspace server is
killed or the control file descriptor closed, but in this case the
userspace server will not be separately requested to unmount itself
and this may result in data loss.
.Sh SEE ALSO
.Xr ioctl 2 ,
.Xr mount 2 ,
.Xr puffs 3 ,
.Xr umount 8
.Rs
.%A Antti Kantee
.%D March 2007
.%J Proceedings of AsiaBSDCon 2007
.%P pp. 29-42
.%T puffs - Pass-to-Userspace Framework File System
.Re
.Sh HISTORY
An unsupported experimental version of
.Nm
first appeared in
.Nx 4.0 .
.Sh AUTHORS
.An Antti Kantee Aq pooka@iki.fi
.Sh BUGS
.Nm
is currently more like a souffle than puff pastry.