| CONFIG(8) |
AerieBSD 1.0 Refernce Manual |
CONFIG(8) |
NAME
config —
build kernel compilation directories or modify a kernel
SYNOPSIS
config
[-p]
[-b builddir]
[-s srcdir]
[config-file]
config
[-u]
[-f | o outfile]
-e
infile
DESCRIPTION
In the first synopsis form, the
config
program creates a kernel build directory from the kernel configuration file
specified by
config-file.
In the second synopsis form,
config
allows editing of the kernel binary specified by
infile.
Devices may be enabled, disabled, or modified without recompiling,
by editing the kernel executable.
Similarly, the same editing can be done at boot-time,
using the in-kernel editor,
as described in
boot_config(8).
For kernel building, the options are as follows:
- -b builddir
-
Create the build directory in the path specified by
builddir
instead of the default
../compile/SYSTEMNAME.
- -p
-
Configure for a system that includes profiling code; see
kgmon(8)
and
gprof(1).
When this option is specified,
config
acts as if the lines
“makeoptions PROF="-pg"”
and
“option GPROF”
appeared in the specified kernel configuration file.
In addition,
“.PROF”
is appended to the default compilation directory name.
The
-p
flag is expected to be used for
“one-shot”
profiles of existing systems; for regular profiling, it is probably wiser to
make a separate configuration containing the makeoptions line.
- -s srcdir
-
Use
srcdir
as the top-level kernel source directory instead of the default (four
directories above the build directory).
For kernel modification, the options are as follows:
- -e
-
Allows the modification of kernel device configuration (see
boot_config(8/)).
Temporary changes can be made to the running kernel's configuration or a new
kernel binary may be written for permanent changes between system reboots.
See the section
below for more details.
- -f
-
Overwrite the
infile
kernel binary with the modified kernel.
Otherwise,
-o
should be given to specify an alternate output file.
- -o outfile
-
Write the modified kernel to
outfile.
- -u
-
Check to see if the kernel configuration was modified at boot-time
(i.e.\&
-boot-c
was used).
If so, compare the running kernel with the kernel to be edited
(infile).
If they seem to be the same, apply all configuration changes performed at
boot.
KERNEL BUILDING
The old
-g
flag is deprecated and no longer supported.
Instead, add
“makeoptions DEBUG="-g"”
to the kernel configuration file, along with (typically)
“option KGDB”.
The output of
config
consists of a number of files, principally
ioconf.c
(a description of I/O devices that may be attached to the system)
and a
Makefile,
used by
make(1)
when building the kernel.
After running
config
it is wise to run
“make depend”
in the new build directory.
config
prints a reminder of this when it completes.
If
config
stops due to errors, the problems reported should be corrected and
config
should be run again.
config
attempts to avoid changing the compilation directory if there are
configuration errors, but this code is not well-tested and some problems
(such as running out of disk space) are unrecoverable.
If
config-file
is not specified,
config
uses the current directory as the build directory, and looks in it for
a file called
CONFIG.
If
config
is run this way, the location of the top-level kernel source
directory must be specified using the
-s
option or by using the
“source”
directive at the beginning of the system configuration file.
The configuration files consists of various statements which
include the following:
- machine var
-
Required.
Specifies the machine architecture.
- include file
-
Include another configuration file.
- option name
-
Set a kernel option.
Kernel options may take either the form
NAME
or the form
NAME=value.
These options are passed to the compiler with the
-D
flag.
- rmoption name
-
Delete a previously set option.
This is useful when including another kernel configuration file.
A typical use is to include the
GENERIC
kernel provided with each release and remove options that are
unwanted, thus allowing for automatic inclusion of new device
drivers.
- maxusers number
-
Required.
Used to size various system tables and maximum operating conditions
in an approximate fashion.
Multiple instances of this keyword may be specified.
The number provided in the last instance will be used, and
warnings will be printed for each duplicate value.
This is convenient when used with the
include
directive.
- config bsdroot on "dev [swap on dev [and dev ...]] [dumps on dev [and dev ...]]"
-
Required.
Specifies the swap and dump devices which the system should use.
- config bsdswap generic
-
Otherwise, if generic is specified, the system follows generic routines to
decide what should happen.
Many other statements exist, and the file format is fairly rich; for more
information see the various configuration files included in the system, as
well as
files.conf(5)
for the
config
rules base.
KERNEL MODIFICATION
When
-e
is specified, device parameters that are normally hard-coded into the kernel
may be changed.
This is useful to avoid the need for kernel recompilation or rebooting.
Modifications are made to the currently running kernel and can be written to
a new kernel binary so changes are preserved during subsequent system restarts.
When invoked, the kernel identification is first shown.
# config -e -o bsd.new /bsd
OpenBSD 2.6-beta (GENERIC.rz0) #0: Mon Oct 4 03:57:22 MEST 1999
root@winona:/usr/src/sys/arch/pmax/compile/GENERIC.rz0
Enter 'help' for information
ukc\*(Gt
One or more warnings may be printed before the
ukc\*(Gt
prompt.
warning: no output file specified
Neither the
-f
nor
-o
option has been specified.
Changes will be ignored.
WARNING this kernel doesn't contain all information needed!
WARNING the commands add and change might not work.
The kernel is too old (pre
OpenBSD 2.6)
and cannot support all of the functionality needed by the
-e
option.
WARNING kernel mismatch. -u ignored.
WARNING the running kernel version:
config
does not believe the running kernel is the same as the
infile
specified.
Since the log of changes (from
-boot-c)
in the running kernel is kernel-specific, the
-u
option is ignored.
The commands are as follows:
- adddev
-
Add a device through copying another.
- base8| 10 | 16
-
Change the base of numbers displayed and entered,
e.g. I/O addresses in a VAXen are octal.
- cachepct[number]
-
Change the BUFCACHEPERCENT value.
Without arguments, displays its current value.
- changedevno| dev
-
Modify one or more devices.
- disableattrval | devno | dev
-
Disable one or more devices.
- enableattrval | devno | dev
-
Enable one or more devices.
- exit
-
Exit without saving changes.
- finddevno| dev
-
Find one or more devices.
- help
-
Give a short summary of all commands and their arguments.
- lines[count]
-
Set the number of rows per page.
- list
-
Show all known devices, a screen at a time.
- nkmempg[number]
-
Change the NKMEMPAGES value.
Without arguments, displays its current value.
- quit
-
Exit and save changes.
- shmmaxpgs[number]
-
Change the SHMMAXPGS value.
Without arguments, displays its current value.
- shmseg[number]
-
Change the SHMSEG value.
Without arguments, displays its current value.
- show[attr[val]]
-
Show all devices for which attribute
attr
has the value
val.
- timezone[minuteswest[dst]]
-
Change the
tz
timezone structure.
minuteswest
is the number of minutes west of GMT and
dst
is non-zero if Daylight Saving Time is in effect.
Without arguments, displays its current value.
EXAMPLES (kernel building)
Note:
The standard
OpenBSD
kernel configuration
(GENERIC or GENERIC.MP)
is suitable for most purposes.
Use of an alternative kernel configuration is not recommended.
A custom kernel is built in the following way.
To compile a kernel from a non-writable media (such as a CD-ROM)
mounted on
/usr/src,
do the following:
# cd /somedir
# cp /usr/src/sys/arch/somearch/conf/SOMEFILE .
# vi SOMEFILE (to make any changes)
# config -s /usr/src/sys -b . SOMEFILE
# make
To compile a kernel inside a writable source tree, do the following:
# cd /usr/src/sys/arch/somearch/conf
# vi SOMEFILE (to make any changes)
# config SOMEFILE
# cd ../compile/SOMEFILE
# make
In the examples above,
somedir
is a writable directory,
somearch
is the architecture (e.g. i386),
and
SOMEFILE
should be a name indicative of a particular configuration (often
that of the hostname).
config
will warn if a
“make clean”
is required;
a
“make depend”
can also be run
to have dependencies there the next time sources are compiled.
The new kernel, called
bsd,
can be copied to
/bsd
and the system will boot it next time.
Most people save their backup kernels as
/bsd.1,
/bsd.2,
etc.
EXAMPLES (kernel modification)
The Ethernet card is not detected at boot because the kernel configuration
does not match the physical hardware configuration,
e.g. wrong IRQ in OpenBSD/i386.
The Ethernet card is supposed to use the
ne(4)
driver.
ukc\*(Gt findne
24 ne0 at isa0 port 0x240 size 0 iomem 0xd8000 iosiz 0 irq 9 drq -1 drq2 -1 flags 0x0
25 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0
26 ne* at isapnp0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 flags 0x0
27 ne* at pci* dev -1 function -1 flags 0x0
28 ne* at pcmcia* function -1 irq -1 flags 0x0
ukc\*(Gt
ne1 seems to match the configuration except it uses IRQ 5 instead of IRQ 10.
So the irq on ne1 should be changed via the
change
command.
The device can be specified by either name or number.
ukc\*(Gt changene1
25 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1
change (y/n) \&? y
port [0x300] \&?
size [0] \&?
iomem [-1] \&?
iosiz [0] \&?
irq [10] \&? 5
drq [-1] \&?
drq2 [-1] \&?
flags [0] \&?
25 ne1 changed
25 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 5 drq -1 drq2 -1 flags 0x0
ukc\*(Gt
Another case is a mistakenly detected non-existing device instead of another
device at the probed location.
One known case is the Mitsumi
CD-ROM in OpenBSD/i386.
The simplest thing to solve that problem is to disable mcd0.
ukc\*(Gt findmcd0
29 mcd0 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0
ukc\*(Gt disablemcd0
29 mcd0 disabled
ukc\*(Gt find29
29 mcd0 at isa0 disable port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0
It's also possible to disable all devices with a common attribute.
For example:
ukc\*(Gt disableport 0x300
25 ne1 disabled
29 mcd0 already disabled
72 we1 disabled
75 el0 disabled
77 ie1 disabled
The
-show
command is useful for finding which devices have a certain attribute.
It can also be used to find those devices with a particular value for
an attribute.
ukc\*(Gt showslot
2 ahc* at eisa0 slot -1
10 uha* at eisa0 slot -1
12 ep0 at eisa0 slot -1
17 ep* at eisa0 slot -1
102 ahb* at eisa0 slot -1
103 fea* at eisa0 slot -1
ukc\*(Gt showport 0x300
25 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0
72 we1 at isa0 port 0x300 size 0 iomem 0xcc000 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0
75 el0 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 9 drq -1 drq2 -1 flags 0x0
77 ie1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0
ukc\*(Gt
It is possible to add new devices, but only devices that were linked into the
kernel.
If a new device is added, following devices will be renumbered.
ukc\*(Gt findep
11 ep0 at isa0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 drq2 -1 flags 0x0
12 ep0 at eisa0 slot -1 flags 0x0
13 ep0 at pci* dev -1 function -1 flags 0x0
14 ep* at isapnp0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 flags 0x0
15 ep* at isa0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 drq2 -1 flags 0x0
16 ep* at eisa0 slot -1 flags 0x0
17 ep* at pci* dev -1 function -1 flags 0x0
18 ep* at pcmcia* dev -1 irq -1 flags 0x0
ukc\*(Gt addep1
"Clone Device (DevNo, 'q' or '\&?') \&?" 13
"Insert before Device (DevNo, 'q' or '\&?')" 14
14 ep1 at pci* dev -1 function -1
ukc\*(Gt change14
14 ep1 at pci* dev -1 function -1
change (y/n) \&? y
dev [-1] \&? 14
function [-1] \&?
flags [0] \&? 18
14 ep1 changed
14 ep1 at pci* dev 14 function -1 flags 0x12
ukc\*(Gt
When done, exit the program with the
quit
or
exit
commands.
exit
will ignore any changes while
quit
writes the changes to
outfile
(if
-o
or
-f
was given, else ignore changes).
ukc\*(Gt quit
SEE ALSO
options(4),
boot.conf(5),
files.conf(5),
boot_config(8)
The SYNOPSIS portion of each device in section 4 of the manual.
.Rs
.%T "Building 4.4 BSD Systems with Config"
.Re
HISTORY
The
config
program appeared in 4.1BSD.
It was completely revised in 4.4BSD.
The
-e
option appeared in
OpenBSD 2.6.
BUGS
Included files should start with an empty line or comment.
| AerieBSD 1.0 Reference Manual |
August 26 2008 |
CONFIG(8) |