doc/en/handbook/kernelconfig/chapter.sgml

    <chapter id="kernelconfig">
      <title>Configuring the FreeBSD Kernel</title>
      
      <para><emphasis>Contributed by &a.jehamby;.<!-- <br> -->6 October
	  1995.</emphasis></para>
      
      <para>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.</para>
      
      
      <sect1>
	<title>Why Build a Custom Kernel?</title>
	
	<para>Building a custom kernel is one of the most important rites of
	  passage every Unix system administrator must endure. This process,
	  while time-consuming, will provide many benefits to your FreeBSD
	  system. Unlike the <literal>GENERIC</literal> 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
	  <emphasis>your</emphasis> PC's hardware. This has a number of
	  benefits:</para>
	
	
	  <itemizedlist>
	    
	    <listitem>
	      <para>It will take less time to boot because it does not have to
		spend time probing for hardware which you do not have.</para>
	    </listitem>
	    
	    <listitem>
	      <para>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.</para>
	    </listitem>
	    
	    <listitem>
	      <para>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
		<emphasis>not</emphasis> present in the GENERIC kernel.</para>
	    </listitem>
	    
	  </itemizedlist>
	
	
      </sect1>
      
      <sect1 id="kernelconfig-building">
	<title>Building and Installing a Custom Kernel</title>
	
	<para>First, let us take a quick tour of the kernel build directory.
	  All directories mentioned will be relative to the main
	  <filename>/usr/src/sys</filename> directory, which is also
	  accessible through <filename>/sys</filename>. There are a number of
	  subdirectories here representing different parts of the kernel, but
	  the most important, for our purposes, are
	  <filename>i386/conf</filename>, where you will edit your custom
	  kernel configuration, and <filename>compile</filename>,
	  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 <filename>i386</filename> directory deals with
	  PC hardware only, while everything outside the
	  <filename>i386</filename> directory is common to all platforms which
	  FreeBSD could potentially be ported to.</para>
	
	<note>
	  <para>If there is <emphasis>not</emphasis> a
	    <filename>/usr/src/sys</filename> 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.</para>
	</note>
	
	<para>Next, move to the <filename>i386/conf</filename> directory and
	  copy the <filename>GENERIC</filename> configuration file to the name
	  you want to give your kernel. For example:</para>
	  
	  <informalexample>
	    <screen>&prompt.root; <userinput>cd /usr/src/sys/i386/conf</userinput>
&prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen>
	  </informalexample>

	<para>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 <filename>MYKERNEL</filename>
	  for the purpose of this example.</para>
	
	<note>
	  <para>You must execute these and all of the following commands
	    under the root account or you will get <errortype>permission denied</errortype>
	    errors.</para>
	</note>
	
	<para>Now, edit <filename>MYKERNEL</filename> with your favorite text
	  editor. If you are just starting out, the only editor available
	  will probably be <command>vi</command>, which is too
	  complex to explain here, but is covered well in many books in the
	  <link
	    linkend="bibliography">bibliography</link>. Feel free to change
	  the comment	lines at the top to reflect your configuration or the
	  changes you have made to differentiate it from
	  <filename>GENERIC</filename>.</para>
	
	<para>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 <filename>GENERIC</filename> configuration file
	  might seem overwhelming to you, so follow the descriptions in the
	  <link
	    linkend="kernelconfig-config">Configuration File</link> section slowly and carefully.</para>
	
	<note>
	  <para>If you are trying to upgrade your kernel from an older version
	    of FreeBSD, you will probably have to get a new version of
	    <citerefentry><refentrytitle>config</refentrytitle><manvolnum>8</manvolnum></citerefentry> from the same place you got the new
	    kernel sources. It is located in
	    <filename>/usr/src/usr.sbin</filename>, so you will need to
	    download those sources as well. Re-build and install it before
	    running the next commands.</para>
	</note>
	
	<para>When you are finished, type the following to compile and install
	  your kernel:</para>

	  <informalexample>
	    <screen>&prompt.root; <userinput>/usr/sbin/config MYKERNEL</userinput>
