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: src/share/man/man9/make_dev.9,v 1.2.2.3 2001/12/17 11:30:18 ru Exp $
  26 .\"
  27 .Dd September 11, 2009
  28 .Dt MAKE_DEV 9
  29 .Os
  30 .Sh NAME
  31 .Nm destroy_dev ,
  32 .Nm destroy_only_dev ,
  33 .Nm devfs_scan_callback ,
  34 .Nm dev_ops_intercept ,
  35 .Nm dev_ops_remove_all ,
  36 .Nm dev_ops_remove_minor ,
  37 .Nm dev_ops_restore ,
  38 .Nm make_dev ,
  39 .Nm make_dev_alias ,
  40 .Nm make_dev_covering ,
  41 .Nm make_only_dev ,
  42 .Nm reference_dev ,
  43 .Nm release_dev
  44 .Nd "device entry manipulation functions"
  45 .Sh SYNOPSIS
  46 .In sys/types.h
  47 .In sys/conf.h
  48 .In sys/devfs.h
  49 .Ft void
  50 .Fn destroy_dev "cdev_t dev"
  51 .Ft void
  52 .Fn destroy_only_dev "cdev_t dev"
  53 .Ft int
  54 .Fn devfs_scan_callback "devfs_scan_t *callback"
  55 .Ft struct dev_ops *
  56 .Fn dev_ops_intercept "cdev_t dev" "struct dev_ops *iops"
  57 .Ft int
  58 .Fn dev_ops_remove_all "struct dev_ops *ops"
  59 .Ft void
  60 .Fn dev_ops_restore "cdev_t dev" "struct dev_ops *oops"
  61 .Ft int
  62 .Fn dev_ops_remove_minor "struct dev_ops *ops" "int minor"
  63 .Ft cdev_t
  64 .Fn make_dev "struct dev_ops *ops" "int minor" "uid_t uid" "gid_t gid" "int perms" "char *fmt" ...
  65 .Ft int
  66 .Fn make_dev_alias "cdev_t target" "const char *fmt" ...
  67 .Ft cdev_t
  68 .Fn make_dev_covering "struct dev_ops *ops" "cdev_t rdev" "int minor" "uid_t uid" "gid_t gid" "int perms" "char *fmt" ...
  69 .Ft cdev_t
  70 .Fn make_only_dev "struct dev_ops *ops" "int minor" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ...
  71 .Ft cdev_t
  72 .Fn reference_dev "cdev_t dev"
  73 .Ft void
  74 .Fn release_dev "cdev_t dev"
  75 .Sh DESCRIPTION
  76 The
  77 .Fn make_dev
  78 function creates a
  79 .Vt cdev_t
  80 structure for a new device and makes the device name visible in the
  81 .Xr devfs 5
  82 mount points.
  83 The device's name must be unique.
  84 The name is the expansion of
  85 .Fa fmt
  86 and following arguments as
  87 .Xr kprintf 9
  88 would print it.
  89 The name determines its path under
  90 .Pa /dev .
  91 The permissions of the file specified in
  92 .Fa perms
  93 are defined in
  94 .In sys/stat.h :
  95 .Pp
  96 .Bd -literal -offset indent -compact
  97 #define S_IRWXU 0000700    /* RWX mask for owner */
  98 #define S_IRUSR 0000400    /* R for owner */
  99 #define S_IWUSR 0000200    /* W for owner */
 100 #define S_IXUSR 0000100    /* X for owner */
 101
 102 #define S_IRWXG 0000070    /* RWX mask for group */
 103 #define S_IRGRP 0000040    /* R for group */
 104 #define S_IWGRP 0000020    /* W for group */
 105 #define S_IXGRP 0000010    /* X for group */
 106
 107 #define S_IRWXO 0000007    /* RWX mask for other */
 108 #define S_IROTH 0000004    /* R for other */
 109 #define S_IWOTH 0000002    /* W for other */
 110 #define S_IXOTH 0000001    /* X for other */
 111
 112 #define S_ISUID 0004000    /* set user id on execution */
 113 #define S_ISGID 0002000    /* set group id on execution */
 114 #define S_ISVTX 0001000    /* sticky bit */
 115 #ifndef _POSIX_SOURCE
 116 #define S_ISTXT 0001000
 117 #endif
 118 .Ed
 119 .Pp
 120 The
 121 .Fa ops
 122 argument is a pointer to a
 123 .Vt dev_ops
 124 data structure, which is defined as follows:
 125 .Bd -literal
 126 struct dev_ops {
 127         struct {
 128                 const char      *name;  /* base name, e.g. 'da' */
 129                 int              maj;   /* major device number */
 130                 u_int            flags; /* D_XXX flags */
 131                 void            *data;  /* custom driver data */
 132                 int              refs;  /* ref count */
 133                 int              id;
 134         } head;
 135
 136 #define dev_ops_first_field     d_default
 137         d_default_t     *d_default;
 138         d_open_t        *d_open;
 139         d_close_t       *d_close;
 140         d_read_t        *d_read;
 141         d_write_t       *d_write;
 142         d_ioctl_t       *d_ioctl;
 143         d_mmap_t        *d_mmap;
 144         d_strategy_t    *d_strategy;
 145         d_dump_t        *d_dump;
 146         d_psize_t       *d_psize;
 147         d_kqfilter_t    *d_kqfilter;
 148         d_clone_t       *d_clone;       /* clone from base dev_ops */
 149         d_revoke_t      *d_revoke;
 150 #define dev_ops_last_field      d_revoke
 151 };
 152 .Ed
 153 .Pp
 154 While one can and should initialize the
 155 .Fa name
 156 and
 157 .Fa maj
 158 fields, they are effectively ignored.
 159 Device major numbers are assigned automatically out of an internal pool of
 160 major numbers, so there is no need to specify a unique major number in the
 161 .Vt dev_ops
 162 structure.
 163 .Pp
 164 Every member of the
 165 .Fn d_xxx_t
 166 family is defined as:
 167 .Bd -literal
 168 typedef int d_xxx_t (struct dev_xxx_args *ap);
 169 .Ed
 170 .Pp
 171 Therefore, if one wants to implement a
 172 .Fn mydev_open
 173 function, this is the way:
 174 .Bd -literal
 175 d_open_t mydev_open;
 176
 177 int
 178 mydev_open(struct dev_open_args *ap)
 179 {
 180 }
 181 .Ed
 182 .Pp
 183 .Fn make_dev_covering
 184 is equivalent to make_dev, except that it also takes an argument
 185 .Vt cdev_t rdev
 186 which is set as the backing device for the newly created device.
 187 This function should be used whenever a device is created covering
 188 another raw device, as the disk subsystem does.
 189 .Pp
 190 .Fn make_only_dev
 191 creates a
 192 .Vt cdev_t
 193 structure and initializes it the same way
 194 .Fn make_dev
 195 would, but the device will not appear in the
 196 .Xr devfs 5
 197 namespace.
 198 .Pp
 199 .Fn destroy_dev
 200 takes the returned
 201 .Vt cdev_t
 202 from
 203 .Fn make_dev
 204 and destroys the registration for that device.
 205 It should not be used to destroy a
 206 .Vt cdev_t
 207 created by
 208 .Fn make_only_dev .
 209 .Pp
 210 .Fn destroy_only_dev
 211 takes the returned
 212 .Vt cdev_t
 213 from
 214 .Fn make_only_dev
 215 and destroys the registration for that device.
 216 It should not be used to destroy a
 217 .Vt cdev_t
 218 created by
 219 .Fn make_dev .
 220 .Pp
 221 .Fn make_dev_alias
 222 creates an automatic
 223 .Xr devfs 5
 224 link (alias) with the given name to the
 225 .Vt cdev_t
 226 specified by
 227 .Fa target .
 228 The
 229 .Vt cdev_t
 230 must have been created either by
 231 .Fn make_dev
 232 or bt a clone handler.
 233 Aliases are alternative names for devices in the
 234 .Xr devfs 5
 235 namespace.
 236 The lifetime of an alias is that of its associated
 237 .Vt cdev_t .
 238 Once the
 239 .Vt cdev_t
 240 is removed or destroyed, the alias is also destroyed and its name is
 241 removed from the
 242 .Xr devfs 5
 243 namespace.
 244 .Pp
 245 .Fn reference_dev
 246 adds a reference to
 247 .Fa dev .
 248 Callers generally add their own references when they are going to store a device
 249 node in a variable for long periods of time, to prevent a disassociation from
 250 freeing the node.
 251 .Pp
 252 .Fn release_dev
 253 releases a reference on
 254 .Fa dev .
 255 The device will be terminated when the last reference has been released.
 256 .Pp
 257 .Fn dev_ops_intercept
 258 intercepts the device operations vector of
 259 .Fa dev
 260 with
 261 .Fa iops .
 262 The old
 263 .Vt dev_ops
 264 is returned which may be used in a subsequent
 265 .Fn dev_ops_restore
 266 call.
 267 The function sets the
 268 .Dv SI_INTERCEPTED
 269 flag in
 270 .Fa dev .
 271 .Pp
 272 .Fn dev_ops_restore
 273 restores the device operations vector of
 274 .Fa dev
 275 to
 276 .Fa oops .
 277 Also it unsets the
 278 .Dv SI_INTERCEPTED
 279 flag in
 280 .Fa dev .
 281 .Pp
 282 .Fn dev_ops_remove_all
 283 destroys all the
 284 .Vt cdev_t
 285 with the given
 286 .Fa ops
 287 and removes the devices from the
 288 .Xr devfs 5
 289 namespace.
 290 This function is useful when uninitializing a driver.
 291 .Pp
 292 .Fn dev_ops_remove_minor
 293 destroys all the
 294 .Vt cdev_t
 295 with the given
 296 .Fa ops
 297 and
 298 .Fa minor
 299 and removes the devices from the
 300 .Xr devfs 5
 301 namespace.
 302 .Pp
 303 .Fn devfs_scan_callback
 304 calls the given
 305 .Fa callback
 306 function for every device registered in
 307 .Xr devfs 5 .
 308 The
 309 .Fa callback
 310 function has the following form:
 311 .Bd -literal
 312 devfs_scan_t mydev_scan_callback;
 313
 314 void
 315 mydev_scan_callback(cdev_t dev)
 316 {
 317 };
 318 .Ed
 319 .Sh HISTORY
 320 The
 321 .Fn make_dev
 322 and
 323 .Fn destroy_dev
 324 functions first appeared in
 325 .Fx 4.0 .
 326 .Pp
 327 A major overhaul of these functions occurred in
 328 .Dx 2.3
 329 with the addition of
 330 .Xr devfs 5 .