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 8, 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 . 190.Pp 191The 192.Fn destroy_dev 193function takes the returned 194.Fa cdev 195from 196.Fn make_dev 197and destroys the registration for that device. 198The notification is sent to 199.Xr devctl 4 200about the destruction event. 201Do not call 202.Fn destroy_dev 203on devices that were created with 204.Fn make_dev_alias . 205.Pp 206The 207.Fn dev_depends 208function establishes a parent-child relationship between two devices. 209The net effect is that a 210.Fn destroy_dev 211of the parent device will also result in the destruction of the 212child device(s), 213if any exist. 214A device may simultaneously be a parent and a child, 215so it is possible to build a complete hierarchy. 216.Pp 217The 218.Fn destroy_dev_sched_cb 219function schedules execution of the 220.Fn destroy_dev 221for the specified 222.Fa cdev 223in the safe context. 224After 225.Fn destroy_dev 226is finished, and if the supplied 227.Fa cb 228is not NULL, the callback 229.Fa cb 230is called, with argument 231.Fa arg . 232The 233.Fn destroy_dev_sched 234function is the same as 235.Bd -literal -offset indent 236destroy_dev_sched(cdev, NULL, NULL); 237.Ed . 238.Pp 239The 240.Fn d_close 241driver method cannot call 242.Fn destroy_dev 243directly. Doing so causes deadlock when 244.Fn destroy_dev 245waits for all threads to leave the driver methods. 246Also, because 247.Fn destroy_dev 248sleeps, no non-sleepable locks may be held over the call. 249The 250.Fn destroy_dev_sched 251family of functions overcome these issues. 252.Pp 253The device driver may call the 254.Fn destroy_dev_drain 255function to wait until all devices that have supplied 256.Fa csw 257as cdevsw, are destroyed. This is useful when driver knows that 258.Fn destroy_dev_sched 259is called for all instantiated devices, but need to postpone module 260unload until 261.Fn destroy_dev 262is actually finished for all of them. 263.Pp 264.Sh SEE ALSO 265.Xr devctl 4 , 266.Xr destroy_dev_drain 9 , 267.Xr dev_clone 9 , 268.Xr devfs 5 269.Sh HISTORY 270The 271.Fn make_dev 272and 273.Fn destroy_dev 274functions first appeared in 275.Fx 4.0 . 276The function 277.Fn make_dev_alias 278first appeared in 279.Fx 4.1 . 280The function 281.Fn dev_depends 282first appeared in 283.Fx 5.0 . 284The functions 285.Fn make_dev_credf , 286.Fn destroy_dev_sched , 287.Fn destroy_dev_sched_cb 288first appeared in 289.Fx 7.0 . 290