Update the make_dev(9) manual page for devfs.
[dragonfly.git] / 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 .