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