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