1.\" $NetBSD: config.samples.5,v 1.4 2008/04/30 13:11:00 martin 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 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 PCI bus. 56This is the most generic case. 57.Pp 58The next two lines allow two distinct drivers to attach to any matching device 59found on any PCI bus, but those two drivers are special because they both 60support some of the same devices. 61Each of the driver has a matching function that returns their score for the 62device that is being considered. 63.Xr autoconf 9 64decides at run-time which driver will attach. 65Of course, it is deterministic so if the user wants to change the driver that 66attaches to the device, the instance of the other driver will have to be 67removed, e.g. by commenting it out. 68.Pp 69The last line configures an instance of an ISA device. 70Unlike the PCI bus, the ISA bus cannot discover the devices that are present on 71the bus. 72The driver has to try accessing the device in order to discover it. 73That implies locators must be specified to some extent: a driver would 74usually need the base address of the device, some need the IRQ line that the 75device is configured to use, thoug some others would just try a set of known 76values, at the risk of badly interacting with other devices on the bus. 77.Ss Hard-wiring kernel configuration 78This technique consists in specifying exactly the location of the devices on a 79given system. 80In the general case it has very little use, because it does not change the size 81of the kernel, and it will prevent it from finding devices in case the hardware 82changes, even slightly. 83.Pp 84Let's consider the following excerpt of 85.Xr dmesg 8 86output: 87.Bd -literal 88auich0 at pci0 dev 31 function 5: i82801DB/DBM (ICH4/ICH4M) AC-97 Audio 89.Ed 90.Pp 91The 92.Xr auich 4 93driver (which controls Intel's AC-97 audio chips) attached there because of the 94following instance of 95.Pa GENERIC : 96.Bd -literal 97auich* at pci? dev ? function ? 98.Ed 99.Pp 100Hard-wiring that instance means re-writing it to the following: 101.Bd -literal 102auich0 at pci0 dev 31 function 5 103.Ed 104.Pp 105and that way, 106.Ar auich0 107will attach to that specific location, or will not attach. 108.Ss Removing options and drivers 109When two kernel configurations differ by a very small number of changes, it is 110easier to manage them by having one include the other, and add or remove the 111differences. 112Removing options and drivers is also useful in the situation of a user who 113wants to follow the development of 114.Nx : 115drivers and options get added to the configuration files found in the source 116tree, such as 117.Pa GENERIC , 118so one can include it and remove all options and drivers that are not relevant 119to the considered system. 120Additions to 121.Pa GENERIC 122will then automatically be followed and used in case they are relevant. 123.Pp 124While negating an options (with 125.Ic no options ) 126is unambiguous, it is not as clear for devices instances. 127.Pp 128The 129.Ic no Ar instance definition 130statements of 131.Xr config 1 132syntax only apply on the current state of the configuration file, not on the 133resulting kernel binary. 134.Xr autoconf 9 135has no knowledge of instance negation, thus it is currently impossible to 136express the following in a kernel configuration file: 137.Bd -ragged -offset indent 138.Do I want support for 139.Xr ath 4 140attaching at 141.Xr pci 4 , 142but I do not want any instance of 143.Xr ath 4 144attaching at 145.Ar pci3 . 146.Dc 147.Ed 148.Pp 149For a real-world use of 150.Ic no device at Ar instance 151consider the following, taken from 152.Nx Ns / Ns i386 : 153.Bd -literal -offset indent 154include "arch/i386/conf/GENERIC" 155 156acpi0 at mainbus? 157 158com* at acpi? 159[... more instances of legacy devices attaching at acpi? ...] 160 161no device at isa0 162.Ed 163.Pp 164One could actually live without the 165.Ar isa0 166instance, as all the legacy devices are attached at 167.Ar acpi0 . 168But unfortunately, dependencies on the 169.Ar isa 170attribute are not well registered all through the source tree, so an instance 171of the 172.Xr isa 4 173driver is required to compile a kernel. 174So while: 175.Bd -literal -offset indent 176no isa* 177.Ed 178.Pp 179is what is intended, the 180.Xr isa 4 181instance itself must be kept, and that is precisely the difference made by: 182.Bd -literal -offset indent 183no device at isa0 184.Ed 185.Ss Interface attributes 186.Em Interface attributes 187are a subtility of 188.Xr config 1 189and 190.Xr autoconf 9 , 191which often confuses users and utilities that parse 192.Xr dmesg 8 193output to manipulate kernel configuration files. 194What they are is best shown by the following example. 195.Pp 196The 197.Xr dmesg 8 198output look like this: 199.Bd -literal -offset indent 200auvia0 at pci0 dev 17 function 5: VIA Technologies VT8235 AC'97 Audio (rev 0x50) 201audio0 at auvia0: full duplex, mmap, independent 202.Ed 203.Pp 204while the kernel configuration look like this: 205.Bd -literal 206auvia* at pci? dev ? function ? 207audio* at audiobus? 208.Ed 209.Pp 210It is not obvious from the kernel configuration file that an 211.Xr audio 4 212device can attach at an 213.Xr auvia 4 214device. 215.Ar audiobus 216is an 217.Em interface attribute , 218exposed by 219.Ar auvia . 220.Pp 221Of course, it is possible to specify 222.Bd -literal -offset indent 223audio* at auvia? 224.Ed 225in the kernel configuration file, but then one instance per audio controler 226would be needed. 227.Em Interface attributes 228reflect the fact there is a standard way to attach a device to its parent, no 229matter what the latter is precisely. 230It also means lower maintainance of the kernel configuration files because 231drivers for audio controlers are added more easily. 232.Pp 233Most attachments are done through 234.Em interface attributes , 235although only a few of them are specified that way in the configuration files 236found in the tree. 237Another example of such an attribute is 238.Ar ata : 239.Bd -literal -offset indent 240viaide0 at pci0 dev 17 function 1 241atabus0 at viaide0 channel 0 242 243viaide* at pci? dev ? function ? 244atabus* at ata? 245.Ed 246.\" Suggested section, maybe for later: 247.\" .Ss Using a third-party driver 248.Sh SEE ALSO 249.Xr config 1 , 250.Xr options 4 , 251.Xr config 5 , 252.Xr dmesg 8 253