1.\" $OpenBSD: autoconf.9,v 1.17 2018/04/18 22:33:18 dlg Exp $ 2.\" $NetBSD: autoconf.9,v 1.9 2002/02/13 08:18:35 ross Exp $ 3.\" 4.\" Copyright (c) 2001 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Gregory McGarry. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd $Mdocdate: April 18 2018 $ 32.Dt CONFIG_SEARCH 9 33.Os 34.Sh NAME 35.Nm config_search , 36.Nm config_rootsearch , 37.Nm config_found_sm , 38.Nm config_found , 39.Nm config_rootfound 40.Nd autoconfiguration framework 41.Sh SYNOPSIS 42.In sys/param.h 43.In sys/device.h 44.Ft "void *" 45.Fn config_search "cfmatch_t func" "struct device *parent" "void *aux" 46.Ft "void *" 47.Fn config_rootsearch "cfmatch_t func" "char *rootname" "void *aux" 48.Ft "struct device *" 49.Fo config_found_sm 50.Fa "struct device *parent" 51.Fa "void *aux" 52.Fa "cfprint_t print" 53.Fa "cfmatch_t submatch" 54.Fc 55.Ft "struct device *" 56.Fn config_found "struct device *parent" "void *aux" "cfprint_t print" 57.Ft "struct device *" 58.Fn config_rootfound "char *rootname" "void *aux" 59.Sh DESCRIPTION 60Autoconfiguration is the process of matching hardware devices with an 61appropriate device driver. 62In its most basic form, autoconfiguration consists of the recursive 63process of finding and attaching all devices on a bus, including other buses. 64.Pp 65The autoconfiguration framework supports 66.Em direct configuration 67where the bus driver can determine the devices present. 68.Pp 69The autoconfiguration framework also supports 70.Em indirect configuration 71where the drivers must probe the bus looking for the presence of a device. 72Direct configuration is preferred since it can find hardware regardless of 73the presence of proper drivers. 74.Pp 75The autoconfiguration process occurs at system bootstrap and is driven by a 76table generated from a 77.Do 78machine description 79.Dc 80file by 81.Xr config 8 . 82For a description of the 83.Xr config 8 84.Do 85device definition 86.Dc 87language, see 88.Xr files.conf 5 . 89.Pp 90Each device must have a name consisting of an alphanumeric string that 91ends with a unit number. 92The unit number identifies an instance of the driver. 93Device data structures are allocated dynamically during autoconfiguration, 94giving a unique address for each instance. 95.Ss Indirect Configuration 96The 97.Fn config_search 98function performs indirect configuration of physical devices by iterating 99over all potential children, calling the given function 100.Fa func 101for each one. 102.Pp 103The 104.Fn config_rootsearch 105function finds the root device identified by the string 106.Fa rootname , 107in a manner similar to 108.Fn config_search , 109except that there is no parent device. 110If 111.Fa func 112is 113.Dv NULL , 114.Fn config_search 115applies each child's match function instead. 116The argument 117.Fa parent 118is the pointer to the parent's device structure. 119The given 120.Fa aux 121argument describes the device that has been found and is simply passed 122on through 123.Fa func 124to the child. 125.Fn config_search 126returns a pointer to the best-matched child or 127.Dv NULL 128otherwise. 129.Pp 130The role of 131.Fa func 132is to call 133the match function for each device and call 134.Fn config_attach 135for any positive matches. 136.Bd -literal 137typedef int (*cfmatch_t)(struct device *parent, void *child, void *aux); 138.Ed 139.Pp 140If 141.Fa func 142is 143.Dv NULL , 144then the parent should record the return value from 145.Fn config_search 146and call 147.Fn config_attach 148itself. 149.Pp 150Note that this function is designed so that it can be used to apply an 151arbitrary function to all potential children. 152In this case callers may choose to ignore the return value. 153.Ss Direct Configuration 154The 155.Fn config_found_sm 156function performs direct configuration on a physical device. 157.Fn config_found_sm 158is called by the parent and in turn calls the 159.Fa submatch 160function to call the match function as determined by the configuration table. 161If 162.Fa submatch 163is 164.Dv NULL , 165the driver match functions are called directly. 166The argument 167.Fa parent 168is the pointer to the parent's device structure. 169The given 170.Fa aux 171argument describes the device that has been found. 172The 173.Em softc 174structure for the matched device will be allocated, and the appropriate 175driver attach function will be called. 176.Pp 177If the device is matched, the system prints the name of the child and 178parent devices, and then calls the 179.Fa print 180function to produce additional information if desired. 181If no driver takes a match, the same 182.Fa print 183function is called to complain. 184The print function is called with the 185.Fa aux 186argument and, if the matches failed, the full name (including unit 187number) of the parent device, otherwise 188.Dv NULL . 189.Bd -literal 190typedef int (*cfprint_t)(void *aux, const char *parentname); 191#define QUIET 0 /* print nothing */ 192#define UNCONF 1 /* print " not configured" */ 193#define UNSUPP 2 /* print " not supported" */ 194.Ed 195.Pp 196Two special strings, 197.Do 198not configured 199.Dc 200and 201.Do 202unsupported 203.Dc 204will be appended automatically to non-driver reports if the return 205value is 206.Dv UNCONF 207or 208.Dv UNSUPP 209respectively, otherwise the function should return the value 210.Dv QUIET . 211.Pp 212The 213.Fn config_found_sm 214function returns a pointer to the attached device's 215.Em softc 216structure if the device is attached, 217.Dv NULL 218otherwise. 219Most callers can ignore this value, since the system will already have 220printed a diagnostic. 221.Pp 222The 223.Fn config_found 224macro expands to 225.Fn config_found_sm "parent" "aux" "print" "submatch" 226with 227.Fa submatch 228set to 229.Dv NULL 230and is provided for compatibility with older drivers. 231.Pp 232The 233.Fn config_rootfound 234function performs the same operation on the root device identified 235by the 236.Fa rootname 237string. 238.Sh CODE REFERENCES 239The autoconfiguration framework itself is implemented within the file 240.Pa sys/kern/subr_autoconf.c . 241Data structures and function prototypes for the framework are located in 242.Pa sys/sys/device.h . 243.Sh SEE ALSO 244.Xr autoconf 4 , 245.Xr files.conf 5 , 246.Xr config 8 , 247.Xr config_attach 9 248.Sh HISTORY 249Autoconfiguration first appeared in 250.Bx 4.1 . 251The autoconfiguration framework was completely revised in 252.Bx 4.4 . 253