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 Jan 3, 2016
  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_p ,
  35 .Nm make_dev_s ,
  36 .Nm make_dev_alias ,
  37 .Nm make_dev_alias_p ,
  38 .Nm destroy_dev ,
  39 .Nm destroy_dev_sched ,
  40 .Nm destroy_dev_sched_cb ,
  41 .Nm destroy_dev_drain ,
  42 .Nm dev_depends
  43 .Nd manage
  44 .Vt cdev Ns 's
  45 and DEVFS registration for devices
  46 .Sh SYNOPSIS
  47 .In sys/param.h
  48 .In sys/conf.h
  49 .Ft void
  50 .Fn make_dev_args_init "struct make_dev_args *args"
  51 .Ft int
  52 .Fn make_dev_s "struct make_dev_args *args" "struct cdev **cdev" "const char *fmt" ...
  53 .Ft int
  54 .Fn make_dev_alias_p "int flags" "struct cdev **cdev" "struct cdev *pdev" "const char *fmt" ...
  55 .Ft void
  56 .Fn destroy_dev "struct cdev *dev"
  57 .Ft void
  58 .Fn destroy_dev_sched "struct cdev *dev"
  59 .Ft void
  60 .Fn destroy_dev_sched_cb "struct cdev *dev" "void (*cb)(void *)" "void *arg"
  61 .Ft void
  62 .Fn destroy_dev_drain "struct cdevsw *csw"
  63 .Ft void
  64 .Fn dev_depends "struct cdev *pdev" "struct cdev *cdev"
  65 .Pp
  66 LEGACY INTERFACES
  67 .Ft struct cdev *
  68 .Fn make_dev "struct cdevsw *cdevsw" "int unit" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ...
  69 .Ft struct cdev *
  70 .Fn make_dev_cred "struct cdevsw *cdevsw" "int unit" "struct ucred *cr" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ...
  71 .Ft struct cdev *
  72 .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" ...
  73 .Ft int
  74 .Fn make_dev_p "int flags" "struct cdev **cdev" "struct cdevsw *devsw" "struct ucred *cr" "uid_t uid" "gid_t gid" "int mode" "const char *fmt" ...
  75 .Ft struct cdev *
  76 .Fn make_dev_alias "struct cdev *pdev" "const char *fmt" ...
  77 .Sh DESCRIPTION
  78 The
  79 .Fn make_dev_s
  80 function creates a
  81 .Fa cdev
  82 structure for a new device, which is returned into the
  83 .Fa cdev
  84 argument.
  85 It also notifies
  86 .Xr devfs 5
  87 of the presence of the new device, that causes corresponding nodes
  88 to be created.
  89 Besides this, a
  90 .Xr devctl 4
  91 notification is sent.
  92 The function takes the structure
  93 .Va struct make_dev_args args ,
  94 which specifies the parameters for the device creation:
  95 .Pp
  96 .Bd -literal -offset indent -compact
  97 struct make_dev_args {
  98         size_t           mda_size;
  99         int              mda_flags;
 100         struct cdevsw   *mda_devsw;
 101         struct ucred    *mda_cr;
 102         uid_t            mda_uid;
 103         gid_t            mda_gid;
 104         int              mda_mode;
 105         int              mda_unit;
 106         void            *mda_si_drv1;
 107         void            *mda_si_drv2;
 108 };
 109 .Ed
 110 Before use and filling with the desired values, the structure must be
 111 initialized by the
 112 .Fn make_dev_args_init
 113 function, which ensures that future kernel interface expansion does
 114 not affect driver source code or binary interface.
 115 .Pp
 116 The created device will be owned by
 117 .Va args.mda_uid ,
 118 with the group ownership as
 119 .Va args.mda_gid .
 120 The name is the expansion of
 121 .Va fmt
 122 and following arguments as
 123 .Xr printf 9
 124 would print it.
 125 The name determines its path under
 126 .Pa /dev
 127 or other
 128 .Xr devfs 5
 129 mount point and may contain slash
 130 .Ql /
 131 characters to denote subdirectories.
 132 The permissions of the file specified in
 133 .Va args.mda_mode
 134 are defined in
 135 .In sys/stat.h :
 136 .Pp
 137 .Bd -literal -offset indent -compact
 138 #define S_IRWXU 0000700    /* RWX mask for owner */
 139 #define S_IRUSR 0000400    /* R for owner */
 140 #define S_IWUSR 0000200    /* W for owner */
 141 #define S_IXUSR 0000100    /* X for owner */
 142
 143 #define S_IRWXG 0000070    /* RWX mask for group */
 144 #define S_IRGRP 0000040    /* R for group */
 145 #define S_IWGRP 0000020    /* W for group */
 146 #define S_IXGRP 0000010    /* X for group */
 147
 148 #define S_IRWXO 0000007    /* RWX mask for other */
 149 #define S_IROTH 0000004    /* R for other */
 150 #define S_IWOTH 0000002    /* W for other */
 151 #define S_IXOTH 0000001    /* X for other */
 152
 153 #define S_ISUID 0004000    /* set user id on execution */
 154 #define S_ISGID 0002000    /* set group id on execution */
 155 #define S_ISVTX 0001000    /* sticky bit */
 156 #ifndef _POSIX_SOURCE
 157 #define S_ISTXT 0001000
 158 #endif
 159 .Ed
 160 .Pp
 161 The
 162 .Va args.mda_cr
 163 argument specifies credentials that will be stored in the
 164 .Fa si_cred
 165 member of the initialized
 166 .Fa struct cdev .
 167 .Pp
 168 The
 169 .Va args.mda_flags
 170 argument alters the operation of
 171 .Fn make_dev_s.
 172 The following values are currently accepted:
 173 .Pp
 174 .Bl -tag -width "It Dv MAKEDEV_CHECKNAME" -compact -offset indent
 175 .It Dv MAKEDEV_REF
 176 reference the created device
 177 .It Dv MAKEDEV_NOWAIT
 178 do not sleep, the call may fail
 179 .It Dv MAKEDEV_WAITOK
 180 allow the function to sleep to satisfy malloc
 181 .It Dv MAKEDEV_ETERNAL
 182 created device will be never destroyed
 183 .It Dv MAKEDEV_CHECKNAME
 184 return an error if the device name is invalid or already exists
 185 .El
 186 .Pp
 187 Only
 188 .Dv MAKEDEV_NOWAIT ,
 189 .Dv MAKEDEV_WAITOK
 190 and
 191 .Dv MAKEDEV_CHECKNAME
 192 values are accepted for the
 193 .Fn make_dev_alias_p
 194 function.
 195 .Pp
 196 The
 197 .Dv MAKEDEV_WAITOK
 198 flag is assumed if none of
 199 .Dv MAKEDEV_WAITOK ,
 200 .Dv MAKEDEV_NOWAIT
 201 is specified.
 202 .Pp
 203 The
 204 .Xr dev_clone 9
 205 event handler shall specify
 206 .Dv MAKEDEV_REF
 207 flag when creating a device in response to lookup, to avoid race where
 208 the device created is destroyed immediately after
 209 .Xr devfs_lookup 9
 210 drops his reference to cdev.
 211 .Pp
 212 The
 213 .Dv MAKEDEV_ETERNAL
 214 flag allows the kernel to not acquire some locks when translating system
 215 calls into the cdevsw methods calls.
 216 It is responsibility of the driver author to make sure that
 217 .Fn destroy_dev
 218 is never called on the returned cdev.
 219 For the convenience, use the
 220 .Dv MAKEDEV_ETERNAL_KLD
 221 flag for the code that can be compiled into kernel or loaded
 222 (and unloaded) as loadable module.
 223 .Pp
 224 A panic will occur if the
 225 .Dv MAKEDEV_CHECKNAME
 226 flag is not specified
 227 and the device name is invalid or already exists.
 228 .Pp
 229 The
 230 .Fn make_dev_p
 231 use of the form
 232 .Bd -literal -offset indent
 233 struct cdev *dev;
 234 int res;
 235 res = make_dev_p(flags, &dev, cdevsw, cred, uid, gid, perms, name);
 236 .Ed
 237 is equivalent to the code
 238 .Bd -literal -offset indent
 239 struct cdev *dev;
 240 struct make_dev_args args;
 241 int res;
 242
 243 make_dev_args_init(&args);
 244 args.mda_flags = flags;
 245 args.mda_devsw = cdevsw;
 246 args.mda_cred = cred;
 247 args.mda_uid = uid;
 248 args.mda_gid = gid;
 249 args.mda_mode = perms;
 250 res = make_dev_s(&args, &dev, name);
 251 .Ed
 252 .Pp
 253 Similarly, the
 254 .Fn make_dev_credf
 255 function call is equivalent to
 256 .Bd -literal -offset indent
 257         (void) make_dev_s(&args, &dev, name);
 258 .Ed
 259 In other words,
 260 .Fn make_dev_credf
 261 does not allow the caller to obtain the return value, and in
 262 kernels compiled with the
 263 .Va INVARIANTS
 264 options, the function asserts that the device creation succeeded.
 265 .Pp
 266 The
 267 .Fn make_dev_cred
 268 function is equivalent to the call
 269 .Bd -literal -offset indent
 270 make_dev_credf(0, cdevsw, unit, cr, uid, gid, perms, fmt, ...);
 271 .Ed
 272 .Pp
 273 The
 274 .Fn make_dev
 275 function call is the same as
 276 .Bd -literal -offset indent
 277 make_dev_credf(0, cdevsw, unit, NULL, uid, gid, perms, fmt, ...);
 278 .Ed
 279 .Pp
 280 The
 281 .Fn make_dev_alias_p
 282 function takes the returned
 283 .Ft cdev
 284 from
 285 .Fn make_dev
 286 and makes another (aliased) name for this device.
 287 It is an error to call
 288 .Fn make_dev_alias_p
 289 prior to calling
 290 .Fn make_dev .
 291 .Pp
 292 The
 293 .Fn make_dev_alias
 294 function is similar to
 295 .Fn make_dev_alias
 296 but it returns the resulting aliasing
 297 .Ft *cdev
 298 and may not return an error.
 299 .Pp
 300 The
 301 .Fa cdev
 302 returned by
 303 .Fn make_dev_s
 304 and
 305 .Fn make_dev_alias_p
 306 has two fields,
 307 .Fa si_drv1
 308 and
 309 .Fa si_drv2 ,
 310 that are available to store state.
 311 Both fields are of type
 312 .Ft void * ,
 313 and can be initialized simultaneously with the
 314 .Va cdev
 315 allocation by filling
 316 .Va args.mda_si_drv1
 317 and
 318 .Va args.mda_si_drv2
 319 members of the
 320 .Fn make_dev_s
 321 argument structure, or filled after the
 322 .Va cdev
 323 is allocated, if using legacy interfaces.
 324 In the latter case, the driver should handle the race of
 325 accessing uninitialized
 326 .Va si_drv1
 327 and
 328 .Va si_drv2
 329 itself.
 330 These are designed to replace the
 331 .Fa unit
 332 argument to
 333 .Fn make_dev ,
 334 which can be obtained with
 335 .Fn dev2unit .
 336 .Pp
 337 The
 338 .Fn destroy_dev
 339 function takes the returned
 340 .Fa cdev
 341 from
 342 .Fn make_dev
 343 and destroys the registration for that device.
 344 The notification is sent to
 345 .Xr devctl 4
 346 about the destruction event.
 347 Do not call
 348 .Fn destroy_dev
 349 on devices that were created with
 350 .Fn make_dev_alias .
 351 .Pp
 352 The
 353 .Fn dev_depends
 354 function establishes a parent-child relationship between two devices.
 355 The net effect is that a
 356 .Fn destroy_dev
 357 of the parent device will also result in the destruction of the
 358 child device(s),
 359 if any exist.
 360 A device may simultaneously be a parent and a child,
 361 so it is possible to build a complete hierarchy.
 362 .Pp
 363 The
 364 .Fn destroy_dev_sched_cb
 365 function schedules execution of the
 366 .Fn destroy_dev
 367 for the specified
 368 .Fa cdev
 369 in the safe context.
 370 After
 371 .Fn destroy_dev
 372 is finished, and if the supplied
 373 .Fa cb
 374 is not
 375 .Dv NULL ,
 376 the callback
 377 .Fa cb
 378 is called, with argument
 379 .Fa arg .
 380 The
 381 .Fn destroy_dev_sched
 382 function is the same as
 383 .Bd -literal -offset indent
 384 destroy_dev_sched_cb(cdev, NULL, NULL);
 385 .Ed
 386 .Pp
 387 The
 388 .Fn d_close
 389 driver method cannot call
 390 .Fn destroy_dev
 391 directly.
 392 Doing so causes deadlock when
 393 .Fn destroy_dev
 394 waits for all threads to leave the driver methods.
 395 Also, because
 396 .Fn destroy_dev
 397 sleeps, no non-sleepable locks may be held over the call.
 398 The
 399 .Fn destroy_dev_sched
 400 family of functions overcome these issues.
 401 .Pp
 402 The device driver may call the
 403 .Fn destroy_dev_drain
 404 function to wait until all devices that have supplied
 405 .Fa csw
 406 as cdevsw, are destroyed.
 407 This is useful when driver knows that
 408 .Fn destroy_dev_sched
 409 is called for all instantiated devices, but need to postpone module
 410 unload until
 411 .Fn destroy_dev
 412 is actually finished for all of them.
 413 .Sh RETURN VALUES
 414 If successful,
 415 .Fn make_dev_s
 416 and
 417 .Fn make_dev_p
 418 will return 0, otherwise they will return an error.
 419 If successful,
 420 .Fn make_dev_credf
 421 will return a valid
 422 .Fa cdev
 423 pointer, otherwise it will return
 424 .Dv NULL .
 425 .Sh ERRORS
 426 The
 427 .Fn make_dev_s ,
 428 .Fn make_dev_p
 429 and
 430 .Fn make_dev_alias_p
 431 calls will fail and the device will be not registered if:
 432 .Bl -tag -width Er
 433 .It Bq Er ENOMEM
 434 The
 435 .Dv MAKEDEV_NOWAIT
 436 flag was specified and a memory allocation request could not be satisfied.
 437 .It Bq Er ENAMETOOLONG
 438 The
 439 .Dv MAKEDEV_CHECKNAME
 440 flag was specified and the provided device name is longer than
 441 .Dv SPECNAMELEN .
 442 .It Bq Er EINVAL
 443 The
 444 .Dv MAKEDEV_CHECKNAME
 445 flag was specified and the provided device name is empty, contains a
 446 .Qq \&.
 447 or
 448 .Qq ..
 449 path component or ends with
 450 .Ql / .
 451 .It Bq Er EINVAL
 452 The
 453 .Dv MAKEDEV_CHECKNAME
 454 flag was specified and the provided device name contains invalid characters.
 455 .It Bq Er EEXIST
 456 The
 457 .Dv MAKEDEV_CHECKNAME
 458 flag was specified and the provided device name already exists.
 459 .El
 460 .Sh SEE ALSO
 461 .Xr devctl 4 ,
 462 .Xr devfs 5 ,
 463 .Xr destroy_dev_drain 9 ,
 464 .Xr dev_clone 9
 465 .Sh HISTORY
 466 The
 467 .Fn make_dev
 468 and
 469 .Fn destroy_dev
 470 functions first appeared in
 471 .Fx 4.0 .
 472 The function
 473 .Fn make_dev_alias
 474 first appeared in
 475 .Fx 4.1 .
 476 The function
 477 .Fn dev_depends
 478 first appeared in
 479 .Fx 5.0 .
 480 The functions
 481 .Fn make_dev_credf ,
 482 .Fn destroy_dev_sched ,
 483 .Fn destroy_dev_sched_cb
 484 first appeared in
 485 .Fx 7.0 .
 486 The function
 487 .Fn make_dev_p
 488 first appeared in
 489 .Fx 8.2 .
 490 The function
 491 .Fn make_dev_s
 492 first appeared in
 493 .Fx 11.0 .