path: root/usr.sbin/config/config.8

.\"	$OpenBSD: config.8,v 1.11 1999/10/12 00:25:30 maja Exp $
.\"	$NetBSD: config.8,v 1.10 1996/08/31 20:58:16 mycroft Exp $
.\"
.\" Copyright (c) 1980, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     from: @(#)config.8	8.2 (Berkeley) 4/19/94
.\"
.Dd April 19, 1994
.Dt CONFIG 8
.Os
.Sh NAME
.Nm config
.Nd build kernel compilation directories or modify a kernel
.Sh SYNOPSIS
.Nm config
.Op Fl b Ar builddir
.Op Fl s Ar srcdir
.Op Fl p
.Op Ar config-file
.Nm config
.Fl e 
.Op Fl f | o Ar outfile
.Op Fl u
.Ar infile
.Sh DESCRIPTION
.Nm config
creates a kernel build directory from the file
.Ar config-file ,
which describes the system to configure.
.Nm config
can also be used to modify a compiled kernel when using the
.Fl e
option, see section modifying kernel.
.Pp
There are several different ways to run the
.Nm config
program.  The traditional way is to run
.Nm config
from the
.Pa conf
subdirectory of the machine-specific directory of the system source
(usually
.Pa /sys/arch/MACHINE/conf ,
where
.Pa MACHINE
is one of
.Pa i386 ,
.Pa sparc ,
.Pa hp300 ,
and so forth), and to specify as the
.Ar config-file
the name of a file located in that directory.
.Nm config
will by default create files in the directory
.Pa ../compile/SYSTEMNAME ,
where
.Pa SYSTEMNAME
is the last path component of
.Ar config-file .
.Nm config
will assume that the top-level kernel source directory is located four
directories above the build directory.
.Pp
Another way is to create the build directory yourself, place the
configuration file in the build directory with the name
.Pa CONFIG ,
and run
.Nm config
from within the build directory without specifying a
.Ar config-file .
.Nm config
will then by default create files in the current directory.  If you
run
.Nm config
this way, you must specify the location of the top-level kernel source
directory using the
.Fl s
option or by using the
.Dq Li source
directive at the beginning of the system configuration file.
.Pp
Finally, you can specify the build directory for
.Nm config
and run it from anywhere.  You can specify a build directory with the
.Fl b
option or by using the
.Dq Li build
directive at the beginning of the system configuration file.  You must
specify the location of the top-level kernel source directory if you
specify a build directory.
.Pp
If the
.Fl p
option is supplied,
.Pa .PROF
is appended to the default compilation directory name, and
.Nm config
acts as if the lines
.Dq Li makeoptions PROF="-pg"
and
.Dq Li options GPROF
appeared in the configuration file.
This will build a system that includes profiling code; see
.Xr kgmon 8
and
.Xr gprof 1 .
The
.Fl p
flag is expected to be used for
.Dq one-shot
profiles of existing systems;
for regular profiling,
it is probably wiser to make a separate configuration
containing the
.Li makeoptions
line.
.Pp
The old undocumented
.Fl g
flag is no longer supported.
Instead, use
.Dq Li makeoptions DEBUG="-g"
and (typically)
.Dq Li options KGDB .
.Pp
The output of
.Nm config
consists of a number of files, principally
.Pa ioconf.c ,
a description of I/O devices that may be attached to the system; and a
.Pa Makefile ,
used by
.Xr make 1
in building the kernel.
.Pp
After running
.Nm config ,
it is wise to run
.Dq Li make depend
in the directory where the new makefile
was created.
.Nm config
prints a reminder of this when it completes.
.Pp
If
.Nm config
stops due to errors, the problems reported should be corrected and
.Nm config
should be run again.
.Nm 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.
.Sh EXAMPLE
A custom kernel is built in the following way.
.Pp
To compile your own kernel from a non-writeable media (such as a CDROM)
mounted on
.Pa /usr/src ,
do the following:
.Sm off
.Bd -literal -offset indent
.Li #\  Xo
.Ic cd\ /
.Ar somedir
.Xc
.Li #\  Xo
.Ic cp\ /usr/src/sys/arch/
.Ar somearch
.Ic /conf/
.Ar SOMEFILE
.Ic \ .
.Xc
.Li #\  Xo
.Ic vi\ \&
.Ar SOMEFILE
.No \ \ \ (to\ make\ any\ changes)
.Xc
.Li #\  Xo
.Ic config\ -s\ /usr/src/sys\ -b\ .\ \&
.Ar SOMEFILE
.Xc
.Li #\  Xo
.Ic make
.Xc
.Ed
.Sm on
.Pp
To compile a kernel inside a writable source tree, do the following:
.Sm off
.Bd -literal -offset indent
.Li #\  Xo
.Ic cd\ /usr/src/sys/arch/
.Ar somearch
.Ic /conf
.Xc
.Li #\  Xo
.Ic vi\ \&
.Ar SOMEFILE
.No \ \ \ (to\ make\ any\ changes)
.Xc
.Li #\  Xo
.Ic config\ \&
.Ar SOMEFILE
.Xc
.Li #\  Xo
.Ic cd\ ../compile/
.Ar SOMEFILE
.Xc
.Li #\  Xo
.Ic make
.Xc
.Ed
.Sm on
.Pp
where
.Ar somedir
is a writable directory,
.Ar somearch
is the architecture (e.g.
.Ic i386 ) ,
and
.Ar SOMEFILE
should be a name indicative of a particular configuration (often
that of the hostname).
.Nm config
will warn you if a
.Ar "make clean"
is required; 
you can also do a
.Ic make depend
so that you will have dependencies there the next time you do a compile.
.Pp
After either of these two methods, you can place the new kernel (called
.Pa bsd )
in
.Pa /
(i.e.
.Pa /bsd )
and the system will boot it next time.
Most people save their backup kernels as
.Pa /bsd.1 ,
.Pa /bsd.2 ,
etc.
.Sh MODIFYING KERNEL
.Nm config
.Fl e
has the same functionalty as
.Xr boot_config 8
, to modify the device configuration of a kernel. One problem with
.Xr boot_config 8
has been that modifications has to be done on every boot.
.Nm config
.Fl e
makes it possible to do permanent changes to a kernel.
.Pp
The options are as follows:
.Bl -tag -width indent
.It Fl f
If
.Fl o Ar outfile
hasn't be given use
.Ar infile
as output file. 
.It Fl o Ar outfile
Save any changes to
.Ar outfile .
.It Fl u
If
.Ar infile
seems to be the same kernel as the current kernel, apply all changes done at
boot.
.El
.Pp
When invoked the kernel identification of the input file will be showed
.Pp
.Bd -literal 
.Li #\  Ic config Fl e o Ar 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>
.Ed
.Pp
Some warnings might be printed before the ukc prompt.
.Bd -literal
warning: not output file specified
.Ed
.Pp
Niether 
.Fl f
or
.Fl o
has been specifed. Changes will be ignored.
.Bd -literal
WARNING this kernel doesn't contain all information needed!
WARNING the commands add and change might not work.
.Ed
.Pp
The kernel is too old (pre
.Ox 2.6 )
and can't support all functionality of
.Ic config Fl e .
.Bd -literal
WARNING kernel mismatch. -u ignored.
WARNING the running kernel version:
.Ed
.Pp
.Nm config
doesn't think that the running kernel is the same as the file specified.
Since the log of changes in the running kernel is kernel specific the 
.Fl u
option is ignored.
.Sh COMMANDS
.Bl -tag -width "disable attr val | devno | dev" indent
.It Ic add Ar dev
Add a device through copying another.
.It Ic base Ar 8 | 10 | 16
Change the base of numbers displayed and entered,
e.g. I/O addresses in a VAXen are octal.
.It Ic change Ar devno | dev
Modify one or more devices.
.It Ic disable Ar attr val | devno | dev
Disable one or more devices.
.It Ic enable Ar attr val | devno | dev
Enable one or more devices.
.It Ic exit
Exit without saving changes.
.It Ic find Ar devno | dev
Find one or more devices.
.It Ic help
Give a short summary of all commands and their arguments.
.It Ic list
Show all known devices, a screen at a time.
.It Ic lines Op Ar count
Set the number of rows per page.
.It Ic quit
Exit and save changes.
.It Ic show Op Ar attr Op Ar val
Show all devices for which attribute
.Ar attr
has the value
.Ar val .
.El
.Sh MORE EXAMPLES
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
.Xr ne 4
driver.
.Pp
.Bd -literal
.No ukc> Ic find ne
24 ne0 at isa0 port 0x240 size 0 iomem 0xd8000 iosiz 0 irq 9 drq -1 drq2 -1
25 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1
26 ne* at isapnp0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1
27 ne* at pci* dev -1 function -1
28 ne* at pcmcia* function -1 irq -1
ukc>
.Ed
.Pp
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
.Fa change
command. The device can be specified by either name or number.
.Pp
.Bd -literal
.No ukc> Ic change ne1
25 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1
.No change (y/n) ? Ic y
.No port [0x300] ?
.No size [0] ?
.No iomem [-1] ?
.No iosiz [0] ?
.No irq [10] ? Ic 5
.No drq [-1] ?
.No drq2 [-1] ?
25 ne1 changed
25 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 5 drq -1 drq2 -1
ukc>
.Ed
.Pp
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.
.Pp
.Bd -literal
.No ukc> Ic find mcd0
 29 mcd0 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1