&prompt.root; <userinput>cd ../../compile/MYKERNEL</userinput>
&prompt.root; <userinput>make depend</userinput>
&prompt.root; <userinput>make</userinput>
&prompt.root; <userinput>make install</userinput></screen>
	  </informalexample>

	<para>The new kernel will be copied to the root
	  directory as <filename>/kernel</filename> and the old kernel will be
	  moved to <filename>/kernel.old</filename>. Now, shutdown the system
	  and reboot to use your kernel. In case something goes wrong, there
	  are some <link linkend="kernelconfig-trouble">troubleshooting</link> instructions at the end of this document.
	  Be sure to read the section which explains how to recover in case
	  your new kernel <link
	    linkend="kernelconfig-noboot">does not boot</link>.</para>
	
	<note>
	  <para>If you have added any new devices (such as sound cards) you
	    may have to add some <link
	      linkend="kernelconfig-nodes">device nodes</link> to your
	    <filename>/dev</filename> directory before you can use
	    them.</para>
	</note>
	
      </sect1>
      
      <sect1 id="kernelconfig-config">
	<title>The Configuration File</title>
	
	<para>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
	  <literal>#</literal> is considered a comment and ignored.
	  The following sections describe each keyword, generally in the order
	  they are listed in <filename>GENERIC</filename>, although some
	  related keywords have been grouped together in a single section
	  (such as Networking) even though they are actually scattered
	  throughout the <filename>GENERIC</filename> file.
	  <anchor id="kernelconfig-options"> An exhaustive list of options and
	  more detailed explanations of the device lines is present in the
	  <filename>LINT</filename> configuration file, located in the same
	  directory as <filename>GENERIC</filename>. If you are in doubt as to
	  the purpose or necessity of a line, check first in
	  <filename>LINT</filename>.</para>
	
	<para>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 <option>-D</option> switch for the
	  <acronym>CFLAGS</acronym> line of the kernel Makefile. Naturally,
	  this caused a creeping optionism, with nobody really knowing which
	  option has been referenced in what files.</para>
	
	<para>In the new scheme, every <literal>#ifdef</literal>
	  that is intended to be dependent upon an option gets this option out
	  of an <filename>opt_<replaceable>foo</replaceable>.h</filename>
	  declaration file created in the compile directory by <command>config</command>. The list of valid options for
	  <command>config</command> lives in two files: options
	  that do not depend on the architecture are listed in
	  <filename>/sys/conf/options</filename>, architecture-dependent ones
	  in
	  <filename>/sys/<replaceable>arch</replaceable>/conf/options.<replaceable>arch</replaceable></filename>, with <emphasis>arch</emphasis> being for example <filename>i386</filename>.</para>
	
	
	<sect2>
	  <title>Mandatory Keywords</title>
	  
	  <para>These keywords are required in every kernel you build.</para>
	  
	  
	    <variablelist>
	    <varlistentry><term><literal>machine "i386"</literal></term>
		<listitem>
		  <para>The first keyword is <literal>machine</literal>, which, since FreeBSD only
		    runs on Intel 386 and compatible chips, is i386.</para>
		  
		  <note>
		      <para>Any keyword which contains numbers used as text
		      must be enclosed in quotation marks, otherwise
		      <command>config</command> gets confused and thinks you
		      mean the actual number 386.</para>
		  </note>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>cpu "<replaceable>cpu_type</replaceable>"</literal></term>
		
		<listitem>
		  <para>The next keyword is <literal>cpu</literal>,
		    which includes support for each CPU supported by FreeBSD.
		    The possible values of <replaceable>cpu_type</replaceable>
		    include:</para>
		    <itemizedlist>
		      
		      <listitem>
			<para>I386_CPU</para>
		      </listitem>
		      
		      <listitem>
			<para>I486_CPU</para>
		      </listitem>
		      
		      <listitem>
			<para>I586_CPU</para>
		      </listitem>
		      
		      <listitem>
			<para>I686_CPU</para>
		      </listitem>
		      
		    </itemizedlist>

		<para>Multiple instances of the <literal>cpu</literal> line may be present with
		    different values of <replaceable>cpu_type</replaceable>
		    as are present in the <filename>GENERIC</filename> kernel.
		    For a custom kernel, it is best to specify only the cpu
		    you have. If, for example, you have an Intel Pentium, use
		    <literal>I586_CPU</literal> for <replaceable>cpu_type</replaceable>.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>ident <replaceable>machine_name</replaceable></literal></term>
		
		<listitem>
		  <para>Next, we have <literal>ident</literal>,
		    which is the identification of the kernel. You should
		    change this from <literal>GENERIC</literal> to whatever
		    you named your kernel, in this example,
		    <literal>MYKERNEL</literal>. The value you put in
		    <literal>ident</literal> 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 <literal>machine</literal> and <literal>
		      cpu</literal>, enclose your kernel's name in quotation
		    marks if it contains any numbers.</para>
		  
		  <para>Since this name is passed to the C compiler as a
		    <option>-D</option> switch, do not use names like
		    <literal>DEBUG</literal>, or something that could be
		    confused with another machine or CPU name, like <literal>vax</literal>.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>maxusers <replaceable>number</replaceable></literal></term>
		
		<listitem>
		  <para>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
		  <literal>maxusers</literal> to at least <literal>4</literal>,
		    especially if you are using the X Window System or
		    compiling software. The reason is that the most important
		    table set by <literal>maxusers</literal> is the
		    maximum number of processes, which is set to <literal>20 + 16 *
			maxusers</literal>, so if you set
		  <literal>maxusers</literal> to <literal>1</literal>, 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
		  <literal>maxusers</literal> to <literal>4</literal> will allow you
		    to have up to 84 simultaneous processes, which should be
		    enough for anyone. If, however, you see the dreaded
		    <errorname>proc table full</errorname> 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.</para>
		  
		  <note>
		    <para><literal>maxuser</literal> does
		      <emphasis>not</emphasis> 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 <emphasis>does</emphasis> limit the number
		      of simultaneous <emphasis>remote logins</emphasis> is
			<link
			  linkend="kernelconfig-ptys">pseudo-device pty
			  16</link>.</para>
		  </note>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>config <replaceable>kernel_name</replaceable></literal> root on
		  <replaceable>root_device</replaceable></term>
		
		<listitem>
		  <para>This line specifies the location and name of the
		    kernel. Traditionally the kernel is called
		    <filename>vmunix</filename> but in FreeBSD, it is aptly
		    named <filename>kernel</filename>. You should always use
		    <literal>kernel</literal> for
		    <replaceable>kernel_name</replaceable> 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 <literal>wd0</literal> for systems
		    with non-SCSI drives, or <literal>sd0</literal>
		    for systems with SCSI drives.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  
	  
	</sect2>
	
	<sect2>
	  <title>General Options</title>
	  
	  <para>These lines provide kernel support for various filesystems and
	    other options.</para>
	  
	  
	    <variablelist>
	    <varlistentry><term><literal>options MATH_EMULATE</literal></term>
		<listitem>
		  <para>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.</para>
		  
		  <note>
		    <para>The normal math co-processor emulation routines that
		      come with FreeBSD are <emphasis>not</emphasis> 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 <literal>GPL_MATH_EMULATE</literal> to use
		      the superior GNU math support, which is not included by
		      default for licensing reasons.</para>
		  </note>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>options "COMPAT_43"</literal></term>
		
		<listitem>
		  <para>Compatibility with 4.3BSD. Leave this in; some
		    programs will act strangely if you comment this
		    out.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>options BOUNCE_BUFFERS</literal></term>
		
		<listitem>
		  <para>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.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>options UCONSOLE</literal></term>
		
		<listitem>
		  <para>Allow users to grab the console, useful for X Windows.
		    For example, you can create a console xterm by typing
		    <command>xterm -C</command>, which will display any
		    <command>write</command>, <command>talk</command>, and other messages you receive, as well
		    as any console messages sent by the kernel.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>options SYSVSHM</literal></term>
		
		<listitem>
		  <para>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.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>options SYSVSEM</literal></term>
		
		<listitem>
		  <para>Support for System V semaphores. Less commonly used
		    but only adds a few hundred bytes to the kernel.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>options SYSVMSG</literal></term>
		
		<listitem>
		  <para>Support for System V messages. Again, only adds a few
		    hundred bytes to the kernel.</para>
		  
		  <note>
		    <para>The <citerefentry><refentrytitle>ipcs</refentrytitle><manvolnum>1</manvolnum></citerefentry> command will tell
		      will list any processes using each of these System V
		      facilities.</para>
		  </note>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  
	  
	</sect2>
	
	<sect2>
	  <title>Filesystem Options</title>
	  
	  <para>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 <acronym>FFS</acronym> if you boot from a
	    hard drive, or <acronym>NFS</acronym> 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 <filename>/lkm</filename> the
	    first time you mount a partition of that type.</para>
	  
	  
	    <variablelist>
	    <varlistentry><term><literal>options FFS</literal></term>
		<listitem>
		  <para>The basic hard drive filesystem; leave it in if you
		    boot from the hard disk.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>options NFS</literal></term>
		
		<listitem>
		  <para>Network Filesystem. Unless you plan to mount
		    partitions from a Unix file server over Ethernet, you can
		    comment this out.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>options MSDOSFS</literal></term>
		
		<listitem>
		  <para>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 <application>mtools</application> 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).</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>options "CD9660"</literal></term>
		
		<listitem>
		  <para>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.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>options PROCFS</literal></term>
		
		<listitem>
		  <para>Process filesystem. This is a pretend filesystem
		    mounted on <filename>/proc</filename> which allows
		    programs like <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> to give you more
		    information on what processes are running.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>options MFS</literal></term>
		
		<listitem>
		  <para>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
		    <filename>/tmp</filename> directory, since many programs
		    store temporary data here. To mount an MFS RAM disk on
		    <filename>/tmp</filename>, add the following line to
		    <filename>/etc/fstab</filename> and then reboot or type
		    <command>mount /tmp</command>:</para>
		    
		    <programlisting>
