1.\" $OpenBSD: files.conf.5,v 1.23 2016/03/02 15:04:20 naddy 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 $Mdocdate: March 2 2016 $ 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.Pp 42The 43.Pa files.*\& 44rules base are simple, human-readable, text files. 45Empty lines, as well as text prefixed by the 46.Sq # 47character, are ignored. 48.Sh DEVICE TREE CONCEPT 49The 50.Ox 51kernel 52.Dq sees 53the various devices as a hierarchical tree, where the various devices 54.Dq attach 55to parent entities, which can either be physical devices themselves 56.Pq such as a computer bus , 57or logical entities, designed to make the driver code simpler. 58Usually, the top-most devices are attached to the pseudo-device 59.Dq mainbus , 60which is itself reported as attached to a fictitious 61.Dq root 62node. 63There is no restriction on the 64.Dq children 65a device node may have; 66some device drivers can attach themselves to different kinds of parent devices. 67For example, the logical 68.Xr scsibus 4 69device can either attach at a SCSI controller device, 70or at the logical 71.Xr atapiscsi 4 72bus. 73.Sh LOCATORS 74Some device attachments need to provide attachment information. 75For example, an 76.Xr isa 4 77device will use a range of I/O ports, one or more DMA channels, and one 78interrupt vector. 79This attachment information is known as the 80.Dq locators 81for the device. 82Most of the buses support default values for unspecified locators, for devices 83that either do not require them 84.Po 85such as 86.Xr isa 4 87cards not using interrupts 88.Pc , 89or which can autoconfigure themselves 90.Po 91such as 92.Xr pci 4 93devices 94.Pc . 95.Pp 96Attachment lines in the kernel configuration file must match the locators of 97the device they are attaching to. 98For example: 99.Bd -literal -offset indent 100define pci {[dev = -1], [function = -1]} 101.Ed 102.Pp 103With the rule above, 104the following kernel configuration lines are valid: 105.Bd -literal -offset indent 106pciknob0 at pci? dev 2 function 42 # use fixed values 107pciknob* at pci? dev ? function ? # use default values 108pciknob* at pci? # use default locators 109.Ed 110.Pp 111But the following are not: 112.Bd -literal -offset indent 113pciknob* at pci? trick ? treat ? # unknown locators 114pciknob* at pci? dev ? function ? usefulness ? # unknown locators 115.Ed 116.Sh ATTRIBUTES 117The following syntax defines a simple attribute, 118which can be later used to factorize code dependencies: 119.Pp 120.Dl define attribute 121.Pp 122An attachment-like attribute will also require locators to be specified. 123If no locators are necessary: 124.Pp 125.Dl define attribute {} 126.Pp 127If locators are provided: 128.Pp 129.Dl define attribute {[locator1 = default1], [locator2 = default2]} 130.Sh DEVICES 131For simple device attachment, the following syntax 132defines a simple device, with no locators: 133.Pp 134.Dl device devicename {} 135.Pp 136If locators are necessary, they are specified as: 137.Pp 138.Dl device devicename {[locator1 = default1], [locator2 = default2]} 139.Pp 140A device can also reference an attribute with locators. 141This is in fact a dependency rule. 142For example, 143.Pa sys/conf/files 144defines the following attribute for SCSI controllers: 145.Pp 146.Dl define scsi {} # no locators 147.Pp 148And SCSI drivers can then be defined as: 149.Pp 150.Dl device scsictrl: scsi 151.Pp 152A device may depend on as many attributes as necessary: 153.Pp 154.Dl device complexdev: simpledev, otherdev, specialattribute 155.Sh PSEUDO DEVICES 156Pseudo devices are defined as regular devices, except that they do not 157need locators, and use a different keyword: 158.Bd -literal -offset indent 159pseudo-device loop: inet 160pseudo-device ksyms 161.Ed 162.Pp 163The rules above define, respectively, 164the loopback network interface and the kernel symbols pseudo-device. 165.Sh DEVICE ATTACHMENT RULES 166Due to the tree structure of the device nodes, every device but the pseudo 167devices need to attach to some parent node. 168A device driver has to specify to which parents it can attach, with the 169following syntax: 170.Pp 171.Dl attach device at parent, parent2, parent3 172.Pp 173The rule above lists all the parent attributes a device may attach to. 174For example, given the following: 175.Bd -literal -offset indent 176device smartknob: bells, whistles 177attach smartknob at brainbus 178.Ed 179.Pp 180The following configuration line is then valid: 181.Pp 182.Dl smartknob* at brainbus? 183.Pp 184Whilst the following is not: 185.Pp 186.Dl smartknob* at dumbbus? 187.Pp 188If a device supports attachments to multiple parents, using different 189.Dq glue 190routines every time, the following syntax specifies the details: 191.Bd -literal -offset indent 192attach device at parent with device_parent_glue 193attach device at parent2 with device_parent2_glue 194.Ed 195.Pp 196This will define more required attributes, depending on the kernel 197configuration file's contents. 198.Sh RULE FILE INCLUSION 199It is possible to include other rules files anywhere in a file, using the 200.Dq include 201keyword: 202.Pp 203.Dl include \&"dev/pci/files.pci\&" 204.Pp 205The above rule will include the rules for machine-independent PCI code. 206.Pp 207The files 208.Pa sys/arch/machine/conf/files.machine , 209for every 210.Dq machine 211listed in the machine line in the kernel configuration file, as well as 212.Pa sys/conf/files , 213are always processed, and do not need to be included. 214.Sh ATTRIBUTE REQUIREMENTS 215The kernel configuration file description passed to 216.Xr config 8 217lists several compilation options, as well as several device definitions. 218From this list, 219.Xr config 8 220will build a list of required attributes, which are: 221.Pp 222.Bl -bullet -offset indent -compact 223.It 224The 225.Dq option 226lines, with the option name translated to lowercase (for example, an 227.Dq option INET6 228line will produce the 229.Dq inet6 230attribute). 231.It 232The device and pseudo-device names, except for 233.Dq root . 234.El 235.Sh KERNEL FILE LIST 236Kernel source files are defined as: 237.Bd -literal -offset indent 238file file-list dependencies need-rules 239.Ed 240.Pp 241.Dq file-list 242typically only specifies a single filename. 243If instead it contains a list of filenames separated by the 244.Sq \&| 245character, 246.Xr config 8 247will select the first file from the list which exists. 248If 249.Dq ${MACHINE_ARCH} 250or 251.Dq ${MACHINE} 252is found in the filename, it will be substituted with the 253relevant base architecture name. 254.Pp 255If the 256.Dq dependencies 257part is empty, the file will always be compiled in. 258This is the case for the core kernel files. 259Otherwise, the file will only be added to the list if the dependencies are met. 260Dependencies are based upon attributes and device names. 261Multiple dependencies can be written using the 262.Dq \&| 263and 264.Dq & 265operators. 266For example: 267.Pp 268.Dl file netinet/ipsec_input.c (inet | inet6) & ipsec 269.Pp 270The above rule teaches 271.Xr config 8 272to only add 273.Pa sys/netinet/ipsec_input.c 274to the filelist if the 275.Dq ipsec 276attribute, and at least one of the 277.Dq inet 278and 279.Dq inet6 280attributes, are required. 281.Pp 282The 283.Dq need 284rules can be empty, or one of the following keywords: 285.Pp 286.Bl -tag -width "needs-count" -compact 287.It Ar needs-flag 288Create an attribute header file, defining whether or not this 289attribute is compiled in. 290.It Ar needs-count 291Create an attribute header file, defining how many instances of this 292attribute are to be compiled in. 293This rule is mostly used for pseudo-devices. 294.El 295.Pp 296The 297.Dq attribute header files 298are simple C header files created in the kernel compilation directory, 299with the name 300.Pa attribute.h 301and containing the following line: 302.Pp 303.Dl #define NATTRIBUTE 0 304.Pp 305This would substitute the attribute name and its uppercase form, prefixed with 306the letter 307.Dq N , 308to 309.Dq attribute 310and 311.Dq NATTRIBUTE , 312respectively. 313For a 314.Dq needs-flag 315rule, the value on the 316.Dq #define 317line is either 1 if the attribute is required, or 0 if it is not required. 318For a 319.Dq needs-count 320rule, the value is the number of device instances required, or 0 321if the device is not required. 322.Pp 323Attribute files are created for every attribute listed with a 324.Dq need 325rule, even if it is never referenced from the kernel configuration file. 326.Sh MISCELLANEOUS ITEMS 327.Pa sys/arch/machine/conf/files.machine 328must also supply the following special commands: 329.Bl -tag -width maxpartitions 330.It Ar maxpartitions 331Defines how many partitions are available on disk block devices, usually 16. 332This value is used by 333.Xr config 8 334to set up various device information structures. 335.It Ar maxusers 336Defines the bounds, and the default value, for the 337.Dq maxusers 338parameter in the kernel configuration file. 339The usual values are 2 8 64 ; 340.Xr config 8 341will report an error if the 342.Dq maxusers parameter 343in the kernel configuration file does not fit in the specified range. 344.El 345.Sh FILES 346.Bl -tag -width Ds 347.It Pa sys/arch/machine/conf/files.machine 348Rules for architecture-dependent files, for the 349.Dq machine 350architecture. 351.It Pa sys/dev/class/files.class 352Rules for the 353.Dq class 354class of devices. 355.It Pa sys/scsi/files.scsi 356Rules for the common SCSI subsystem. 357.El 358.Sh SEE ALSO 359.Xr config 8 360