usr.bin/config/config.samples.5

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