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