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