1.\" $NetBSD: autoconf.9,v 1.20 2006/10/13 20:47:42 wiz 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" "cfsubmatch_t submatch" 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" "submatch" 279This function is equivalent to calling 280.Fn config_found_sm_loc "parent" "ia" "locs" "aux" "print" "submatch" 281with 282.Fa locs 283set to 284.Dv NULL . 285It is provided for better source code readability with locator-less device 286buses. 287.It Fn config_found "parent" "aux" "print" 288This function is equivalent to calling 289.Fn config_found_sm_loc "parent" "ia" "locs" "aux" "print" "submatch" 290with 291.Fa ia , locs 292and 293.Fa submatch 294set to 295.Dv NULL 296and is provided for compatibility with older drivers. 297New code should either make the interface attribute explicit or prefer an 298indirect method based on 299.Fn config_search_loc . 300.It Fn config_match "parent" "cf" "aux" 301Match a device. 302Invokes the drivers match function according to the 303configuration table. 304The 305.Fn config_match 306function returns a nonzero integer indicating the confidence of 307supporting this device and a value of 0 if the driver doesn't support 308the device. 309.It Fn config_attach_loc "parent" "locs" "cf" "aux" "print" 310Attach a found device. 311Allocates the memory for the 312.Em softc 313structure and calls the drivers attach function according to the 314configuration table. 315If successful, 316.Fn config_attach_loc 317returns the 318.Em softc . 319If unsuccessful, it returns 320.Dv NULL . 321.It Fn config_attach "parent" "cf" "aux" print" 322This function is equivalent to calling 323.Fn config_attach_loc "parent" "cf" "locs" "aux" "print" 324with 325.Fa locs 326set to 327.Dv NULL . 328.It Fn config_attach_pseudo "cf" 329Create an instance of a pseudo-device driver. 330.Xr config 5 331syntax allows the creation of pseudo-devices from which regular 332.Ft device_t 333instances can be created. 334Such objects are similar to the devices that attach at the root of the device 335tree. 336.Pp 337The caller is expected to allocate and fill the 338.Ft cfdata_t 339object and pass it to 340.Fn config_attach_pseudo . 341The content of that object is similar to what is returned by 342.Fn config_search_loc 343for regular devices. 344.It Fn config_detach "dev" "flags" 345Called by the parent to detach the child device. 346The second argument 347.Em flags 348contains detachment flags. 349Valid values are DETACH_FORCE (force detachment (e.g., because of hardware 350removal)) and DETACH_QUIET (do not print a notice). 351.Fn config_detach 352returns zero if successful and an error code otherwise. 353.Fn config_detach 354is always called from a thread context, allowing 355.Xr ltsleep 9 356to be called while the device detaches itself. 357.It Fn config_activate "dev" 358Called by the parent to activate the child device 359.Fa dev . 360It is called to activate resources and initialise other kernel 361subsystems (such as the network subsystem). 362.Fn config_activate 363is called from interrupt context after the device has been attached. 364.It Fn config_deactivate "dev" 365Called by the parent to deactivate the child device 366.Fa dev . 367.Fn config_deactivate 368is called from interrupt context to immediately relinquish resources 369and notify dependent kernel subsystems that the device is about to be 370detached. 371At some later point 372.Fn config_detach 373will be called to finalise the removal of the device. 374.It Fn config_defer "dev" "func" 375Called by the child to defer the remainder of its configuration until 376all its parent's devices have been attached. 377At this point, the function 378.Fa func 379is called with the argument 380.Fa dev . 381.It Fn config_interrupts "struct device *dev" "void (*func)(struct device *)" 382Called by the child to defer the remainder of its configuration until 383interrupts are enabled. 384At this point, the function 385.Fa func 386is called with the argument 387.Fa dev . 388.It Fn config_pending_incr 389Increment the 390.Va config_pending 391semaphore. 392It is used to account for deferred configurations before 393mounting the root file system. 394.It Fn config_pending_decr 395Decrement the 396.Va config_pending 397semaphore. 398It is used to account for deferred configurations before 399mounting the root file system. 400.It Fn config_finalize_register "dev" "func" 401Register a function to be called after all real devices have been found. 402.Pp 403Registered functions are all executed until all of them return 0. 404The callbacks should return 0 to indicate they do not require to be called 405another time, but they should be aware that they still might be in case one of 406them returns 1. 407.El 408.Sh CODE REFERENCES 409This section describes places within the 410.Nx 411source tree where actual code implementing or using the 412autoconfiguration framework can be found. 413All pathnames are relative to 414.Pa /usr/src . 415.Pp 416The autoconfiguration framework itself is implemented within the file 417.Pa sys/kern/subr_autoconf.c . 418Data structures and function prototypes for the framework are located in 419.Pa sys/sys/device.h . 420.Sh SEE ALSO 421.Xr config 1 , 422.Xr config 5 , 423.Xr config 9 , 424.Xr driver 9 425.Sh HISTORY 426Autoconfiguration first appeared in 427.Bx 4.1 . 428The autoconfiguration framework was completely revised in 429.Bx 4.4 . 430The detach and activate/deactivate interfaces appeared in 431.Nx 1.5 . 432