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