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