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 May 6, 2010 28.Dt MAKE_DEV 9 29.Os 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 136MAKEDEV_NOWAIT do not sleep, may return NULL 137MAKEDEV_WAITOK allow the function to sleep to satisfy malloc 138.Ed 139.Pp 140The 141.Dv MAKEDEV_WAITOK 142flag is assumed if none of 143.Dv MAKEDEV_WAITOK , 144.Dv MAKEDEV_NOWAIT 145is specified. 146.Pp 147The 148.Xr dev_clone 9 149event handler shall specify 150.Dv MAKEDEV_REF 151flag when creating a device in response to lookup, to avoid race where 152the device created is destroyed immediately after 153.Xr devfs_lookup 9 154drops his reference to cdev. 155.Pp 156The 157.Fn make_dev_cred 158function is equivalent to the call 159.Bd -literal -offset indent 160make_dev_credf(0, cdevsw, unit, cr, uid, gid, perms, fmt, ...); 161.Ed 162.Pp 163The 164.Fn make_dev 165function call is the same as 166.Bd -literal -offset indent 167make_dev_credf(0, cdevsw, unit, NULL, uid, gid, perms, fmt, ...); 168.Ed 169.Pp 170The 171.Fn make_dev_alias 172function takes the returned 173.Ft cdev 174from 175.Fn make_dev 176and makes another (aliased) name for this device. 177It is an error to call 178.Fn make_dev_alias 179prior to calling 180.Fn make_dev . 181.Pp 182The 183.Fa cdev 184returned by 185.Fn make_dev 186and 187.Fn make_dev_alias 188has two fields, 189.Fa si_drv1 190and 191.Fa si_drv2 , 192that are available to store state. 193Both fields are of type 194.Ft void * . 195These are designed to replace the 196.Fa unit 197argument to 198.Fn make_dev , 199which can be obtained with 200.Fn dev2unit . 201.Pp 202The 203.Fn destroy_dev 204function takes the returned 205.Fa cdev 206from 207.Fn make_dev 208and destroys the registration for that device. 209The notification is sent to 210.Xr devctl 4 211about the destruction event. 212Do not call 213.Fn destroy_dev 214on devices that were created with 215.Fn make_dev_alias . 216.Pp 217The 218.Fn dev_depends 219function establishes a parent-child relationship between two devices. 220The net effect is that a 221.Fn destroy_dev 222of the parent device will also result in the destruction of the 223child device(s), 224if any exist. 225A device may simultaneously be a parent and a child, 226so it is possible to build a complete hierarchy. 227.Pp 228The 229.Fn destroy_dev_sched_cb 230function schedules execution of the 231.Fn destroy_dev 232for the specified 233.Fa cdev 234in the safe context. 235After 236.Fn destroy_dev 237is finished, and if the supplied 238.Fa cb 239is not NULL, the callback 240.Fa cb 241is called, with argument 242.Fa arg . 243The 244.Fn destroy_dev_sched 245function is the same as 246.Bd -literal -offset indent 247destroy_dev_sched(cdev, NULL, NULL); 248.Ed 249.Pp 250The 251.Fn d_close 252driver method cannot call 253.Fn destroy_dev 254directly. Doing so causes deadlock when 255.Fn destroy_dev 256waits for all threads to leave the driver methods. 257Also, because 258.Fn destroy_dev 259sleeps, no non-sleepable locks may be held over the call. 260The 261.Fn destroy_dev_sched 262family of functions overcome these issues. 263.Pp 264The device driver may call the 265.Fn destroy_dev_drain 266function to wait until all devices that have supplied 267.Fa csw 268as cdevsw, are destroyed. This is useful when driver knows that 269.Fn destroy_dev_sched 270is called for all instantiated devices, but need to postpone module 271unload until 272.Fn destroy_dev 273is actually finished for all of them. 274.Pp 275.Sh SEE ALSO 276.Xr devctl 4 , 277.Xr destroy_dev_drain 9 , 278.Xr dev_clone 9 , 279.Xr devfs 5 280.Sh HISTORY 281The 282.Fn make_dev 283and 284.Fn destroy_dev 285functions first appeared in 286.Fx 4.0 . 287The function 288.Fn make_dev_alias 289first appeared in 290.Fx 4.1 . 291The function 292.Fn dev_depends 293first appeared in 294.Fx 5.0 . 295The functions 296.Fn make_dev_credf , 297.Fn destroy_dev_sched , 298.Fn destroy_dev_sched_cb 299first appeared in 300.Fx 7.0 . 301