File:  [NetBSD Developer Wiki] / wikisrc / guide / kernel.mdwn
Revision 1.5: download - view: text, annotated - select for diffs
Fri Jun 19 19:18:31 2015 UTC (5 years ago) by plunky
Branches: MAIN
CVS tags: HEAD
replace direct links to manpages on netbsd.gw.com with templates

    1: **Contents**
    2: 
    3: [[!toc levels=3]]
    4: 
    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: [[!template id=man name="options" section="4"]]
  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: [[!template id=man name="dmesg" section="8"]]
  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: [[!template id=man name="options" section="4"]]
  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: [[!template id=man name="config" section="1"]]
  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: [[!template id=man name="config" section="1"]]
  169: again.
  170: 
  171: ### Notes for crosscompilings
  172: 
  173: As the
  174: [[!template id=man name="config" section="1"]]
  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: 
  179:     /usr/src/build.sh -m sparc64 tools
  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: [[!template id=man name="config" section="1"]].
  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: [[!template id=man name="make" section="1"]] 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: 
  238: ## Building the kernel using build.sh
  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