Annotation of wikisrc/guide/kernel.mdwn, revision 1.4

1.3       jdf         1: **Contents**
                      2: 
                      3: [[!toc levels=3]]
                      4: 
1.1       jdf         5: # Compiling the kernel
                      6: 
                      7: Most NetBSD users will sooner or later want to recompile their kernel, or
                      8: compile a customized kernel. This might be for several reasons:
                      9: 
                     10:  * you can install bug-fixes, security updates, or new functionality by
                     11:    rebuilding the kernel from updated sources.
                     12:  * by removing unused device drivers and kernel sub-systems from your
                     13:    configuration, you can dramatically reduce kernel size and, therefore, memory
                     14:    usage.
                     15:  * by enabling optimisations more specific to your hardware, or tuning the
                     16:    system to match your specific sizing and workload, you can improve
                     17:    performance.
                     18:  * you can access additional features by enabling kernel options or sub-systems,
                     19:    some of which are experimental or disabled by default.
                     20:  * you can solve problems of detection/conflicts of peripherals.
                     21:  * you can customize some options (for example keyboard layout, BIOS clock
                     22:    offset, ...)
                     23:  * you can get a deeper knowledge of the system.
                     24: 
                     25: ## Requirements and procedure
                     26: 
                     27: To recompile the kernel you must have installed the compiler set (`comp.tgz`).
                     28: 
                     29: The basic steps to an updated or customised kernel then are:
                     30: 
                     31:  1. Install or update the kernel sources
                     32:  2. Create or modify the kernel configuration file
                     33:  3. Building the kernel from the configuration file, either manually or using
                     34:     `build.sh`
                     35:  4. Install the kernel
                     36: 
                     37: 
                     38: ## Installing the kernel sources
                     39: 
                     40: You can get the kernel sources from AnonCVS (see [[Obtaining the
                     41: sources|guide/fetch]]), or from the `syssrc.tgz` tarball that is located in the
                     42: `source/sets/` directory of the release that you are using.
                     43: 
                     44: If you chose to use AnonCVS to fetch the entire source tree, be patient, the
                     45: operation can last many minutes, because the repository contains thousands of
                     46: files.
                     47: 
                     48: If you have a source tarball, you can extract it as root:
                     49: 
                     50:     # cd /
                     51:     # tar zxf /path/to/syssrc.tgz
                     52: 
                     53: Even if you used the tarball from the release, you may wish to use AnonCVS to
                     54: update the sources with changes that have been applied since the release. This
                     55: might be especially relevant if you are updating the kernel to include the fix
                     56: for a specific bug, including a vulnerability described in a NetBSD Security
                     57: Advisory. You might want to get the latest sources on the relevant release or
                     58: critical updates branch for your version, or Security Advisories will usually
                     59: contain information on the dates or revisions of the files containing the
                     60: specific fixes concerned. See [[Fetching by CVS|guide/fetch#cvs]] for more
                     61: details on the CVS commands used to update sources from these branches.
                     62: 
                     63: Once you have the sources available, you can create a custom kernel: this is not
                     64: as difficult as you might think. In fact, a new kernel can be created in a few
                     65: steps which will be described in the following sections.
                     66: 
                     67: ## Creating the kernel configuration file
                     68: 
                     69: The directories described in this section are i386 specific. Users of other
                     70: architectures must substitute the appropriate directories, see the
                     71: subdirectories of `src/sys/arch` for a list.
                     72: 
                     73: The kernel configuration file defines the type, the number and the
                     74: characteristics of the devices supported by the kernel as well as several kernel
                     75: configuration options. For the i386 port, kernel configuration files are located
                     76: in the `/usr/src/sys/arch/i386/conf` directory.
                     77: 
                     78: Please note that the names of the kernel configuration files are historically in
                     79: all uppercase, so they are easy to distinguish from other files in that
                     80: directory:
                     81: 
                     82:     $ cd /usr/src/sys/arch/i386/conf/
                     83:     $ ls
                     84:     CARDBUS                 GENERIC_PS2TINY         NET4501
                     85:     CVS                     GENERIC_TINY            SWINGER
                     86:     DELPHI                  GENERIC_VERIEXEC        SWINGER.MP
                     87:     DISKLESS                INSTALL                 VIRTUALPC
                     88:     GENERIC                 INSTALL.MP              files.i386
                     89:     GENERIC.FAST_IPSEC      INSTALL_LAPTOP          kern.ldscript
                     90:     GENERIC.MP              INSTALL_PS2             kern.ldscript.4MB
                     91:     GENERIC.MPDEBUG         INSTALL_SMALL           largepages.inc
                     92:     GENERIC.local           INSTALL_TINY            majors.i386
                     93:     GENERIC_DIAGNOSTIC      IOPENER                 std.i386
                     94:     GENERIC_ISDN            LAMB
                     95:     GENERIC_LAPTOP          Makefile.i386
                     96: 
                     97: The easiest way to create a new file is to copy an existing one and modify it.
                     98: Usually the best choice on most platforms is the GENERIC configuration, as it
                     99: contains most drivers and options. In the configuration file there are comments
                    100: describing the options; a more detailed description is found in the
                    101: [options(4)](http://netbsd.gw.com/cgi-bin/man-cgi?options+4+NetBSD-5.0.1+i386)
                    102: man page. So, the usual procedure is:
                    103: 
                    104:     $ cp GENERIC MYKERNEL
                    105:     $ vi MYKERNEL
                    106: 
                    107: The modification of a kernel configuration file basically involves three operations:
                    108: 
                    109:  1. support for hardware devices is included/excluded in the kernel (for
                    110:     example, SCSI support can be removed if it is not needed.)
                    111:  2. support for kernel features is enabled/disabled (for example, enable NFS
                    112:     client support, enable Linux compatibility, ...)
                    113:  3. tuning kernel parameters.
                    114: 
                    115: Lines beginning with `#` are comments; lines are disabled by commenting them
                    116: and enabled by removing the comment character. It is better to comment lines
                    117: instead of deleting them; it is always possible uncomment them later.
                    118: 
                    119: The output of the
                    120: [dmesg(8)](http://netbsd.gw.com/cgi-bin/man-cgi?dmesg+8+NetBSD-5.0.1+i386)
                    121: command can be used to determine which lines can be disabled. For each line of
                    122: the type:
                    123: 
                    124:     XXX at YYY
                    125: 
                    126: both `XXX` and `YYY` must be active in the kernel configuration file. You'll
                    127: probably have to experiment a bit before achieving a minimal configuration but
                    128: on a desktop system without SCSI and PCMCIA you can halve the kernel size.
                    129: 
                    130: You should also examine the options in the configuration file and disable the
                    131: ones that you don't need. Each option has a short comment describing it, which
                    132: is normally sufficient to understand what the option does. Many options have a
                    133: longer and more detailed description in the
                    134: [options(4)](http://netbsd.gw.com/cgi-bin/man-cgi?options+4+NetBSD-5.0.1+i386)
                    135: man page. While you are at it you should set correctly the options for local
                    136: time on the CMOS clock. For example:
                    137: 
                    138:     options RTC_OFFSET=-60
                    139: 
                    140: ## Building the kernel manually
                    141: 
                    142: Based on your kernel configuration file, either one of the standard
                    143: configurations or your customised configuration, a new kernel must be built.
                    144: 
                    145: These steps can either be performed manually, or using the `build.sh` command
                    146: that was introduced in section [Chapter 31, *Crosscompiling NetBSD with
                    147: `build.sh`*](chap-build.html "Chapter 31. Crosscompiling NetBSD with build.sh").
                    148: This section will give instructions on how to build a native kernel using manual
                    149: steps, the following section
                    150: [[Building the kernel using build.sh|guide/kernel#building_the_kernel_using_build.sh]]
                    151: describes how to use **build.sh** to do the same.
                    152: 
                    153:  * Configure the kernel
                    154:  * Generate dependencies
                    155:  * Compile the kernel
                    156: 
                    157: ### Configuring the kernel manually
                    158: 
                    159: When you've finished modifying the kernel configuration file (which we'll call
                    160: `MYKERNEL`), you should issue the following command:
                    161: 
                    162:     $ config MYKERNEL
                    163: 
                    164: If `MYKERNEL` contains no errors, the
                    165: [config(1)](http://netbsd.gw.com/cgi-bin/man-cgi?config+1+NetBSD-5.0.1+i386)
                    166: program will create the necessary files for the compilation of the kernel,
                    167: otherwise it will be necessary to correct the errors before running
                    168: [config(1)](http://netbsd.gw.com/cgi-bin/man-cgi?config+1+NetBSD-5.0.1+i386)
                    169: again.
                    170: 
                    171: ### Notes for crosscompilings
                    172: 
                    173: As the
                    174: [config(1)](http://netbsd.gw.com/cgi-bin/man-cgi?config+1+NetBSD-5.0.1+i386)
                    175: program used to create header files and Makefile for a kernel build is platform
                    176: specific, it is necessary to use the `nbconfig` program that's part of a newly
                    177: created toolchain (created for example with
                    178: 
1.4     ! mspo      179:     /usr/src/build.sh -m sparc64 tools
1.1       jdf       180: 
                    181: ). That aside, the procedure is just as like compiling a "native" NetBSD kernel.
                    182: The command is for example:
                    183: 
                    184:     % /usr/src/tooldir.NetBSD-4.0-i386/bin/nbconfig MYKERNEL
                    185: 
                    186: This command has created a directory `../compile/MYKERNEL` with a number of
                    187: header files defining information about devices to compile into the kernel, a
                    188: Makefile that is setup to build all the needed files for the kernel, and link
                    189: them together.
                    190: 
                    191: ### Generating dependencies and recompiling manually
                    192: 
                    193: Dependencies generation and kernel compilation is performed by the following
                    194: commands:
                    195: 
                    196:     $ cd ../compile/MYKERNEL
                    197:     $ make depend
                    198:     $ make
                    199: 
                    200: It can happen that the compilation stops with errors; there can be a variety of
                    201: reasons but the most common cause is an error in the configuration file which
                    202: didn't get caught by
                    203: [config(1)](http://netbsd.gw.com/cgi-bin/man-cgi?config+1+NetBSD-5.0.1+i386).
                    204: Sometimes the failure is caused by a hardware problem (often faulty RAM chips):
                    205: the compilation puts a higher stress on the system than most applications do.
                    206: Another typical error is the following: option B, active, requires option A
                    207: which is not active. A full compilation of the kernel can last from some minutes
                    208: to several hours, depending on the hardware.
                    209: 
                    210: The result of a successful make command is the `netbsd` file in the compile
                    211: directory, ready to be installed.
                    212: 
                    213: ### Notes for crosscompilings
                    214: 
                    215: For crosscompiling a sparc64 kernel, it is necessary to use the crosscompiler
                    216: toolchain's `nbmake-sparc64` shell wrapper, which calls
                    217: [make(1)](http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-5.0.1+i386) with
                    218: all the necessary settings for crosscompiling for a sparc64 platform:
                    219: 
                    220:     % cd ../compile/MYKERNEL/
                    221:     % /usr/src/tooldir.NetBSD-4.0-i386/bin/nbmake-sparc64 depend
                    222:     % /usr/src/tooldir.NetBSD-4.0-i386/bin/nbmake-sparc64
                    223: 
                    224: This will churn away a bit, then spit out a kernel:
                    225: 
                    226:     ...
                    227:     text    data     bss     dec     hex filename
                    228:     5016899  163728  628752 5809379  58a4e3 netbsd
                    229:     % ls -l netbsd
                    230:     -rwxr-xr-x  1 feyrer  666  5874663 Dec  2 23:17 netbsd
                    231:     % file netbsd
                    232:     netbsd: ELF 64-bit MSB executable, SPARC V9, version 1 (SYSV), statically linked, not stripped
                    233: 
                    234: Now the kernel in the file `netbsd` can either be transferred to an UltraSPARC
                    235: machine (via NFS, FTP, scp, etc.) and booted from a possible harddisk, or
                    236: directly from the cross-development machine using NFS.
                    237: 
1.2       jdf       238: ## Building the kernel using build.sh
1.1       jdf       239: 
                    240: After creating and possibly editing the kernel config file, the manual steps of
                    241: configuring the kernel, generating dependencies and recompiling can also be done
                    242: using the `src/build.sh` script, all in one go:
                    243: 
                    244:     $ cd /usr/src
                    245:     $ ./build.sh kernel=MYKERNEL
                    246: 
                    247: This will perform the same steps as above, with one small difference: before
                    248: compiling, all old object files will be removed, to start with a fresh build.
                    249: This is usually overkill, and it's fine to keep the old file and only rebuild
                    250: the ones whose dependencies have changed. To do this, add the `-u` option to
                    251: `build.sh`:
                    252: 
                    253:     $ cd /usr/src
                    254:     $ ./build.sh -u kernel=MYKERNEL
                    255: 
                    256: At the end of its job, `build.sh` will print out the location where the new
                    257: compiled kernel can be found. It can then be installed.
                    258: 
                    259: ## Installing the new kernel
                    260: 
                    261: Whichever method was used to produce the new kernel file, it must now be
                    262: installed. The new kernel file should be copied to the root directory, after
                    263: saving the previous version.
                    264: 
                    265:     # mv /netbsd /netbsd.old
                    266:     # mv netbsd /
                    267: 
                    268: Customization can considerably reduce the kernel's size. In the following
                    269: example `netbsd.old` is the install kernel and `netbsd` is the new kernel.
                    270: 
                    271:     -rwxr-xr-x  3 root  wheel  3523098 Dec 10 00:13 /netbsd
                    272:     -rwxr-xr-x  3 root  wheel  7566271 Dec 10 00:13 /netbsd.old
                    273: 
                    274: The new kernel is activated after rebooting:
                    275: 
                    276:     # shutdown -r now
                    277: 
                    278: ## If something went wrong
                    279: 
                    280: When the computer is restarted it can happen that the new kernel doesn't work as
                    281: expected or even doesn't boot at all. Don't worry: if this happens, just reboot
                    282: with the previously saved kernel and remove the new one (it is better to reboot
                    283: `single user`):
                    284: 
                    285:  * Reboot the machine
                    286:  * Press the space bar at the boot prompt during the 5 seconds countdown
                    287: 
                    288:         boot:
                    289: 
                    290:  * Type
                    291: 
                    292:         > boot netbsd.old -s
                    293: 
                    294:  * Now issue the following commands to restore the previous version of the kernel:
                    295: 
                    296:         # fsck /
                    297:         # mount /
                    298:         # mv netbsd.old netbsd
                    299:         # reboot
                    300: 
                    301: This will give you back the working system you started with, and you can revise
                    302: your custom kernel config file to resolve the problem. In general, it's wise to
                    303: start with a GENERIC kernel first, and then make gradual changes.
                    304: 
                    305: 

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb