1.\" Copyright (c) 1999 Chris Costello 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd September 28, 2008 28.Os 29.Dt MAKE_DEV 9 30.Sh NAME 31.Nm make_dev , 32.Nm make_dev_cred , 33.Nm make_dev_credf , 34.Nm make_dev_alias , 35.Nm destroy_dev , 36.Nm destroy_dev_sched , 37.Nm destroy_dev_sched_cb , 38.Nm destroy_dev_drain , 39.Nm dev_depends 40.Nd manage 41.Vt cdev Ns 's 42and DEVFS registration for devices 43.Sh SYNOPSIS 44.In sys/param.h 45.In sys/conf.h 46.Ft struct cdev * 47.Fn make_dev "struct cdevsw *cdevsw" "int unit" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... 48.Ft struct cdev * 49.Fn make_dev_cred "struct cdevsw *cdevsw" "int unit" "struct ucred *cr" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... 50.Ft struct cdev * 51.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" ... 52.Ft struct cdev * 53.Fn make_dev_alias "struct cdev *pdev" "const char *fmt" ... 54.Ft void 55.Fn destroy_dev "struct cdev *dev" 56.Ft void 57.Fn destroy_dev_sched "struct cdev *dev" 58.Ft void 59.Fn destroy_dev_sched_cb "struct cdev *dev" "void (*cb)(void *)" "void *arg" 60.Ft void 61.Fn destroy_dev_drain "struct cdevsw *csw" 62.Ft void 63.Fn dev_depends "struct cdev *pdev" "struct cdev *cdev" 64.Sh DESCRIPTION 65The 66.Fn make_dev_credf 67function creates a 68.Fa cdev 69structure for a new device. 70It also notifies 71.Xr devfs 5 72of the presence of the new device, that causes corresponding nodes 73to be created. 74Besides this, a 75.Xr devctl 4 76notification is sent. 77The device will be owned by 78.Va uid , 79with the group ownership as 80.Va gid . 81The name is the expansion of 82.Va fmt 83and following arguments as 84.Xr printf 9 85would print it. 86The name determines its path under 87.Pa /dev 88or other 89.Xr devfs 5 90mount point and may contain slash 91.Ql / 92characters to denote subdirectories. 93The permissions of the file specified in 94.Va perms 95are defined in 96.In sys/stat.h : 97.Pp 98.Bd -literal -offset indent -compact 99#define S_IRWXU 0000700 /* RWX mask for owner */ 100#define S_IRUSR 0000400 /* R for owner */ 101#define S_IWUSR 0000200 /* W for owner */ 102#define S_IXUSR 0000100 /* X for owner */ 103 104#define S_IRWXG 0000070 /* RWX mask for group */ 105#define S_IRGRP 0000040 /* R for group */ 106#define S_IWGRP 0000020 /* W for group */ 107#define S_IXGRP 0000010 /* X for group */ 108 109#define S_IRWXO 0000007 /* RWX mask for other */ 110#define S_IROTH 0000004 /* R for other */ 111#define S_IWOTH 0000002 /* W for other */ 112#define S_IXOTH 0000001 /* X for other */ 113 114#define S_ISUID 0004000 /* set user id on execution */ 115#define S_ISGID 0002000 /* set group id on execution */ 116#define S_ISVTX 0001000 /* sticky bit */ 117#ifndef _POSIX_SOURCE 118#define S_ISTXT 0001000 119#endif 120.Ed 121.Pp 122The 123.Va cr 124argument specifies credentials that will be stored in the 125.Fa si_cred 126member of the initialized 127.Fa struct cdev . 128The 129.Va flags 130argument alters the operation of 131.Fn make_dev_credf . 132The following values are currently accepted: 133.Pp 134.Bd -literal -offset indent -compact 135MAKEDEV_REF reference the created device 136.Ed 137.Pp 138The 139.Xr dev_clone 9 140event handler shall specify 141.Dv MAKEDEV_REF 142flag when creating a device in response to lookup, to avoid race where 143the device created is destroyed immediately after 144.Xr devfs_lookup 9 145drops his reference to cdev. 146.Pp 147The 148.Fn make_dev_cred 149function is equivalent to the call 150.Bd -literal -offset indent 151make_dev_credf(0, cdevsw, unit, cr, uid, gid, perms, fmt, ...); 152.Ed . 153.Pp 154The 155.Fn make_dev 156function call is the same as 157.Bd -literal -offset indent 158make_dev_credf(0, cdevsw, unit, NULL, uid, gid, perms, fmt, ...); 159.Ed . 160.Pp 161The 162.Fn make_dev_alias 163function takes the returned 164.Ft cdev 165from 166.Fn make_dev 167and makes another (aliased) name for this device. 168It is an error to call 169.Fn make_dev_alias 170prior to calling 171.Fn make_dev . 172.Pp 173The 174.Fa cdev 175returned by 176.Fn make_dev 177and 178.Fn make_dev_alias 179has two fields, 180.Fa si_drv1 181and 182.Fa si_drv2 , 183that are available to store state. 184Both fields are of type 185.Ft void * . 186These are designed to replace the 187.Fa unit 188argument to 189.Fn make_dev , 190which can be obtained with 191.Fn dev2unit . 192.Pp 193The 194.Fn destroy_dev 195function takes the returned 196.Fa cdev 197from 198.Fn make_dev 199and destroys the registration for that device. 200The notification is sent to 201.Xr devctl 4 202about the destruction event. 203Do not call 204.Fn destroy_dev 205on devices that were created with 206.Fn make_dev_alias . 207.Pp 208The 209.Fn dev_depends 210function establishes a parent-child relationship between two devices. 211The net effect is that a 212.Fn destroy_dev 213of the parent device will also result in the destruction of the 214child device(s), 215if any exist. 216A device may simultaneously be a parent and a child, 217so it is possible to build a complete hierarchy. 218.Pp 219The 220.Fn destroy_dev_sched_cb 221function schedules execution of the 222.Fn destroy_dev 223for the specified 224.Fa cdev 225in the safe context. 226After 227.Fn destroy_dev 228is finished, and if the supplied 229.Fa cb 230is not NULL, the callback 231.Fa cb 232is called, with argument 233.Fa arg . 234The 235.Fn destroy_dev_sched 236function is the same as 237.Bd -literal -offset indent 238destroy_dev_sched(cdev, NULL, NULL); 239.Ed . 240.Pp 241The 242.Fn d_close 243driver method cannot call 244.Fn destroy_dev 245directly. Doing so causes deadlock when 246.Fn destroy_dev 247waits for all threads to leave the driver methods. 248Also, because 249.Fn destroy_dev 250sleeps, no non-sleepable locks may be held over the call. 251The 252.Fn destroy_dev_sched 253family of functions overcome these issues. 254.Pp 255The device driver may call the 256.Fn destroy_dev_drain 257function to wait until all devices that have supplied 258.Fa csw 259as cdevsw, are destroyed. This is useful when driver knows that 260.Fn destroy_dev_sched 261is called for all instantiated devices, but need to postpone module 262unload until 263.Fn destroy_dev 264is actually finished for all of them. 265.Pp 266.Sh SEE ALSO 267.Xr devctl 4 , 268.Xr destroy_dev_drain 9 , 269.Xr dev_clone 9 , 270.Xr devfs 5 271.Sh HISTORY 272The 273.Fn make_dev 274and 275.Fn destroy_dev 276functions first appeared in 277.Fx 4.0 . 278The function 279.Fn make_dev_alias 280first appeared in 281.Fx 4.1 . 282The function 283.Fn dev_depends 284first appeared in 285.Fx 5.0 . 286The functions 287.Fn make_dev_credf , 288.Fn destroy_dev_sched , 289.Fn destroy_dev_sched_cb 290first appeared in 291.Fx 7.0 . 292