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