1.\" $OpenBSD: autoconf.9,v 1.16 2015/12/11 16:07:02 mpi 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: December 11 2015 $ 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.Sh DESCRIPTION 45Autoconfiguration is the process of matching hardware devices with an 46appropriate device driver. 47In its most basic form, autoconfiguration consists of the recursive 48process of finding and attaching all devices on a bus, including other buses. 49.Pp 50The autoconfiguration framework supports 51.Em direct configuration 52where the bus driver can determine the devices present. 53.Pp 54The autoconfiguration framework also supports 55.Em indirect configuration 56where the drivers must probe the bus looking for the presence of a device. 57Direct configuration is preferred since it can find hardware regardless of 58the presence of proper drivers. 59.Pp 60The autoconfiguration process occurs at system bootstrap and is driven by a 61table generated from a 62.Do 63machine description 64.Dc 65file by 66.Xr config 8 . 67For a description of the 68.Xr config 8 69.Do 70device definition 71.Dc 72language, see 73.Xr files.conf 5 . 74.Pp 75Each device must have a name consisting of an alphanumeric string that 76ends with a unit number. 77The unit number identifies an instance of the driver. 78Device data structures are allocated dynamically during autoconfiguration, 79giving a unique address for each instance. 80.Sh INDIRECT CONFIGURATION 81.nr nS 1 82.Ft "void *" 83.Fn config_search "cfmatch_t func" "struct device *parent" "void *aux" 84.Ft "void *" 85.Fn config_rootsearch "cfmatch_t func" "char *rootname" "void *aux" 86.nr nS 0 87.Pp 88The 89.Fn config_search 90function performs indirect configuration of physical devices by iterating 91over all potential children, calling the given function 92.Fa func 93for each one. 94.Pp 95The 96.Fn config_rootsearch 97function finds the root device identified by the string 98.Fa rootname , 99in a manner similar to 100.Fn config_search , 101except that there is no parent device. 102If 103.Fa func 104is 105.Dv NULL , 106.Fn config_search 107applies each child's match function instead. 108The argument 109.Fa parent 110is the pointer to the parent's device structure. 111The given 112.Fa aux 113argument describes the device that has been found and is simply passed 114on through 115.Fa func 116to the child. 117.Fn config_search 118returns a pointer to the best-matched child or 119.Dv NULL 120otherwise. 121.Pp 122The role of 123.Fa func 124is to call 125the match function for each device and call 126.Fn config_attach 127for any positive matches. 128.Bd -literal 129typedef int (*cfmatch_t)(struct device *parent, void *child, void *aux); 130.Ed 131.Pp 132If 133.Fa func 134is 135.Dv NULL , 136then the parent should record the return value from 137.Fn config_search 138and call 139.Fn config_attach 140itself. 141.Pp 142Note that this function is designed so that it can be used to apply an 143arbitrary function to all potential children. 144In this case callers may choose to ignore the return value. 145.Sh DIRECT CONFIGURATION 146.nr nS 1 147.Ft "struct device *" 148.Fn config_found_sm "struct device *parent" "void *aux" "cfprint_t print" \ 149 "cfmatch_t submatch" 150.Ft "struct device *" 151.Fn config_found "struct device *parent" "void *aux" "cfprint_t print" 152.Ft "struct device *" 153.Fn config_rootfound "char *rootname" "void *aux" 154.nr nS 0 155.Pp 156The 157.Fn config_found_sm 158function performs direct configuration on a physical device. 159.Fn config_found_sm 160is called by the parent and in turn calls the 161.Fa submatch 162function to call the match function as determined by the configuration table. 163If 164.Fa submatch 165is 166.Dv NULL , 167the driver match functions are called directly. 168The argument 169.Fa parent 170is the pointer to the parent's device structure. 171The given 172.Fa aux 173argument describes the device that has been found. 174The 175.Em softc 176structure for the matched device will be allocated, and the appropriate 177driver attach function will be called. 178.Pp 179If the device is matched, the system prints the name of the child and 180parent devices, and then calls the 181.Fa print 182function to produce additional information if desired. 183If no driver takes a match, the same 184.Fa print 185function is called to complain. 186The print function is called with the 187.Fa aux 188argument and, if the matches failed, the full name (including unit 189number) of the parent device, otherwise 190.Dv NULL . 191.Bd -literal 192typedef int (*cfprint_t)(void *aux, const char *parentname); 193#define QUIET 0 /* print nothing */ 194#define UNCONF 1 /* print " not configured" */ 195#define UNSUPP 2 /* print " not supported" */ 196.Ed 197.Pp 198Two special strings, 199.Do 200not configured 201.Dc 202and 203.Do 204unsupported 205.Dc 206will be appended automatically to non-driver reports if the return 207value is 208.Dv UNCONF 209or 210.Dv UNSUPP 211respectively, otherwise the function should return the value 212.Dv QUIET . 213.Pp 214The 215.Fn config_found_sm 216function returns a pointer to the attached device's 217.Em softc 218structure if the device is attached, 219.Dv NULL 220otherwise. 221Most callers can ignore this value, since the system will already have 222printed a diagnostic. 223.Pp 224The 225.Fn config_found 226macro expands to 227.Fn config_found_sm "parent" "aux" "print" "submatch" 228with 229.Fa submatch 230set to 231.Dv NULL 232and is provided for compatibility with older drivers. 233.Pp 234The 235.Fn config_rootfound 236function performs the same operation on the root device identified 237by the 238.Fa rootname 239string. 240.Sh CODE REFERENCES 241The autoconfiguration framework itself is implemented within the file 242.Pa sys/kern/subr_autoconf.c . 243Data structures and function prototypes for the framework are located in 244.Pa sys/sys/device.h . 245.Sh SEE ALSO 246.Xr autoconf 4 , 247.Xr files.conf 5 , 248.Xr config 8 , 249.Xr config_attach 9 250.Sh HISTORY 251Autoconfiguration first appeared in 252.Bx 4.1 . 253The autoconfiguration framework was completely revised in 254.Bx 4.4 . 255