diff options
| -rw-r--r-- | usr.sbin/config/config.8 | 460 |
1 files changed, 226 insertions, 234 deletions
diff --git a/usr.sbin/config/config.8 b/usr.sbin/config/config.8 index d4b4d26bfe2..982db0e97ce 100644 --- a/usr.sbin/config/config.8 +++ b/usr.sbin/config/config.8 @@ -1,4 +1,4 @@ -.\" $OpenBSD: config.8,v 1.11 1999/10/12 00:25:30 maja Exp $ +.\" $OpenBSD: config.8,v 1.12 1999/10/16 04:48:22 aaron Exp $ .\" $NetBSD: config.8,v 1.10 1996/08/31 20:58:16 mycroft Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -34,155 +34,247 @@ .\" .\" from: @(#)config.8 8.2 (Berkeley) 4/19/94 .\" -.Dd April 19, 1994 +.Dd October 15, 1999 .Dt CONFIG 8 .Os .Sh NAME .Nm config -.Nd build kernel compilation directories or modify a kernel +.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 +.Ar config-file .Nm config -.Fl e -.Op Fl f | o Ar outfile +.Op Fl e +.Op Fl f | Fl 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 +In the first synopsis form, the +.Nm +program creates a kernel build directory from the kernel configuration file +specified by .Ar config-file . -.Nm config -will assume that the top-level kernel source directory is located four -directories above the build directory. +In the second synopsis form, +.Nm +allows editing of the kernel binary specified by +.Ar infile . +Devices may be enabled, disabled, or modified without recompiling (see +.Xr boot_config 8 ) . +.Pp +.Nm +is most commonly invoked from the directory containing +.Ox +kernel configuration files (i.e., +.Pa /sys/arch/i386/conf +for i386 machines). +For instance, the following steps would be followed to configure and compile +a new GENERIC kernel (assuming a complete kernel source tree is available in +.Pa /sys ) : +.Bd -literal -offset indent +# cd /sys/arch/i386/conf +# config ./GENERIC +# cd ../compile/GENERIC +# make depend && make +.Ed .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 +Replace +.Dq i386 +with the appropriate architecture name. +.Pp +The options are as follows: +.Pp +.Bl -tag -width Ds +.It Fl e +Allows the modification of kernel device configuration (see +.Xr 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 +.Sx Kernel modification +below for more details. +.It Fl f +Overwrite the +.Ar infile +kernel binary with the modified kernel. Otherwise, +.Fl o +should be given to specify an alternate output file. +.It Fl o Ar outfile +Write the modified kernel to +.Ar outfile . +.It Fl u +Check to see if the kernel configuration was modified at boot-time +(i.e., +.Cm boot -c +was used). +If so, compare the running kernel with the kernel to be edited +.Pq Ar infile . +If they seem to be the same, apply all configuration changes performed at +boot. +.It Fl b Ar builddir +Create the build directory in the path specified by +.Ar builddir +instead of the default +.Pa ../compile/SYSTEMNAME . +.It Fl s Ar srcdir +Use +.Ar srcdir +as the top-level kernel source directory instead of the default (four +directories above the build directory). +.It Fl p +Configure for a system that includes profiling code; see .Xr kgmon 8 and .Xr gprof 1 . +When this option is specified, +.Nm +acts as if the lines +.Dq makeoptions PROF="-pg" +and +.Dq options GPROF +appeared in the specified kernel configuration file. +In addition, +.Dq .PROF +is appended to the default compliation directory name. +.Pp 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 +profiles of existing systems; for regular profiling, it is probably wiser to +make a separate configuration containing the makeoptions line. +.El +.Pp +The old .Fl g -flag is no longer supported. -Instead, use -.Dq Li makeoptions DEBUG="-g" -and (typically) -.Dq Li options KGDB . +flag is deprecated and no longer supported. +Instead, add +.Dq makeoptions DEBUG="-g" +to the kernel configuration file, along with (typically) +.Dq options KGDB . .Pp The output of -.Nm config +.Nm 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 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. +when building the kernel. .Pp After running -.Nm config , +.Nm it is wise to run -.Dq Li make depend -in the directory where the new makefile -was created. -.Nm config +.Dq make depend +in the new build directory. +.Nm prints a reminder of this when it completes. .Pp If -.Nm config +.Nm stops due to errors, the problems reported should be corrected and -.Nm config +.Nm 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 +.Nm +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. +.Ss Kernel modification +When +.Fl 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. +.Pp +When invoked, the kernel identification is first shown. +.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 +One or more warnings may be printed before the +.Li ukc> +prompt. +.Bd -literal -offset indent +warning: no output file specified +.Ed +.Pp +Neither the +.Fl f +nor +.Fl o +option has been specified. +Changes will be ignored. +.Pp +.Bd -literal -offset indent +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 cannot support all of the functionality needed by the +.Fl e +option. +.Pp +.Bd -literal -offset indent +WARNING kernel mismatch. -u ignored. +WARNING the running kernel version: +.Ed +.Pp +.Nm +does not believe the running kernel is the same as the +.Ar infile +specified. +Since the log of changes (from +.Cm boot -c ) +in the running kernel is kernel-specific, the +.Fl u +option is ignored. +.Pp +The commands are as follows: +.Pp +.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 EXAMPLES (First synopsis) A custom kernel is built in the following way. .Pp To compile your own kernel from a non-writeable media (such as a CDROM) @@ -248,7 +340,7 @@ where .Ar somedir is a writable directory, .Ar somearch -is the architecture (e.g. +is the architecture (e.g., .Ic i386 ) , and .Ar SOMEFILE @@ -273,111 +365,11 @@ 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 +.Sh EXAMPLES (Second synopsis) +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 +e.g., wrong IRQ in OpenBSD/i386. +The Ethernet card is supposed to use the .Xr ne 4 driver. .Pp @@ -393,7 +385,7 @@ ukc> .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 +.Ic change command. The device can be specified by either name or number. .Pp .Bd -literal @@ -438,7 +430,9 @@ It's also possible to disable all devices with a common attribute. e.g. 77 ie1 disabled .Ed .Pp -The show command is useful for finding which devices have a certain attribute. +The +.Cm 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 @@ -484,7 +478,7 @@ kernel. If a new device is added, following devices will be renumbered. ukc> .Ed .Pp -When done exit the program with the +When done, exit the program with the .Ic quit or .Ic exit @@ -492,7 +486,7 @@ commands. .Ic exit will ignore any changes while .Ic quit -writes the changes in +writes the changes to .Ar outfile (if .Fl o @@ -503,24 +497,22 @@ was given, else ignore changes). .Bd -literal .No ukc> Ic quit .Ed -.Pp .Sh SEE ALSO -.Xr options 4 +.Xr options 4 , +.Xr boot_config 8 +.Pp +The SYNOPSIS portion of each device in section 4 of the manual. .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 . +.Nm +program appeared in 4.1BSD. +It was completely revised in 4.4BSD. The -.Nm config Fl e -command appeared in +.Fl e +option appeared in .Ox 2.6 . + |