272 lines
8.3 KiB
Groff
272 lines
8.3 KiB
Groff
.\" $NetBSD: puffs.4,v 1.7 2007/12/04 19:48:24 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"
|
|
.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.
|