diff options
Diffstat (limited to 'share/man/man9/make_dev.9')
| -rw-r--r-- | share/man/man9/make_dev.9 | 291 |
1 files changed, 291 insertions, 0 deletions
diff --git a/share/man/man9/make_dev.9 b/share/man/man9/make_dev.9 new file mode 100644 index 000000000000..b39ca8b833e4 --- /dev/null +++ b/share/man/man9/make_dev.9 @@ -0,0 +1,291 @@ +.\" Copyright (c) 1999 Chris Costello +.\" 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 28, 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 +and DEVFS registration for devices +.Sh SYNOPSIS +.In sys/param.h +.In sys/conf.h +.Ft struct cdev * +.Fn make_dev "struct cdevsw *cdevsw" "int unit" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... +.Ft struct cdev * +.Fn make_dev_cred "struct cdevsw *cdevsw" "int unit" "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 unit" "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_credf +function creates a +.Fa cdev +structure for a new device. +It also notifies +.Xr devfs 5 +of the presence of the new device, that causes corresponding nodes +to be created. +Besides this, a +.Xr devctl 4 +notification is sent. +The device will be owned by +.Va uid , +with the group ownership as +.Va gid . +The name is the expansion of +.Va fmt +and following arguments as +.Xr printf 9 +would print it. +The name determines its path under +.Pa /dev +or other +.Xr devfs 5 +mount point and may contain slash +.Ql / +characters to denote subdirectories. +The permissions of the file specified in +.Va perms +are defined in +.In sys/stat.h : +.Pp +.Bd -literal -offset indent -compact +#define S_IRWXU 0000700 /* RWX mask for owner */ +#define S_IRUSR 0000400 /* R for owner */ +#define S_IWUSR 0000200 /* W for owner */ +#define S_IXUSR 0000100 /* X for owner */ + +#define S_IRWXG 0000070 /* RWX mask for group */ +#define S_IRGRP 0000040 /* R for group */ +#define S_IWGRP 0000020 /* W for group */ +#define S_IXGRP 0000010 /* X for group */ + +#define S_IRWXO 0000007 /* RWX mask for other */ +#define S_IROTH 0000004 /* R for other */ +#define S_IWOTH 0000002 /* W for other */ +#define S_IXOTH 0000001 /* X for other */ + +#define S_ISUID 0004000 /* set user id on execution */ +#define S_ISGID 0002000 /* set group id on execution */ +#define S_ISVTX 0001000 /* sticky bit */ +#ifndef _POSIX_SOURCE +#define S_ISTXT 0001000 +#endif +.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 alters the operation of +.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, unit, 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, unit, NULL, uid, gid, perms, fmt, ...); +.Ed . +.Pp +The +.Fn make_dev_alias +function takes the returned +.Ft cdev +from +.Fn make_dev +and makes another (aliased) name for this device. +It is an error to call +.Fn make_dev_alias +prior to calling +.Fn make_dev . +.Pp +The +.Fa cdev +returned by +.Fn make_dev +and +.Fn make_dev_alias +has two fields, +.Fa si_drv1 +and +.Fa si_drv2 , +that are available to store state. +Both fields are of type +.Ft void * . +These are designed to replace the +.Fa unit +argument to +.Fn make_dev , +which can be obtained with +.Fn dev2unit . +.Pp +The +.Fn destroy_dev +function takes the returned +.Fa cdev +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 +.Fn make_dev_alias . +.Pp +The +.Fn dev_depends +function establishes a parent-child relationship between two devices. +The net effect is that a +.Fn destroy_dev +of the parent device will also result in the destruction of the +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 +.Fn make_dev +and +.Fn destroy_dev +functions first appeared in +.Fx 4.0 . +The function +.Fn make_dev_alias +first appeared in +.Fx 4.1 . +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 . |