1.\" $NetBSD: autoconf.9,v 1.10 2002/04/02 14:14:45 heinz Exp $ 2.\" 3.\" Copyright (c) 2001 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd June 17, 2001 38.Dt AUTOCONF 9 39.Os 40.Sh NAME 41.Nm autoconf , 42.Nm config_search , 43.Nm config_found_sm , 44.Nm config_found , 45.Nm config_attach , 46.Nm config_detach , 47.Nm config_activate , 48.Nm config_deactivate , 49.Nm config_defer , 50.Nm config_interrupts , 51.Nm config_pending_incr , 52.Nm config_pending_decr 53.Nd autoconfiguration framework 54.Sh SYNOPSIS 55.Fd #include \*[Lt]sys/param.h\*[Gt] 56.Fd #include \*[Lt]sys/device.h\*[Gt] 57.Fd #include \*[Lt]sys/error.h\*[Gt] 58.Ft struct cfdata * 59.Fn config_search "cfmatch_t func" "struct device *parent" "void *aux" 60.Ft struct device * 61.Fn config_found_sm "struct device *parent" "void *aux" "cfprint_t print" \ 62"cfmatch_t submatch" 63.Ft struct device * 64.Fn config_found "struct device *parent" "void *aux" "cfprint_t print" 65.Ft struct device * 66.Fn config_attach "struct device *parent" "struct cfdata *cf" "void *aux" \ 67"cfprint_t print" 68.Ft int 69.Fn config_detach "struct device *dev" "int flags" 70.Ft int 71.Fn config_activate "struct device *dev" 72.Ft int 73.Fn config_deactivate "struct device *dev" 74.Ft int 75.Fn config_defer "struct device *dev" "void (*func)(struct device *)" 76.Ft void 77.Fn config_interrupts "struct device *dev" "void (*func)(struct device *)" 78.Ft void 79.Fn config_pending_incr 80.Ft void 81.Fn config_pending_decr 82.Sh DESCRIPTION 83Autoconfiguration is the process of matching hardware devices with an 84appropriate device driver. In its most basic form, autoconfiguration 85consists of the recursive process of finding and attaching all devices 86on a bus, including other busses. 87.Pp 88The autoconfiguration framework supports 89.Em direct configuration 90where the bus driver can determine the devices present. The 91autoconfiguration framework also supports 92.Em indirect configuration 93where the drivers must probe the bus looking for the presence of a device. 94Direct configuration is preferred since it can find hardware 95regardless of the presence of proper drivers. 96.Pp 97The autoconfiguration process occurs at system bootstrap and is driven 98by a table generated from a 99.Do 100machine description 101.Dc 102file by 103.Xr config 8 . 104For a description of the 105.Xr config 8 106.Do 107device definition 108.Dc 109language, see 110.Xr config 9 . 111.Pp 112Each device must have a name consisting of an alphanumeric string that 113ends with a unit number. The unit number identifies an instance of 114the driver. Device data structures are allocated dynamically during 115autoconfiguration, giving a unique address for each instance. 116.Sh FUNCTIONS 117.Bl -tag -width compact 118.It Fn config_search "func" "parent" "aux" 119Performs indirect configuration of physical devices. 120.Fn config_search 121iterates over all potential children, calling the given 122function 123.Fa func 124for each one. If 125.Fa func 126is NULL, 127.Fn config_search 128applies each child's match function instead. The argument 129.Fa parent 130is the pointer to the parent's device structure. The given 131.Fa aux 132argument describes the device that has been found and is simply passed 133on through 134.Fa func 135to the child. 136.Fn config_search 137returns a pointer to the best-matched child or NULL otherwise. 138.Pp 139The role of 140.Fa func 141is to call 142the match function for each device and call 143.Fn config_attach 144for any positive matches. If 145.Fa func 146is NULL, then the parent should record the return value from 147.Fn config_search 148and call 149.Fn config_attach 150itself. 151.Pp 152Note that this function is designed so that it can be used to apply an 153arbitrary function to all potential children. In this case callers 154may choose to ignore the return value. 155.It Fn config_found_sm "parent" "aux" "print" "submatch" 156Performs direct configuration on a physical device. 157.Fn config_found_sm 158is called by the parent and in turn calls the 159.Fa submatch 160function to call the match function as 161determined by the configuration table. If 162.Fa submatch 163is NULL, the driver match functions are called directly. The argument 164.Fa parent 165is the pointer to the parent's device structure. The given 166.Fa aux 167argument describes the device that has been found. The 168.Em softc 169structure for the matched device will be allocated, and the 170appropriate driver attach function will be called. If the device is 171matched, the system prints the name of the child and parent devices, 172and then calls the 173.Fa print 174function to produce additional information if desired. If no driver 175takes a match, the same 176.Fa print 177function is called to complain. The print function is called with the 178.Fa aux 179argument and, if the matches failed, the full name (including unit 180number) of the parent device, otherwise NULL. The 181.Fa print 182function must return an integer value. 183.Pp 184Two special strings, 185.Do 186 not configured 187.Dc 188and 189.Do 190 unsupported 191.Dc 192will be appended automatically to non-driver reports if the return 193value is UNCONF or UNSUPP respectively; otherwise the function should 194return the value QUIET. 195.Pp 196.Fn config_found_sm 197returns a pointer to the attached device's 198.Em softc 199structure if the device is attached, NULL otherwise. Most callers can 200ignore this value, since the system will already have printed a 201diagnostic. 202.It Fn config_found "parent" "aux" "print" 203This function is equivalent to calling 204.Fn config_found_sm "parent" "aux" "print" "submatch" 205with 206.Fa submatch 207set to NULL and is provided for compatibility with older drivers. 208.It Fn config_attach "parent" "cf" "aux" "print" 209Attach a found device. Allocates the memory for the 210.Em softc 211structure and calls the drivers attach function according to the 212configuration table. 213If successful, 214.Fn config_attach 215returns the 216.Em softc . 217If unsuccessful, it returns NULL. 218.It Fn config_detach "dev" "flags" 219Called by the parent to detach the child device. The second argument 220.Em flags 221contains detachment flags. Valid values are DETACH_FORCE (force 222detachment (eg. because of hardware removal) and DETACH_QUIET (do not 223print a notice). 224.Fn config_detach 225returns zero if successful and an error code otherwise. 226.Fn config_detach 227is always called from a thread context, allowing 228.Xr sleep 9 229to be called while the device detaches itself. 230.It Fn config_activate "dev" 231Called by the parent to activate the child device 232.Fa dev . 233It is called to activate resources and initialise other kernel 234subsystems (such as the network subsystem). 235.Fn config_activate 236is called from interrupt context after the device has been attached. 237.It Fn config_deactivate "dev" 238Called by the parent to deactivate the child device 239.Fa dev . 240.Fn config_deactivate 241is called from interrupt context to immediately relinquish resources 242and notify dependent kernel subsystems that the device is about to be 243detached. At some later point 244.Fn config_detach 245will be called to finalise the removal of the device. 246.It Fn config_defer "dev" "func" 247Called by the child to defer the remainder of its configuration until 248all its parent's devices have been attached. At this point, the 249function 250.Fa func 251is called with the argument 252.Fa dev . 253.It Fn config_interrupts "struct device *dev" "void (*func)(struct device *)" 254Called by the child to defer the remainder of its configuration until 255interrupts are enabled. At this point, the function 256.Fa func 257is called with the argument 258.Fa dev . 259.It Fn config_pending_incr 260Increment the 261.Va config_pending 262semaphore. It is used to account for deferred configurations before 263mounting the root file system. 264.It Fn config_pending_decr 265Decrement the 266.Va config_pending 267semaphore. It is used to account for deferred configurations before 268mounting the root file system. 269.El 270.Sh CODE REFERENCES 271This section describes places within the 272.Nx 273source tree where actual code implementing or utilising the 274autoconfiguration framework can be found. All pathnames are relative 275to 276.Pa /usr/src . 277.Pp 278The autoconfiguration framework itself is implemented within the file 279.Pa sys/kern/subr_autoconf.c . 280Data structures and function prototypes for the framework are located in 281.Pa sys/sys/device.h . 282.Sh SEE ALSO 283.Xr config 8 , 284.Xr config 9 , 285.Xr driver 9 286.Sh HISTORY 287Autoconfiguration first appeared in 288.Bx 4.1 . 289The autoconfiguration framework was completely revised in 290.Bx 4.4 . 291The detach and activate/deactivate interfaces appeared in 292.Nx 1.5 . 293