/dev/wd1s2b   /tmp mfs rw 0 0</programlisting>

		  
		  <note>
		    <para>Replace the <filename>/dev/wd1s2b</filename> with
		      the name of your swap partition, which will be listed in
		      your <filename>/etc/fstab</filename> as follows:</para>
		      
		      <programlisting>
/dev/wd1s2b none swap sw 0 0</programlisting>

		  </note>
		  
		  <note>
		    <para>Also, the <acronym>MFS</acronym> filesystem can
		      <emphasis>not</emphasis> be dynamically loaded, so you
		      <emphasis>must</emphasis> compile it into your kernel if
		      you want to experiment with it.</para>
		  </note>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>options "EXT2FS"</literal></term>
		
		<listitem>
		  <para>Linux's native file system. With ext2fs support you
		    are able to read and write to Linux partitions. This is
		    useful if you dual-boot FreeBSD and Linux and want to
		    share data between the two systems.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>options QUOTA</literal></term>
		
		<listitem>
		  <para>Enable disk quotas. If you have a public access
		    system, and do not want users to be able to overflow the
		    <filename>/home</filename> partition, you can establish
		    disk quotas for each user. Refer to the
		    <link linkend="quotas">Disk Quotas</link> section for
		    more information.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  
	  
	</sect2>
	
	<sect2>
	  <title>Basic Controllers and Devices</title>
	  
	  <para>These sections describe the basic disk, tape, and CD-ROM
	    controllers supported by FreeBSD. There are separate sections for
	    <link linkend="kernelconfig-scsi">SCSI</link> controllers and <link
	      linkend="kernelconfig-network">network</link> cards.</para>
	  
	  
	    <variablelist>
	    <varlistentry><term><literal>controller isa0</literal></term>
		<listitem>
		  <para>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.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>controller pci0</literal></term>
		
		<listitem>
		  <para>Include this if you have a PCI motherboard. This
		    enables auto-detection of PCI cards and gatewaying from
		    the PCI to the ISA bus.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>controller fdc0</literal></term>
		
		<listitem>
		  <para>Floppy drive controller: <literal>fd0</literal> is the
		  <devicename>A:</devicename> floppy drive, and
		    <literal>fd1</literal> is the <devicename>B:</devicename> drive.
		    <literal>ft0</literal> is a QIC-80 tape drive
		    attached to the floppy controller. Comment out any lines
		    corresponding to devices you do not have.</para>
		  
		  <note>
		    <para>QIC-80 tape support requires a separate filter
		      program called <citerefentry><refentrytitle>ft</refentrytitle><manvolnum>8</manvolnum></citerefentry>, see the manual
		      page for details.</para>
		  </note>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>controller wdc0</literal></term>
		
		<listitem>
		  <para>This is the primary IDE controller. <literal>wd0</literal> and <literal>wd1</literal> are the master and slave hard
		    drive, respectively. <literal>wdc1</literal> 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).</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device wcd0<anchor id="kernelconfig-atapi"></literal></term>
		
		<listitem>
		  <para>This device provides IDE CD-ROM support. Be sure to
		    leave <literal>wdc0</literal> uncommented, and
		    <literal>wdc1</literal> 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
		    <literal>options ATAPI</literal>.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device npx0 at isa? port "IO_NPX" irq 13
		  vector npxintr</literal></term>
		
		<listitem>
		  <para><literal>npx0</literal> is the interface to
		    the floating point math unit in FreeBSD, either the
		    hardware co-processor or the software math emulator. It
		    is <emphasis>not</emphasis> optional.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device wt0 at isa? port 0x300 bio irq 5 drq
		  1 vector wtintr</literal></term>
		
		<listitem>
		  <para>Wangtek and Archive QIC-02/QIC-36 tape drive
		    support</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry><term>Proprietary CD-ROM support</term>
		
		<listitem>
		  <para>The following drivers are for the so-called
		    <emphasis>proprietary</emphasis> CD-ROM drives. These
		    drives have their own controller card or might plug into a
		    sound card such as the SoundBlaster 16. They are
		    <emphasis>not</emphasis> IDE or SCSI. Most older
		    single-speed and double-speed CD-ROMs use these
		    interfaces, while newer quad-speeds are likely to be <link
		      linkend="kernelconfig-atapi">IDE</link> or <link
		      linkend="kernelconfig-scsi">SCSI</link>.</para>
		  
		  
		    <variablelist>
		  <varlistentry><term><literal>device mcd0 at isa? port 0x300 bio
			  irq 10 vector mcdintr</literal></term>
			<listitem>
			  <para>Mitsumi CD-ROM (LU002, LU005, FX001D).</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>device scd0 at isa? port 0x230
			  bio</literal></term>
			
			<listitem>
			  <para>Sony CD-ROM (CDU31, CDU33A).</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>controller matcd0 at isa? port ?
			  bio</literal></term>
			
			<listitem>
			  <para>Matsushita/Panasonic CD-ROM (sold by Creative
			    Labs for SoundBlaster).</para>
			</listitem>
		      </varlistentry>
		    </variablelist>
		  
		</listitem>
	      </varlistentry>
	    </variablelist>
	  
	  
	</sect2>
	
	<sect2 id="kernelconfig-scsi">
	  <title>SCSI Device Support</title>
	  
	  <para>This section describes the various SCSI controllers and
	    devices supported by FreeBSD.</para>
	  
	  
	    <variablelist>
	      <varlistentry><term>SCSI Controllers</term>
		<listitem>
		  <para>The next ten or so lines include support for different
		    kinds of SCSI controllers. Comment out all except for the
		    one(s) you have:</para>
		  
		  
		    <variablelist>
		  <varlistentry><term><literal>controller bt0 at isa? port
			  "IO_BT0" bio irq ? vector btintr</literal></term>
			<listitem>
			  <para>Most Buslogic controllers</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>controller uha0 at isa? port
			  "IO_UHA0" bio irq ? drq 5 vector uhaintr</literal></term>
			
			<listitem>
			  <para>UltraStor 14F and 34F</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>controller ahc0</literal></term>
			
			<listitem>
			  <para>Adaptec 274x/284x/294x</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>controller ahb0    at isa? bio irq ?
			  vector ahbintr</literal></term>
			
			<listitem>
			  <para>Adaptec 174x</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>controller aha0    at isa? port
			  "IO_AHA0" bio irq ? drq 5 vector ahaintr</literal></term>
			
			<listitem>
			  <para>Adaptec 154x</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>controller aic0    at isa? port
			  0x340 bio irq 11 vector aicintr</literal></term>
			
			<listitem>
			  <para>Adaptec 152x and sound cards using Adaptec
			    AIC-6360 (slow!)</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>controller nca0    at isa? port
			  0x1f88 bio irq 10 vector ncaintr</literal></term>
			
			<listitem>
			  <para>ProAudioSpectrum cards using NCR 5380 or
			    Trantor T130</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>controller sea0    at isa? bio irq 5
			  iomem 0xc8000 iosiz 0x2000 vector seaintr</literal></term>
			
			<listitem>
			  <para>Seagate ST01/02 8 bit controller
			    (slow!)</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>controller wds0    at isa? port
			  0x350 bio irq 15 drq 6 vector wdsintr</literal></term>
			
			<listitem>
			  <para>Western Digital WD7000 controller</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>controller ncr0</literal></term>
			
			<listitem>
			  <para>NCR 53C810, 53C815, 53C825, 53C860, 53C875 PCI
			    SCSI controller</para>
			</listitem>
		      </varlistentry>
		    </variablelist>
		  
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>options "SCSI_DELAY=15"</literal></term>
		
		<listitem>
		  <para>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.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>controller scbus0</literal></term>
		
		<listitem>
		  <para>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.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device sd0</literal></term>
		
		<listitem>
		  <para>Support for SCSI hard drives.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device st0</literal></term>
		
		<listitem>
		  <para>Support for SCSI tape drives.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device cd0</literal></term>
		
		<listitem>
		  <para>Support for SCSI CD-ROM drives.</para>

		  <para>Note that the number <literal>0</literal>
		    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.</para>
		  
		  <para>If you want to &ldquo;wire down&rdquo; specific target IDs to
		    particular devices, refer to the appropriate section of
		  the <filename>LINT</filename> kernel config file.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  
	  
	</sect2>
	
	<sect2>
	  <title>Console, Bus Mouse, and X Server Support</title>
	  
	  <para>You must choose one of these two console types, and, if you
	    plan to use the X Window System with the vt220 console, enable the
	    XSERVER option and optionally, a bus mouse or PS/2 mouse
	    device.</para>
	  
	  
	    <variablelist>
	    <varlistentry><term><literal>device sc0 at isa? port "IO_KBD" tty irq 1
		  vector scintr</literal></term>
		<listitem>
		  <para><literal>sc0</literal> is the default
		    console driver, which resembles an SCO console. Since most
		    full-screen programs access the console through a terminal
		    database library like <filename>termcap</filename>, it
		    should not matter much whether you use this or <literal>vt0</literal>, the VT220 compatible console
		  driver. When you log in, set your <envar>TERM</envar> variable to
		    &ldquo;scoansi&rdquo; if full-screen programs have trouble running
		    under this console.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device vt0 at isa? port "IO_KBD" tty irq 1
		  vector pcrint</literal></term>
		
		<listitem>
		  <para>This is a VT220-compatible console driver, backwards
		    compatible to VT100/102. It works well on some laptops
		  which have hardware incompatibilities with <literal>sc0</literal>. Also, set your <envar>TERM</envar> variable
		    to <literal>vt100</literal> or <literal>vt220</literal> when you log in. This driver
		    might also prove useful when connecting to a large number
		    of different machines over the network, where the
		    <filename>termcap</filename> or
		    <filename>terminfo</filename> entries for the <devicename>sc0</devicename> device are often not available
		    &mdash; <literal>vt100</literal> should be available on virtually any
		    platform.</para>
		  
		  
		    <variablelist>
		  <varlistentry><term><literal>options "PCVT_FREEBSD=210"</literal></term>
			<listitem>
			  <para>Required with the <literal>vt0</literal> console driver.</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>options XSERVER</literal></term>
			
			<listitem>
			  <para>Only applicable with the <literal>vt0</literal> console driver. This
			    includes code required to run the <application>XFree86</application> X Window Server
			    under the <literal>vt0</literal>
			    console driver.</para>
			</listitem>
		      </varlistentry>
		    </variablelist>
		  
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device mse0 at isa? port 0x23c tty irq 5
		  vector ms</literal></term>
		
		<listitem>
		  <para>Use this device if you have a Logitech or ATI InPort
		    bus mouse card.</para>
		  
		  <note>
		    <para>If you have a serial mouse, ignore these two lines,
		      and instead, make sure the appropriate <link
			linkend="kernelconfig-serial">serial</link> port is enabled (probably
		      COM1).</para>
		  </note>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device psm0 at isa? port "IO_KBD"
		  conflicts tty irq 12 vector psmintr</literal></term>
		
		<listitem>
		  <para>Use this device if your mouse plugs into the PS/2
		    mouse port.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  
	  
	</sect2>
	
	<sect2>
	  <title>Serial and Parallel Ports</title>
	  
	  <para>Nearly all systems have these. If you are attaching a printer
	    to one of these ports, the <link linkend="printing">Printing</link> section of the handbook is very useful. If
	    you are using modem, <link linkend="dialup">Dialup access</link> provides extensive detail on serial port
	    configuration for use with such devices.</para>
	  
	  
	    <variablelist>
	    <varlistentry><term><literal>device sio0 at isa? port "IO_COM1" tty irq
		  4 vector siointr</literal><anchor id="kernelconfig-serial"></term>
		<listitem>
		  <para><literal>sio0</literal> through <literal>sio3</literal> 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
		    <citerefentry><refentrytitle>sio</refentrytitle><manvolnum>4</manvolnum></citerefentry> 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
		    <literal>0x*2e8</literal>, 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.</para>
		  
		  <para>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.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device lpt0 at isa? port? tty irq 7 vector
		  lptintr</literal></term>
		
		<listitem>
		  <para><literal>lpt0</literal> through <literal>lpt2</literal> 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.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  
	  
	</sect2>
	
	<sect2 id="kernelconfig-network">
	  <title>Networking</title>
	  
	  <para>FreeBSD, as with Unix in general, places a
	    <emphasis>big</emphasis> 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.</para>
	  
	  
	    <variablelist>
	    <varlistentry><term><literal>options INET</literal></term>
		<listitem>
		  <para>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.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry><term>Ethernet cards</term>
		
		<listitem>
		  <para>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):</para>
		  
		  
		    <variablelist>
		  <varlistentry><term><literal>device de0</literal></term>
			<listitem>
			  <para>Ethernet adapters based on Digital Equipment
			    DC21040, DC21041 or DC21140 chips</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>device fxp0</literal></term>
			
			<listitem>
			  <para>Intel EtherExpress Pro/100B</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>device vx0</literal></term>
			
			<listitem>
			  <para>3Com 3C590 and 3C595 (buggy)</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>device cx0 at isa? port 0x240 net
			  irq 15 drq 7 vector cxintr</literal></term>
			
			<listitem>
			  <para>Cronyx/Sigma multiport sync/async (with Cisco
			    or PPP framing)</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>device ed0 at isa? port 0x280 net
			  irq 5 iomem 0xd8000 vector edintr</literal></term>
			
			<listitem>
			  <para>Western Digital and SMC 80xx and 8216; Novell
			    NE1000 and NE2000; 3Com 3C503; HP PC Lan Plus
			    (HP27247B and HP27252A)</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>device el0 at isa? port 0x300 net
			  irq 9 vector elintr</literal></term>
			
			<listitem>
			  <para>3Com 3C501 (slow!)</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>device eg0 at isa? port 0x310 net
			  irq 5 vector egintr</literal></term>
			
			<listitem>
			  <para>3Com 3C505</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>device ep0 at isa? port 0x300 net
			  irq 10 vector epintr</literal></term>
			
			<listitem>
			  <para>3Com 3C509 (buggy)</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>device fe0 at isa? port 0x240 net
			  irq ? vector feintr</literal></term>
			
			<listitem>
			  <para>Fujitsu MB86960A/MB86965A Ethernet</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>device fea0 at isa? net irq ? vector
			  feaintr</literal></term>
			
			<listitem>
			  <para>DEC DEFEA EISA FDDI adapter</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>device ie0 at isa? port 0x360 net
			  irq 7 iomem 0xd0000 vector ieintr</literal></term>
			
			<listitem>
			  <para>AT&amp;T StarLAN 10 and EN100; 3Com 3C507;
			    unknown NI5210; Intel EtherExpress 16</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>device le0 at isa? port 0x300 net
			  irq 5 iomem 0xd0000 vector le_intr</literal></term>
			
			<listitem>
			  <para>Digital Equipment EtherWorks 2 and EtherWorks
			    3 (DEPCA, DE100, DE101, DE200, DE201, DE202,
			    DE203, DE204, DE205, DE422)</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>device lnc0 at isa? port 0x300 net
			  irq 10 drq 0 vector lncintr</literal></term>
			
			<listitem>
			  <para>Lance/PCnet cards (Isolan, Novell NE2100,
			    NE32-VL)</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>device ze0 at isa? port 0x300 net
			  irq 5 iomem 0xd8000 vector zeintr</literal></term>
			
			<listitem>
			  <para>IBM/National Semiconductor PCMCIA ethernet
			    controller.</para>
			</listitem>
		      </varlistentry>
		      
		  <varlistentry><term><literal>device zp0 at isa? port 0x300 net
			  irq 10 iomem 0xd8000 vector zpintr</literal></term>
			
			<listitem>
			  <para>3Com PCMCIA Etherlink III</para>
			</listitem>
		      </varlistentry>
		    </variablelist>
		  
		  
		  <note>
		    <para>With certain cards (notably the NE2000) you will
		      have to change the port and/or IRQ since there is no
		      &ldquo;standard&rdquo; location for these cards.</para>
		  </note>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>pseudo-device loop</literal></term>
		
		<listitem>
		  <para><literal>loop</literal> is the generic
		    loopback device for TCP/IP. If you telnet or FTP to
		    <hostid>localhost</hostid> (a.k.a. <hostid role="ipaddr">127.0.0.1</hostid>) it will come back at you
		    through this pseudo-device. Mandatory.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>pseudo-device ether</literal></term>
		
		<listitem>
		  <para><literal>ether</literal> is only needed if
		    you have an Ethernet card and includes generic Ethernet
		    protocol code.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>pseudo-device sl
		  <replaceable>number</replaceable></literal></term>
		
		<listitem>
		  <para><literal>sl</literal> 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 <replaceable>number</replaceable> after
		    <literal>sl</literal> specifies how many
		    simultaneous SLIP sessions to support. This handbook has
		    more information on setting up a SLIP <link
		      linkend="slipc">client</link> or <link linkend="slips">server</link>.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>pseudo-device ppp
		  <replaceable>number</replaceable></literal></term>
		
		<listitem>
		  <para><literal>ppp</literal> 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 <devicename>tun</devicename> and offers more flexibility and
		    features such as demand dialing. If you still want to use
		    this PPP driver, read the <link linkend="ppp">kernel-mode PPP</link>
		    section of the handbook. As with the <literal>sl</literal> device,
		    <replaceable>number</replaceable> specifies how many
		    simultaneous PPP connections to support.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>pseudo-device tun
		  <replaceable>number</replaceable></literal></term>
		
		<listitem>
		  <para><literal>tun</literal> 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 <literal>tun</literal> specifies the number of
		    simultaneous PPP sessions to support. See the <link
		      linkend="userppp">user-mode PPP</link> section of the handbook for more
		    information.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>pseudo-device bpfilter
		  <replaceable>number</replaceable></literal></term>
		
		<listitem>
		  <para>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 <citerefentry><refentrytitle>tcpdump</refentrytitle><manvolnum>1</manvolnum></citerefentry> program.
		    Note that implementation of this capability can seriously
		    compromise your overall network security. The
		    <replaceable>number</replaceable> 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.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  
	  
	</sect2>
	
	<sect2>
	  <title>Sound cards</title>
	  
	  <para>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 <emphasis>every</emphasis> device) as follows:</para>
	  
	  
	    <variablelist>
	    <varlistentry><term><literal>controller snd0</literal></term>
		<listitem>
		  <para>Generic sound driver code. Required for all of the
		    following sound cards except <literal>pca</literal>.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device pas0 at isa? port 0x388 irq 10 drq 6
		  vector pasintr</literal></term>
		
		<listitem>
		  <para>ProAudioSpectrum digital audio and MIDI.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device sb0 at isa? port 0x220 irq 7
		  conflicts drq 1 vector sbintr</literal></term>
		
		<listitem>
		  <para>SoundBlaster digital audio.</para>
		  
		  <note>
		    <para>If your SoundBlaster is on a different IRQ (such as
		      5), change <literal>irq 7</literal> to, for
		      example, <literal>irq 5</literal> and remove
		      the <literal>conflicts</literal> keyword.
		      Also, you must add the line: <literal>options
			"SBC_IRQ=5"</literal></para>
		  </note>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device sbxvi0 at isa? drq 5</literal></term>
		
		<listitem>
		  <para>SoundBlaster 16 digital 16-bit audio.</para>
		  
		  <note>
		    <para>If your SB16 is on a different 16-bit DMA channel
		      (such as 6 or 7), change the <literal>drq
			5</literal> keyword appropriately, and then add the
		      line: <literal>options "SB16_DMA=6"</literal></para>
		  </note>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device sbmidi0 at isa? port 0x330</literal></term>
		
		<listitem>
		  <para>SoundBlaster 16 MIDI interface. If you have a
		    SoundBlaster 16, you must include this line, or the kernel
		    will not compile.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device gus0 at isa? port 0x220 irq 10 drq 1
		  vector gusintr</literal></term>
		
		<listitem>
		  <para>Gravis Ultrasound.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device mss0 at isa? port 0x530 irq 10 drq 1
		  vector adintr</literal></term>
		
		<listitem>
		  <para>Microsoft Sound System.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device opl0 at isa? port 0x388
		  conflicts</literal></term>
		
		<listitem>
		  <para>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 <command>playmidi</command> (in the ports
		    collection).</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device mpu0 at isa? port 0x330 irq 6 drq
		  0</literal></term>
		
		<listitem>
		  <para>Roland MPU-401 stand-alone card.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device uart0 at isa? port 0x330 irq 5 vector
		  "m6850intr"</literal></term>
		
		<listitem>
		  <para>Stand-alone 6850 UART for MIDI.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>device pca0 at isa? port "IO_TIMER1"
		  tty</literal><anchor id="kernelconfig-pcaudio"></term>
		
		<listitem>
		  <para>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).</para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  
	  
	  <note>
	    <para>There is some additional documentation in
	      <filename>/usr/src/sys/i386/isa/sound/sound.doc</filename>.
	      Also, if you add any of these devices, be sure to create the
	      sound <link linkend="kernelconfig-nodes">device nodes</link>.</para>
	  </note>
	  
	</sect2>
	
	<sect2>
	  <title>Pseudo-devices</title>
	  
	  <para>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 <link linkend="kernelconfig-network">network-related</link> pseudo-devices are in that section,
	    while the remainder are here.</para>
	  
	  
	    <variablelist>
	    <varlistentry><term><literal>pseudo-device gzip</literal></term>
		<listitem>
		  <para><literal>gzip</literal> allows you to run
		    FreeBSD programs that have been compressed with <command>gzip</command>. The programs in
		    <filename>/stand</filename> are compressed so it is a good
		    idea to have this option in your kernel.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>pseudo-device log</literal></term>
		
		<listitem>
		  <para><literal>log</literal> is used for logging
		    of kernel error messages. Mandatory.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>pseudo-device pty
		  <replaceable>number</replaceable></literal><anchor id="kernelconfig-ptys"></term>
		
		<listitem>
		  <para><literal>pty</literal> is a
		    &ldquo;pseudo-terminal&rdquo; or simulated login port. It is used
		    by incoming <command>telnet</command> and
		    <command>rlogin</command> sessions, xterm, and
		    some other applications such as emacs. The
		    <replaceable>number</replaceable> indicates the number of
		    <literal>pty</literal>s to create. If you need
		  more than <filename>GENERIC</filename> default of 16 simultaneous xterm windows
		    and/or remote logins, be sure to increase this number
		    accordingly, up to a maximum of 64.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>pseudo-device snp
		  <replaceable>number</replaceable></literal></term>
		
		<listitem>
		  <para>Snoop device. This pseudo-device allows one terminal
		    session to watch another using the
		    <citerefentry><refentrytitle>watch</refentrytitle><manvolnum>8</manvolnum></citerefentry> command. Note that
		    implementation of this capability has important security
		    and privacy implications. The <replaceable>number</replaceable>
		    after snp is the total number of simultaneous snoop
		    sessions. Optional.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>pseudo-device vn</literal></term>
		
		<listitem>
		  <para>Vnode driver. Allows a file to be treated as a device
		    after being set up with the <citerefentry><refentrytitle>vnconfig</refentrytitle><manvolnum>8</manvolnum></citerefentry>
		    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.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>pseudo-device ccd
		  <replaceable>number</replaceable></literal></term>
		
		<listitem>
		  <para>Concatenated disks. This pseudo-device allows you to
		    concatenate multiple disk partitions into one large
		    &ldquo;meta&rdquo;-disk. The <replaceable>number</replaceable> after ccd
		    is the total number of concatenated disks (not total
		    number of disks that can be concatenated) that can be
		    created. (See <citerefentry><refentrytitle>ccd</refentrytitle><manvolnum>4</manvolnum></citerefentry> and
		    <citerefentry><refentrytitle>ccdconfig</refentrytitle><manvolnum>8</manvolnum></citerefentry> man pages for more
		    details.)  Optional.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  
	  
	</sect2>
	
	<sect2>
	  <title>Joystick, PC Speaker, Miscellaneous</title>
	  
	  <para>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
	    <emphasis>every</emphasis> device):</para>
	  
	  
	    <variablelist>
	    <varlistentry><term><literal>device joy0 at isa? port "IO_GAME"</literal></term>
		<listitem>
		  <para>PC joystick device.</para>
		</listitem>
	      </varlistentry>
	      
	    <varlistentry><term><literal>pseudo-device speaker</literal></term>
		
		<listitem>
		  <para>Supports IBM BASIC-style noises through the PC
		    speaker. Some fun programs which use this are
		    <filename>/usr/sbin/spkrtest</filename>, which is a shell
		    script that plays some simple songs, and
		    <filename>/usr/games/piano</filename> which lets you play
		    songs using the keyboard as a simple piano (this file only
		    exists if you have installed the
		    <literal>games</literal> package). Also, the excellent
		  text role-playing game <application>NetHack</application> (in the ports collection)
		    can be configured to use this device to play songs when
		    you play musical instruments in the game.</para>

		  <para>See also the <link linkend="kernelconfig-pcaudio">pca0</link> device.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  
	  
	</sect2>
      </sect1>
      
      <sect1 id="kernelconfig-nodes">
	<title>Making Device Nodes</title>
	
	<para>Almost every device in the kernel has a corresponding &ldquo;node&rdquo;
	  entry in the <filename>/dev</filename> 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
	  <filename>/dev/MAKEDEV</filename>, which is executed when you first
	  install the operating system, creates nearly all of the device nodes
	  supported. However, it does not create <emphasis>all</emphasis> 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:</para>
	
	<para>Suppose you add the IDE CD-ROM support to the kernel. The line
	  to add is:</para>
	  
	  <programlisting>
