Configuring the FreeBSD Kernel
Contributed by &a.jehamby;.6 October 1995.
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.
Why build a custom kernel?
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 your PC's hardware. This has a number of
benefits:
- It will take less time to boot because it does not
have to spend time probing for hardware which you
do not have.
- 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.
- 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
not present
in the GENERIC kernel.
Building and Installing a Custom Kernel
First, let us take a quick tour of the kernel build
directory. All directories mentioned will be relative to
the main /usr/src/sys directory, which is also
accessible through /sys . There are a number of
subdirectories here representing different parts of the
kernel, but the most important, for our purposes, are
i386/conf , where you will edit your custom
kernel configuration, and compile , 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 i386
directory deals with PC hardware only, while everything
outside the i386 directory is common to all
platforms which FreeBSD could potentially be ported to.
not a
/usr/src/sys 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.
Next, move to the i386/conf directory and copy
the GENERIC configuration file to the name you want to
give your kernel. For example:
# cd /usr/src/sys/i386/conf
# cp GENERIC MYKERNEL
Now, edit MYKERNEL with your favorite text editor. If
you are just starting out, the only editor available will
probably be vi , which is too complex to explain
here, but is covered well in many books in the [. 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 ][
section slowly and carefully.
]config(8) from the same place you got the new
kernel sources. It is located in /usr/src/usr.sbin , so
you will need to download those sources as well. Re-build and install
it before running the next commands.
When you are finished, type the following to compile and
install your kernel:
# /usr/sbin/config MYKERNEL
# cd ../../compile/MYKERNEL
# make depend
# make
# make install
/kernel and the old kernel will be moved to
/kernel.old . Now, shutdown the system and
reboot to use your kernel. In case something goes wrong,
there are some [ instructions at the end of this
document. Be sure to read the section which explains how
to recover in case your new kernel ][.
] to your
/dev directory before you can use them.
The Configuration File
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 # 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.
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 -D switch
for the CFLAGS line of the kernel Makefile. Naturally,
this caused a creeping optionism, with nobody really knowing
which option has been referenced in what files.
In the new scheme, every #ifdef that is intended to
be dependent upon an option gets this option out of an
opt_foo .h declaration file created in the
compile directory by config . The list of valid options
for config lives in two files: options that do not
depend on the architecture are listed in
/sys/conf/options , architecture-dependent ones
in /sys/arch /conf/options.arch ,
with arch being for example i386 .
Mandatory Keywords
These keywords are required in every kernel you build.
machine ``i386''
The first keyword is machine , which,
since FreeBSD only runs on Intel 386 and compatible
chips, is i386.
Note: that any keyword which
contains numbers used as text must be enclosed in
quotation marks, otherwise config gets
confused and thinks you mean the actual number
386.
cpu ``cpu_type ''
The next keyword is cpu , which includes
support for each CPU supported by FreeBSD. The
possible values of cpu_type
- I386_CPU
- I486_CPU
- I586_CPU
- I686_CPU
and multiple instances of the cpu line may
be present with different values of
cpu_type I586_CPU
for cpu_type ident machine_name
Next, we have ident , 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 ident 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 machine and cpu , enclose
your kernel's name in quotation marks if it
contains any numbers.
Since this name is passed to the C compiler as a
-D switch, do not use names like
DEBUG , or something that could be confused
with another machine or CPU name, like vax .
maxusers number
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
maxusers to at least four, especially if
you are using the X Window System or compiling software. The
reason is that the most important table set by
maxusers is the maximum number of
processes, which is set to 20 + 16 *
maxusers maxusers
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 the X Window System. Even a
simple task like reading a man page will
start up nine processes to filter, decompress, and
view it. Setting maxusers 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.
maxuser does
not 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
does limit the number of simultaneous
remote logins is [.]
config kernel_name root on root_device
This line specifies the location and name of the
kernel. Traditionally the kernel is called
vmunix but in FreeBSD, it is aptly named
kernel . You should always use
kernel for kernel_name 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
wd0 for systems with non-SCSI drives, or
sd0 for systems with SCSI drives.
General Options
These lines provide kernel support for various
filesystems and other options.
options MATH_EMULATE
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.
Note: The normal math co-processor
emulation routines that come with FreeBSD are
not 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
GPL_MATH_EMULATE to use the superior GNU
math support, which is not included by default
for licensing reasons.
options ``COMPAT_43''
Compatibility with 4.3BSD. Leave this in; some
programs will act strangely if you comment this
out.
options BOUNCE_BUFFERS
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.
options UCONSOLE
Allow users to grab the console, useful for X
Windows. For example, you can create a console
xterm by typing xterm -C , which will
display any `write', `talk', and other messages you
receive, as well as any console messages sent by the
kernel.
options SYSVSHM
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 the X Window System, you will definitely
want to include this.
options SYSVSEM
Support for System V
semaphores. Less commonly used but only adds a few
hundred bytes to the kernel.
options SYSVMSG
Support for System V
messages. Again, only adds a few hundred bytes to
the kernel.
ipcs(1) command will
tell will list any processes using each of
these System V facilities.
Filesystem Options
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
FFS if you boot from a hard drive, or
NFS 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
/lkm the first time you mount a partition of
that type.
options FFS
The basic hard drive
filesystem; leave it in if you boot from the hard
disk.
options NFS
Network Filesystem. Unless
you plan to mount partitions from a Unix file
server over Ethernet, you can comment this out.
options MSDOSFS
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 mtools 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).
options ``CD9660''
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.
options PROCFS
Process filesystem. This
is a pretend filesystem mounted on /proc which
allows programs like ps(1) to give you
more information on what processes are running.
options MFS
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
/tmp directory, since many programs store
temporary data here. To mount an MFS RAM disk on
/tmp , add the following line to
/etc/fstab and then reboot or type
mount /tmp :
/dev/wd1s2b /tmp mfs rw 0 0
/dev/wd1s2b
with the name of your swap partition, which will
be listed in your /etc/fstab as follows:
/dev/wd1s2b none swap sw 0 0
/tmp device
simultaneously). As such, you may want to avoid
it for now. --> Also, the MFS filesystem
can not be dynamically loaded, so you
must compile it into your kernel if you
want to experiment with it.
options QUOTA
Enable disk quotas. If you
have a public access system, and do not want users
to be able to overflow the /home
partition, you can establish disk quotas for each
user. Refer to the
[
section for more information.
]
Basic Controllers and Devices
These sections describe the basic disk, tape, and
CD-ROM controllers supported by FreeBSD. There are
separate sections for [ controllers and ][ cards.
]
controller isa0
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.
controller pci0
Include this if you have a
PCI motherboard. This enables auto-detection of
PCI cards and gatewaying from the PCI to the ISA
bus.
controller fdc0
Floppy drive controller:
fd0 is the ``A:'' floppy drive, and
fd1 is the ``B:'' drive. ft0 is
a QIC-80 tape drive attached to the floppy
controller. Comment out any lines corresponding to
devices you do not have.
ft(8), see
the manual page for details.
controller wdc0
This is the primary IDE
controller. wd0 and wd1 are the
master and slave hard drive, respectively.
wdc1 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).
device wcd0
This device
provides IDE CD-ROM support. Be sure to leave
wdc0 uncommented, and options ATAPI .
device npx0 at isa? port ``IO_NPX'' irq 13 vector npxintr
npx0 is the interface to the floating point math
unit in FreeBSD, either the hardware co-processor or the
software math emulator. It is device wt0 at isa? port 0x300 bio irq 5 drq 1 vector wtintr
Wangtek and Archive
QIC-02/QIC-36 tape drive support
Proprietary CD-ROM support
The following
drivers are for the so-called proprietary
CD-ROM drives. These drives have their own
controller card or might plug into a sound card
such as the SoundBlaster 16. They are not
IDE or SCSI. Most older single-speed and
double-speed CD-ROMs use these interfaces, while
newer quad-speeds are likely to be [ or ][.
]
device mcd0 at isa? port 0x300 bio irq 10 vector mcdintr
Mitsumi CD-ROM (LU002,
LU005, FX001D).
device scd0 at isa? port 0x230 bio
Sony CD-ROM (CDU31, CDU33A).
controller matcd0 at isa? port ? bio
Matsushita/Panasonic CD-ROM (sold by Creative
Labs for SoundBlaster).
SCSI Device Support
This section describes the various SCSI controllers
and devices supported by FreeBSD.
SCSI Controllers
The next ten or so lines include support for
different kinds of SCSI controllers. Comment out
all except for the one(s) you have:
controller bt0 at isa? port ``IO_BT0'' bio irq ? vector btintr
Most Buslogic controllers
controller uha0 at isa? port ``IO_UHA0'' bio irq ? drq 5 vector uhaintr
UltraStor 14F and 34F
controller ahc0
Adaptec 274x/284x/294x
controller ahb0 at isa? bio irq ? vector ahbintr
Adaptec 174x
controller aha0 at isa? port ``IO_AHA0'' bio irq ? drq 5 vector ahaintr
Adaptec 154x
controller aic0 at isa? port 0x340 bio irq 11 vector aicintr
Adaptec 152x and sound cards using Adaptec AIC-6360 (slow!)
controller nca0 at isa? port 0x1f88 bio irq 10 vector ncaintr
ProAudioSpectrum cards using NCR 5380 or Trantor T130
controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr
Seagate ST01/02 8 bit controller (slow!)
controller wds0 at isa? port 0x350 bio irq 15 drq 6 vector wdsintr
Western Digital WD7000 controller
controller ncr0
NCR 53C810, 53C815, 53C825, 53C860, 53C875 PCI SCSI controller
options ``SCSI_DELAY=15''
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.
controller scbus0
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.
device sd0
Support for SCSI hard
drives.
device st0
Support for SCSI tape
drives.
device cd0
Support for SCSI CD-ROM
drives.
Note that the number 0 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.
Console, Bus Mouse, and X Server Support
You must choose one of these two console types, and, if you plan
to use the X Window System, enable the XSERVER option and optionally, a bus
mouse or PS/2 mouse device.
device sc0 at isa? port ``IO_KBD' tty irq 1 vector scintr
sc0 is the default
console driver, which resembles an SCO console.
Since most full-screen programs access the console
through a terminal database library like
termcap , it should not matter much whether
you use this or vt0 , 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.
device vt0 at isa? port ``IO_KBD'' tty irq 1 vector pcrint
This is a VT220-compatible
console driver, backwards compatible to VT100/102.
It works well on some laptops which have hardware
incompatibilities with sc0 . 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 termcap
or terminfo entries for the sc0
device are often not available -- ``vt100'' should be
available on virtually any platform.
options ``PCVT_FREEBSD=210''
Required
with the vt0 console driver.
options XSERVER
This includes code
required to run the XFree86 X Window
Server.
device mse0 at isa? port 0x23c tty irq 5 vector ms
Use this device if you have a Logitech or
ATI InPort bus mouse card.
port is enabled (probably
COM1).
device psm0 at isa? port ``IO_KBD'' conflicts tty irq 12 vector psmintr
Use this device if your
mouse plugs into the PS/2 mouse port.
Serial and Parallel Ports
Nearly all systems have these. If you are attaching a
printer to one of these ports, the [ section of the handbook is very
useful. If you are using modem, ][ provides extensive detail on
serial port configuration for use with such devices.
]
device sio0 at isa? port ``IO_COM1'' tty irq 4 vector siointr
sio0
through sio3 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 sio(4) 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 0x*2e8 , 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.
device lpt0 at isa? port? tty irq 7 vector lptintr
lpt0 through lpt2
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.
Networking
FreeBSD, as with Unix in general, places a
big 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.
options INET
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.
Ethernet cards
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):
device de0
Ethernet adapters based on Digital Equipment DC21040,
DC21041 or DC21140 chips
device fxp0
Intel EtherExpress Pro/100B
device vx0
3Com 3C590 and 3C595 (buggy)
device cx0 at isa? port 0x240 net irq 15 drq 7 vector cxintr
Cronyx/Sigma multiport
sync/async (with Cisco or PPP framing)
device ed0 at isa? port 0x280 net irq 5 iomem 0xd8000 vector edintr
Western Digital and SMC 80xx and 8216; Novell NE1000
and NE2000; 3Com 3C503; HP PC Lan Plus (HP27247B and HP27252A)
device el0 at isa? port 0x300 net irq 9 vector elintr
3Com 3C501 (slow!)
device eg0 at isa? port 0x310 net irq 5 vector egintr
3Com 3C505
device ep0 at isa? port 0x300 net irq 10 vector epintr
3Com 3C509 (buggy)
device fe0 at isa? port 0x240 net irq ? vector feintr
Fujitsu MB86960A/MB86965A Ethernet
device fea0 at isa? net irq ? vector feaintr
DEC DEFEA EISA FDDI adapter
device ie0 at isa? port 0x360 net irq 7 iomem 0xd0000 vector ieintr
AT&T StarLAN 10 and EN100; 3Com 3C507;
unknown NI5210
device ix0 at isa? port 0x300 net irq 10 iomem 0xd0000 iosiz 32768 vector ixintr
Intel EtherExpress 16
device le0 at isa? port 0x300 net irq 5 iomem 0xd0000 vector le_intr
Digital Equipment EtherWorks 2 and EtherWorks
3 (DEPCA, DE100, DE101, DE200, DE201, DE202,
DE203, DE204, DE205, DE422)
device lnc0 at isa? port 0x300 net irq 10 drq 0 vector lncintr
Lance/PCnet cards (Isolan, Novell NE2100,
NE32-VL)
device ze0 at isa? port 0x300 net irq 5 iomem 0xd8000 vector zeintr
IBM/National Semiconductor PCMCIA ethernet
controller.
device zp0 at isa? port 0x300 net irq 10 iomem 0xd8000 vector zpintr
3Com PCMCIA Etherlink III
pseudo-device loop
loop is the
generic loopback device for TCP/IP. If you telnet
or FTP to localhost
(a.k.a. 127.0.0.1 ) it will come back at
you through this pseudo-device. Mandatory.
pseudo-device ether
ether is only
needed if you have an Ethernet card and includes
generic Ethernet protocol code.
pseudo-device sl number
sl 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 number after
sl specifies how many simultaneous SLIP
sessions to support. This handbook has more
information on setting up a SLIP [ or ][.
]pseudo-device ppp number
ppp 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 tun and offers
more flexibility and features such as demand
dialing. If you still want to use this PPP driver,
read the [
section of the handbook. As with the ]sl
device, number specifies how many
simultaneous PPP connections to support.
pseudo-device tun number
tun 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 tun
specifies the number of simultaneous PPP sessions
to support. See the [ section of the handbook for
more information.
]pseudo-device bpfilter number
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
tcpdump(1) program. Note that
implementation of this capability can seriously
compromise your overall network security.
The number 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.
Sound cards
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
every device) as follows:
controller snd0
Generic sound driver code.
Required for all of the following sound cards
except pca .
device pas0 at isa? port 0x388 irq 10 drq 6 vector pasintr
ProAudioSpectrum digital audio and MIDI.
device sb0 at isa? port 0x220 irq 7 conflicts drq 1 vector sbintr
SoundBlaster digital audio.
irq 7
to, for example, irq 5 and remove the
conflicts keyword. Also, you must add
the line: options ``SBC_IRQ=5''
device sbxvi0 at isa? drq 5
SoundBlaster 16 digital 16-bit audio.
drq 5 keyword appropriately, and then
add the line: options
"SB16_DMA=6"
device sbmidi0 at isa? port 0x330
SoundBlaster 16 MIDI interface. If you have a
SoundBlaster 16, you must include this line, or the
kernel will not compile.
device gus0 at isa? port 0x220 irq 10 drq 1 vector gusintr
Gravis Ultrasound.
device mss0 at isa? port 0x530 irq 10 drq 1 vector adintr
Microsoft Sound System.
device opl0 at isa? port 0x388 conflicts
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
playmidi (in the ports collection).
device mpu0 at isa? port 0x330 irq 6 drq 0
Roland MPU-401 stand-alone card.
device uart0 at isa? port 0x330 irq 5 vector ``m6850intr''
Stand-alone 6850 UART for MIDI.
device pca0 at isa? port ``IO_TIMER1'' tty
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).
/usr/src/sys/i386/isa/sound/sound.doc.
Also, if you add any of these devices, be sure to
create the sound [.]
Pseudo-devices
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 [
pseudo-devices are in that section, while the remainder
are here.
]
pseudo-device gzip
gzip allows you to run FreeBSD programs
that have been compressed with gzip . The
programs in /stand are compressed so it
is a good idea to have this option in your kernel.
pseudo-device log
log is used for logging of kernel error
messages. Mandatory.
pseudo-device pty number
pty is a ``pseudo-terminal'' or simulated
login port. It is used by incoming telnet
and rlogin sessions, xterm, and some other
applications such as emacs. The number
indicates the number of pty 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.
pseudo-device snp number
Snoop device. This pseudo-device allows one
terminal session to watch another using the
watch(8) command. Note that
implementation of this capability has important
security and privacy implications. The
number after snp is the total number of
simultaneous snoop sessions. Optional.
pseudo-device vn
Vnode driver. Allows a file to be treated as a
device after being set up with the
vnconfig(8) 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.
pseudo-device ccd number
Concatenated disks. This pseudo-device allows you to
concatenate multiple disk partitions into one large
``meta''-disk. The number after ccd is the
total number of concatenated disks (not total number of
disks that can be concatenated) that can be created.
(See ccd(4) and ccdconfig(8) man pages
for more details.) Optional.
Joystick, PC Speaker, Miscellaneous
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 every device):
device joy0 at isa? port ``IO_GAME''
PC joystick device.
pseudo-device speaker
Supports IBM BASIC-style noises through the PC
speaker. Some fun programs which use this are
/usr/sbin/spkrtest , which is a shell
script that plays some simple songs, and
/usr/games/piano which lets you play songs
using the keyboard as a simple piano (this file
only exists if you have installed the games
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.
See also the [ device.
]
Making Device Nodes
Almost every device in the kernel has a corresponding
``node'' entry in the /dev 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 /dev/MAKEDEV , which is
executed when you first install the operating system,
creates nearly all of the device nodes supported.
However, it does not create all 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:
controller wcd0
wcd0 in the /dev 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 /dev directory and type:
# sh MAKEDEV wcd0
wcd0c and rwcd0c entries in
/dev so you know that it executed correctly.
For sound cards, the command:
# sh MAKEDEV snd0
/etc/fbtab file. See man fbtab for
more information.
Follow this simple procedure for any other non-GENERIC
devices which do not have entries.
/dev entries, so you do not need to create
these. Also, network cards and SLIP/PPP pseudo-devices
do not have entries in /dev at all, so you do
not have to worry about these either.
If Something Goes Wrong
There are four categories of trouble that can occur when
building a custom kernel. They are:
Config command fails
If the config
command fails when you give it your kernel
description, you have probably made a simple error
somewhere. Fortunately, config will print
the line number that it had trouble with, so you can
quickly skip to it with vi . For example, if
you see:
config: line 17: syntax error
vi by typing
``17G'' in command mode. Make sure the keyword is
typed correctly, by comparing it to the GENERIC
kernel or another reference.
Make command fails
If the make
command fails, it usually signals an error in your
kernel description, but not severe enough for
config 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.
Kernel will not boot
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
/var/log/messages file which records, among
other things, all of the kernel messages from every
successful boot. Also, the dmesg(8) command
will print the kernel messages from the current boot.
kernel.old
because when installing a new kernel,
kernel.old 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 ps(1) will not work properly. The
proper command to ``unlock'' the kernel file that
make installs (in order to move another
kernel back permanently) is:
# chflags noschg /kernel
# chflags schg /kernel
Kernel works, but ps does not work any more!
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 ps(1) and
vmstat(8) will not work any more. You must
recompile the libkvm 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.