freebsd/share/doc/handbook/kernelconfig.sgml

<!-- $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>

    <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. <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.

	<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 creeping 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 dependent 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 not
	depend on the architecture are listed in
	<tt>/sys/conf/options</tt>, architecture-dependent 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
		<item>I686_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 the X Window System 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 the X Window System.  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 4.3BSD.  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 the X Window System, 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 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>device wcd0<label id="kernelconfig:atapi"></tag>

	      <p>This device
		provides IDE CD-ROM support.  Be sure to leave
		<tt>wdc0</tt> uncommented, and <tt/wdc1/ if you have
		more than one IDE controller and your CD-ROM is on
		the second one 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, 53C815, 53C825, 53C860, 53C875 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 the X Window System, 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>Ethernet adapters based on Digital Equipment DC21040,
		   DC21041 or DC21140 chips

		<tag>device fxp0</tag>

		<p>Intel EtherExpress Pro/100B

		<tag>device vx0</tag>

		<p>3Com 3C590 and 3C595 (buggy)

		<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 and 8216; Novell NE1000
		  and NE2000; 3Com 3C503; HP PC Lan Plus (HP27247B and HP27252A)

		<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&amp;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.

	    <tag>pseudo-device ccd <em>number</em></tag>

	    <p>Concatenated disks.  This pseudo-device allows you to
	      concatenate multiple disk partitions into one large
	      ``meta''-disk.  The <em>number</em> after ccd is the
	      total number of concatenated disks (not total number of
	      disks that can be concatenated) that can be created.
	      (See <tt>ccd(4)</tt> and <tt>ccdconfig(8)</tt> man pages
	      for more details.)  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.  Note: when creating device
	nodes for devices such as sound cards, if other people have
	access to your machine, it may be desirable to
	protect the devices from outside access by adding them to the
	<tt>/etc/fbtab</tt> file.  See <tt>man fbtab</tt> for
	more information.

	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>