.No ukc> Ic disable mcd0
 29 mcd0 disabled
.No ukc> Ic find 29
 29 mcd0 at isa0 disable port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1
.Ed
.Pp
It's also possible to disable all devices with a common attribute. e.g.
.Pp
.Bd -literal
.No ukc> Ic disable port 0x300
 25 ne1 disabled
 29 mcd0 alredy disabled
 72 we1 disabled
 75 el0 disabled
 77 ie1 disabled
.Ed
.Pp
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.
.Bd -literal
.No ukc> Ic show slot
  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
.No ukc> Ic show port 0x300
 25 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1
 72 we1 at isa0 port 0x300 size 0 iomem 0xcc000 iosiz 0 irq 10 drq -1 drq2 -1
 75 el0 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 9 drq -1 drq2 -1
 77 ie1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1
ukc>
.Ed
.Pp
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.
.Pp
.Bd -literal
.No ukc> Ic find ep
 11 ep0 at isa0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 drq2 -1
 12 ep0 at eisa0 slot -1
 13 ep0 at pci* dev -1 function -1
 14 ep* at isapnp0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1
 15 ep* at isa0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 drq2 -1
 16 ep* at eisa0 slot -1
 17 ep* at pci* dev -1 function -1
 18 ep* at pcmcia* dev -1 irq -1
