diff options
Diffstat (limited to 'share/doc/handbook/kernelconfig.sgml')
| -rw-r--r-- | share/doc/handbook/kernelconfig.sgml | 1285 |
1 files changed, 0 insertions, 1285 deletions
diff --git a/share/doc/handbook/kernelconfig.sgml b/share/doc/handbook/kernelconfig.sgml deleted file mode 100644 index 4310d28..0000000 --- a/share/doc/handbook/kernelconfig.sgml +++ /dev/null @@ -1,1285 +0,0 @@ -<!-- $Id: kernelconfig.sgml,v 1.27 1997/02/22 12:58:42 peter 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 are 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 - can 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. Refer to the - <ref id="quotas" name="Disk Quotas"> - section for more information. - - </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 with the vt220 console, 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>Only applicable with the <tt>vt0</tt> console driver. - This includes code - required to run the <tt>XFree86</tt> X Window - Server under the <tt>vt0</tt> console driver. - - </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&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> |
