1.\" $NetBSD: autoconf.9,v 1.13 2002/10/14 13:43:15 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 5, 2002 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_match , 46.Nm config_attach , 47.Nm config_detach , 48.Nm config_activate , 49.Nm config_deactivate , 50.Nm config_defer , 51.Nm config_interrupts , 52.Nm config_pending_incr , 53.Nm config_pending_decr 54.Nd autoconfiguration framework 55.Sh SYNOPSIS 56.Fd #include \*[Lt]sys/param.h\*[Gt] 57.Fd #include \*[Lt]sys/device.h\*[Gt] 58.Fd #include \*[Lt]sys/error.h\*[Gt] 59.Ft struct cfdata * 60.Fn config_search "cfmatch_t func" "struct device *parent" "void *aux" 61.Ft struct device * 62.Fn config_found_sm "struct device *parent" "void *aux" "cfprint_t print" \ 63"cfmatch_t submatch" 64.Ft struct device * 65.Fn config_found "struct device *parent" "void *aux" "cfprint_t print" 66.Ft int 67.Fn config_match "struct device *parent" "struct cfdata *cf" "void *aux" 68.Ft struct device * 69.Fn config_attach "struct device *parent" "struct cfdata *cf" "void *aux" \ 70"cfprint_t print" 71.Ft int 72.Fn config_detach "struct device *dev" "int flags" 73.Ft int 74.Fn config_activate "struct device *dev" 75.Ft int 76.Fn config_deactivate "struct device *dev" 77.Ft int 78.Fn config_defer "struct device *dev" "void (*func)(struct device *)" 79.Ft void 80.Fn config_interrupts "struct device *dev" "void (*func)(struct device *)" 81.Ft void 82.Fn config_pending_incr 83.Ft void 84.Fn config_pending_decr 85.Sh DESCRIPTION 86Autoconfiguration is the process of matching hardware devices with an 87appropriate device driver. 88In its most basic form, autoconfiguration consists of the recursive process 89of finding and attaching all devices on a bus, including other busses. 90.Pp 91The autoconfiguration framework supports 92.Em direct configuration 93where the bus driver can determine the devices present. 94The autoconfiguration framework also supports 95.Em indirect configuration 96where the drivers must probe the bus looking for the presence of a device. 97Direct configuration is preferred since it can find hardware 98regardless of the presence of proper drivers. 99.Pp 100The autoconfiguration process occurs at system bootstrap and is driven 101by a table generated from a 102.Do 103machine description 104.Dc 105file by 106.Xr config 8 . 107For a description of the 108.Xr config 8 109.Do 110device definition 111.Dc 112language, see 113.Xr config 9 . 114.Pp 115Each device must have a name consisting of an alphanumeric string that 116ends with a unit number. 117The unit number identifies an instance of the driver. 118Device data structures are allocated dynamically during 119autoconfiguration, giving a unique address for each instance. 120.Sh FUNCTIONS 121.Bl -tag -width compact 122.It Fn config_search "func" "parent" "aux" 123Performs indirect configuration of physical devices. 124.Fn config_search 125iterates over all potential children, calling the given 126function 127.Fa func 128for each one. 129If 130.Fa func 131is 132.Dv NULL , 133.Fn config_search 134applies each child's match function instead. 135The argument 136.Fa parent 137is the pointer to the parent's device structure. 138The given 139.Fa aux 140argument describes the device that has been found and is simply passed 141on through 142.Fa func 143to the child. 144.Fn config_search 145returns a pointer to the best-matched child or 146.Dv NULL 147otherwise. 148.Pp 149The role of 150.Fa func 151is to call 152the match function for each device and call 153.Fn config_attach 154for any positive matches. 155If 156.Fa func 157is 158.Dv NULL , 159then the parent should record the return value from 160.Fn config_search 161and call 162.Fn config_attach 163itself. 164.Pp 165Note that this function is designed so that it can be used to apply an 166arbitrary function to all potential children. 167In this case callers may choose to ignore the return value. 168.It Fn config_found_sm "parent" "aux" "print" "submatch" 169Performs direct configuration on a physical device. 170.Fn config_found_sm 171is called by the parent and in turn calls the 172.Fa submatch 173function to call the match function as 174determined by the configuration table. 175If 176.Fa submatch 177is 178.Dv NULL , 179the driver match functions are called directly. 180The argument 181.Fa parent 182is the pointer to the parent's device structure. 183The given 184.Fa aux 185argument describes the device that has been found. 186The 187.Em softc 188structure for the matched device will be allocated, and the 189appropriate driver attach function will be called. 190If the device is matched, the system prints the name of the child and 191parent devices, and then calls the 192.Fa print 193function to produce additional information if desired. 194If no driver takes a match, the same 195.Fa print 196function is called to complain. 197The print function is called with the 198.Fa aux 199argument and, if the matches failed, the full name (including unit 200number) of the parent device, otherwise 201.Dv NULL . 202The 203.Fa print 204function must return an integer value. 205.Pp 206Two special strings, 207.Do 208not configured 209.Dc 210and 211.Do 212unsupported 213.Dc 214will be appended automatically to non-driver reports if the return 215value is UNCONF or UNSUPP respectively; otherwise the function should 216return the value QUIET. 217.Pp 218.Fn config_found_sm 219returns a pointer to the attached device's 220.Em softc 221structure if the device is attached, 222.Dv NULL 223otherwise. 224Most callers can ignore this value, since the system will already have 225printed a diagnostic. 226.It Fn config_found "parent" "aux" "print" 227This function is equivalent to calling 228.Fn config_found_sm "parent" "aux" "print" "submatch" 229with 230.Fa submatch 231set to 232.Dv NULL 233and is provided for compatibility with older drivers. 234.It Fn config_match "parent" "cf" "aux" 235Match a device. 236Invokes the drivers match function according to the 237configuration table. 238The 239.Fn config_match 240function returns a nonzero integer indicating the confidence of 241supporting this device and a value of 0 if the driver doesn't support 242the device. 243.It Fn config_attach "parent" "cf" "aux" "print" 244Attach a found device. 245Allocates the memory for the 246.Em softc 247structure and calls the drivers attach function according to the 248configuration table. 249If successful, 250.Fn config_attach 251returns the 252.Em softc . 253If unsuccessful, it returns 254.Dv NULL . 255.It Fn config_detach "dev" "flags" 256Called by the parent to detach the child device. 257The second argument 258.Em flags 259contains detachment flags. 260Valid values are DETACH_FORCE (force detachment (e.g., because of hardware 261removal)) and DETACH_QUIET (do not print a notice). 262.Fn config_detach 263returns zero if successful and an error code otherwise. 264.Fn config_detach 265is always called from a thread context, allowing 266.Xr sleep 9 267to be called while the device detaches itself. 268.It Fn config_activate "dev" 269Called by the parent to activate the child device 270.Fa dev . 271It is called to activate resources and initialise other kernel 272subsystems (such as the network subsystem). 273.Fn config_activate 274is called from interrupt context after the device has been attached. 275.It Fn config_deactivate "dev" 276Called by the parent to deactivate the child device 277.Fa dev . 278.Fn config_deactivate 279is called from interrupt context to immediately relinquish resources 280and notify dependent kernel subsystems that the device is about to be 281detached. 282At some later point 283.Fn config_detach 284will be called to finalise the removal of the device. 285.It Fn config_defer "dev" "func" 286Called by the child to defer the remainder of its configuration until 287all its parent's devices have been attached. 288At this point, the function 289.Fa func 290is called with the argument 291.Fa dev . 292.It Fn config_interrupts "struct device *dev" "void (*func)(struct device *)" 293Called by the child to defer the remainder of its configuration until 294interrupts are enabled. 295At this point, the function 296.Fa func 297is called with the argument 298.Fa dev . 299.It Fn config_pending_incr 300Increment the 301.Va config_pending 302semaphore. 303It is used to account for deferred configurations before 304mounting the root file system. 305.It Fn config_pending_decr 306Decrement the 307.Va config_pending 308semaphore. 309It is used to account for deferred configurations before 310mounting the root file system. 311.El 312.Sh CODE REFERENCES 313This section describes places within the 314.Nx 315source tree where actual code implementing or utilising the 316autoconfiguration framework can be found. 317All pathnames are relative to 318.Pa /usr/src . 319.Pp 320The autoconfiguration framework itself is implemented within the file 321.Pa sys/kern/subr_autoconf.c . 322Data structures and function prototypes for the framework are located in 323.Pa sys/sys/device.h . 324.Sh SEE ALSO 325.Xr config 8 , 326.Xr config 9 , 327.Xr driver 9 328.Sh HISTORY 329Autoconfiguration first appeared in 330.Bx 4.1 . 331The autoconfiguration framework was completely revised in 332.Bx 4.4 . 333The detach and activate/deactivate interfaces appeared in 334.Nx 1.5 . 335