CONFIG.SAMPLES(5)

📦 version 11.0, in nixpkgs unstable

💖 CONFIG.SAMPLES(5) 💖

okay so welcome to CONFIG.SAMPLES(5), bestie — this is the File Formats Manual page for config.samples, and it’s literally all about kernel configuration file syntax examples. it’s giving “let me show you the vibes of kernel config” energy, and honestly? iconic. 💅

✨ NAME ✨

config.samples — kernel configuration file syntax examples

✨ DESCRIPTION ✨

🛠️ Devices, drivers and instances 🛠️

so for any one device, at most one driver will attach. and for a driver to attach, the kernel configuration file has to include a compatible instance of that driver for the location of the device. no cap. the following lines from the GENERIC kernel configuration file of NetBSD/i386 are examples of instances of drivers:

pchb*   at pci? dev ? function ?    # PCI-Host bridges
pcib*   at pci? dev ? function ?    # PCI-ISA bridges
ppb*    at pci? dev ? function ?    # PCI-PCI bridges

siop*   at pci? dev ? function ?    # Symbios 53c8xx SCSI
esiop*  at pci? dev ? function ?    # Symbios 53c875 SCSI and newer

ix0     at isa? port 0x300 irq 10   # EtherExpress/16

the first three instances let three different drivers attach to all the matching devices found on any PCI bus. that’s the most generic case, fr fr.

the next two lines let two distinct drivers attach to any matching device found on any PCI bus, but those two drivers are special because they both support some of the same devices. each driver has a matching function that returns its score for the device being considered. autoconf(9) decides at run-time which driver will attach. of course, it’s deterministic, so if the user wants to change the driver that attaches to the device, the instance of the other driver has to be removed, e.g. by commenting it out. periodt.

the last line configures an instance of an ISA device. unlike the PCI bus, the ISA bus cannot discover the devices that are present on the bus. the driver has to try accessing the device in order to discover it. that implies locators must be specified to some extent: a driver would usually need the base address of the device, some need the IRQ line that the device is configured to use, though some others would just try a set of known values, at the risk of badly interacting with other devices on the bus. 😭

🔧 Hard-wiring kernel configuration 🔧

this technique is all about specifying exactly the location of the devices on a given system. in the general case it has very little use, because it does not change the size of the kernel, and it will prevent it from finding devices in case the hardware changes, even slightly. ngl, that’s a lot of downside for not much slay.

let’s consider the following excerpt of dmesg(8) output:

auich0 at pci0 dev 31 function 5: i82801DB/DBM (ICH4/ICH4M) AC-97 Audio

the auich(4) driver (which controls Intel’s AC-97 audio chips) attached there because of the following instance of GENERIC:

auich* at pci? dev ? function ?

hard-wiring that instance means re-writing it to the following:

auich0 at pci0 dev 31 function 5

and that way, auich0 will attach to that specific location, or will not attach. that’s it. that’s the whole vibe check. 🫶

🧹 Removing options and drivers 🧹

when two kernel configurations differ by a very small number of changes, it is easier to manage them by having one include the other, and add or remove the differences. removing options and drivers is also useful in the situation of a user who wants to follow the development of NetBSD: drivers and options get added to the configuration files found in the source tree, such as GENERIC, so one can include it and remove all options and drivers that are not relevant to the considered system. additions to GENERIC will then automatically be followed and used in case they are relevant. lowkey efficient. 💅

while negating an options with no options is unambiguous, it is not as clear for devices instances. 🙈

the no instance-definition statements of config(5) syntax only apply on the current state of the configuration file, not on the resulting kernel binary. autoconf(9) has no knowledge of instance negation, thus it is currently impossible to express the following in a kernel configuration file:

“I want support for ath(4) attaching at pci(4), but I do not want any instance of ath(4) attaching at pci3.”

for a real-world use of no device at instance, consider the following, taken from NetBSD/i386:

include "arch/i386/conf/GENERIC"

acpi0 at mainbus?

com* at acpi?
[... more instances of legacy devices attaching at acpi? ...]

no device at isa0

one could actually live without the isa0 instance, as all the legacy devices are attached at acpi0. but unfortunately, dependencies on the isa attribute are not well registered all through the source tree, so an instance of the isa(4) driver is required to compile a kernel. so while:

no isa*

is what is intended, the isa(4) instance itself must be kept, and that is precisely the difference made by:

no device at isa0

see? it’s giving “I know what you meant, but the source tree said no ❤️”. 😭

🧚 Interface attributes 🧚

interface attributes are a subtlety of config(5) and autoconf(9), which often confuses users and utilities that parse dmesg(8) output to manipulate kernel configuration files. what they are is best shown by the following example. 🦋

the dmesg(8) output look like this:

auvia0 at pci0 dev 17 function 5: VIA Technologies VT8235 AC'97 Audio (rev 0x50)
audio0 at auvia0: full duplex, mmap, independent

while the kernel configuration look like this:

auvia* at pci? dev ? function ?
audio* at audiobus?

it is not obvious from the kernel configuration file that an audio(4) device can attach at an auvia(4) device. audiobus is an interface attribute, exposed by auvia. the way that works is lowkey underrated.

of course, it is possible to specify:

audio* at auvia?

in the kernel configuration file, but then one instance per audio controller would be needed. interface attributes reflect the fact there is a standard way to attach a device to its parent, no matter what the latter is precisely. it also means lower maintenance of the kernel configuration files because drivers for audio controllers are added more easily. obsessed. ✨

most attachments are done through interface attributes, although only a few of them are specified that way in the configuration files found in the tree. another example of such an attribute is ata:

viaide0 at pci0 dev 17 function 1
atabus0 at viaide0 channel 0

viaide* at pci? dev ? function ?
atabus* at ata?

🫶 SEE ALSO 🫶

and that’s the page, bestie. this little icon is from Debian, dated June 4, 2006, and it’s the CONFIG.SAMPLES(5) page — periodt. 🎀💖

📦 where this page comes from