controller wcd0</programlisting>

	<para>This means that you should look for some entries
	  that start with <filename>wcd0</filename> in the
	  <filename>/dev</filename> directory, possibly followed by a letter,
	  such as <literal>c</literal>, or preceded by the letter <literal>r</literal>, which means a &ldquo;raw&rdquo;
	  device. It turns out that those files are not there, so I must
	  change to the <filename>/dev</filename> directory and type:</para>
	  
	  <informalexample>
	    <screen>&prompt.root; <userinput>sh MAKEDEV wcd0</userinput></screen>
	  </informalexample>

	<para>When this script finishes, you will find that
	  there are now <filename>wcd0c</filename> and <filename>rwcd0c</filename> entries in <filename>/dev</filename> so
	  you know that it executed correctly.</para>
	
	<para>For sound cards, the command:

	  <informalexample>
	    <screen>&prompt.root; <userinput>sh MAKEDEV snd0</userinput></screen>
	  </informalexample> creates the appropriate entries.</para>

	<note>
	  <para>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
	    <filename>/etc/fbtab</filename> file. See <command>man
	      fbtab</command> for more information.</para>
	</note>
	
	<para>Follow this simple procedure for any other non-<filename>GENERIC</filename>  devices
	  which do not have entries.</para>
	
	<note>
	  <para>All SCSI controllers use the same set of
	    <filename>/dev</filename> entries, so you do not need to create
	    these. Also, network cards and SLIP/PPP pseudo-devices do not
	    have entries in <filename>/dev</filename> at all, so you do not
	    have to worry about these either.</para>
	</note>
	
      </sect1>
      
      <sect1 id="kernelconfig-trouble">
	<title>If Something Goes Wrong</title>
	
	<para>There are four categories of trouble that can occur when
	  building a custom kernel. They are:</para>
	
	
	  <variablelist>
	    <varlistentry><term>Config command fails</term>
	      <listitem>
		<para>If the <command>config</command> command
		  fails when you give it your kernel description, you have
		  probably made a simple error somewhere. Fortunately,
		  <command>config</command> will print the line
		  number that it had trouble with, so you can quickly skip to
		  it with <command>vi</command>. For example, if
		  you see:
		
		  <informalexample>
		    <screen>config: line 17: syntax error</screen>
		  </informalexample> you can skip to the problem in <command>vi</command> by typing <COMMAND>17G</COMMAND> in command mode.
		  Make sure the keyword is typed correctly, by comparing it to
		  the GENERIC kernel or another reference.</para>
	      </listitem>
	    </varlistentry>
	    
	    <varlistentry><term>Make command fails</term>
	      
	      <listitem>
		<para>If the <command>make</command> command fails,
		  it usually signals an error in your kernel description, but
		  not severe enough for <command>config</command>
		  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.</para>
	      </listitem>
	    </varlistentry>
	    
	    <varlistentry><term>Kernel will not boot<anchor id="kernelconfig-noboot"></term>
	      
	      <listitem>
		<para>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. <filename>kernel.old</filename>) 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.</para>
		
		<para>After booting with a good kernel you can check over your
		  configuration file and try to build it again. One helpful
		  resource is the <filename>/var/log/messages</filename> file
		  which records, among other things, all of the kernel
		  messages from every successful boot. Also, the
		  <citerefentry><refentrytitle>dmesg</refentrytitle><manvolnum>8</manvolnum></citerefentry> command will print the kernel
		  messages from the current boot.</para>
		
		<note>
		  <para>If you are having trouble building a kernel, make sure
		  to keep a <filename>GENERIC</filename>, 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
		    <filename>kernel.old</filename> because when installing a
		    new kernel, <filename>kernel.old</filename> is overwritten
		    with the last installed kernel which may be
		    non-functional. Also, as soon as possible, move the
		    working kernel to the proper <filename>kernel</filename> location or
		    commands such as <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> will not work
		    properly. The proper command to &ldquo;unlock&rdquo; the
		    kernel file that <command>make</command> installs (in
		    order to move another kernel back permanently) is:</para>
		  
		    <informalexample>
		    <screen>&prompt.root; <userinput>chflags noschg /kernel</userinput></screen>
		    </informalexample>

		<para>And, if you want to
		    &ldquo;lock&rdquo; your new kernel into place, or any
		    file for that matter, so that it cannot be moved or
		    tampered with:</para>
		  
		    <informalexample>
		    <screen>&prompt.root; <userinput>chflags schg /kernel</userinput></screen>
		    </informalexample>
	        </note>
	      </listitem>
	    </varlistentry>
	    
	    <varlistentry><term>Kernel works, but <command>ps</command> does not work any more!</term>
	      
	      <listitem>
		<para>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 &ldquo;2.2.0&rdquo; kernel on a
		  2.1.0-RELEASE system, many system-status commands like
		  <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> and <citerefentry><refentrytitle>vmstat</refentrytitle><manvolnum>8</manvolnum></citerefentry>
		  will not work any more. You must recompile the <filename>libkvm</filename> 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.</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	  
	
	
      </sect1>
    </chapter>


<!-- 
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-shorttag: nil
     sgml-always-quote-attributes: t
     sgml-minimize-attributes: max
     sgml-parent-document: ("../handbook.sgml" "part" "chapter")
     End:
-->