Commit | Line | Data |
---|---|---|
984263bc MD |
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 | .\" | |
b28e21ef | 27 | .Dd August 26, 2012 |
984263bc | 28 | .Dt MAKE_DEV 9 |
fb5b3747 | 29 | .Os |
984263bc | 30 | .Sh NAME |
f7ca11e0 | 31 | .Nm destroy_dev , |
1e811a6e SW |
32 | .Nm destroy_only_dev , |
33 | .Nm devfs_scan_callback , | |
f7ca11e0 | 34 | .Nm dev_ops_intercept , |
1e811a6e SW |
35 | .Nm dev_ops_remove_all , |
36 | .Nm dev_ops_remove_minor , | |
f7ca11e0 | 37 | .Nm dev_ops_restore , |
984263bc | 38 | .Nm make_dev , |
1e811a6e | 39 | .Nm make_dev_alias , |
7d6ff826 | 40 | .Nm make_dev_covering , |
1e811a6e | 41 | .Nm make_only_dev , |
f7ca11e0 SW |
42 | .Nm reference_dev , |
43 | .Nm release_dev | |
44 | .Nd "device entry manipulation functions" | |
984263bc MD |
45 | .Sh SYNOPSIS |
46 | .In sys/types.h | |
47 | .In sys/conf.h | |
d0bbd768 | 48 | .In sys/devfs.h |
984263bc | 49 | .Ft void |
f7ca11e0 | 50 | .Fn destroy_dev "cdev_t dev" |
1e811a6e SW |
51 | .Ft void |
52 | .Fn destroy_only_dev "cdev_t dev" | |
f7ca11e0 | 53 | .Ft int |
5b48c5b0 | 54 | .Fn devfs_scan_callback "devfs_scan_t *callback" "void *arg" |
f7ca11e0 SW |
55 | .Ft struct dev_ops * |
56 | .Fn dev_ops_intercept "cdev_t dev" "struct dev_ops *iops" | |
f7ca11e0 | 57 | .Ft int |
1e811a6e | 58 | .Fn dev_ops_remove_all "struct dev_ops *ops" |
f7ca11e0 SW |
59 | .Ft void |
60 | .Fn dev_ops_restore "cdev_t dev" "struct dev_ops *oops" | |
61 | .Ft int | |
1e811a6e | 62 | .Fn dev_ops_remove_minor "struct dev_ops *ops" "int minor" |
f7ca11e0 | 63 | .Ft cdev_t |
7d807da9 | 64 | .Fn make_dev "struct dev_ops *ops" "int minor" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... |
1e811a6e SW |
65 | .Ft int |
66 | .Fn make_dev_alias "cdev_t target" "const char *fmt" ... | |
f7ca11e0 | 67 | .Ft cdev_t |
7d807da9 | 68 | .Fn make_dev_covering "struct dev_ops *ops" "struct dev_ops *bops" "int minor" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... |
8fc40216 | 69 | .Ft cdev_t |
1e811a6e | 70 | .Fn make_only_dev "struct dev_ops *ops" "int minor" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... |
f7ca11e0 SW |
71 | .Ft cdev_t |
72 | .Fn reference_dev "cdev_t dev" | |
73 | .Ft void | |
74 | .Fn release_dev "cdev_t dev" | |
984263bc MD |
75 | .Sh DESCRIPTION |
76 | The | |
77 | .Fn make_dev | |
78 | function creates a | |
f7ca11e0 | 79 | .Vt cdev_t |
1e811a6e SW |
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. | |
f7ca11e0 SW |
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 . | |
984263bc | 91 | The permissions of the file specified in |
f7ca11e0 | 92 | .Fa perms |
984263bc | 93 | are defined in |
44cb301e | 94 | .In sys/stat.h : |
984263bc MD |
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 | |
1e811a6e SW |
120 | The |
121 | .Fa ops | |
122 | argument is a pointer to a | |
f7ca11e0 SW |
123 | .Vt dev_ops |
124 | data structure, which is defined as follows: | |
125 | .Bd -literal | |
126 | struct dev_ops { | |
1e811a6e SW |
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; | |
f7ca11e0 | 135 | |
1e811a6e SW |
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; | |
1e811a6e SW |
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 | |
f7ca11e0 SW |
151 | }; |
152 | .Ed | |
153 | .Pp | |
1e811a6e SW |
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 | |
f7ca11e0 SW |
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 | |
8fc40216 AH |
183 | .Fn make_dev_covering |
184 | is equivalent to make_dev, except that it also takes an argument | |
7d807da9 | 185 | .Fa bops |
07c0ca79 | 186 | which is set as the ops of the backing device for the newly created device. |
8fc40216 AH |
187 | This function should be used whenever a device is created covering |
188 | another raw device, as the disk subsystem does. | |
189 | .Pp | |
1e811a6e SW |
190 | .Fn make_only_dev |
191 | creates a | |
192 | .Vt cdev_t | |
193 | structure and initializes it the same way | |
f7ca11e0 | 194 | .Fn make_dev |
1e811a6e SW |
195 | would, but the device will not appear in the |
196 | .Xr devfs 5 | |
197 | namespace. | |
f7ca11e0 | 198 | .Pp |
984263bc | 199 | .Fn destroy_dev |
f7ca11e0 SW |
200 | takes the returned |
201 | .Vt cdev_t | |
984263bc MD |
202 | from |
203 | .Fn make_dev | |
204 | and destroys the registration for that device. | |
1e811a6e SW |
205 | It should not be used to destroy a |
206 | .Vt cdev_t | |
207 | created by | |
208 | .Fn make_only_dev . | |
f7ca11e0 | 209 | .Pp |
1e811a6e SW |
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. | |
f7ca11e0 SW |
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. | |
f7ca11e0 SW |
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 | |
f7ca11e0 SW |
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 | |
1e811a6e SW |
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 | |
b28e21ef | 315 | mydev_scan_callback(char *name, cdev_t dev, bool is_alias, void *arg) |
1e811a6e SW |
316 | { |
317 | }; | |
318 | .Ed | |
b28e21ef SW |
319 | .Pp |
320 | The | |
321 | .Fa name | |
322 | argument is the alias' name (if | |
323 | .Fa is_alias | |
324 | is | |
325 | .Dv true ) | |
ff0e921b | 326 | or the |
b28e21ef SW |
327 | .Vt cdev Ap s |
328 | .Fa si_name | |
329 | field. | |
984263bc MD |
330 | .Sh HISTORY |
331 | The | |
332 | .Fn make_dev | |
333 | and | |
334 | .Fn destroy_dev | |
335 | functions first appeared in | |
336 | .Fx 4.0 . | |
1e811a6e | 337 | .Pp |
0b874f77 SW |
338 | A major overhaul of these functions occurred in |
339 | .Dx 2.3 | |
340 | with the addition of | |
1e811a6e | 341 | .Xr devfs 5 . |