share/doc/handbook/kernelopts.sgml

   1 <!-- $Id$ -->
   2 <!-- The FreeBSD Documentation Project -->
   3 <!-- <!DOCTYPE linuxdoc PUBLIC '-//FreeBSD//DTD linuxdoc//EN'> -->
   4
   5 <chapt><heading>Adding New Kernel Configuration Options<label id="kernelopts"></heading>
   6
   7 <p><em>Contributed by &a.joerg;</em>
   8
   9 <em/Note:/ You should be familiar with the section about <ref
  10 id="kernelconfig" name="kernel configuration"> before reading here.
  11
  12 <sect><heading>What's a <em>kernel option</em>, anyway?</heading>
  13
  14   <p>The use of kernel options is basically described in the <ref
  15   id="kernelconfig:options" name="kernel configuration"> section.
  16   There's also an explanation about ``historic'' and ``new-style''
  17   options.  The ultimate goal is to eventually turn all the supported
  18   options in the kernel into new-style ones, so for people who
  19   correctly did a <tt/make depend/ in their kernel compile directory
  20   after running <tt/config(8)/, the build process will automatically
  21   pick up modified options, and only recompile those files where it is
  22   necessary.  Wiping out the old compile directory on each run of
  23   <tt/config(8)/ as it is still done now can then be eliminated again.
  24
  25   <p>Basically, a kernel option is nothing else than the definition of
  26   a C preprocessor macro for the kernel compilation process.  To make
  27   the build truly optional, the corresponding part of the kernel
  28   source (or kernel <tt/.h/ file) must be written with the option
  29   concept in mind, i. e. the default must have been made overridable
  30   by the config option.  This is usually done with something like:
  31
  32 <verb>
  33 #ifndef THIS_OPTION
  34 #define THIS_OPTION (some_default_value)
  35 #endif /* THIS_OPTION */
  36 </verb>
  37   <p>This way, an administrator mentioning another value for the
  38   option in his config file will take the default out of effect, and
  39   replace it with his new value.  Apparently, the new value will be
  40   substituted into the source code during the preprocessor run, so it
  41   must be a valid C expression in whatever context the default value
  42   would have been used.
  43
  44   <p>It is also possible to create value-less options that simply
  45   enable or disable a particular piece of code by embracing it in
  46
  47 <verb>
  48 #ifdef THAT_OPTION
  49
  50 [your code here]
  51
  52 #endif
  53 </verb>
  54   <p>Simply mentioning <tt/THAT_OPTION/ in the config file (with or
  55   without any value) will then turn on the corresponding piece of
  56   code.
  57
  58   <p>People familiar with the C language will immediately recognize
  59   that everything could be counted as a ``config option'' where
  60   there is at least a single <tt/#ifdef/ referencing it...  Now only
  61   few people probably would try to say
  62
  63 <verb>
  64         options         notyet,notdef
  65 </verb>
  66   <p>in their config file however, and watch the kernel compilation
  67   fall over. :-)
  68
  69   <p>Apparently, using arbitrary names for the options makes it very
  70   hard to track their usage throughout the kernel source tree.  That is
  71   the rationale behind the <em/new-style/ option scheme, where each
  72   option goes into a separate <tt/.h/ file in the kernel compile
  73   directory, which is by convention named <tt>opt_<em>foo</em>.h</tt>.
  74   This way, the usual Makefile dependencies could be applied, and
  75   <tt/make/ can determine what needs to be recompiled once an option
  76   has been changed.
  77
  78   <p>The old-style option mechanism still has one advantage for local
  79   options or maybe experimental options that have a short anticipated
  80   lifetime: since it is easy to add a new <tt/#ifdef/ to the kernel
  81   source, this has already made it a kernel config option.
  82   In this case, the administrator using such an
  83   option is responsible himself for knowing about its implications
  84   (and maybe manually forcing the recompilation of parts of his
  85   kernel).  Once the transition of all supported options has been
  86   done, <tt/config(8)/ will warn whenever an unsupported option
  87   appears in the config file, but it will nevertheless include it into
  88   the kernel Makefile.
  89
  90
  91 <sect><heading>Now what do I have to do for it?</heading>
  92
  93   <p>First, edit <tt>sys/conf/options</tt> (or
  94   <tt>sys/i386/conf/options.<em>&lt;arch&gt;</em></tt>, e. g.
  95   <tt>sys/i386/conf/options.i386</tt>), and select an
  96   <tt>opt_<em>foo</em>.h</tt> file where your new option would best go
  97   into.
  98
  99   <p>If there is already something that comes close to the purpose of
 100   the new option, pick this.  For example, options modifying the
 101   overall behaviour of the SCSI subsystem can go into <tt/opt_scsi.h/.
 102   By default, simply mentioning an option in the appropriate option
 103   file, say <tt/FOO/, implies its value will go into the
 104   corresponding file <tt/opt_foo.h/.  This can be overridden on the
 105   right-hand side of a rule by specifying another filename.
 106
 107   <p>If there is no <tt>opt_<em>foo</em>.h</tt> already available for
 108   the intended new option, invent a new name.  Make it meaningful, and
 109   comment the new section in the
 110   <tt>options[<em>.&lt;arch&gt;</em>]</tt> file.  <tt/config(8)/ will
 111   automagically pick up the change, and create that file next time it
 112   is run.  Most options should go in a header file by themselves..
 113
 114   <p>Packing too many options into a single
 115   <tt>opt_<em>foo</em>.h</tt> will cause too many kernel files to be
 116   rebuilt when one of the options has been changed in the config file.
 117
 118   <p>Finally, find out which kernel files depend on the new option.
 119   Unless you have just invented your option, and it does not exist
 120   anywhere yet,
 121
 122 <verb>
 123         find /usr/src/sys -name type f | xargs fgrep NEW_OPTION
 124 </verb>
 125   <p>is your friend in finding them.  Go and edit all those files, and
 126   add
 127
 128 <verb>
 129 #include "opt_foo.h"
 130 </verb>
 131   <p><em>on top</em>, before all the <tt/#include &lt;xxx.h&gt;/
 132   stuff.  The sequence is most important in case the options will
 133   override some defaults from the regular include files, where the
 134   defaults are protected by
 135
 136 <verb>
 137 #ifndef NEW_OPTION
 138 #define NEW_OPTION (something)
 139 #endif
 140 </verb>
 141   <p>in the regular header.
 142
 143   <p>Adding an option that overrides something in a system header file
 144   (i. e., a file sitting in <tt>/usr/include/sys/</tt>) is almost
 145   always a mistake.  <tt>opt_<em>foo</em>.h</tt> cannot be included
 146   into those files since it would break the headers more seriously,
 147   but if it is not included, then places that include it may get an
 148   inconsistent value for the option.  Yes, there are precedents for
 149   this right now, but that does not make them more correct.