1.\" $OpenBSD: files.conf.5,v 1.7 2003/07/09 20:23:34 jmc Exp $ 2.\" 3.\" Copyright (c) 2002 Miodrag Vallat. 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. Redistribution 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 AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" 27.Dd October 8, 2002 28.Dt FILES.CONF 5 29.Os 30.Sh NAME 31.Nm files.conf 32.Nd rules base for the config utility 33.Sh DESCRIPTION 34The various 35.Pa files.* 36files located in the kernel source tree 37contain all the necessary information needed by 38.Xr config 8 39to parse a kernel configuration file and determine the list of files to 40compile. 41.Sh SYNTAX 42The 43.Pa files.* 44rules base are simple, human-readable, text files. 45Empty lines, as well as text prefixed by the 46.Dq # 47character, are ignored. 48.\" 49.Ss Device tree concept 50.\" 51The 52.Ox 53kernel 54.Dq sees 55the various devices as a hierarchical tree, where the various devices 56.Dq attach 57to parent entities, which can either be physical devices themselves 58.Pq such as a computer bus , 59or logical entities, designed to make the driver code simpler. 60Usually, the top-most devices are attached to the pseudo-device 61.Dq mainbus , 62which is itself reported as attached to a fictitious 63.Dq root 64node. 65There is no restriction on the 66.Dq children 67a device node may have; 68some device drivers can attach themselves to different kinds of parent devices. 69For example, the logical 70.Xr scsibus 4 71device can either attach at an 72.Tn SCSI 73controller device, or at the logical 74.Xr atapiscsi 4 75bus. 76.\" 77.Ss Locators 78.\" 79Some device attachments need to provide attachment information. 80For example, an 81.Xr isa 4 82device will use a range of io ports, one or more DMA channels, and one 83interrupt vector. 84This attachment information is known as the 85.Dq locators 86for the device. 87Most of the busses support default values for unspecified locators, for devices 88that either do not require them 89.Po 90such as 91.Xr isa 4 92cards not using interrupts 93.Pc , 94or which can autoconfigure themselves 95.Po 96such as 97.Xr pci 4 98devices 99.Pc . 100.Pp 101Attachment lines in the kernel configuration file must match the locators of 102the device they are attaching to. 103For example, given 104.Bl -item -offset indent -compact 105.It 106.Em define pci {[dev = -1], [function = -1]} 107.El 108in the rules files, the following kernel configuration lines are valid: 109.Bl -item -offset indent -compact 110.It 111.Cd "pciknob0 at pci? dev 2 function 42 # use fixed values" 112.It 113.Cd "pciknob* at pci? dev ? function ? # use default values" 114.It 115.Cd "pciknob* at pci? # use default locators" 116.El 117.Pp 118but the following are not: 119.Bl -item -offset indent -compact 120.It 121.Cd "pciknob* at pci? trick ? treat ? # unknown locators" 122.It 123.Cd "pciknob* at pci? dev ? function ? usefulness ? # unknown locators" 124.El 125.\" 126.Ss Attributes 127.\" 128The syntax 129.Bl -item -offset indent -compact 130.It 131.Em define attribute 132.El 133defines a simple attribute, which can be later used to factorize 134code dependencies. 135An attachment-like attribute will also require locators to be specified, 136such as 137.Bl -item -offset indent -compact 138.It 139.Em define attribute {} 140.El 141if no locators are necessary, or 142.Bl -item -offset indent -compact 143.It 144.Em define attribute {[locator1 = default1], [locator2 = default2]} 145.El 146if locators are provided. 147.\" 148.Ss Devices 149.\" 150For simple device attachment, the syntax 151.Bl -item -offset indent -compact 152.It 153.Em define device {} 154.El 155defines a simple device, with no locators. 156If locators are necessary, they are specified as: 157.Bl -item -offset indent -compact 158.It 159.Em define device {[locator1 = default1], [locator2 = default2]} 160.El 161A device can also reference an attribute with locators. 162This is in fact a dependency rule. 163For example, 164.Pa sys/dev/conf/files 165defines the following attribute for 166.Tn SCSI 167controllers: 168.Bl -item -offset indent -compact 169.It 170.Em define scsi {} # no locators 171.El 172and 173.Tn SCSI 174drivers can then be defined as 175.Bl -item -offset indent -compact 176.It 177.Em define scsictrl: scsi 178.El 179A device may depend on as many attributes as necessary: 180.Bl -item -offset indent -compact 181.It 182.Em define complexdev: simpledev, otherdev, specialattribute 183.El 184.\" 185.Ss Pseudo devices 186.\" 187Pseudo device are defined as regular devices, except that they do not need 188locators, and use a different keyword: 189.Bl -item -offset indent -compact 190.It 191.Em pseudo-device loop: inet 192.It 193.Em pseudo-device ksyms 194.El 195define, respectively, the loopback network interface and the kernel symbols 196pseudo-device. 197.\" 198.Ss Device attachment rules 199.\" 200Due to the tree structure of the device nodes, every device but the pseudo 201devices need to attach to some parent node. 202A device driver has to specify to which parents it can attach, with the 203following syntax: 204.Bl -item -offset indent -compact 205.It 206.Em attach device at parent, parent2, parent3 207.El 208which lists all the parent attributes a device may attach to. 209For example, if a device is specified as: 210.Bl -item -offset indent -compact 211.It 212.Em device smartknob: bells, whistles 213.It 214.Em attach smartknob at brainbus 215.El 216then a 217.Bl -item -offset indent -compact 218.It 219.Cd smartknob* at brainbus? 220.El 221configuration file line is valid, while a 222.Bl -item -offset indent -compact 223.It 224.Cd smartknob* at dumbbus? 225.El 226is not. 227.Pp 228If a device supports attachments to multiple parents, using different 229.Dq glue 230routines every time, the following syntax specifies the details: 231.Bl -item -offset indent -compact 232.It 233.Em attach device at parent with device_parent_glue 234.It 235.Em attach device at parent2 with device_parent2_glue 236.El 237and will define more required attributes, depending on the kernel 238configuration file's contents. 239.\" 240.Ss Rule file inclusion 241.\" 242It is possible to include other rules files anywhere in a file, using the 243.Dq include 244keyword: 245.Bl -item -offset indent -compact 246.It 247.Em include "dev/pci/files.pci" 248.El 249will include the rules for machine-independent PCI code. 250.Pp 251The files 252.Pa sys/arch/machine/conf/files.machine , 253for every 254.Dq machine 255listed in the machine line in the kernel configuration file, as well as 256.Pa sys/conf/files , 257are always processed, and do not need to be included. 258.\" 259.Ss Attribute requirements 260.\" 261The kernel configuration file description passed to 262.Xr config 8 263lists several compilation options, as well as several device definitions. 264From this list, 265.Xr config 8 266will build a list of required attributes, which are 267.Bl -bullet -offset XXX -compact 268.It 269the 270.Dq option 271lines, with the option name translated to lowercase (for example, an 272.Dq option INET 273line will produce the 274.Dq inet 275attribute). 276.It 277the device and pseudo-device names, except for 278.Dq root . 279.El 280.\" 281.Ss Kernel file list 282.\" 283Kernel source files are defined as: 284.Bl -item -offset indent -compact 285.It 286.Em file somewhere/somefile.c dependencies need-rules 287.El 288If the 289.Dq dependencies 290part is empty, the file will always be compiled in. 291This is the case for the core kernel files. 292Otherwise, the file will only be added to the list if the dependencies are met. 293Dependencies are based upon attributes and device names. 294Multiple dependencies can be written using the 295.Dq \&| 296and 297.Dq & 298operators. 299For example, the line 300.Bl -item -offset indent -compact 301.It 302.Em file netinet/ipsec_input.c (inet | inet6) & ipsec 303.El 304teaches 305.Xr config 8 306to only add 307.Pa sys/netinet/ipsec_input.c 308to the filelist if the 309.Dq ipsec 310attribute, and at least one of the 311.Dq inet 312and 313.Dq inet6 314attributes, are required. 315.Pp 316The 317.Dq need 318rules can be empty, or one of the following keywords: 319.Bl -tag -width "needs-count" -compact 320.It Ar needs-flag 321Create an attribute header file, defining whether or not this 322attribute is compiled in. 323.It Ar needs-count 324Create an attribute header file, defining how many instances of this 325attribute are to be compiled in. 326This rule is mostly used for pseudo-devices. 327.El 328.Pp 329The 330.Dq attribute header files 331are simple C header files created in the kernel compilation directory, 332with the name 333.Pa attribute.h 334and containing the following line: 335.Bl -item -offset indent -compact 336.It 337#define NATTRIBUTE 0 338.El 339substituting the attribute name and its uppercase form, prefixed with 340the letter 341.Dq N , 342to 343.Dq attribute 344and 345.Dq NATTRIBUTE , 346respectively. 347For a 348.Dq needs-flag 349rule, the value on the 350.Dq #define 351line is either 1 if the attribute is required, or 0 if it is not required. 352For a 353.Dq needs-count 354rule, the value is the number of device instances required, or 0 355if the device is not required. 356.Pp 357Attribute files are created for every attribute listed with a 358.Dq need 359rule, even if it is never referenced from the kernel configuration file. 360.\" 361.Ss Miscellaneous items 362.\" 363.Pa sys/arch/machine/conf/files.machine 364must also supply the following special commands: 365.Bl -tag -width maxpartitions \" -compact 366.It Ar maxpartitions 367Defines how many partitions are available on disk block devices, usually 16. 368This value is used by 369.Xr config 8 370to set up various device information structures. 371.It Ar maxusers 372Defines the bounds, and the default value, for the 373.Dq maxusers 374parameter in the kernel configuration file. 375The usual values are 2 8 64 ; 376.Xr config 8 377will report an error if the 378.Dq maxusers parameter 379in the kernel configuration file does not fit in the specified range. 380.El 381.\" 382.Sh FILES 383.Bl -tag -width XXX -compact \" deliberately small width 384.It Pa sys/arch/machine/conf/files.machine 385Rules for architecture-dependent files, for the 386.Dq machine 387architecture. 388.Pp 389.It Pa sys/compat/emul/files.emul 390Rules for the 391.Dq emul 392operating system or subsystem emulation. 393.Pp 394.It Pa sys/dev/class/files.class 395Rules for the 396.Dq class 397class of devices. 398.Pp 399.It Pa sys/gnu/arch/i386/fpemul/files.fpemul 400Rules for the i386 GPL floating-point emulator. 401.Pp 402.It Pa sys/scsi/files.scsi 403Rules for the common 404.Tn SCSI 405subsystem. 406.El 407.Sh SEE ALSO 408.Xr config 8 409