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