1.\" $NetBSD: config.samples.5,v 1.8 2022/04/04 19:33:46 andvar Exp $ 2.\" 3.\" Copyright (c) 2006 The NetBSD Foundation. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd June 4, 2006 28.Dt CONFIG.SAMPLES 5 29.Os 30.Sh NAME 31.Nm config.samples 32.Nd kernel configuration file syntax examples 33.Sh DESCRIPTION 34.Ss Devices, drivers and instances 35For a given device, at most one driver will attach. 36In order for a driver to attach, the kernel configuration file must include a 37compatible instance of the driver for the location of the device. 38The following lines from the 39.Pa GENERIC 40kernel configuration file of 41.Nx Ns / Ns i386 42are examples of instances of drivers: 43.Bd -literal -offset indent 44pchb* at pci? dev ? function ? # PCI-Host bridges 45pcib* at pci? dev ? function ? # PCI-ISA bridges 46ppb* at pci? dev ? function ? # PCI-PCI bridges 47 48siop* at pci? dev ? function ? # Symbios 53c8xx SCSI 49esiop* at pci? dev ? function ? # Symbios 53c875 SCSI and newer 50 51ix0 at isa? port 0x300 irq 10 # EtherExpress/16 52.Ed 53.Pp 54The first three instances allow three different drivers to attach to all the 55matching devices found on any 56.Tn PCI 57bus. 58This is the most generic case. 59.Pp 60The next two lines allow two distinct drivers to attach to any matching device 61found on any 62.Tn PCI 63bus, but those two drivers are special because they both 64support some of the same devices. 65Each of the driver has a matching function that returns their score for the 66device that is being considered. 67.Xr autoconf 9 68decides at run-time which driver will attach. 69Of course, it is deterministic so if the user wants to change the driver that 70attaches to the device, the instance of the other driver will have to be 71removed, e.g. by commenting it out. 72.Pp 73The last line configures an instance of an 74.Tn ISA 75device. 76Unlike the 77.Tn PCI 78bus, the 79.Tn ISA 80bus cannot discover the devices that are present on the bus. 81The driver has to try accessing the device in order to discover it. 82That implies locators must be specified to some extent: a driver would 83usually need the base address of the device, some need the 84.Tn IRQ 85line that the 86device is configured to use, though some others would just try a set of known 87values, at the risk of badly interacting with other devices on the bus. 88.Ss Hard-wiring kernel configuration 89This technique consists in specifying exactly the location of the devices on a 90given system. 91In the general case it has very little use, because it does not change the size 92of the kernel, and it will prevent it from finding devices in case the hardware 93changes, even slightly. 94.Pp 95Let's consider the following excerpt of 96.Xr dmesg 8 97output: 98.Bd -literal -offset indent 99auich0 at pci0 dev 31 function 5: i82801DB/DBM (ICH4/ICH4M) AC-97 Audio 100.Ed 101.Pp 102The 103.Xr auich 4 104driver (which controls Intel's AC-97 audio chips) attached there because of the 105following instance of 106.Pa GENERIC : 107.Bd -literal -offset indent 108auich* at pci? dev ? function ? 109.Ed 110.Pp 111Hard-wiring that instance means re-writing it to the following: 112.Bd -literal -offset indent 113auich0 at pci0 dev 31 function 5 114.Ed 115.Pp 116and that way, 117.Li auich0 118will attach to that specific location, or will not attach. 119.Ss Removing options and drivers 120When two kernel configurations differ by a very small number of changes, it is 121easier to manage them by having one include the other, and add or remove the 122differences. 123Removing options and drivers is also useful in the situation of a user who 124wants to follow the development of 125.Nx : 126drivers and options get added to the configuration files found in the source 127tree, such as 128.Pa GENERIC , 129so one can include it and remove all options and drivers that are not relevant 130to the considered system. 131Additions to 132.Pa GENERIC 133will then automatically be followed and used in case they are relevant. 134.Pp 135While negating an 136.Ic options 137with 138.Ic no options 139is unambiguous, it is not as clear for devices instances. 140.Pp 141The 142.Ic no Ar instance-definition 143statements of 144.Xr config 5 145syntax only apply on the current state of the configuration file, not on the 146resulting kernel binary. 147.Xr autoconf 9 148has no knowledge of instance negation, thus it is currently impossible to 149express the following in a kernel configuration file: 150.Bd -ragged -offset indent 151.Do I want support for 152.Xr ath 4 153attaching at 154.Xr pci 4 , 155but I do not want any instance of 156.Xr ath 4 157attaching at 158.Li pci3 . 159.Dc 160.Ed 161.Pp 162For a real-world use of 163.Ic no device at Ar instance 164consider the following, taken from 165.Nx Ns / Ns i386 : 166.Bd -literal -offset indent 167include "arch/i386/conf/GENERIC" 168 169acpi0 at mainbus? 170 171com* at acpi? 172[... more instances of legacy devices attaching at acpi? ...] 173 174no device at isa0 175.Ed 176.Pp 177One could actually live without the 178.Li isa0 179instance, as all the legacy devices are attached at 180.Li acpi0 . 181But unfortunately, dependencies on the 182.Li isa 183attribute are not well registered all through the source tree, so an instance 184of the 185.Xr isa 4 186driver is required to compile a kernel. 187So while: 188.Bd -literal -offset indent 189no isa* 190.Ed 191.Pp 192is what is intended, the 193.Xr isa 4 194instance itself must be kept, and that is precisely the difference made by: 195.Bd -literal -offset indent 196no device at isa0 197.Ed 198.Ss Interface attributes 199.Em Interface attributes 200are a subtlety of 201.Xr config 5 202and 203.Xr autoconf 9 , 204which often confuses users and utilities that parse 205.Xr dmesg 8 206output to manipulate kernel configuration files. 207What they are is best shown by the following example. 208.Pp 209The 210.Xr dmesg 8 211output look like this: 212.Bd -literal -offset indent 213auvia0 at pci0 dev 17 function 5: VIA Technologies VT8235 AC'97 Audio (rev 0x50) 214audio0 at auvia0: full duplex, mmap, independent 215.Ed 216.Pp 217while the kernel configuration look like this: 218.Bd -literal -offset indent 219auvia* at pci? dev ? function ? 220audio* at audiobus? 221.Ed 222.Pp 223It is not obvious from the kernel configuration file that an 224.Xr audio 4 225device can attach at an 226.Xr auvia 4 227device. 228.Li audiobus 229is an 230.Em interface attribute , 231exposed by 232.Li auvia . 233.Pp 234Of course, it is possible to specify 235.Bd -literal -offset indent 236audio* at auvia? 237.Ed 238.Pp 239in the kernel configuration file, but then one instance per audio controller 240would be needed. 241.Em Interface attributes 242reflect the fact there is a standard way to attach a device to its parent, no 243matter what the latter is precisely. 244It also means lower maintenance of the kernel configuration files because 245drivers for audio controllers are added more easily. 246.Pp 247Most attachments are done through 248.Em interface attributes , 249although only a few of them are specified that way in the configuration files 250found in the tree. 251Another example of such an attribute is 252.Li ata : 253.Bd -literal -offset indent 254viaide0 at pci0 dev 17 function 1 255atabus0 at viaide0 channel 0 256 257viaide* at pci? dev ? function ? 258atabus* at ata? 259.Ed 260.\" Suggested section, maybe for later: 261.\" .Ss Using a third-party driver 262.Sh SEE ALSO 263.Xr config 1 , 264.Xr options 4 , 265.Xr config 5 , 266.Xr dmesg 8 267