1.\" $OpenBSD: files.conf.5,v 1.14 2006/10/28 10:26:26 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 I/O 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 buses 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.Bd -literal -offset indent 105define pci {[dev = -1], [function = -1]} 106.Ed 107.Pp 108in the rules files, the following kernel configuration lines are valid: 109.Bd -literal -offset indent 110pciknob0 at pci? dev 2 function 42 # use fixed values 111pciknob* at pci? dev ? function ? # use default values 112pciknob* at pci? # use default locators 113.Ed 114.Pp 115but the following are not: 116.Bd -literal -offset indent 117pciknob* at pci? trick ? treat ? # unknown locators 118pciknob* at pci? dev ? function ? usefulness ? # unknown locators 119.Ed 120.\" 121.Ss Attributes 122.\" 123The syntax 124.Pp 125.Dl define attribute 126.Pp 127defines a simple attribute, which can be later used to factorize 128code dependencies. 129An attachment-like attribute will also require locators to be specified, 130such as 131.Pp 132.Dl define attribute {} 133.Pp 134if no locators are necessary, or 135.Pp 136.Dl define attribute {[locator1 = default1], [locator2 = default2]} 137.Pp 138if locators are provided. 139.\" 140.Ss Devices 141.\" 142For simple device attachment, the syntax 143.Pp 144.Dl device devicename {} 145.Pp 146defines a simple device, with no locators. 147If locators are necessary, they are specified as: 148.Pp 149.Dl device devicename {[locator1 = default1], [locator2 = default2]} 150.Pp 151A device can also reference an attribute with locators. 152This is in fact a dependency rule. 153For example, 154.Pa sys/conf/files 155defines the following attribute for 156.Tn SCSI 157controllers: 158.Pp 159.Dl define scsi {} # no locators 160.Pp 161and 162.Tn SCSI 163drivers can then be defined as 164.Pp 165.Dl device scsictrl: scsi 166.Pp 167A device may depend on as many attributes as necessary: 168.Pp 169.Dl device complexdev: simpledev, otherdev, specialattribute 170.Pp 171.\" 172.Ss Pseudo devices 173.\" 174Pseudo devices are defined as regular devices, except that they do not 175need locators, and use a different keyword: 176.Bd -literal -offset indent 177pseudo-device loop: inet 178pseudo-device ksyms 179.Ed 180.Pp 181define, respectively, the loopback network interface and the kernel symbols 182pseudo-device. 183.\" 184.Ss Device attachment rules 185.\" 186Due to the tree structure of the device nodes, every device but the pseudo 187devices need to attach to some parent node. 188A device driver has to specify to which parents it can attach, with the 189following syntax: 190.Pp 191.Dl attach device at parent, parent2, parent3 192.Pp 193which lists all the parent attributes a device may attach to. 194For example, if a device is specified as: 195.Bd -literal -offset indent 196device smartknob: bells, whistles 197attach smartknob at brainbus 198.Ed 199.Pp 200then a 201.Pp 202.Dl smartknob* at brainbus? 203.Pp 204configuration file line is valid, while a 205.Pp 206.Dl smartknob* at dumbbus? 207.Pp 208is not. 209.Pp 210If a device supports attachments to multiple parents, using different 211.Dq glue 212routines every time, the following syntax specifies the details: 213.Bd -literal -offset indent 214attach device at parent with device_parent_glue 215attach device at parent2 with device_parent2_glue 216.Ed 217.Pp 218and will define more required attributes, depending on the kernel 219configuration file's contents. 220.\" 221.Ss Rule file inclusion 222.\" 223It is possible to include other rules files anywhere in a file, using the 224.Dq include 225keyword: 226.Pp 227.Dl include \&"dev/pci/files.pci\&" 228.Pp 229will include the rules for machine-independent PCI code. 230.Pp 231The files 232.Pa sys/arch/machine/conf/files.machine , 233for every 234.Dq machine 235listed in the machine line in the kernel configuration file, as well as 236.Pa sys/conf/files , 237are always processed, and do not need to be included. 238.\" 239.Ss Attribute requirements 240.\" 241The kernel configuration file description passed to 242.Xr config 8 243lists several compilation options, as well as several device definitions. 244From this list, 245.Xr config 8 246will build a list of required attributes, which are 247.Pp 248.Bl -bullet -offset indent -compact 249.It 250the 251.Dq option 252lines, with the option name translated to lowercase (for example, an 253.Dq option INET 254line will produce the 255.Dq inet 256attribute). 257.It 258the device and pseudo-device names, except for 259.Dq root . 260.El 261.\" 262.Ss Kernel file list 263.\" 264Kernel source files are defined as: 265.Bd -literal -offset indent 266file somewhere/somefile.c dependencies need-rules 267.Ed 268.Pp 269If the 270.Dq dependencies 271part is empty, the file will always be compiled in. 272This is the case for the core kernel files. 273Otherwise, the file will only be added to the list if the dependencies are met. 274Dependencies are based upon attributes and device names. 275Multiple dependencies can be written using the 276.Dq \&| 277and 278.Dq & 279operators. 280For example, the line 281.Pp 282.Dl file netinet/ipsec_input.c (inet | inet6) & ipsec 283.Pp 284teaches 285.Xr config 8 286to only add 287.Pa sys/netinet/ipsec_input.c 288to the filelist if the 289.Dq ipsec 290attribute, and at least one of the 291.Dq inet 292and 293.Dq inet6 294attributes, are required. 295.Pp 296The 297.Dq need 298rules can be empty, or one of the following keywords: 299.Pp 300.Bl -tag -width "needs-count" -compact 301.It Ar needs-flag 302Create an attribute header file, defining whether or not this 303attribute is compiled in. 304.It Ar needs-count 305Create an attribute header file, defining how many instances of this 306attribute are to be compiled in. 307This rule is mostly used for pseudo-devices. 308.El 309.Pp 310The 311.Dq attribute header files 312are simple C header files created in the kernel compilation directory, 313with the name 314.Pa attribute.h 315and containing the following line: 316.Pp 317.Dl #define NATTRIBUTE 0 318.Pp 319substituting the attribute name and its uppercase form, prefixed with 320the letter 321.Dq N , 322to 323.Dq attribute 324and 325.Dq NATTRIBUTE , 326respectively. 327For a 328.Dq needs-flag 329rule, the value on the 330.Dq #define 331line is either 1 if the attribute is required, or 0 if it is not required. 332For a 333.Dq needs-count 334rule, the value is the number of device instances required, or 0 335if the device is not required. 336.Pp 337Attribute files are created for every attribute listed with a 338.Dq need 339rule, even if it is never referenced from the kernel configuration file. 340.\" 341.Ss Miscellaneous items 342.\" 343.Pa sys/arch/machine/conf/files.machine 344must also supply the following special commands: 345.Bl -tag -width maxpartitions 346.It Ar maxpartitions 347Defines how many partitions are available on disk block devices, usually 16. 348This value is used by 349.Xr config 8 350to set up various device information structures. 351.It Ar maxusers 352Defines the bounds, and the default value, for the 353.Dq maxusers 354parameter in the kernel configuration file. 355The usual values are 2 8 64 ; 356.Xr config 8 357will report an error if the 358.Dq maxusers parameter 359in the kernel configuration file does not fit in the specified range. 360.El 361.\" 362.Sh FILES 363.Bl -tag -width XXX \" deliberately small width 364.It Pa sys/arch/machine/conf/files.machine 365Rules for architecture-dependent files, for the 366.Dq machine 367architecture. 368.It Pa sys/compat/emul/files.emul 369Rules for the 370.Dq emul 371operating system or subsystem emulation. 372.It Pa sys/dev/class/files.class 373Rules for the 374.Dq class 375class of devices. 376.It Pa sys/scsi/files.scsi 377Rules for the common 378.Tn SCSI 379subsystem. 380.El 381.Sh SEE ALSO 382.Xr config 8 383