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