| blob | f7c85409ebc3352374694febcc830618acc83837 |
1 .\" $NetBSD: autoconf.9,v 1.25 2009/09/16 22:47:29 dyoung Exp $
2 .\"
3 .\" Copyright (c) 2001, 2002 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Gregory McGarry.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd December 7, 2009
31 .Dt AUTOCONF 9
32 .Os
33 .Sh NAME
34 .Nm autoconf ,
35 .Nm config_search_loc ,
36 .Nm config_search_ia ,
37 .Nm config_found_sm_loc ,
38 .Nm config_found_ia ,
39 .Nm config_found ,
40 .Nm config_match ,
41 .Nm config_attach_loc ,
42 .Nm config_attach ,
43 .Nm config_attach_pseudo ,
44 .Nm config_detach ,
45 .Nm config_deactivate ,
46 .Nm config_defer ,
47 .Nm config_interrupts ,
48 .Nm config_pending_incr ,
49 .Nm config_pending_decr ,
50 .Nm config_finalize_register
51 .Nd autoconfiguration framework
52 .Sh SYNOPSIS
53 .In sys/param.h
54 .In sys/device.h
55 .In sys/errno.h
56 .Ft cfdata_t
57 .Fn config_search_loc "cfsubmatch_t func" "device_t parent" "const char *ia" \
58 "const int *locs" "void *aux"
59 .Ft cfdata_t
60 .Fn config_search_ia "cfsubmatch_t func" "device_t parent" "const char *ia" \
61 "void *aux"
62 .Ft device_t
63 .Fn config_found_sm_loc "device_t parent" "const char *ia" "const int *locs" \
64 "void *aux" "cfprint_t print" "cfsubmatch_t submatch"
65 .Ft device_t
66 .Fn config_found_ia "device_t parent" "const char *ia" "void *aux" \
67 "cfprint_t print"
68 .Ft device_t
69 .Fn config_found "device_t parent" "void *aux" "cfprint_t print"
70 .Ft int
71 .Fn config_match "device_t parent" "cfdata_t cf" "void *aux"
72 .Ft device_t
73 .Fn config_attach_loc "device_t parent" "cfdata_t cf" "const int *locs" \
74 "void *aux" "cfprint_t print"
75 .Ft device_t
76 .Fn config_attach "device_t parent" "cfdata_t cf" "void *aux" \
77 "cfprint_t print"
78 .Ft device_t
79 .Fn config_attach_pseudo "cfdata_t cf"
80 .Ft int
81 .Fn config_detach "device_t dev" "int flags"
82 .Ft int
83 .Fn config_deactivate "device_t dev"
84 .Ft int
85 .Fn config_defer "device_t dev" "void (*func)(device_t)"
86 .Ft void
87 .Fn config_interrupts "device_t dev" "void (*func)(device_t)"
88 .Ft void
89 .Fn config_pending_incr
90 .Ft void
91 .Fn config_pending_decr
92 .Ft int
93 .Fn config_finalize_register "device_t dev" "int (*func)(device_t)"
94 .Sh DESCRIPTION
95 Autoconfiguration is the process of matching hardware devices with an
96 appropriate device driver.
97 In its most basic form, autoconfiguration consists of the recursive process
98 of finding and attaching all devices on a bus, including other busses.
99 .Pp
100 The autoconfiguration framework supports
101 .Em direct configuration
102 where the bus driver can determine the devices present.
103 The autoconfiguration framework also supports
104 .Em indirect configuration
105 where the drivers must probe the bus looking for the presence of a device.
106 Direct configuration is preferred since it can find hardware
107 regardless of the presence of proper drivers.
108 .Pp
109 The autoconfiguration process occurs at system bootstrap and is driven
110 by a table generated from a
111 .Do
112 machine description
113 .Dc
114 file by
115 .Xr config 1 .
116 For a description of the
117 .Xr config 1
118 .Do
119 device definition
120 .Dc
121 language, see
122 .Xr config 9 .
123 .Pp
124 Each device must have a name consisting of an alphanumeric string that
125 ends with a unit number.
126 The unit number identifies an instance of the driver.
127 Device data structures are allocated dynamically during
128 autoconfiguration, giving a unique address for each instance.
129 .Sh FUNCTIONS
130 .Bl -tag -width compact
131 .It Fn config_search_loc "func" "parent" "ia" "locs" "aux"
132 Performs indirect configuration of physical devices.
133 .Fn config_search_loc
134 iterates over all potential children, calling the given
135 function
136 .Fa func
137 for each one.
138 If
139 .Fa func
140 is
141 .Dv NULL ,
142 .Fn config_search_loc
143 applies each child's match function instead.
144 The argument
145 .Fa parent
146 is the pointer to the parent's device structure.
147 The argument
148 .Fa ia
149 is the interface attribute on which the potential children should attach.
150 It can be
151 .Dv NULL ,
152 in which case all children attaching to any attribute are considered.
153 The
154 .Fa locs
155 argument lists the locator values for the device and are passed to function
156 .Fa func .
157 The given
158 .Fa aux
159 argument describes the device that has been found and is simply passed
160 on through
161 .Fa func
162 to the child.
163 .Fn config_search_loc
164 returns a pointer to the best-matched child or
165 .Dv NULL
166 otherwise.
167 .Pp
168 The role of
169 .Fa func
170 is to call
171 the match function for each device and call
172 .Fn config_attach_loc
173 for any positive matches.
174 If
175 .Fa func
176 is
177 .Dv NULL ,
178 then the parent should record the return value from
179 .Fn config_search_loc
180 and call
181 .Fn config_attach_loc
182 itself.
183 .Pp
184 Note that this function is designed so that it can be used to apply an
185 arbitrary function to all potential children.
186 In this case callers may choose to ignore the return value.
187 .It Fn config_search_ia "func" "parent" "ia" "aux"
188 This function is equivalent to calling
189 .Fn config_search_loc "func" "parent" "ia" "locs" "aux"
190 with
191 .Fa locs
192 set to
193 .Dv NULL .
194 .It Fn config_found_sm_loc "parent" "ia" "locs" "aux" "print" "submatch"
195 Performs direct configuration on a physical device.
196 .Fn config_found_sm_loc
197 is called by the parent and in turn calls the
198 .Fa submatch
199 function to call the match function as
200 determined by the configuration table.
201 If
202 .Fa submatch
203 is
204 .Dv NULL ,
205 the driver match functions are called directly.
206 The argument
207 .Fa parent
208 is the pointer to the parent's device structure.
209 The argument
210 .Fa ia
211 is the name of the interface attribute on which the child will attach,
212 per
213 .Xr config 5
214 syntax.
215 The argument
216 .Fa locs
217 lists the locator values for the device.
218 The given
219 .Fa aux
220 argument describes the device that has been found.
221 .Fn config_found_sm_loc
222 internally uses
223 .Fn config_search_loc ,
224 passing on
225 .Fa submatch , ia , locs
226 and
227 .Fa aux .
228 The
229 .Em softc
230 structure for the matched device will be allocated, and the
231 appropriate driver attach function will be called.
232 If the device is matched, the system prints the name of the child and
233 parent devices, and then calls the
234 .Fa print
235 function to produce additional information if desired.
236 If no driver takes a match, the same
237 .Fa print
238 function is called to complain.
239 The print function is called with the
240 .Fa aux
241 argument and, if the matches failed, the full name (including unit
242 number) of the parent device, otherwise
243 .Dv NULL .
244 The
245 .Fa print
246 function must return an integer value.
247 .Pp
248 Two special strings,
249 .Do
250 not configured
251 .Dc
252 and
253 .Do
254 unsupported
255 .Dc
256 will be appended automatically to non-driver reports if the return
257 value is UNCONF or UNSUPP respectively; otherwise the function should
258 return the value QUIET.
259 .Pp
260 .Fn config_found_sm_loc
261 returns a pointer to the attached device's
262 .Em softc
263 structure if the device is attached,
264 .Dv NULL
265 otherwise.
266 Most callers can ignore this value, since the system will already have
267 printed a diagnostic.
268 .It Fn config_found_ia "parent" "ia" "aux" "print"
269 This function is equivalent to calling
270 .Fn config_found_sm_loc "parent" "ia" "locs" "aux" "print" "submatch"
271 with
272 .Fa locs
273 and
274 .Fa submatch
275 set to
276 .Dv NULL .
277 It is provided for better source code readability with locator-less device
278 buses.
279 .It Fn config_found "parent" "aux" "print"
280 This function is equivalent to calling
281 .Fn config_found_sm_loc "parent" "ia" "locs" "aux" "print" "submatch"
282 with
283 .Fa ia , locs
284 and
285 .Fa submatch
286 set to
287 .Dv NULL
288 and is provided for compatibility with older drivers.
289 New code should either make the interface attribute explicit or prefer an
290 indirect method based on
291 .Fn config_search_loc .
292 .It Fn config_match "parent" "cf" "aux"
293 Match a device.
294 Invokes the drivers match function according to the
295 configuration table.
296 The
297 .Fn config_match
298 function returns a nonzero integer indicating the confidence of
299 supporting this device and a value of 0 if the driver doesn't support
300 the device.
301 .It Fn config_attach_loc "parent" "locs" "cf" "aux" "print"
302 Attach a found device.
303 Allocates the memory for the
304 .Em softc
305 structure and calls the drivers attach function according to the
306 configuration table.
307 If successful,
308 .Fn config_attach_loc
309 returns the
310 .Em softc .
311 If unsuccessful, it returns
312 .Dv NULL .
313 .It Fn config_attach "parent" "cf" "aux" "print"
314 This function is equivalent to calling
315 .Fn config_attach_loc "parent" "cf" "locs" "aux" "print"
316 with
317 .Fa locs
318 set to
319 .Dv NULL .
320 .It Fn config_attach_pseudo "cf"
321 Create an instance of a pseudo-device driver.
322 .Xr config 5
323 syntax allows the creation of pseudo-devices from which regular
324 .Ft device_t
325 instances can be created.
326 Such objects are similar to the devices that attach at the root of the device
327 tree.
328 .Pp
329 The caller is expected to allocate and fill the
330 .Ft cfdata_t
331 object and pass it to
332 .Fn config_attach_pseudo .
333 The content of that object is similar to what is returned by
334 .Fn config_search_loc
335 for regular devices.
336 .It Fn config_detach "dev" "flags"
337 Called by the parent to detach the child device.
338 The second argument
339 .Em flags
340 contains detachment flags.
341 Valid values are DETACH_FORCE (force detachment (e.g., because of hardware
342 removal)) and DETACH_QUIET (do not print a notice).
343 .Fn config_detach
344 returns zero if successful and an error code otherwise.
345 .Fn config_detach
346 is always called from a thread context, allowing condition variables
347 to be used while the device detaches itself.
348 .It Fn config_deactivate "dev"
349 Called by the parent to deactivate the child device
350 .Fa dev .
351 .Fn config_deactivate
352 is called from interrupt context to immediately relinquish resources
353 and notify dependent kernel subsystems that the device is about to be
354 detached.
355 At some later point
356 .Fn config_detach
357 will be called to finalise the removal of the device.
358 .It Fn config_defer "dev" "func"
359 Called by the child to defer the remainder of its configuration until
360 all its parent's devices have been attached.
361 At this point, the function
362 .Fa func
363 is called with the argument
364 .Fa dev .
365 .It Fn config_interrupts "dev" "func"
366 Called by the child to defer the remainder of its configuration until
367 interrupts are enabled.
368 At this point, the function
369 .Fa func
370 is called with the argument
371 .Fa dev .
372 .It Fn config_pending_incr
373 Increment the
374 .Va config_pending
375 semaphore.
376 It is used to account for deferred configurations before
377 mounting the root file system.
378 .It Fn config_pending_decr
379 Decrement the
380 .Va config_pending
381 semaphore.
382 It is used to account for deferred configurations before
383 mounting the root file system.
384 .It Fn config_finalize_register "dev" "func"
385 Register a function to be called after all real devices have been found.
386 .Pp
387 Registered functions are all executed until all of them return 0.
388 The callbacks should return 0 to indicate they do not require to be called
389 another time, but they should be aware that they still might be in case one of
390 them returns 1.
391 .El
392 .Sh CODE REFERENCES
393 This section describes places within the
394 .Nx
395 source tree where actual code implementing or using the
396 autoconfiguration framework can be found.
397 All pathnames are relative to
398 .Pa /usr/src .
399 .Pp
400 The autoconfiguration framework itself is implemented within the file
401 .Pa sys/kern/subr_autoconf.c .
402 Data structures and function prototypes for the framework are located in
403 .Pa sys/sys/device.h .
404 .Sh SEE ALSO
405 .Xr config 1 ,
406 .Xr config 5 ,
407 .Xr condvar 9 ,
408 .Xr config 9 ,
409 .Xr driver 9
410 .Sh HISTORY
411 Autoconfiguration first appeared in
412 .Bx 4.1 .
413 The autoconfiguration framework was completely revised in
414 .Bx 4.4 .
415 The detach and deactivate interfaces appeared in
416 .Nx 1.5 .