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