share/man/man9/make_dev.9

   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
  42 and 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
  65 The
  66 .Fn make_dev_credf
  67 function creates a
  68 .Fa cdev
  69 structure for a new device.
  70 It also notifies
  71 .Xr devfs 5
  72 of the presence of the new device, that causes corresponding nodes
  73 to be created.
  74 Besides this, a
  75 .Xr devctl 4
  76 notification is sent.
  77 The device will be owned by
  78 .Va uid ,
  79 with the group ownership as
  80 .Va gid .
  81 The name is the expansion of
  82 .Va fmt
  83 and following arguments as
  84 .Xr printf 9
  85 would print it.
  86 The name determines its path under
  87 .Pa /dev
  88 or other
  89 .Xr devfs 5
  90 mount point and may contain slash
  91 .Ql /
  92 characters to denote subdirectories.
  93 The permissions of the file specified in
  94 .Va perms
  95 are 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
 122 The
 123 .Va cr
 124 argument specifies credentials that will be stored in the
 125 .Fa si_cred
 126 member of the initialized
 127 .Fa struct cdev .
 128 The
 129 .Va flags
 130 argument alters the operation of
 131 .Fn make_dev_credf .
 132 The following values are currently accepted:
 133 .Pp
 134 .Bd -literal -offset indent -compact
 135 MAKEDEV_REF     reference the created device
 136 .Ed
 137 .Pp
 138 The
 139 .Xr dev_clone 9
 140 event handler shall specify
 141 .Dv MAKEDEV_REF
 142 flag when creating a device in response to lookup, to avoid race where
 143 the device created is destroyed immediately after
 144 .Xr devfs_lookup 9
 145 drops his reference to cdev.
 146 .Pp
 147 The
 148 .Fn make_dev_cred
 149 function is equivalent to the call
 150 .Bd -literal -offset indent
 151 make_dev_credf(0, cdevsw, unit, cr, uid, gid, perms, fmt, ...);
 152 .Ed .
 153 .Pp
 154 The
 155 .Fn make_dev
 156 function call is the same as
 157 .Bd -literal -offset indent
 158 make_dev_credf(0, cdevsw, unit, NULL, uid, gid, perms, fmt, ...);
 159 .Ed .
 160 .Pp
 161 The
 162 .Fn make_dev_alias
 163 function takes the returned
 164 .Ft cdev
 165 from
 166 .Fn make_dev
 167 and makes another (aliased) name for this device.
 168 It is an error to call
 169 .Fn make_dev_alias
 170 prior to calling
 171 .Fn make_dev .
 172 .Pp
 173 The
 174 .Fa cdev
 175 returned by
 176 .Fn make_dev
 177 and
 178 .Fn make_dev_alias
 179 has two fields,
 180 .Fa si_drv1
 181 and
 182 .Fa si_drv2 ,
 183 that are available to store state.
 184 Both fields are of type
 185 .Ft void * .
 186 These are designed to replace the
 187 .Fa unit
 188 argument to
 189 .Fn make_dev ,
 190 which can be obtained with
 191 .Fn dev2unit .
 192 .Pp
 193 The
 194 .Fn destroy_dev
 195 function takes the returned
 196 .Fa cdev
 197 from
 198 .Fn make_dev
 199 and destroys the registration for that device.
 200 The notification is sent to
 201 .Xr devctl 4
 202 about the destruction event.
 203 Do not call
 204 .Fn destroy_dev
 205 on devices that were created with
 206 .Fn make_dev_alias .
 207 .Pp
 208 The
 209 .Fn dev_depends
 210 function establishes a parent-child relationship between two devices.
 211 The net effect is that a
 212 .Fn destroy_dev
 213 of the parent device will also result in the destruction of the
 214 child device(s),
 215 if any exist.
 216 A device may simultaneously be a parent and a child,
 217 so it is possible to build a complete hierarchy.
 218 .Pp
 219 The
 220 .Fn destroy_dev_sched_cb
 221 function schedules execution of the
 222 .Fn destroy_dev
 223 for the specified
 224 .Fa cdev
 225 in the safe context.
 226 After
 227 .Fn destroy_dev
 228 is finished, and if the supplied
 229 .Fa cb
 230 is not NULL, the callback
 231 .Fa cb
 232 is called, with argument
 233 .Fa arg .
 234 The
 235 .Fn destroy_dev_sched
 236 function is the same as
 237 .Bd -literal -offset indent
 238 destroy_dev_sched(cdev, NULL, NULL);
 239 .Ed .
 240 .Pp
 241 The
 242 .Fn d_close
 243 driver method cannot call
 244 .Fn destroy_dev
 245 directly. Doing so causes deadlock when
 246 .Fn destroy_dev
 247 waits for all threads to leave the driver methods.
 248 Also, because
 249 .Fn destroy_dev
 250 sleeps, no non-sleepable locks may be held over the call.
 251 The
 252 .Fn destroy_dev_sched
 253 family of functions overcome these issues.
 254 .Pp
 255 The device driver may call the
 256 .Fn destroy_dev_drain
 257 function to wait until all devices that have supplied
 258 .Fa csw
 259 as cdevsw, are destroyed. This is useful when driver knows that
 260 .Fn destroy_dev_sched
 261 is called for all instantiated devices, but need to postpone module
 262 unload until
 263 .Fn destroy_dev
 264 is 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
 272 The
 273 .Fn make_dev
 274 and
 275 .Fn destroy_dev
 276 functions first appeared in
 277 .Fx 4.0 .
 278 The function
 279 .Fn make_dev_alias
 280 first appeared in
 281 .Fx 4.1 .
 282 The function
 283 .Fn dev_depends
 284 first appeared in
 285 .Fx 5.0 .
 286 The functions
 287 .Fn make_dev_credf ,
 288 .Fn destroy_dev_sched ,
 289 .Fn destroy_dev_sched_cb
 290 first appeared in
 291 .Fx 7.0 .