Custom kernels

The configuration file

The directory /sys/i386/conf contains a number of configuration files:

• generic General-purpose configuration file
• lint This file used to be a "complete" configuration file with comments, used for testing and documentation. Since FreeBSD Release 5, it no longer exists. Youcan create it from the files NOTES and /usr/src/sys/conf/NOTES with the command:

  $ make LIN
  
• notes A complete pseudo-configuration file with copious comments. This file is descended from LINT, but it also includes device hints. You can't use it for building kernels. Instead, create the file LINT as described above. NOTES contains only platform-specific information. Most of the information is in the platform-independent file /usr/src/sys/conf/NOTES.
• oldcard A configuration file for laptops that use PCCARD controllers. At the time of writing, PCCARD support has largely been rewritten, but the new code does not support some of the devices that the old code supports. This configuration file uses the old PCCARD code instead of the new code. When the new code is complete, it will go away.

The general format of a configuration file is quite simple. Each line contains a keyword and one or more arguments. Anything following a # is considered a comment and ignored. Keywords that contain numbers used as text must be enclosed in quotation marks.

One of the results of this simplicity is that you can put in options that have absolutely no effect. For example, you could add a line like this:

options APPLE_MAC_COMPATIBILITY

You can build a kernel with this option. It will make no difference whatsoever. Now it's unlikely that you'll think up a non-existent option like this, but it's much more possible that you'll misspell a valid option, especially finger-twisters like SYSVSHM, with the result that you don't compile in the option you wanted. The config program warns if you use unknown options, so take these warnings seriously.

Kernel options change from release to release, so there's no point in describing them all here. In the following sections we'll look at some of the more interesting ones; for a complete list, read LINT or the online handbook. See above for details of how to create LINT.

Naming the kernel

Every kernel you build requires the keywords machine, cpu, and ident. For example,

machine  "i386"       For 386 architecture
machine  "alpha"      For alpha architecture
machine  "sparc64"    For PARC 64 architecture
cpu      "I486_CPU"
cpu      "I586_CPU"
cpu      "I686_CPU"
ident     FREEBIE

machine

The keyword machine describes the machine architecture for which the kernel is to be built. Currently it should be i386 for the Intel architecture, and alpha for the AXP architecture. Don't confuse this with the processor: for example, the i386 architecture refers to the Intel 80386 and all its successors, including lookalikes made by AMD, Cyrix and IBM.

cpu cpu_type

cpu describes which CPU chip or chips this kernel should support. For the i386 architecture, the possible values are I386_CPU, I486_CPU, I586_CPU and I686_CPU, and you can specify any combination of these values. For a custom kernel, it is best to specify only the CPU you have. If, for example, you have an Intel Pentium, use I586_CPU for cpu_type.

If you're not sure what processor type you have, look at the output from the dmesg command when running the GENERIC kernel. For example:

CPU: AMD Athlon(tm) XP processor 1700+ (1462.51-MHz 686-class CPU)
Origin = "AuthenticAMD"    Id = 0x662   Stepping = 2
Features=0x383f9ff<FPU,VME,DE,PSE,TSC,MSR,PAE,MCE,CX8,SEP,MTRR,PGE,MCA,^OV,PAT,PS E36,MMX,FXSR,SSE>
AMD Features=0xc0480000<<b19>,AMIE,DSP,3DNcw!>

This shows that the processor, an AMD Athlon XP, is a "686 class" CPU, so to run a kernel on this processor, you must set I686_CPU in the config file.

Since Release 5 of FreeBSD, it is no longer possible to build a single kernel with support for both the 80386 processor and later processors: the code for the later processors is optimized to use instructions that the 80386 processor does not have. Choose either I386_CPU or any combination of the others.

ident machine_name

ident specifies a name used to identify the kernel. In the file GENERIC it is GENERIC. Change this to whatever you named your kernel, in this example, FREEBIE. The value you put in ident will print when you boot up the kernel, so it's 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). As with machine and cpu, enclose your kernel's name in quotation marks if it contains any numbers.

This name is passed to the C compiler as a variable, so don't use names like DEBUG, or something that could be confused with another machine or CPU name, like vax.

Kernel options

There are a number of global kernel options, most of which you don't need to change. In the following section, we'll look at some of the few exceptions.

Configuring specific I/O devices

There are some devices that the GENERIC kernel does not support. In older releases of FreeBSD, you needed to build a new kernel to support them. This is seldom the case any more: most devices can be supported by klds. Work is under way to support the remainder. In case of doubt, look at the file HARDWARE.TXT on the installation CD-ROM.

maxusers number

This value sets the size of a number of important system tables. It is still included in the kernel configuration file, but you no longer need build a new kernel to change it. Instead, you can set it at boot time. For example, you might add the following line to your /boot/loader.conf file:

maxusers="64"

See 532 for more details of /boot/loader.conf.

maxusers is intended to be roughly equal to the number of simultaneous users you expect to have on your machine, but it is only used to determine the size of some system tables. The default value 0 tells the kernel to autosize the tables depending on the amount of memory on the system. If the autosizing doesn' t work to your satisfaction, change this value. Even if you are the only person to use the machine, you shouldn't set maxusers lower than the default value 32, especially if you're using X or compiling software. The reason is that the most important table set by maxusers is the maximum number of processes, which is set to 20 + 16 * maxusers, so if you set maxusers to one, you can only have 36 simultaneous processes, including the 18 or so that the system starts up at boot time, and the 15 or so you will probably create when you start X. Even a simple task like reading a man page can start up nine processes to filter, decompress, and view it. Setting maxusers to 32 will allow you to have up to 532 simultaneous processes, which is normally ample. 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, you can always increase this number and reboot.

Multiple processors

FreeBSD 5.0 supports most modern multiprocessor systems. Earlier versions of the GENERIC kernel did not support them by default. Nowadays GENERIC supports multiple processors, so you don't need to do anything special. Look at the option SMP and the device apic in the configuration file if you're interested.