[src/trunk]: src/share/man/man4 Remove extra crud which hasn't been up-to-dat...

[pooka <pooka%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/f80e4c46d6e1
branches:  trunk
changeset: 749238:f80e4c46d6e1
user:      pooka <pooka%NetBSD.org@localhost>
date:      Sun Nov 22 18:36:16 2009 +0000

description:
Remove extra crud which hasn't been up-to-date in eons.

diffstat:

 share/man/man4/puffs.4 |  237 ++----------------------------------------------
 1 files changed, 13 insertions(+), 224 deletions(-)

diffs (272 lines):

diff -r b98035c0cf98 -r f80e4c46d6e1 share/man/man4/puffs.4
--- a/share/man/man4/puffs.4    Sun Nov 22 18:14:49 2009 +0000
+++ b/share/man/man4/puffs.4    Sun Nov 22 18:36:16 2009 +0000
@@ -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
+.Ss Termination
+A
 .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
+file system can be unmounted regularly using
+.Xr umount 8 .
+The file system will automatically be unmounted in case the userspace
+server is killed or the control file descriptor closed.
+.Sh SEE ALSO
 .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 .
+A stable version appeared in
+.Nx 5.0 .
 .Sh AUTHORS
 .An Antti Kantee Aq pooka%iki.fi@localhost
-.Sh BUGS
-.Nm
-is currently more like a souffle than puff pastry.