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