<!-- $Id: kernelconfig.sgml,v 1.1.2.3 1996-06-19 20:27:58 jkh Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!-- <!DOCTYPE linuxdoc PUBLIC '-//FreeBSD//DTD linuxdoc//EN'> -->
<chapt><heading>Configuring the FreeBSD Kernel<label id="kernelconfig"></heading>
<p><em>Contributed by &a.jehamby;.<newline>6 October 1995.</em>
This large section of the handbook discusses the basics of
building your own custom kernel for FreeBSD. This section
is appropriate for both novice system administrators and
those with advanced Unix experience.
<sect><heading>Why build a custom kernel?</heading>
<p>Building a custom kernel is one of the most important
rites of passage every Unix system administrator must
learn. This process, while time-consuming, will provide
many benefits to your FreeBSD system. Unlike the GENERIC
kernel, which must support every possible SCSI and
network card, along with tons of other rarely used
hardware support, a custom kernel only contains support
for <em>your</em> PC's hardware. This has a number of
benefits:
<itemize>
<item>It will take less time to boot because it does not
have to spend time probing for hardware which you
do not have.
<item>A custom kernel often uses less memory, which is
important because the kernel is the one process which
must always be present in memory, and so all of that
unused code ties up pages of RAM that your programs
would otherwise be able to use. Therefore, on a
system with limited RAM, building a custom kernel is
of critical importance.
<item>Finally, there are several kernel options which
you can tune to fit your needs, and device driver
support for things like sound cards which you can
include in your kernel but are <em>not</em> present
in the GENERIC kernel.
</itemize></p>
<sect><heading>Building and Installing a Custom Kernel<label id="kernelconfig:building"></heading>
<p>First, let us take a quick tour of the kernel build
directory. All directories mentioned will be relative to
the main <tt>/usr/src/sys</tt> directory, which is also
accessible through <tt>/sys</tt>. There are a number of
subdirectories here representing different parts of the
kernel, but the most important, for our purposes, are
<tt>i386/conf</tt>, where you will edit your custom
kernel configuration, and <tt>compile</tt>, which is the
staging area where your kernel will be built. Notice the
logical organization of the directory tree, with each
supported device, filesystem, and option in its own
subdirectory. Also, anything inside the <tt>i386</tt>
directory deals with PC hardware only, while everything
outside the <tt>i386</tt> directory is common to all
platforms which FreeBSD could potentially be ported to.
<quote><em/Note:/ If there is <em>not</em> a
<tt>/usr/src/sys</tt> directory on your system, then the
kernel source has not been been installed. Follow the
instructions for installing packages to add this package
to your system.</quote>
Next, move to the <tt>i386/conf</tt> directory and copy
the GENERIC configuration file to the name you want to
give your kernel. For example:
<tscreen><verb>
# cd /usr/src/sys/i386/conf
# cp GENERIC MYKERNEL
</verb></tscreen>
Traditionally, this name is in all capital letters and,
if you are maintaining multiple FreeBSD machines with
different hardware, it is a good idea to name it after
your machine's hostname. We will call it MYKERNEL for
the purpose of this example.
<quote><em/Note:/ You must execute these and all of the
following commands under the root account or you will get
``permission denied'' errors.</quote>
Now, edit MYKERNEL with your favorite text editor. If
you're just starting out, the only editor available will
probably be <tt>vi</tt>, which is too complex to explain
here, but is covered well in many books in the <ref
id="bibliography" name="bibliography">. Feel free to change the
comment lines at the top to reflect your configuration or the
changes you have made to differentiate it from GENERIC.
If you have build a kernel under SunOS or some other BSD
operating system, much of this file will be very familiar
to you. If you are coming from some other operating
system such as DOS, on the other hand, the GENERIC
configuration file might seem overwhelming to you, so
follow the descriptions in the <ref
id="kernelconfig:config" name="Configuration File">
section slowly and carefully.
<quote><em/Note:/ If you are trying to upgrade your kernel from an
older version of FreeBSD, you will probably have to get a new
version of <tt>config(8)</tt> from the same place you got the new
kernel sources. It is located in <tt>/usr/src/usr.sbin</tt>, so
you will need to download those sources as well. Re-build and install
it before running the next commands.</quote>
When you are finished, type the following to compile and
install your kernel:
<tscreen><verb>
# /usr/sbin/config MYKERNEL
# cd ../../compile/MYKERNEL
# make depend
# make
# make install
</verb></tscreen>
The new kernel will be copied to the root directory as
<tt>/kernel</tt> and the old kernel will be moved to
<tt>/kernel.old</tt>. Now, shutdown the system and
reboot to use your kernel. In case something goes wrong,
there are some <ref id="kernelconfig:trouble" name=
"troubleshooting"> instructions at the end of this
document. Be sure to read the section which explains how
to recover in case your new kernel <ref
id="kernelconfig:noboot" name="does not boot">.
<quote><em/Note:/ If you have added any new devices (such
as sound cards) you may have to add some <ref
id="kernelconfig:nodes" name="device nodes"> to your
<tt>/dev</tt> directory before you can use them.</quote>
<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
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.
<p>The kernel is currently being moved to a better organization
of the option handling. Traditionally, each option in the
config file was simply converted into a <tt>-D</tt> switch
for the <tt>CFLAGS</tt> line of the kernel Makefile. Naturally,
this caused a creaping optionism, with nobody really knowing
which option has been referenced in what files.
<p>In the new scheme, every <tt>#ifdef</tt> that is intended to
be dependant upon an option gets this option out of an
<tt>opt_<em>foo</em>.h</tt> declaration file created in the
compile directory by <tt>config</tt>. The list of valid options
for <tt>config</tt> lives in two files: options that do nott
depend on the architecture are listed in
<tt>/sys/conf/options</tt>, architecture-dependant ones
in <tt>/sys/<em>arch</em>/conf/options.<em>arch</em></tt>,
with <em>arch</em> being for example <tt>i386</tt>.
<sect1><heading>Mandatory Keywords</heading>
<p>These keywords are required in every kernel you build.
<descrip>
<tag>machine ``i386''</tag>
<p>The first keyword is <tt>machine</tt>, which,
since FreeBSD only runs on Intel 386 and compatible
chips, is i386.
<quote><em>Note:</em> that any keyword which
contains numbers used as text must be enclosed in
quotation marks, otherwise <tt>config</tt> gets
confused and thinks you mean the actual number
386.</quote>
<tag>cpu ``<em>cpu_type</em>''</tag>
<p>The next keyword is <tt>cpu</tt>, which includes
support for each CPU supported by FreeBSD. The
possible values of <tt><em>cpu_type</em></tt>
include:
<itemize>
<item>I386_CPU
<item>I486_CPU
<item>I586_CPU
</itemize>
and multiple instances of the <tt>cpu</tt> line may
be present with different values of
<tt><em>cpu_type</em></tt> as are present in the
GENERIC kernel. For a custom kernel, it is best to
specify only the cpu you have. If, for example,
you have an Intel Pentium, use <tt>I586_CPU</tt>
for <tt><em>cpu_type</em></tt>.
<tag>ident <em>machine_name</em></tag>
<p>Next, we have <tt>ident</tt>, which is the
identification of the kernel. You should change
this from GENERIC to whatever you named your
kernel, in this example, MYKERNEL. The value you
put in <tt>ident</tt> will print when you boot up
the kernel, so it is useful to give a kernel a
different name if you want to keep it separate from
your usual kernel (if you want to build an
experimental kernel, for example). Note that, as
with <tt>machine</tt> and <tt> cpu</tt>, enclose
your kernel's name in quotation marks if it
contains any numbers.
Since this name is passed to the C compiler as a
<tt>-D</tt> switch, do not use names like <tt>
DEBUG</tt>, or something that could be confused
with another machine or CPU name, like <tt>vax</tt>.
<tag>maxusers <em>number</em></tag>
<p>This file sets the size of a number of important
system tables. This number is supposed to be
roughly equal to the number of simultaneous users
you expect to have on your machine. However, under
normal circumstances, you will want to set
<tt>maxusers</tt> to at least four, especially if
you are using X Windows or compiling software. The
reason is that the most important table set by
<tt>maxusers</tt> is the maximum number of
processes, which is set to <bf><tt>20 + 16 *
maxusers</tt></bf>, so if you set <tt>maxusers</tt>
to one, then you can only have 36 simultaneous
processes, including the 18 or so that the system
starts up at boot time, and the 15 or so you will
probably create when you start X Windows. Even a
simple task like reading a <tt>man</tt> page will
start up nine processes to filter, decompress, and
view it. Setting <tt>maxusers</tt> to 4 will allow
you to have up to 84 simultaneous processes, which
should be enough for anyone. If, however, you see
the dreaded ``proc table full'' error when trying
to start another program, or are running a server
with a large number of simultaneous users (like
Walnut Creek CDROM's FTP site), you can always
increase this number and rebuild.
<quote><em/Note:/ <tt>maxuser</tt> does
<em>not</em> limit the number of users which can
log into your machine. It simply sets various
table sizes to reasonable values considering the
maximum number of users you will likely have on
your system and how many processes each of them
will be running. One keyword which
<em>does</em> limit the number of simultaneous
<em>remote logins</em> is <ref
id="kernelconfig:ptys" name="pseudo-device pty
16">.</quote>
<tag>config <em>kernel_name</em> root on <em>root_device</em></tag>
<p>This line specifies the location and name of the
kernel. Traditionally the kernel is called
<tt>vmunix</tt> but in FreeBSD, it is aptly named
<tt>kernel</tt>. You should always use
<tt>kernel</tt> for <em>kernel_name</em> because
changing it will render numerous system utilities
inoperative. The second part of the line specifies
the disk and partition where the root filesystem
and kernel can be found. Typically this will be
<tt>wd0</tt> for systems with non-SCSI drives, or
<tt>sd0</tt> for systems with SCSI drives.
</descrip>
<sect1><heading>General Options</heading>
<p>These lines provide kernel support for various
filesystems and other options.
<descrip>
<label id="kernelconfig:mathemu">
<tag>options MATH_EMULATE</tag>
<p>This line allows the kernel to simulate a math
co-processor if your computer does not have one (386
or 486SX). If you have a Pentium, a 486DX, or a
386 or 486SX with a separate 387 or 487 chip, you
can comment this line out.
<quote><em>Note:</em> The normal math co-processor
emulation routines that come with FreeBSD are
<em>not</em> very accurate. If you do not have a
math co-processor, and you need the best accuracy,
I recommend that you change this option to
<tt>GPL_MATH_EMULATE</tt> to use the superior GNU
math support, which is not included by default
for licensing reasons.</quote>
<tag>options ``COMPAT_43''</tag>
<p>Compatibility with BSD 4.3. Leave this in; some
programs will act strangely if you comment this
out.
<tag>options BOUNCE_BUFFERS</tag>
<p>ISA devices and EISA devices operating in an ISA
compatibility mode can only perform DMA (Direct
Memory Access) to memory below 16 megabytes. This
option enables such devices to work in systems with
more than 16 megabytes of memory.
<tag>options UCONSOLE</tag>
<p>Allow users to grab the console, useful for X
Windows. For example, you can create a console
xterm by typing <tt>xterm -C</tt>, which will
display any `write', `talk', and other messages you
receive, as well as any console messages sent by the
kernel.
<tag>options SYSVSHM</tag>
<p>This option
provides for System V shared memory. The most
common use of this is the XSHM extension in X
Windows, which many graphics-intensive programs
(such as the movie player XAnim, and Linux DOOM)
will automatically take advantage of for extra
speed. If you use X Windows, you will definitely
want to include this.
<tag>options SYSVSEM</tag>
<p>Support for System V
semaphores. Less commonly used but only adds a few
hundred bytes to the kernel.
<tag>options SYSVMSG</tag>
<p>Support for System V
messages. Again, only adds a few hundred bytes to
the kernel.
<quote><em/Note:/ The <tt>ipcs(1)</tt> command will
tell will list any processes using using each of
these System V facilities.</quote>
</descrip>
<sect1><heading>Filesystem Options</heading>
<p>These options add support for various filesystems.
You must include at least one of these to support the
device you boot from; typically this will be
<tt>FFS</tt> if you boot from a hard drive, or
<tt>NFS</tt> if you are booting a diskless workstation
from Ethernet. You can include other commonly-used
filesystems in the kernel, but feel free to comment out
support for filesystems you use less often (perhaps the
MS-DOS filesystem?), since they will be dynamically
loaded from the Loadable Kernel Module directory
<tt>/lkm</tt> the first time you mount a partition of
that type.
<descrip>
<tag>options FFS</tag>
<p>The basic hard drive
filesystem; leave it in if you boot from the hard
disk.
<tag>options NFS</tag>
<p>Network Filesystem. Unless
you plan to mount partitions from a Unix file
server over Ethernet, you can comment this out.
<tag>options MSDOSFS</tag>
<p>MS-DOS Filesystem. Unless
you plan to mount a DOS formatted hard drive
partition at boot time, you can safely comment this
out. It will be automatically loaded the first
time you mount a DOS partition, as described above.
Also, the excellent <tt>mtools</tt> software (in
the ports collection) allows you to access DOS
floppies without having to mount and unmount them
(and does not require MSDOSFS at all).
<tag>options ``CD9660''</tag>
<p>ISO 9660 filesystem for
CD-ROMs. Comment it out if you do not have a
CD-ROM drive or only mount data CD's occasionally
(since it will be dynamically loaded the first time
you mount a data CD). Audio CD's do not need this
filesystem.
<tag>options PROCFS</tag>
<p>Process filesystem. This
is a pretend filesystem mounted on /proc which
allows programs like <tt>ps(1)</tt> to give you
more information on what processes are running.
<tag>options MFS</tag>
<p>Memory-mapped file system.
This is basically a RAM disk for fast storage of
temporary files, useful if you have a lot of swap
space that you want to take advantage of. A
perfect place to mount an MFS partition is on the
<tt>/tmp</tt> directory, since many programs store
temporary data here. To mount an MFS RAM disk on
<tt>/tmp</tt>, add the following line to
<tt>/etc/fstab</tt> and then reboot or type
<tt>mount /tmp</tt>:
<tscreen><verb>
/dev/wd1s2b /tmp mfs rw 0 0
</verb></tscreen>
<quote><em/Note:/ Replace the <tt>/dev/wd1s2b</tt>
with the name of your swap partition, which will
be listed in your <tt>/etc/fstab</tt> as follows:
<tscreen><verb>
/dev/wd1s2b none swap sw 0 0
</verb></tscreen>
</quote>
<quote><em/Note:/ <!-- MFS is currently a bit
limited (for example, I noticed that two programs
ca not access the <tt>/tmp</tt> device
simultaneously). As such, you may want to avoid
it for now. --> Also, the <tt>MFS</tt> filesystem
can <em>not</em> be dynamically loaded, so you
<em>must</em> compile it into your kernel if you
want to experiment with it.</quote>
<tag>options QUOTA</tag>
<p>Enable disk quotas. If you
have a public access system, and do not want users
to be able to overflow the <tt>/home</tt>
partition, you can establish disk quotas for each
user. This code is a little buggy, so do not
enable it unless you have to. View the manual page
for <tt>quota(1)</tt> to learn more about disk
quotas.
</descrip>
<sect1><heading>Basic Controllers and Devices</heading>
<p>These sections describe the basic disk, tape, and
CD-ROM controllers supported by FreeBSD. There are
separate sections for <ref id="kernelconfig:scsi"
name="SCSI"> controllers and <ref
id="kernelconfig:network" name="network"> cards.
<descrip>
<tag>controller isa0</tag>
<p>All PC's supported by
FreeBSD have one of these. If you have an IBM PS/2
(Micro Channel Architecture), then you cannot run
FreeBSD at this time.
<tag>controller pci0</tag>
<p>Include this if you have a
PCI motherboard. This enables auto-detection of
PCI cards and gatewaying from the PCI to the ISA
bus.
<tag>controller fdc0</tag>
<p>Floppy drive controller:
<tt>fd0</tt> is the ``A:'' floppy drive, and
<tt>fd1</tt> is the ``B:'' drive. <tt>ft0</tt> is
a QIC-80 tape drive attached to the floppy
controller. Comment out any lines corresponding to
devices you do not have.
<quote><em/Note:/ QIC-80 tape support requires a
separate filter program called <tt>ft(8)</tt>, see
the manual page for details.</quote>
<tag>controller wdc0</tag>
<p>This is the primary IDE
controller. <tt>wd0</tt> and <tt>wd1</tt> are the
master and slave hard drive, respectively.
<tt>wdc1</tt> is a secondary IDE controller where
you might have a third or fourth hard drive, or an
IDE CD-ROM. Comment out the lines which do not
apply (if you have a SCSI hard drive, you will
probably want to comment out all six lines, for
example).
<tag>controller wcd0<label id="kernelconfig:atapi"></tag>
<p>This device
provides IDE CD-ROM support. Be sure to leave
<tt>wdc1</tt> uncommented if your CD-ROM is on
its own controller card. To use this, you must
also include the line <tt>options ATAPI</tt>.
<tag>device npx0 at isa? port ``IO_NPX'' irq 13 vector npxintr</tag>
<p><tt>npx0</tt> is the interface to the floating point math
unit in FreeBSD, either the hardware co-processor or the
software math emulator. It is <em/NOT/ optional.
<tag>device wt0 at isa? port 0x300 bio irq 5 drq 1 vector wtintr</tag>
<p>Wangtek and Archive
QIC-02/QIC-36 tape drive support
<tag>Proprietary CD-ROM support</tag>
<p>The following
drivers are for the so-called <em>proprietary</em>
CD-ROM drives. These drives have their own
controller card or might plug into a sound card
such as the SoundBlaster 16. They are <em>not</em>
IDE or SCSI. Most older single-speed and
double-speed CD-ROMs use these interfaces, while
newer quad-speeds are likely to be <ref
id="kernelconfig:atapi" name="IDE"> or <ref
id="kernelconfig:scsi" name="SCSI">.
<descrip>
<tag>device mcd0 at isa? port 0x300 bio irq 10 vector mcdintr</tag>
<p>Mitsumi CD-ROM (LU002,
LU005, FX001D).
<tag>device scd0 at isa? port 0x230 bio</tag>
<p>Sony CD-ROM (CDU31, CDU33A).
<tag>controller matcd0 at isa? port ? bio</tag>
<p>Matsushita/Panasonic CD-ROM (sold by Creative
Labs for SoundBlaster).
</descrip>
</descrip>
<sect1><heading>SCSI Device Support<label id="kernelconfig:scsi"></heading>
<p>This section describes the various SCSI controllers
and devices supported by FreeBSD.
<descrip>
<tag>SCSI Controllers</tag>
<p>The next ten or so lines include support for
different kinds of SCSI controllers. Comment out
all except for the one(s) you have:
<descrip>
<tag>controller bt0 at isa? port ``IO_BT0'' bio irq ? vector btintr</tag>
<p>Most Buslogic controllers
<tag>controller uha0 at isa? port ``IO_UHA0'' bio irq ? drq 5 vector uhaintr</tag>
<p>UltraStor 14F and 34F
<tag>controller ahc0</tag>
<p>Adaptec 274x/284x/294x
<tag>controller ahb0 at isa? bio irq ? vector ahbintr</tag>
<p>Adaptec 174x
<tag>controller aha0 at isa? port ``IO_AHA0'' bio irq ? drq 5 vector ahaintr</tag>
<p>Adaptec 154x
<tag>controller aic0 at isa? port 0x340 bio irq 11 vector aicintr
</tag>
<p>Adaptec 152x and sound cards using Adaptec AIC-6360 (slow!)
<tag>controller nca0 at isa? port 0x1f88 bio irq 10 vector ncaintr
</tag>
<p>ProAudioSpectrum cards using NCR 5380 or Trantor T130
<tag>controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr</tag>
<p>Seagate ST01/02 8 bit controller (slow!)
<tag>controller wds0 at isa? port 0x350 bio irq 15 drq 6 vector wdsintr</tag>
<p>Western Digital WD7000 controller
<tag>controller ncr0</tag>
<p>NCR 53C810 and 53C825 PCI SCSI controller
</descrip>
<tag>options ``SCSI_DELAY=15''</tag>
<p>This causes the
kernel to pause 15 seconds before probing each SCSI
device in your system. If you only have IDE hard
drives, you can ignore this, otherwise you will
probably want to lower this number, perhaps to 5
seconds, to speed up booting. Of course if you do
this, and FreeBSD has trouble recognizing your SCSI
devices, you will have to raise it back up.
<tag>controller scbus0</tag>
<p>If you have any SCSI
controllers, this line provides generic SCSI
support. If you do not have SCSI, you can comment
this, and the following three lines, out.
<tag>device sd0</tag>
<p>Support for SCSI hard
drives.
<tag>device st0</tag>
<p>Support for SCSI tape
drives.
<tag>device cd0</tag>
<p>Support for SCSI CD-ROM
drives.
<p>Note that the number <bf>0</bf> in the above entries
is slightly misleading: all these devices are
automatically configured as they are found, regardless
of how many of them are hooked up to the SCSI bus(es),
and which target IDs they have.
If you want to ``wire down'' specific target IDs to
particular devices, refer to the appropriate section
of the LINT kernel config file.
</descrip>
<sect1><heading>Console, Bus Mouse, and X Server Support</heading>
<p>You must choose one of these two console types, and, if you plan
to use X Windows, enable the XSERVER option and optionally, a bus
mouse or PS/2 mouse device.
<descrip>
<tag>device sc0 at isa? port ``IO_KBD' tty irq 1 vector scintr</tag>
<p><tt>sc0</tt> is the default
console driver, which resembles an SCO console.
Since most full-screen programs access the console
through a terminal database library like
<em>termcap</em>, it should not matter much whether
you use this or <tt>vt0</tt>, the VT220 compatible
console driver. When you log in, set your TERM
variable to ``scoansi'' if full-screen programs
have trouble running under this console.
<tag>device vt0 at isa? port ``IO_KBD'' tty irq 1 vector pcrint</tag>
<p>This is a VT220-compatible
console driver, backwards compatible to VT100/102.
It works well on some laptops which have hardware
incompatibilities with <tt>sc0</tt>. Also, set
your TERM variable to ``vt100'' or ``vt220'' when
you log in. This driver might also prove useful
when connecting to a large number of different
machines over the network, where the <em>termcap</em>
or <em>terminfo</em> entries for the <tt>sc0</tt>
device are often not available -- ``vt100'' should be
available on virtually any platform.
<descrip>
<tag>options ``PCVT_FREEBSD=210''</tag>
<p>Required
with the <tt>vt0</tt> console driver.
<tag>options XSERVER</tag>
<p>This includes code
required to run the <tt>XFree86</tt> X Window
Server.
</descrip>
<tag>device mse0 at isa? port 0x23c tty irq 5 vector ms</tag>
<p>Use this device if you have a Logitech or
ATI InPort bus mouse card.
<quote><em/Note:/ If you have a serial mouse,
ignore these two lines, and instead, make sure
the appropriate <ref id="kernelconfig:serial"
name="serial"> port is enabled (probably
COM1).</quote>
<tag>device psm0 at isa? port ``IO_KBD'' conflicts tty irq 12 vector psmintr</tag>
<p>Use this device if your
mouse plugs into the PS/2 mouse port.
</descrip>
<sect1><heading>Serial and Parallel Ports</heading>
<p>Nearly all systems have these. If you are attaching a
printer to one of these ports, the <ref id="printing"
name="Printing"> section of the handbook is very
useful. If you are using modem, <ref id="dialup"
name="Dialup access"> provides extensive detail on
serial port configuration for use with such devices.
<descrip>
<tag>device sio0 at isa? port ``IO_COM1'' tty irq 4 vector siointr<label id="kernelconfig:serial"></tag>
<p><tt>sio0</tt>
through <tt>sio3</tt> are the four serial ports
referred to as COM1 through COM4 in the MS-DOS
world. Note that if you have an internal modem on
COM4 and a serial port at COM2 you will have to
change the IRQ of the modem to 2 (for obscure
technical reasons IRQ 2 = IRQ 9) in order to access
it from FreeBSD. If you have a multiport serial
card, check the manual page for <tt>sio(4)</tt> for
more information on the proper values for these
lines. Some video cards (notably
those based on S3 chips) use IO addresses of the
form <tt>0x*2e8</tt>, and since many cheap serial
cards do not fully decode the 16-bit IO address
space, they clash with these cards, making the
COM4 port practically unavailable.
Each serial port is required to have a unique
IRQ (unless you are using one of the multiport cards
where shared interrupts are supported), so the default
IRQs for COM3 and COM4 cannot be used.
<tag>device lpt0 at isa? port? tty irq 7 vector lptintr</tag>
<p><tt>lpt0</tt> through <tt>lpt2</tt>
are the three printer ports you could conceivably
have. Most people just have one, though, so feel
free to comment out the other two lines if you do
not have them.
</descrip>
<sect1><heading>Networking<label id="kernelconfig:network"></heading>
<p>FreeBSD, as with Unix in general, places a
<em>big</em> emphasis on networking. Therefore, even
if you do not have an Ethernet card, pay attention to
the mandatory options and the dial-up networking
support.
<descrip>
<tag>options INET</tag>
Networking support. Leave it in even if you do not plan
to be connected to a network. Most programs require at least
loopback networking (i.e. making network connections within your
PC) so this is essentially mandatory.
<tag>Ethernet cards</tag>
<p>The next lines enable support for various Ethernet
cards. If you do not have a network card, you can
comment out all of these lines. Otherwise, you will
want to leave in support for your particular
Ethernet card(s):
<descrip>
<tag>device de0</tag>
<p>Digital Equipment DC21040 PCI Ethernet adapter
<tag>device cx0 at isa? port 0x240 net irq 15 drq 7 vector cxintr</tag>
<p>Cronyx/Sigma multiport
sync/async (with Cisco or PPP framing)
<tag>device ed0 at isa? port 0x280 net irq 5 iomem 0xd8000 vector edintr</tag>
<p>Western Digital and SMC 80xx; Novell NE1000
and NE2000; 3Com 3C503
<tag>device el0 at isa? port 0x300 net irq 9 vector elintr</tag>
<p>3Com 3C501 (slow!)
<tag>device eg0 at isa? port 0x310 net irq 5 vector egintr</tag>
<p>3Com 3C505
<tag>device ep0 at isa? port 0x300 net irq 10 vector epintr</tag>
<p>3Com 3C509 (buggy)
<tag>device fe0 at isa? port 0x240 net irq ? vector feintr</tag>
<p>Fujitsu MB86960A/MB86965A Ethernet
<tag>device fea0 at isa? net irq ? vector feaintr</tag>
<p>DEC DEFEA EISA FDDI adapter
<tag>device ie0 at isa? port 0x360 net irq 7 iomem 0xd0000 vector ieintr</tag>
<p>AT&T StarLAN 10 and EN100; 3Com 3C507;
unknown NI5210
<tag>device ix0 at isa? port 0x300 net irq 10 iomem 0xd0000 iosiz 32768 vector ixintr</tag>
<p>Intel EtherExpress 16
<tag>device le0 at isa? port 0x300 net irq 5 iomem 0xd0000 vector le_intr</tag>
<p>Digital Equipment EtherWorks 2 and EtherWorks
3 (DEPCA, DE100, DE101, DE200, DE201, DE202,
DE203, DE204, DE205, DE422)
<tag>device lnc0 at isa? port 0x300 net irq 10 drq 0 vector lncintr</tag>
<p>Lance/PCnet cards (Isolan, Novell NE2100,
NE32-VL)
<tag>device ze0 at isa? port 0x300 net irq 5 iomem 0xd8000 vector zeintr</tag>
<p>IBM/National Semiconductor PCMCIA ethernet
controller.
<tag>device zp0 at isa? port 0x300 net irq 10 iomem 0xd8000 vector zpintr</tag>
<p>3Com PCMCIA Etherlink III
</descrip>
<quote><em/Note:/ With certain cards (notably the
NE2000) you will have to change the port and/or IRQ
since there is no ``standard'' location for these
cards.</quote>
<tag>pseudo-device loop</tag>
<p><tt>loop</tt> is the
generic loopback device for TCP/IP. If you telnet
or FTP to <em>localhost</em>
(a.k.a. <tt>127.0.0.1</tt>) it will come back at
you through this pseudo-device. Mandatory.
<tag>pseudo-device ether</tag>
<p><tt>ether</tt> is only
needed if you have an Ethernet card and includes
generic Ethernet protocol code.
<tag>pseudo-device sl <em>number</em></tag>
<p><tt>sl</tt> is for SLIP (Serial Line Internet
Protocol) support. This has been almost entirely
supplanted by PPP, which is easier to set up,
better suited for modem-to-modem connections, as
well as more powerful. The <em>number</em> after
<tt>sl</tt> specifies how many simultaneous SLIP
sessions to support. This handbook has more
information on setting up a SLIP <ref id="slipc"
name="client"> or <ref id="slips" name="server">.
<tag>pseudo-device ppp <em>number</em></tag>
<p><tt>ppp</tt> is for kernel-mode PPP (Point-to-Point
Protocol) support for dial-up Internet connections.
There is also version of PPP implemented as a user
application that uses the <tt>tun</tt> and offers
more flexibility and features such as demand
dialing. If you still want to use this PPP driver,
read the <ref id="ppp" name="kernel-mode PPP">
section of the handbook. As with the <tt>sl</tt>
device, <em>number</em> specifies how many
simultaneous PPP connections to support.
<tag>pseudo-device tun <em>number</em></tag>
<p><tt>tun</tt> is used by the user-mode PPP software.
This program is easy to set up and very fast. It
also has special features such as automatic
dial-on-demand. The number after <tt>tun</tt>
specifies the number of simultaneous PPP sessions
to support. See the <ref id="userppp"
name="user-mode PPP"> section of the handbook for
more information.
<tag>pseudo-device bpfilter <em>number</em></tag>
<p>Berkeley packet filter. This pseudo-device allows
network interfaces to be placed in promiscuous
mode, capturing every packet on a broadcast network
(e.g. an ethernet). These packets can be captured
to disk and/or examined with the
<tt>tcpdump(1)</tt> program. Note that
implementation of this capability can seriously
compromise your overall network security.
The <em>number</em> after bpfilter is the number of
interfaces that can be examined
simultaneously. Optional, not recommended except
for those who are fully aware of the potential
pitfalls. Not all network cards support this
capability.
</descrip>
<sect1><heading>Sound cards</heading>
<p>This is the first section containing lines that are
not in the GENERIC kernel. To include sound card
support, you will have to copy the appropriate lines from
the LINT kernel (which contains support for
<em>every</em> device) as follows:
<descrip>
<tag>controller snd0</tag>
<p>Generic sound driver code.
Required for all of the following sound cards
except <tt>pca</tt>.
<tag>device pas0 at isa? port 0x388 irq 10 drq 6 vector pasintr</tag>
<p>ProAudioSpectrum digital audio and MIDI.
<tag>device sb0 at isa? port 0x220 irq 7 conflicts drq 1 vector sbintr</tag>
<p>SoundBlaster digital audio.
<quote><em/Note:/ If your SoundBlaster is on a
different IRQ (such as 5), change <tt>irq 7</tt>
to, for example, <tt>irq 5</tt> and remove the
<tt>conflicts</tt> keyword. Also, you must add
the line: <tt>options ``SBC_IRQ=5''</tt></quote>
<tag>device sbxvi0 at isa? drq 5</tag>
<p>SoundBlaster 16 digital 16-bit audio.
<quote><em/Note:/ If your SB16 is on a different
16-bit DMA channel (such as 6 or 7), change the
<tt>drq 5</tt> keyword appropriately, and then
add the line: <tt>options
"SB16_DMA=6"</tt></quote>
<tag>device sbmidi0 at isa? port 0x330</tag>
<p>SoundBlaster 16 MIDI interface. If you have a
SoundBlaster 16, you must include this line, or the
kernel will not compile.
<tag>device gus0 at isa? port 0x220 irq 10 drq 1 vector gusintr</tag>
<p>Gravis Ultrasound.
<tag>device mss0 at isa? port 0x530 irq 10 drq 1 vector adintr</tag>
<p>Microsoft Sound System.
<tag>device opl0 at isa? port 0x388 conflicts</tag>
<p>AdLib FM-synthesis audio. Include this line for
AdLib, SoundBlaster, and ProAudioSpectrum users, if
you want to play MIDI songs with a program such as
<tt>playmidi</tt> (in the ports collection).
<tag>device mpu0 at isa? port 0x330 irq 6 drq 0</tag>
<p>Roland MPU-401 stand-alone card.
<tag>device uart0 at isa? port 0x330 irq 5 vector ``m6850intr''</tag>
<p>Stand-alone 6850 UART for MIDI.
<tag>device pca0 at isa? port ``IO_TIMER1'' tty<label id="kernelconfig:pcaudio"></tag>
<p>Digital audio through PC speaker. This is going to
be very poor sound quality and quite CPU-intensive,
so you have been warned (but it does not require a
sound card).
</descrip>
<quote><em/Note:/ There is some additional
documentation in
<tt>/usr/src/sys/i386/isa/sound/sound.doc</tt>.
Also, if you add any of these devices, be sure to
create the sound <ref id="kernelconfig:nodes"
name="device nodes">.</quote>
<sect1><heading>Pseudo-devices</heading>
<p>Pseudo-device drivers are parts of the kernel that act
like device drivers but do not correspond to any actual
hardware in the machine. The <ref
id="kernelconfig:network" name="network-related">
pseudo-devices are in that section, while the remainder
are here.
<descrip>
<tag>pseudo-device gzip</tag>
<p><tt>gzip</tt> allows you to run FreeBSD programs
that have been compressed with <tt>gzip</tt>. The
programs in <tt>/stand</tt> are compressed so it
is a good idea to have this option in your kernel.</p>
<tag>pseudo-device log</tag>
<p><tt>log</tt> is used for logging of kernel error
messages. Mandatory.
<tag>pseudo-device pty <em>number</em><label id="kernelconfig:ptys"></tag>
<p><tt>pty</tt> is a ``pseudo-terminal'' or simulated
login port. It is used by incoming <bf>telnet</bf>
and <bf>rlogin</bf> sessions, xterm, and some other
applications such as emacs. The <em>number</em>
indicates the number of <tt>pty</tt>s to create.
If you need more than GENERIC default of 16
simultaneous xterm windows and/or remote logins, be
sure to increase this number accordingly, up to a
maximum of 64.
<tag>pseudo-device snp <em>number</em></tag>
<p>Snoop device. This pseudo-device allows one
terminal session to watch another using the
<tt>watch(8)</tt> command. Note that
implementation of this capability has important
security and privacy implications. The
<em>number</em> after snp is the total number of
simultaneous snoop sessions. Optional.
<tag>pseudo-device vn</tag>
<p>Vnode driver. Allows a file to be treated as a
device after being set up with the
<tt>vnconfig(8)</tt> command. This driver can be
useful for manipulating floppy disk images and
using a file as a swap device (e.g. an MS Windows
swap file). Optional.
</descrip>
<sect1><heading>Joystick, PC Speaker, Miscellaneous</heading>
<p>This section describes some miscellaneous hardware
devices supported by FreeBSD. Note that none of these
lines are included in the GENERIC kernel, you will have
to copy them from this handbook or the LINT kernel
(which contains support for <em>every</em> device):
<descrip>
<tag>device joy0 at isa? port ``IO_GAME''</tag>
<p>PC joystick device.
<tag>pseudo-device speaker</tag>
<p>Supports IBM BASIC-style noises through the PC
speaker. Some fun programs which use this are
<tt>/usr/sbin/spkrtest</tt>, which is a shell
script that plays some simple songs, and
<tt>/usr/games/piano</tt> which lets you play songs
using the keyboard as a simple piano (this file
only exists if you have installed the <em>games</em>
package). Also, the excellent text role-playing
game NetHack (in the ports collection) can be
configured to use this device to play songs when
you play musical instruments in the game.
<p>See also the <ref id="kernelconfig:pcaudio"
name="pca0"> device.
</descrip>
<sect><heading>Making Device Nodes<label id="kernelconfig:nodes"></heading>
<p>Almost every device in the kernel has a corresponding
``node'' entry in the <tt>/dev</tt> directory. These
nodes look like regular files, but are actually special
entries into the kernel which programs use to access the
device. The shell script <tt>/dev/MAKEDEV</tt>, which is
executed when you first install the operating system,
creates nearly all of the device nodes supported.
However, it does not create <em>all</em> of them, so when
you add support for a new device, it pays to make sure
that the appropriate entries are in this directory, and
if not, add them. Here is a simple example:
Suppose you add the IDE CD-ROM support to the kernel.
The line to add is:
<tscreen><verb>
controller wcd0
</verb></tscreen>
This means that you should look for some entries that
start with <tt>wcd0</tt> in the <tt>/dev</tt> directory,
possibly followed by a letter, such as `c', or preceded
by the letter 'r', which means a `raw' device. It turns
out that those files are not there, so I must change to
the <tt>/dev</tt> directory and type:
<tscreen><verb>
# sh MAKEDEV wcd0
</verb></tscreen>
When this script finishes, you will find that there are
now <tt>wcd0c</tt> and <tt>rwcd0c</tt> entries in
<tt>/dev</tt> so you know that it executed correctly.
For sound cards, the command:
<tscreen><verb>
# sh MAKEDEV snd0
</verb></tscreen>
creates the appropriate entries. Follow this simple
procedure for any other non-GENERIC devices which do not
have entries.
<quote><em/Note:/ All SCSI controllers use the same set
of <tt>/dev</tt> entries, so you do not need to create
these. Also, network cards and SLIP/PPP pseudo-devices
do not have entries in <tt>/dev</tt> at all, so you do
not have to worry about these either.</quote>
<sect><heading>If Something Goes Wrong<label id="kernelconfig:trouble"></heading>
<p>There are four categories of trouble that can occur when
building a custom kernel. They are:
<descrip>
<tag>Config command fails</tag>
<p>If the <tt>config</tt>
command fails when you give it your kernel
description, you have probably made a simple error
somewhere. Fortunately, <tt>config</tt> will print
the line number that it had trouble with, so you can
quickly skip to it with <tt>vi</tt>. For example, if
you see:
<tscreen><verb>
config: line 17: syntax error
</verb></tscreen>
you can skip to the problem in <tt>vi</tt> by typing
``17G'' in command mode. Make sure the keyword is
typed correctly, by comparing it to the GENERIC
kernel or another reference.
<tag>Make command fails</tag>
<p>If the <tt>make</tt>
command fails, it usually signals an error in your
kernel description, but not severe enough for
<tt>config</tt> to catch it. Again, look over your
configuration, and if you still cannot resolve the
problem, send mail to the &a.questions with your kernel
configuration, and it should be diagnosed very
quickly.
<tag>Kernel will not boot<label id="kernelconfig:noboot"></tag>
<p>If your new kernel
does not boot, or fails to recognize your devices,
do not panic! Fortunately, BSD has an excellent
mechanism for recovering from incompatible kernels.
Simply type the name of the kernel you want to boot
from (i.e. ``kernel.old'') at the FreeBSD boot
prompt instead of pressing return. When
reconfiguring a kernel, it is always a good idea to
keep a kernel that is known to work on hand.
After booting with a good kernel you can check over
your configuration file and try to build it again.
One helpful resource is the
<tt>/var/log/messages</tt> file which records, among
other things, all of the kernel messages from every
successful boot. Also, the <tt>dmesg(8)</tt> command
will print the kernel messages from the current boot.
<quote><em/Note:/ If you are having trouble building
a kernel, make sure to keep a GENERIC, or some
other kernel that is known to work on hand as a
different name that will not get erased on the next
build. You cannot rely on <tt>kernel.old</tt>
because when installing a new kernel,
<tt>kernel.old</tt> is overwritten with the last
installed kernel which may be non-functional.
Also, as soon as possible, move the working kernel
to the proper ``kernel'' location or commands such
as <tt>ps(1)</tt> will not work properly. The
proper command to ``unlock'' the kernel file that
<tt>make</tt> installs (in order to move another
kernel back permanently) is:
<tscreen><verb>
# chflags noschg /kernel
</verb></tscreen>
And, if you want to ``lock'' your new kernel into place, or any file
for that matter, so that it cannot be moved or tampered with:
<tscreen><verb>
# chflags schg /kernel
</verb></tscreen>
</quote>
<tag>Kernel works, but <tt>ps</tt> does not work any more!</tag>
<p>If you have installed a different version
of the kernel from the one that the system utilities
have been built with, for example, an experimental
``2.2.0'' kernel on a 2.1.0-RELEASE system, many
system-status commands like <tt>ps(1)</tt> and
<tt>vmstat(8)</tt> will not work any more. You must
recompile the <tt>libkvm</tt> library as well as
these utilities. This is one reason it is not
normally a good idea to use a different version of
the kernel from the rest of the operating system.
</descrip>
