Remove extra crud which hasn't been up-to-date in eons.
This commit is contained in:
pooka
parent
5a9a1f8306
commit
16f3281f94
|
|
@ -1,6 +1,6 @@
|
|||
.\" $NetBSD: puffs.4,v 1.9 2009/11/22 18:02:22 mbalmer Exp $
|
||||
.\" $NetBSD: puffs.4,v 1.10 2009/11/22 18:36:16 pooka Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 2006 Antti Kantee. All rights reserved.
|
||||
.\" Copyright (c) 2009 Antti Kantee. All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
|
|
@ -23,7 +23,7 @@
|
|||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.Dd December 1, 2006
|
||||
.Dd November 22, 2009
|
||||
.Dt PUFFS 4
|
||||
.Os
|
||||
.Sh NAME
|
||||
|
|
@ -33,240 +33,29 @@
|
|||
.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
|
||||
People looking to implement file systems should use 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 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
|
||||
A
|
||||
.Nm
|
||||
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.
|
||||
The file system will automatically be unmounted in case the userspace
|
||||
server is killed or the control file descriptor closed.
|
||||
.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
|
||||
.Xr puffs 3
|
||||
.Sh HISTORY
|
||||
An unsupported experimental version of
|
||||
.Nm
|
||||
first appeared in
|
||||
.Nx 4.0 .
|
||||
A stable version appeared in
|
||||
.Nx 5.0 .
|
||||
.Sh AUTHORS
|
||||
.An Antti Kantee Aq pooka@iki.fi
|
||||
.Sh BUGS
|
||||
.Nm
|
||||
is currently more like a souffle than puff pastry.
|
||||
|
|
|
|||
Loading…
Reference in New Issue