diff --git a/share/man/man9/dev_clone.9 b/share/man/man9/dev_clone.9 new file mode 100644 index 0000000..ce3774a --- /dev/null +++ b/share/man/man9/dev_clone.9 @@ -0,0 +1,74 @@ +.\" Copyright (c) 2008 Konstantin Belousov +.\" 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. +.\" +.\" $FreeBSD$ +.\" +.Dd September 8, 2008 +.Sh NAME +.Nm dev_clone , +.Nm drain_dev_clone_events +.Nd eventhandler for name-based device cloning in devfs +.Sh SYNOPSIS +.In sys/param.h +.In sys/conf.h +.Ft void +.Fn clone_handler "void *arg" "struct ucred *cr" "char *name" "int namelen" "struct cdev **dev" +.Bd -literal +EVENTHANDLER_REGISTER(dev_clone, clone_handler, arg, priority); +.Ed +.Ft void +.Fn drain_dev_clone_events +.Sh DESCRIPTION +Device driver may register a listener that will be notified each time +name lookup on the +.Xr devfs +mount point fails to find the vnode. +Listener shall be registered for the +.Va dev_clone +event. +When called, it is supplied with the first argument +.Va arg +that was specified at handler registration time, +appropriate credentials +.Va cr , +.Va name +of the length +.Va namelen +that was looked for. +If handler decides that the name is appropriate and want to create device +that will be associated with the name, it should return it to the devfs +in the +.Va dev . +.Pp +The +.Fn drain_dev_clone_events +function is a barrier. +It is guaranteed that all calls to eventhandlers for dev_clone that were +started before +.Fn drain_dev_clone_events +call, are finished before it returns control. +.Pp +.Sh SEE ALSO +.Xr devfs 5 , +.Xr namei 9 diff --git a/share/man/man9/devfs_set_cdevpriv.9 b/share/man/man9/devfs_set_cdevpriv.9 new file mode 100644 index 0000000..98a3a79 --- /dev/null +++ b/share/man/man9/devfs_set_cdevpriv.9 @@ -0,0 +1,121 @@ +.\" Copyright (c) 2008 Konstantin Belousov +.\" 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. +.\" +.\" $FreeBSD$ +.\" +.Dd September 8, 2008 +.Os +.Dt DEVFS_CDEVPRIV +.Sh NAME +.Nm devfs_set_cdevpriv , +.Nm devfs_get_cdevpriv , +.Nm devfs_clear_cdevpriv +.Nd manage per-open filedescriptor data for devices +.Sh SYNOPSIS +.In sys/param.h +.In sys/conf.h +.Bd -literal +typedef void (*cdevpriv_dtr_t)(void *data); +.Ed +.Ft int +.Fn devfs_get_cdevpriv void **datap +.Ft int +.Fn devfs_set_cdevpriv "void *priv" "cdevpriv_dtr_t dtr" +.Ft void +.Fn devfs_clear_cdevpriv "void" +.Sh DESCRIPTION +The +.Fn devfs_xxx_cdevpriv +family of functions allows the +.Fa cdev +driver methods to associate some driver-specific data with each +user process +.Xr open 2 +of the device special file. +Currently, functioning of these functions is restricted to the context +of the +.Fa cdevsw +switch method calls performed as +.Xr devfs 5 +operations in response to system calls that use filedescriptors. +.Pp +The +.Fn devfs_set_cdevpriv +function associates a data pointed by +.Va priv +with current calling context (filedescriptor). +The data may be retrieved later, possibly from another call +performed on this filedescriptor, by the +.Fn devfs_get_cdevpriv +function. +The +.Fn devfs_clear_cdevpriv +disassociates previously attached data from context. +Immediately after +.Fn devfs_clear_cdevpriv +finished operating, the +.Va dtr +callback is called, with private data supplied +.Va data +argument. +.Pp +On the last filedescriptor close, system automatically arranges +.Fn devfs_clear_cdevpriv +call. +.Pp +If successful, the functions return 0. +.Pp +The function +.Fn devfs_set_cdevpriv +returns the following values on error: +.Bl -tag -width Er +.It Bq Er ENOENT +The current call is not associated with some filedescriptor. +.It Bq Er EBUSY +The private driver data is already associated with current +filedescriptor. +.El +.Pp +The function +.Fn devfs_get_cdevpriv +returns the following values on error: +.Bl -tag -width Er +.It Bq Er EBADF +The current call is not associated with some filedescriptor. +.It Bq Er ENOENT +The private driver data was not associated with current +filedescriptor, or +.Fn devfs_clear_cdevpriv +was called. +.Pp +.Sh SEE ALSO +.Xr open 2 , +.Xr close 2 , +.Xr devfs 5 , +.Xr kern_openat 9 +.Sh HISTORY +The +.Fn devfs_cdevpriv +family of functions first appeared in +.Fx 7.1 . diff --git a/share/man/man9/insmntque.9 b/share/man/man9/insmntque.9 index 42c7cb6..906a59f 100644 --- a/share/man/man9/insmntque.9 +++ b/share/man/man9/insmntque.9 @@ -26,17 +26,20 @@ .\" .\" $FreeBSD$ .\" -.Dd February 25, 2008 +.Dd September 08, 2008 .Dt insmntque 9 .Os .Sh NAME -.Nm insmntque +.Nm insmntque , +.Nm insmntque1 .Nd "associate a vnode with a mount" .Sh SYNOPSIS .In sys/param.h .In sys/vnode.h .Ft int .Fn insmntque "struct vnode *vp" "struct mount *mp" +.Ft int +.Fn insmntque1 "struct vnode *vp" "struct mount *mp" "void (*dtr)(struct vnode *, void *)" "void *dtr_arg" .Sh DESCRIPTION The .Fn insmntque @@ -50,11 +53,39 @@ mount, and that reference is decremented by .Fn vgone 9 . .Pp The mount's interlock is held while the vnode is inserted. +For MP-SAFE filesystems, vnode must be exclusively locked. +.Pp +On failure, +.Fn insmntque +calls +.Fn vgone 9 +on the supplied vnode, and then drops vnode lock and reference. +If more elaborated cleanup after insmntque failure is needed, +the +.Fn insmntque1 +function may be used instead. +It takes +.Fa dtr +argument, that is the pointer to function that is called on failure. +This function may perform any custom cleanup. +The vnode pointer is supplied as first argument to +.Fa dtr, +and +.Fa dtr_arg +is the second, supplying any additional context needed. .Sh RETURN VALUES .Fn insmntque will always return 0, unless the file system is currently being unmounted -in which case it will return +in which case it may return .Dv EBUSY . +The +.Fn insmntque +function may be forced to insert the vnode into the mounts vnode list +by setting +.Va VV_FORCEINSMQ +flag in the vnode +.Va v_flag , +even if the filesystem is being unmounted. .Sh SEE ALSO .Xr vgone 9 .Sh AUTHORS diff --git a/share/man/man9/make_dev.9 b/share/man/man9/make_dev.9 index 7680052..ea23354 100644 --- a/share/man/man9/make_dev.9 +++ b/share/man/man9/make_dev.9 @@ -24,13 +24,18 @@ .\" .\" $FreeBSD$ .\" -.Dd May 6, 2007 +.Dd September 8, 2008 .Os .Dt MAKE_DEV 9 .Sh NAME .Nm make_dev , +.Nm make_dev_cred , +.Nm make_dev_credf , .Nm make_dev_alias , .Nm destroy_dev , +.Nm destroy_dev_sched , +.Nm destroy_dev_sched_cb , +.Nm destroy_dev_drain , .Nm dev_depends .Nd manage .Vt cdev Ns 's @@ -41,19 +46,34 @@ and DEVFS registration for devices .Ft struct cdev * .Fn make_dev "struct cdevsw *cdevsw" "int minor" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... .Ft struct cdev * +.Fn make_dev_cred "struct cdevsw *cdevsw" "int minor" "struct ucred *cr" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... +.Ft struct cdev * +.Fn make_dev_credf "int flags" "struct cdevsw *cdevsw" "int minor" "struct ucred *cr" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... +.Ft struct cdev * .Fn make_dev_alias "struct cdev *pdev" "const char *fmt" ... .Ft void .Fn destroy_dev "struct cdev *dev" .Ft void +.Fn destroy_dev_sched "struct cdev *dev" +.Ft void +.Fn destroy_dev_sched_cb "struct cdev *dev" "void (*cb)(void *)" "void *arg" +.Ft void +.Fn destroy_dev_drain "struct cdevsw *csw" +.Ft void .Fn dev_depends "struct cdev *pdev" "struct cdev *cdev" .Sh DESCRIPTION The -.Fn make_dev +.Fn make_dev_credf function creates a .Fa cdev structure for a new device. -If DEVFS is available, it is also notified of -the presence of the new device. +It also notifies +.Xr devfs 5 +of the presence of the new device, that causes corresponding nodes +to be created. +Besides this, +.Xr devctl 4 +notification is sent. The device will be owned by .Va uid , with the group ownership as @@ -100,6 +120,45 @@ are defined in .Ed .Pp The +.Va cr +argument specifies credentials that will be stored in the +.Fa si_cred +member of the initialized +.Fa struct cdev . +The +.Va flags +argument adjust the operation of the +.Fn make_dev_credf , +the following values are currently accepted: +.Pp +.Bd -literal -offset indent -compact +MAKEDEV_REF reference the created device +.Ed +.Pp +The +.Xr dev_clone 9 +event handler shall specify +.Dv MAKEDEV_REF +flag when creating a device in response to lookup, to avoid race where +the device created is destroyed immediately after +.Xr devfs_lookup 9 +drops his reference to cdev. +.Pp +The +.Fn make_dev_cred +function is equivalent to the call +.Bd -literal -offset indent +make_dev_credf(0, cdevsw, minor, cr, uid, gid, perms, fmt, ...); +.Ed . +.Pp +The +.Fn make_dev +function call is the same as +.Bd -literal -offset indent +make_dev_credf(0, cdevsw, minor, NULL, uid, gid, perms, fmt, ...); +.Ed . +.Pp +The .Fn make_dev_alias function takes the returned .Ft cdev @@ -136,6 +195,9 @@ function takes the returned from .Fn make_dev and destroys the registration for that device. +The notification is sent to +.Xr devctl 4 +about the destruction event. Do not call .Fn destroy_dev on devices that were created with @@ -151,7 +213,58 @@ child device(s), if any exist. A device may simultaneously be a parent and a child, so it is possible to build a complete hierarchy. +.Pp +The +.Fn destroy_dev_sched_cb +function schedules execution of the +.Fn destroy_dev +for the specified +.Fa cdev +in the safe context. +After +.Fn destroy_dev +is finished, and if the supplied +.Fa cb +is not NULL, the callback +.Fa cb +is called, with argument +.Fa arg . +The +.Fn destroy_dev_sched +function is the same as +.Bd -literal -offset indent +destroy_dev_sched(cdev, NULL, NULL); +.Ed . +.Pp +The +.Fn d_close +driver method cannot call +.Fn destroy_dev +directly. Doing so causes deadlock when +.Fn destroy_dev +waits for all threads to leave the driver methods. +Also, because +.Fn destroy_dev +sleeps, no non-sleepable locks may be held over the call. +The +.Fn destroy_dev_sched +family of functions overcome these issues. +.Pp +The device driver may call the +.Fn destroy_dev_drain +function to wait until all devices that have supplied +.Fa csw +as cdevsw, are destroyed. This is useful when driver knows that +.Fn destroy_dev_sched +is called for all instantiated devices, but need to postpone module +unload until +.Fn destroy_dev +is actually finished for all of them. +.Pp .Sh SEE ALSO +.Xr devctl 4 , +.Xr destroy_dev_drain 9 , +.Xr dev_clone 9 , .Xr devfs 5 .Sh HISTORY The @@ -168,3 +281,9 @@ The function .Fn dev_depends first appeared in .Fx 5.0 . +The functions +.Fn make_dev_credf , +.Fn destroy_dev_sched , +.Fn destroy_dev_sched_cb +first appeared in +.Fx 7.0 .