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

1.1     ! jdf         1: # Compiling the kernel
        !             2: 
        !             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:
        !             5: 
        !             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.
        !            20: 
        !            21: ## Requirements and procedure
        !            22: 
        !            23: To recompile the kernel you must have installed the compiler set (`comp.tgz`).
        !            24: 
        !            25: The basic steps to an updated or customised kernel then are:
        !            26: 
        !            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
        !            32: 
        !            33: 
        !            34: ## Installing the kernel sources
        !            35: 
        !            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.
        !            39: 
        !            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.
        !            43: 
        !            44: If you have a source tarball, you can extract it as root:
        !            45: 
        !            46:     # cd /
        !            47:     # tar zxf /path/to/syssrc.tgz
        !            48: 
        !            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.
        !            58: 
        !            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.
        !            62: 
        !            63: ## Creating the kernel configuration file
        !            64: 
        !            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.
        !            68: 
        !            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.
        !            73: 
        !            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:
        !            77: 
        !            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
        !            92: 
        !            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:
        !            99: 
        !           100:     $ cp GENERIC MYKERNEL
        !           101:     $ vi MYKERNEL
        !           102: 
        !           103: The modification of a kernel configuration file basically involves three operations:
        !           104: 
        !           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.
        !           110: 
        !           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.
        !           114: 
        !           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:
        !           119: 
        !           120:     XXX at YYY
        !           121: 
        !           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.
        !           125: 
        !           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:
        !           133: 
        !           134:     options RTC_OFFSET=-60
        !           135: 
        !           136: ## Building the kernel manually
        !           137: 
        !           138: Based on your kernel configuration file, either one of the standard
        !           139: configurations or your customised configuration, a new kernel must be built.
        !           140: 
        !           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.
        !           148: 
        !           149:  * Configure the kernel
        !           150:  * Generate dependencies
        !           151:  * Compile the kernel
        !           152: 
        !           153: ### Configuring the kernel manually
        !           154: 
        !           155: When you've finished modifying the kernel configuration file (which we'll call
        !           156: `MYKERNEL`), you should issue the following command:
        !           157: 
        !           158:     $ config MYKERNEL
        !           159: 
        !           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.
        !           166: 
        !           167: ### Notes for crosscompilings
        !           168: 
        !           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
        !           174: 
        !           175:     /usr/src/build.sh -m sparc64 tools/
        !           176: 
        !           177: ). That aside, the procedure is just as like compiling a "native" NetBSD kernel.
        !           178: The command is for example:
        !           179: 
        !           180:     % /usr/src/tooldir.NetBSD-4.0-i386/bin/nbconfig MYKERNEL
        !           181: 
        !           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.
        !           186: 
        !           187: ### Generating dependencies and recompiling manually
        !           188: 
        !           189: Dependencies generation and kernel compilation is performed by the following
        !           190: commands:
        !           191: 
        !           192:     $ cd ../compile/MYKERNEL
        !           193:     $ make depend
        !           194:     $ make
        !           195: 
        !           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.
        !           205: 
        !           206: The result of a successful make command is the `netbsd` file in the compile
        !           207: directory, ready to be installed.
        !           208: 
        !           209: ### Notes for crosscompilings
        !           210: 
        !           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:
        !           215: 
        !           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
        !           219: 
        !           220: This will churn away a bit, then spit out a kernel:
        !           221: 
        !           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
        !           229: 
        !           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.
        !           233: 
        !           234: ## Building the kernel using `build.sh`
        !           235: 
        !           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:
        !           239: 
        !           240:     $ cd /usr/src
        !           241:     $ ./build.sh kernel=MYKERNEL
        !           242: 
        !           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`:
        !           248: 
        !           249:     $ cd /usr/src
        !           250:     $ ./build.sh -u kernel=MYKERNEL
        !           251: 
        !           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.
        !           254: 
        !           255: ## Installing the new kernel
        !           256: 
        !           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.
        !           260: 
        !           261:     # mv /netbsd /netbsd.old
        !           262:     # mv netbsd /
        !           263: 
        !           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.
        !           266: 
        !           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
        !           269: 
        !           270: The new kernel is activated after rebooting:
        !           271: 
        !           272:     # shutdown -r now
        !           273: 
        !           274: ## If something went wrong
        !           275: 
        !           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`):
        !           280: 
        !           281:  * Reboot the machine
        !           282:  * Press the space bar at the boot prompt during the 5 seconds countdown
        !           283: 
        !           284:         boot:
        !           285: 
        !           286:  * Type
        !           287: 
        !           288:         > boot netbsd.old -s
        !           289: 
        !           290:  * Now issue the following commands to restore the previous version of the kernel:
        !           291: 
        !           292:         # fsck /
        !           293:         # mount /
        !           294:         # mv netbsd.old netbsd
        !           295:         # reboot
        !           296: 
        !           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.
        !           300: 
        !           301: 

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