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