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