kernconf.5: Add info on 64-bit kernels & improve markup
[dragonfly.git] / share / man / man5 / kernconf.5
1 .\"
2 .\" Copyright (c) 2007
3 .\"     The DragonFly Project.  All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\"
9 .\" 1. Redistributions 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
13 .\"    the documentation and/or other materials provided with the
14 .\"    distribution.
15 .\" 3. Neither the name of The DragonFly Project nor the names of its
16 .\"    contributors may be used to endorse or promote products derived
17 .\"    from this software without specific, prior written permission.
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
22 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
23 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
24 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
25 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
27 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
29 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\" $DragonFly: src/share/man/man5/kernconf.5,v 1.8 2008/07/16 01:02:07 thomas Exp $
33 .\"
34 .Dd September 28, 2009
35 .Os
36 .Dt KERNCONF 5
37 .Sh NAME
38 .Nm kernconf
39 .Nd kernel configuration file
40 .Sh SYNOPSIS
41 .Cd cpu ...
42 .Cd device ...
43 .Cd ident ...
44 .Cd machine ...
45 .Cd machine-arch ...
46 .Cd makeoptions ...
47 .Cd maxusers ...
48 .Cd options ...
49 .Cd platform ...
50 .Cd pseudo-device ...
51 .Sh DESCRIPTION
52 This manual page describes the structure of the kernel configuration file.
53 It is processed by
54 .Xr config 8
55 to create a build environment where a kernel may be built using
56 .Xr make 1 .
57 See
58 .Xr build 7
59 for information on how to build kernels.
60 .Pp
61 Each line starts with a keyword at the beginning of the line and is
62 followed by additional parameters.
63 Long input lines may be broken into shorter lines by starting the
64 second and subsequent lines with a white space character.
65 Numbers are specified using
66 .Tn C Ns -style
67 syntax.
68 Blank lines are ignored.
69 The
70 .Sq #
71 character is interpreted as a comment and is ignored along with everything
72 that follows it on the same line.
73 .Sh KEYWORDS
74 The following keywords are recognized in a configuration file:
75 .Pp
76 .Bl -tag -width indent -compact
77 .It Sy cpu Xo
78 .Ar name
79 .Xc
80 This system is to run on the CPU type
81 .Ar name .
82 Legal types are, for
83 .Sy i386 :
84 .Sy I486_CPU
85 (i486),
86 .Sy I586_CPU
87 .Tn ( Pentium ) ,
88 and
89 .Sy I686_CPU
90 .Tn ( Pentium Pro ) ;
91 for
92 .Sy amd64 :
93 .Sy HAMMER_CPU
94 .Tn ( x86-64 ) .
95 More than one CPU type specification can appear in a configuration file.
96 .Pp
97 .It Sy device Xo
98 .Ar name
99 .Op Sy at Ar bus
100 .Op Sy port Ar num
101 .Op Sy irq Ar num
102 .Op Sy drq Ar num
103 .Op Sy iomem Ar num
104 .Op Sy iosiz Ar num
105 .Op Sy flags Ar num
106 .Xc
107 Configures support for device
108 .Ar name .
109 Additional parameters may be passed to specify
110 .Tm I/O
111 configuration settings (most often for
112 .Xr isa 4
113 devices):
114 .Bl -tag -width ".Sy iomem"
115 .It Sy at
116 specifies a bus to which the device is attached.
117 .It Sy port
118 specifies the start address of
119 .Tm I/O
120 ports to be used by the device.
121 .It Sy irq
122 specifies the number of ports used by the device.
123 .It Sy drq
124 is the interrupt line number to be used.
125 .It Sy iomem
126 specifies the physical memory address used by the device.
127 .It Sy iosiz
128 specifies the physical memory size used by the device.
129 .It Sy flags
130 sets various flag bits for the device.
131 .El
132 .Pp
133 .It Sy ident Xo
134 .Ar string
135 .Xc
136 Sets the kernel identification string to
137 .Ar string .
138 .Pp
139 .It Sy machine Xo
140 .Ar name
141 .Xc
142 The system is to run on the machine type
143 .Ar name .
144 This is a legacy keyword, it is normally set to same value as
145 .Sy machine_arch .
146 .Pp
147 .It Sy machine_arch Xo
148 .Ar name
149 .Xc
150 The system is to run on the machine architecture
151 .Ar name .
152 The legal architectures are
153 .Sy i386 ,
154 and
155 .Sy amd64 .
156 .Pp
157 .It Sy makeoptions Xo
158 .Ar name Ns Sy = Ns Ar value
159 .Xc
160 Defines a
161 .Xr make 1
162 macro
163 .Ar name
164 with the value
165 .Ar value
166 in the kernel Makefile.
167 .Pp
168 .It Sy maxusers Xo
169 .Ar integer
170 .Xc
171 Set the
172 .Va maxusers
173 variable in the kernel.
174 .Pp
175 .It Sy options Xo
176 .Ar name Ns Op Sy = Ns Ar value
177 .Xc
178 Sets the option
179 .Ar name .
180 Some options expect to be assigned a value, which may be an integer,
181 a double-quoted word, a bare word, or an empty string
182 .Pq Qq .
183 Note that those are eventually handled by the C compiler, so the rules
184 of that language apply.
185 .\"For more information see the
186 .\".Sx OPTIONS
187 .\"section.
188 .Pp
189 .It Sy platform Xo
190 .Ar name
191 .Xc
192 Sets the platform of this kernel to
193 .Ar name .
194 Legal platforms are
195 .Sy pc32 ,
196 .Sy pc64 ,
197 and
198 .Sy vkernel ,
199 meaning either a 32 bit
200 .Tn Intel
201 architecture, a 64 bit
202 .Tn AMD
203 architecture, or a virtual kernel.
204 .Pp
205 .It Sy pseudo-device Xo
206 .Ar name
207 .Op Ar N
208 .Xc
209 Includes support for the pseudo-device
210 .Ar name .
211 Some pseudo-devices can have multiple or
212 .Ar N
213 instances.
214 .El
215 .\".Sh OPTIONS
216 .Sh FILES
217 .Bl -tag -width ".Pa /sys/config/AMD64_GENERIC"
218 .It Pa /sys/config/LINT
219 description of kernel configuration options
220 .It Pa /sys/config/AMD64_GENERIC
221 default
222 .Sy amd64
223 kernel configuration file
224 .It Pa /sys/config/GENERIC
225 default
226 .Sy i386
227 kernel configuration file
228 .It Pa /sys/config/VKERNEL
229 default
230 .Xr vkernel 7
231 kernel configuration file
232 .El
233 .Sh SEE ALSO
234 .Xr make 1 ,
235 .Xr build 7 ,
236 .Xr vkernel 7 ,
237 .Xr config 8
238 .Sh HISTORY
239 The
240 .Nm
241 manual page first appeared in
242 .Dx 1.11 .