Add my description for how to add a new-style kernel option, including
Bruce's comments.
This commit is contained in:
Joerg Wunsch
parent
7e24fc58bf
commit
1c57564d21
@ -1,4 +1,4 @@
|
||||
# $Id: Makefile,v 1.19 1996/11/28 18:09:24 jfieber Exp $
|
||||
# $Id: Makefile,v 1.20 1996/12/19 20:24:36 jkh Exp $
|
||||
|
||||
SRCS= authors.sgml basics.sgml bibliography.sgml boothelp.sgml
|
||||
SRCS+= booting.sgml contrib.sgml crypt.sgml ctm.sgml current.sgml cvsup.sgml
|
||||
@ -6,7 +6,7 @@ SRCS+= cyclades.sgml development.sgml dialup.sgml dialout.sgml
|
||||
SRCS+= diskless.sgml dma.sgml eresources.sgml esdi.sgml
|
||||
SRCS+= firewalls.sgml glossary.sgml goals.sgml
|
||||
SRCS+= handbook.sgml history.sgml hw.sgml install.sgml isdn.sgml
|
||||
SRCS+= kerberos.sgml kernelconfig.sgml kerneldebug.sgml
|
||||
SRCS+= kerberos.sgml kernelconfig.sgml kerneldebug.sgml kernelopts.sgml
|
||||
SRCS+= lists.sgml mail.sgml memoryuse.sgml
|
||||
SRCS+= mirrors.sgml nfs.sgml nutshell.sgml pgpkeys.sgml policies.sgml
|
||||
SRCS+= porting.sgml ports.sgml ppp.sgml printing.sgml
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
<!-- $Id: handbook.sgml,v 1.62 1996/12/11 11:41:35 asami Exp $ -->
|
||||
<!-- $Id: handbook.sgml,v 1.63 1996/12/11 14:14:28 jfieber Exp $ -->
|
||||
<!-- The FreeBSD Documentation Project -->
|
||||
|
||||
<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN" [
|
||||
@ -146,6 +146,7 @@ name="FreeBSD FTP server"> or one of the numerous
|
||||
&submitters;
|
||||
&troubleshooting;
|
||||
&kerneldebug;
|
||||
&kernelopts;
|
||||
&linuxemu;
|
||||
<chapt><heading>FreeBSD internals</heading>
|
||||
&booting;
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
<!-- $Id: kernelconfig.sgml,v 1.21 1996/10/05 18:36:17 wosch Exp $ -->
|
||||
<!-- $Id: kernelconfig.sgml,v 1.22 1996/12/16 22:33:35 mpp Exp $ -->
|
||||
<!-- The FreeBSD Documentation Project -->
|
||||
<!-- <!DOCTYPE linuxdoc PUBLIC '-//FreeBSD//DTD linuxdoc//EN'> -->
|
||||
<chapt><heading>Configuring the FreeBSD Kernel<label id="kernelconfig"></heading>
|
||||
@ -135,19 +135,19 @@
|
||||
|
||||
<sect><heading>The Configuration File<label id="kernelconfig:config"></heading>
|
||||
|
||||
<p>The general format of a configuration file is quite
|
||||
simple. Each line contains a keyword and one or more
|
||||
arguments. For simplicity, most lines only contain one
|
||||
argument. Anything following a <tt>#</tt> is considered
|
||||
a comment and ignored. The following sections describe
|
||||
each keyword, generally in the order they are listed in
|
||||
GENERIC, although some related keywords have been grouped
|
||||
together in a single section (such as Networking) even
|
||||
though they are actually scattered throughout the GENERIC
|
||||
file. An exhaustive list of options and more detailed explanations
|
||||
<p>The general format of a configuration file is quite simple.
|
||||
Each line contains a keyword and one or more arguments. For
|
||||
simplicity, most lines only contain one argument. Anything
|
||||
following a <tt>#</tt> is considered a comment and ignored.
|
||||
The following sections describe each keyword, generally in the
|
||||
order they are listed in GENERIC, although some related
|
||||
keywords have been grouped together in a single section (such
|
||||
as Networking) even though they are actually scattered
|
||||
throughout the GENERIC file. <label id="kernelconfig:options">
|
||||
An exhaustive list of options and more detailed explanations
|
||||
of the device lines is present in the LINT configuration file,
|
||||
located in the same directory as GENERIC. If you are in doubt as to
|
||||
the purpose or necessity of a line, check first in LINT.
|
||||
located in the same directory as GENERIC. If you are in doubt
|
||||
as to the purpose or necessity of a line, check first in LINT.
|
||||
|
||||
<p>The kernel is currently being moved to a better organization
|
||||
of the option handling. Traditionally, each option in the
|
||||
|
||||
149
share/doc/handbook/kernelopts.sgml
Normal file
149
share/doc/handbook/kernelopts.sgml
Normal file
@ -0,0 +1,149 @@
|
||||
<!-- $Id$ -->
|
||||
<!-- The FreeBSD Documentation Project -->
|
||||
<!-- <!DOCTYPE linuxdoc PUBLIC '-//FreeBSD//DTD linuxdoc//EN'> -->
|
||||
|
||||
<chapt><heading>Adding New Kernel Configuration Options<label id="kernelopts"></heading>
|
||||
|
||||
<p><em>Contributed by &a.joerg;</em>
|
||||
|
||||
<em/Note:/ You should be familiar with the section about <ref
|
||||
id="kernelconfig" name="kernel configuration"> before reading here.
|
||||
|
||||
<sect><heading>What's a <em>kernel option</em>, anyway?</heading>
|
||||
|
||||
<p>The use of kernel options is basically described in the <ref
|
||||
id="kernelconfig:options" name="kernel configuration"> section.
|
||||
There's also an explanation about ``historic'' and ``new-style''
|
||||
options. The ultimate goal is to eventually turn all the supported
|
||||
options in the kernel into new-style ones, so for people who
|
||||
correctly did a <tt/make depend/ in their kernel compile directory
|
||||
after running <tt/config(8)/, the build process will automatically
|
||||
pick up modified options, and only recompile those files where it is
|
||||
necessary. Wiping out the old compile directory on each run of
|
||||
<tt/config(8)/ as it's still done now can then be eliminated again.
|
||||
|
||||
<p>Basically, a kernel option is nothing else than the definition of
|
||||
a C preprocessor macro for the kernel compilation process. To make
|
||||
the build truly optional, the corresponding part of the kernel
|
||||
source (or kernel <tt/.h/ file) must be written with the option
|
||||
concept in mind, i. e. the default must have been made overridable
|
||||
by the config option. This is usually done with something like:
|
||||
|
||||
<verb>
|
||||
#ifndef THIS_OPTION
|
||||
#define THIS_OPTION (some_default_value)
|
||||
#endif /* THIS_OPTION */
|
||||
</verb>
|
||||
<p>This way, an administrator mentioning another value for the
|
||||
option in his config file will take the default out of effect, and
|
||||
replace it with his new value. Apparently, the new value will be
|
||||
substituted into the source code during the preprocessor run, so it
|
||||
must be a valid C expression in whatever context the default value
|
||||
would have been used.
|
||||
|
||||
<p>It's also possible to create value-less options that simply
|
||||
enable or disable a particular piece of code by embracing it in
|
||||
|
||||
<verb>
|
||||
#ifdef THAT_OPTION
|
||||
|
||||
...
|
||||
|
||||
#endif
|
||||
</verb>
|
||||
<p>Simply mentioning <tt/THAT_OPTION/ in the config file (with or
|
||||
without any value) will then turn on the corresponding piece of
|
||||
code.
|
||||
|
||||
<p>People familiar with the C language will immediately recognize
|
||||
that everything could be counted as a ``config option'' where
|
||||
there's at least a single <tt/#ifdef/ referencing it... Now only
|
||||
few people probably would try to say
|
||||
|
||||
<verb>
|
||||
options notyet,notdef
|
||||
</verb>
|
||||
<p>in their config file however, and watch the kernel compilation
|
||||
fall over. :-)
|
||||
|
||||
<p>Apparently, using arbitrary names for the options makes it very
|
||||
hard to track their usage throughout the kernel source tree. That's
|
||||
the rationale behind the <em/new-style/ option scheme, where each
|
||||
option goes into a separate <tt/.h/ file in the kernel compile
|
||||
directory, which is by convention named <tt>opt_<em>foo</em>.h</tt>.
|
||||
This way, the usual Makefile dependencies could be applied, and
|
||||
<tt/make/ can determine what needs to be recompiled once an option
|
||||
has been changed.
|
||||
|
||||
<p>The old-style option mechanism still has one advantage for local
|
||||
options or maybe experimental options that have a short anticipated
|
||||
lifetime: since it's easy to add a new <tt/#ifdef/ to the kernel
|
||||
source, this already made it a kernel config option, so that's
|
||||
already all about it. In this case, the administrator using such an
|
||||
option is responsible himself for knowing about its implications
|
||||
(and maybe manually forcing the recompilation of parts of his
|
||||
kernel). Once the transition of all supported options has been
|
||||
done, <tt/config(8)/ will warn whenever an unsupported option
|
||||
appears in the config file, but it will nevertheless include it into
|
||||
the kernel Makefile.
|
||||
|
||||
|
||||
<sect><heading>Now what do I have to do for it?</heading>
|
||||
|
||||
<p>First, edit <tt>sys/conf/options</tt> (or
|
||||
<tt>sys/i386/conf/options.<em><arch></em></tt>, e. g.
|
||||
<tt>sys/i386/conf/options.i386</tt>), and select an
|
||||
<tt>opt_<em>foo</em>.h</tt> file where your new option would best go
|
||||
into.
|
||||
|
||||
<p>If there's already something that comes close to the purpose of
|
||||
the new option, pick this. For example, options modifying the
|
||||
overall behaviour of the SCSI subsystem can go into <tt/opt_scsi.h/.
|
||||
By default, simply mentioning an option in the appropriate option
|
||||
file, say <tt/FOO/, implies its value will go into the
|
||||
corresponding file <tt/opt_foo.h/. This can be overridden on the
|
||||
right-hand side of a rule by specifying another filename.
|
||||
|
||||
<p>If there's no <tt>opt_<em>foo</em>.h</tt> already available for
|
||||
the intended new option, invent a new name. Make it meaningful, and
|
||||
comment the new section in the
|
||||
<tt>options[<em>.<arch></em>]</tt> file. <tt/config(8)/ will
|
||||
automagically pick up the change, and create that file next time it
|
||||
is run. Most options should go in a header file by themself.
|
||||
|
||||
<p>Packing too many options into a single
|
||||
<tt>opt_<em>foo</em>.h</tt> will cause too many kernel files to be
|
||||
rebuilt when one of the options has been changed in the config file.
|
||||
|
||||
<p>Finally, find out which kernel files depend on the new option.
|
||||
Unless you've just invented your option, so it doesn't exist
|
||||
anywhere yet,
|
||||
|
||||
<verb>
|
||||
find /usr/src/sys -name type f | xargs fgrep NEW_OPTION
|
||||
</verb>
|
||||
<p>is your friend in finding them. Go and edit all those files, and
|
||||
add
|
||||
|
||||
<verb>
|
||||
#include "opt_foo.h"
|
||||
</verb>
|
||||
<p><em>on top</em>, before all the <tt/#include <xxx.h>/
|
||||
stuff. The sequence is most important in case the options will
|
||||
override some defaults from the regular include files, where the
|
||||
defaults are protected by
|
||||
|
||||
<verb>
|
||||
#ifndef NEW_OPTION
|
||||
#define NEW_OPTION (something)
|
||||
#endif
|
||||
</verb>
|
||||
<p>in the regular header.
|
||||
|
||||
<p>Adding an option that overrides something in a system header file
|
||||
(i. e., a file sitting in <tt>/usr/include/sys/</tt>) is almost
|
||||
always a mistake. <tt>opt_<em>foo</em>.h</tt> cannot be included
|
||||
into those files since it would break the headers more seriously,
|
||||
but if it isn't included, then places that include it may get an
|
||||
inconsistent value for the option. Yes, there are precedents for
|
||||
this right now, but that doesn't make them more correct.
|
||||
@ -1,4 +1,4 @@
|
||||
<!-- $Id: sections.sgml,v 1.18 1996/11/28 18:09:29 jfieber Exp $ -->
|
||||
<!-- $Id: sections.sgml,v 1.19 1996/12/19 20:24:36 jkh Exp $ -->
|
||||
<!-- The FreeBSD Documentation Project -->
|
||||
|
||||
<!-- Entities containing all the pieces of the handbook are -->
|
||||
@ -31,6 +31,7 @@
|
||||
<!ENTITY kerberos SYSTEM "kerberos.sgml">
|
||||
<!ENTITY kernelconfig SYSTEM "kernelconfig.sgml">
|
||||
<!ENTITY kerneldebug SYSTEM "kerneldebug.sgml">
|
||||
<!ENTITY kernelopts SYSTEM "kernelopts.sgml">
|
||||
<!ENTITY linuxemu SYSTEM "linuxemu.sgml">
|
||||
<!ENTITY mail SYSTEM "mail.sgml">
|
||||
<!ENTITY memoryuse SYSTEM "memoryuse.sgml">
|
||||
|
||||
Loading…
Reference in New Issue
Block a user