1 Linux kernel !! 1 Linux kernel release 2.6.xx
2 ============ <<
3 2
4 There are several guides for kernel developers !! 3 These are the release notes for Linux version 2.6. Read them carefully,
5 be rendered in a number of formats, like HTML !! 4 as they tell you what this is all about, explain how to install the
6 Documentation/admin-guide/README.rst first. !! 5 kernel, and what to do if something goes wrong.
7 6
8 In order to build the documentation, use ``mak !! 7 WHAT IS LINUX?
9 ``make pdfdocs``. The formatted documentation <<
10 8
11 https://www.kernel.org/doc/html/latest/ !! 9 Linux is a Unix clone written from scratch by Linus Torvalds with
>> 10 assistance from a loosely-knit team of hackers across the Net.
>> 11 It aims towards POSIX compliance.
12 12
13 There are various text files in the Documentat !! 13 It has all the features you would expect in a modern fully-fledged
14 several of them using the reStructuredText mar !! 14 Unix, including true multitasking, virtual memory, shared libraries,
>> 15 demand loading, shared copy-on-write executables, proper memory
>> 16 management and TCP/IP networking.
>> 17
>> 18 It is distributed under the GNU General Public License - see the
>> 19 accompanying COPYING file for more details.
>> 20
>> 21 ON WHAT HARDWARE DOES IT RUN?
>> 22
>> 23 Linux was first developed for 386/486-based PCs. These days it also
>> 24 runs on ARMs, DEC Alphas, SUN Sparcs, M68000 machines (like Atari and
>> 25 Amiga), MIPS and PowerPC, and others.
>> 26
>> 27 DOCUMENTATION:
>> 28
>> 29 - There is a lot of documentation available both in electronic form on
>> 30 the Internet and in books, both Linux-specific and pertaining to
>> 31 general UNIX questions. I'd recommend looking into the documentation
>> 32 subdirectories on any Linux FTP site for the LDP (Linux Documentation
>> 33 Project) books. This README is not meant to be documentation on the
>> 34 system: there are much better sources available.
>> 35
>> 36 - There are various README files in the Documentation/ subdirectory:
>> 37 these typically contain kernel-specific installation notes for some
>> 38 drivers for example. See ./Documentation/00-INDEX for a list of what
>> 39 is contained in each file. Please read the Changes file, as it
>> 40 contains information about the problems, which may result by upgrading
>> 41 your kernel.
>> 42
>> 43 - The Documentation/DocBook/ subdirectory contains several guides for
>> 44 kernel developers and users. These guides can be rendered in a
>> 45 number of formats: PostScript (.ps), PDF, and HTML, among others.
>> 46 After installation, "make psdocs", "make pdfdocs", or "make htmldocs"
>> 47 will render the documentation in the requested format.
>> 48
>> 49 INSTALLING the kernel:
>> 50
>> 51 - If you install the full sources, put the kernel tarball in a
>> 52 directory where you have permissions (eg. your home directory) and
>> 53 unpack it:
>> 54
>> 55 gzip -cd linux-2.6.XX.tar.gz | tar xvf -
>> 56
>> 57 Replace "XX" with the version number of the latest kernel.
>> 58
>> 59 Do NOT use the /usr/src/linux area! This area has a (usually
>> 60 incomplete) set of kernel headers that are used by the library header
>> 61 files. They should match the library, and not get messed up by
>> 62 whatever the kernel-du-jour happens to be.
>> 63
>> 64 - You can also upgrade between 2.6.xx releases by patching. Patches are
>> 65 distributed in the traditional gzip and the new bzip2 format. To
>> 66 install by patching, get all the newer patch files, enter the
>> 67 top level directory of the kernel source (linux-2.6.xx) and execute:
>> 68
>> 69 gzip -cd ../patch-2.6.xx.gz | patch -p1
>> 70
>> 71 or
>> 72 bzip2 -dc ../patch-2.6.xx.bz2 | patch -p1
>> 73
>> 74 (repeat xx for all versions bigger than the version of your current
>> 75 source tree, _in_order_) and you should be ok. You may want to remove
>> 76 the backup files (xxx~ or xxx.orig), and make sure that there are no
>> 77 failed patches (xxx# or xxx.rej). If there are, either you or me has
>> 78 made a mistake.
>> 79
>> 80 Alternatively, the script patch-kernel can be used to automate this
>> 81 process. It determines the current kernel version and applies any
>> 82 patches found.
>> 83
>> 84 linux/scripts/patch-kernel linux
>> 85
>> 86 The first argument in the command above is the location of the
>> 87 kernel source. Patches are applied from the current directory, but
>> 88 an alternative directory can be specified as the second argument.
>> 89
>> 90 - Make sure you have no stale .o files and dependencies lying around:
>> 91
>> 92 cd linux
>> 93 make mrproper
>> 94
>> 95 You should now have the sources correctly installed.
>> 96
>> 97 SOFTWARE REQUIREMENTS
>> 98
>> 99 Compiling and running the 2.6.xx kernels requires up-to-date
>> 100 versions of various software packages. Consult
>> 101 ./Documentation/Changes for the minimum version numbers required
>> 102 and how to get updates for these packages. Beware that using
>> 103 excessively old versions of these packages can cause indirect
>> 104 errors that are very difficult to track down, so don't assume that
>> 105 you can just update packages when obvious problems arise during
>> 106 build or operation.
>> 107
>> 108 BUILD directory for the kernel:
>> 109
>> 110 When compiling the kernel all output files will per default be
>> 111 stored together with the kernel source code.
>> 112 Using the option "make O=output/dir" allow you to specify an alternate
>> 113 place for the output files (including .config).
>> 114 Example:
>> 115 kernel source code: /usr/src/linux-2.6.N
>> 116 build directory: /home/name/build/kernel
>> 117
>> 118 To configure and build the kernel use:
>> 119 cd /usr/src/linux-2.6.N
>> 120 make O=/home/name/build/kernel menuconfig
>> 121 make O=/home/name/build/kernel
>> 122 sudo make O=/home/name/build/kernel install_modules install
>> 123
>> 124 Please note: If the 'O=output/dir' option is used then it must be
>> 125 used for all invocations of make.
>> 126
>> 127 CONFIGURING the kernel:
>> 128
>> 129 Do not skip this step even if you are only upgrading one minor
>> 130 version. New configuration options are added in each release, and
>> 131 odd problems will turn up if the configuration files are not set up
>> 132 as expected. If you want to carry your existing configuration to a
>> 133 new version with minimal work, use "make oldconfig", which will
>> 134 only ask you for the answers to new questions.
>> 135
>> 136 - Alternate configuration commands are:
>> 137 "make menuconfig" Text based color menus, radiolists & dialogs.
>> 138 "make xconfig" X windows (Qt) based configuration tool.
>> 139 "make gconfig" X windows (Gtk) based configuration tool.
>> 140 "make oldconfig" Default all questions based on the contents of
>> 141 your existing ./.config file.
>> 142
>> 143 NOTES on "make config":
>> 144 - having unnecessary drivers will make the kernel bigger, and can
>> 145 under some circumstances lead to problems: probing for a
>> 146 nonexistent controller card may confuse your other controllers
>> 147 - compiling the kernel with "Processor type" set higher than 386
>> 148 will result in a kernel that does NOT work on a 386. The
>> 149 kernel will detect this on bootup, and give up.
>> 150 - A kernel with math-emulation compiled in will still use the
>> 151 coprocessor if one is present: the math emulation will just
>> 152 never get used in that case. The kernel will be slightly larger,
>> 153 but will work on different machines regardless of whether they
>> 154 have a math coprocessor or not.
>> 155 - the "kernel hacking" configuration details usually result in a
>> 156 bigger or slower kernel (or both), and can even make the kernel
>> 157 less stable by configuring some routines to actively try to
>> 158 break bad code to find kernel problems (kmalloc()). Thus you
>> 159 should probably answer 'n' to the questions for
>> 160 "development", "experimental", or "debugging" features.
>> 161
>> 162 - Check the top Makefile for further site-dependent configuration
>> 163 (default SVGA mode etc).
>> 164
>> 165 COMPILING the kernel:
>> 166
>> 167 - Make sure you have gcc 2.95.3 available.
>> 168 gcc 2.91.66 (egcs-1.1.2), and gcc 2.7.2.3 are known to miscompile
>> 169 some parts of the kernel, and are *no longer supported*.
>> 170 Also remember to upgrade your binutils package (for as/ld/nm and company)
>> 171 if necessary. For more information, refer to ./Documentation/Changes.
>> 172
>> 173 Please note that you can still run a.out user programs with this kernel.
>> 174
>> 175 - Do a "make bzImage" to create a compressed kernel image. If you want
>> 176 to make a boot disk (without root filesystem or LILO), insert a floppy
>> 177 in your A: drive, and do a "make bzdisk". It is also possible to do
>> 178 "make install" if you have lilo installed to suit the kernel makefiles,
>> 179 but you may want to check your particular lilo setup first.
>> 180
>> 181 To do the actual install you have to be root, but none of the normal
>> 182 build should require that. Don't take the name of root in vain.
>> 183
>> 184 - In the unlikely event that your system cannot boot bzImage kernels you
>> 185 can still compile your kernel as zImage. However, since zImage support
>> 186 will be removed at some point in the future in favor of bzImage we
>> 187 encourage people having problems with booting bzImage kernels to report
>> 188 these, with detailed hardware configuration information, to the
>> 189 linux-kernel mailing list and to H. Peter Anvin <hpa+linux@zytor.com>.
>> 190
>> 191 - If you configured any of the parts of the kernel as `modules', you
>> 192 will have to do "make modules" followed by "make modules_install".
>> 193
>> 194 - Keep a backup kernel handy in case something goes wrong. This is
>> 195 especially true for the development releases, since each new release
>> 196 contains new code which has not been debugged. Make sure you keep a
>> 197 backup of the modules corresponding to that kernel, as well. If you
>> 198 are installing a new kernel with the same version number as your
>> 199 working kernel, make a backup of your modules directory before you
>> 200 do a "make modules_install".
>> 201
>> 202 - In order to boot your new kernel, you'll need to copy the kernel
>> 203 image (found in .../linux/arch/i386/boot/bzImage after compilation)
>> 204 to the place where your regular bootable kernel is found.
>> 205
>> 206 For some, this is on a floppy disk, in which case you can copy the
>> 207 kernel bzImage file to /dev/fd0 to make a bootable floppy.
>> 208
>> 209 If you boot Linux from the hard drive, chances are you use LILO which
>> 210 uses the kernel image as specified in the file /etc/lilo.conf. The
>> 211 kernel image file is usually /vmlinuz, /boot/vmlinuz, /bzImage or
>> 212 /boot/bzImage. To use the new kernel, save a copy of the old image
>> 213 and copy the new image over the old one. Then, you MUST RERUN LILO
>> 214 to update the loading map!! If you don't, you won't be able to boot
>> 215 the new kernel image.
>> 216
>> 217 Reinstalling LILO is usually a matter of running /sbin/lilo.
>> 218 You may wish to edit /etc/lilo.conf to specify an entry for your
>> 219 old kernel image (say, /vmlinux.old) in case the new one does not
>> 220 work. See the LILO docs for more information.
>> 221
>> 222 After reinstalling LILO, you should be all set. Shutdown the system,
>> 223 reboot, and enjoy!
>> 224
>> 225 If you ever need to change the default root device, video mode,
>> 226 ramdisk size, etc. in the kernel image, use the 'rdev' program (or
>> 227 alternatively the LILO boot options when appropriate). No need to
>> 228 recompile the kernel to change these parameters.
>> 229
>> 230 - Reboot with the new kernel and enjoy.
>> 231
>> 232 IF SOMETHING GOES WRONG:
>> 233
>> 234 - If you have problems that seem to be due to kernel bugs, please check
>> 235 the file MAINTAINERS to see if there is a particular person associated
>> 236 with the part of the kernel that you are having trouble with. If there
>> 237 isn't anyone listed there, then the second best thing is to mail
>> 238 them to me (torvalds@osdl.org), and possibly to any other relevant
>> 239 mailing-list or to the newsgroup.
>> 240
>> 241 - In all bug-reports, *please* tell what kernel you are talking about,
>> 242 how to duplicate the problem, and what your setup is (use your common
>> 243 sense). If the problem is new, tell me so, and if the problem is
>> 244 old, please try to tell me when you first noticed it.
>> 245
>> 246 - If the bug results in a message like
>> 247
>> 248 unable to handle kernel paging request at address C0000010
>> 249 Oops: 0002
>> 250 EIP: 0010:XXXXXXXX
>> 251 eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx
>> 252 esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx
>> 253 ds: xxxx es: xxxx fs: xxxx gs: xxxx
>> 254 Pid: xx, process nr: xx
>> 255 xx xx xx xx xx xx xx xx xx xx
>> 256
>> 257 or similar kernel debugging information on your screen or in your
>> 258 system log, please duplicate it *exactly*. The dump may look
>> 259 incomprehensible to you, but it does contain information that may
>> 260 help debugging the problem. The text above the dump is also
>> 261 important: it tells something about why the kernel dumped code (in
>> 262 the above example it's due to a bad kernel pointer). More information
>> 263 on making sense of the dump is in Documentation/oops-tracing.txt
>> 264
>> 265 - You can use the "ksymoops" program to make sense of the dump. This
>> 266 utility can be downloaded from
>> 267 ftp://ftp.<country>.kernel.org/pub/linux/utils/kernel/ksymoops.
>> 268 Alternately you can do the dump lookup by hand:
>> 269
>> 270 - In debugging dumps like the above, it helps enormously if you can
>> 271 look up what the EIP value means. The hex value as such doesn't help
>> 272 me or anybody else very much: it will depend on your particular
>> 273 kernel setup. What you should do is take the hex value from the EIP
>> 274 line (ignore the "0010:"), and look it up in the kernel namelist to
>> 275 see which kernel function contains the offending address.
>> 276
>> 277 To find out the kernel function name, you'll need to find the system
>> 278 binary associated with the kernel that exhibited the symptom. This is
>> 279 the file 'linux/vmlinux'. To extract the namelist and match it against
>> 280 the EIP from the kernel crash, do:
>> 281
>> 282 nm vmlinux | sort | less
>> 283
>> 284 This will give you a list of kernel addresses sorted in ascending
>> 285 order, from which it is simple to find the function that contains the
>> 286 offending address. Note that the address given by the kernel
>> 287 debugging messages will not necessarily match exactly with the
>> 288 function addresses (in fact, that is very unlikely), so you can't
>> 289 just 'grep' the list: the list will, however, give you the starting
>> 290 point of each kernel function, so by looking for the function that
>> 291 has a starting address lower than the one you are searching for but
>> 292 is followed by a function with a higher address you will find the one
>> 293 you want. In fact, it may be a good idea to include a bit of
>> 294 "context" in your problem report, giving a few lines around the
>> 295 interesting one.
>> 296
>> 297 If you for some reason cannot do the above (you have a pre-compiled
>> 298 kernel image or similar), telling me as much about your setup as
>> 299 possible will help.
>> 300
>> 301 - Alternately, you can use gdb on a running kernel. (read-only; i.e. you
>> 302 cannot change values or set break points.) To do this, first compile the
>> 303 kernel with -g; edit arch/i386/Makefile appropriately, then do a "make
>> 304 clean". You'll also need to enable CONFIG_PROC_FS (via "make config").
>> 305
>> 306 After you've rebooted with the new kernel, do "gdb vmlinux /proc/kcore".
>> 307 You can now use all the usual gdb commands. The command to look up the
>> 308 point where your system crashed is "l *0xXXXXXXXX". (Replace the XXXes
>> 309 with the EIP value.)
>> 310
>> 311 gdb'ing a non-running kernel currently fails because gdb (wrongly)
>> 312 disregards the starting offset for which the kernel is compiled.
15 313
16 Please read the Documentation/process/changes. <<
17 requirements for building and running the kern <<
18 the problems which may result by upgrading you <<
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.