.No ukc> Ic add ep1
.No "Clone Device (DevNo, 'q' or '?') ?" Ic 13
.No "Insert before Device (DevNo, 'q' or '?')" Ic 14
 14 ep1 at pci* dev -1 function -1
.No ukc> Ic change 14
 14 ep1 at pci* dev -1 function -1
.No change (y/n) ? Ic y
.No dev [-1] ? Ic 14
.No function [-1] ?
 14 ep1 changed
 14 ep1 at pci* dev 14 function -1
ukc>
.Ed
.Pp
When done exit the program with the
.Ic quit
or
.Ic exit
commands.
.Ic exit
will ignore any changes while
.Ic quit
writes the changes in
.Ar outfile
(if
.Fl o
or
.Fl f
was given, else ignore changes).
.Pp
.Bd -literal
.No ukc> Ic quit
.Ed
.Pp
.Sh SEE ALSO
.Xr options 4
.Pp
The SYNOPSIS portion of each device in section 4.
.Rs
.%T "Building 4.4 BSD Systems with Config"
.\" .%T "Device Support in 4.4BSD"
.Re
.Pp
.Sh HISTORY
The
.Nm config
command appeared in
.Bx 4.1 .
It was completely revised in
.Bx 4.4 .
The
.Nm config Fl e
command appeared in
.Ox 2.6 .