1 Linux kernel !! 1 Linux kernel release 2.4.xx
2 ============ <<
3 2
4 There are several guides for kernel developers !! 3 These are the release notes for Linux version 2.4. 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.4.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.4.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.4.xx) and execute:
>> 68
>> 69 gzip -cd ../patch-2.4.xx.gz | patch -p1
>> 70
>> 71 or
>> 72 bzip2 -dc ../patch-2.4.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.4.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 CONFIGURING the kernel:
>> 109
>> 110 - Do a "make config" to configure the basic kernel. "make config" needs
>> 111 bash to work: it will search for bash in $BASH, /bin/bash and /bin/sh
>> 112 (in that order), so one of those must be correct for it to work.
>> 113
>> 114 Do not skip this step even if you are only upgrading one minor
>> 115 version. New configuration options are added in each release, and
>> 116 odd problems will turn up if the configuration files are not set up
>> 117 as expected. If you want to carry your existing configuration to a
>> 118 new version with minimal work, use "make oldconfig", which will
>> 119 only ask you for the answers to new questions.
>> 120
>> 121 - Alternate configuration commands are:
>> 122 "make menuconfig" Text based color menus, radiolists & dialogs.
>> 123 "make xconfig" X windows based configuration tool.
>> 124 "make oldconfig" Default all questions based on the contents of
>> 125 your existing ./.config file.
>> 126
>> 127 NOTES on "make config":
>> 128 - having unnecessary drivers will make the kernel bigger, and can
>> 129 under some circumstances lead to problems: probing for a
>> 130 nonexistent controller card may confuse your other controllers
>> 131 - compiling the kernel with "Processor type" set higher than 386
>> 132 will result in a kernel that does NOT work on a 386. The
>> 133 kernel will detect this on bootup, and give up.
>> 134 - A kernel with math-emulation compiled in will still use the
>> 135 coprocessor if one is present: the math emulation will just
>> 136 never get used in that case. The kernel will be slightly larger,
>> 137 but will work on different machines regardless of whether they
>> 138 have a math coprocessor or not.
>> 139 - the "kernel hacking" configuration details usually result in a
>> 140 bigger or slower kernel (or both), and can even make the kernel
>> 141 less stable by configuring some routines to actively try to
>> 142 break bad code to find kernel problems (kmalloc()). Thus you
>> 143 should probably answer 'n' to the questions for
>> 144 "development", "experimental", or "debugging" features.
>> 145
>> 146 - Check the top Makefile for further site-dependent configuration
>> 147 (default SVGA mode etc).
>> 148
>> 149 - Finally, do a "make dep" to set up all the dependencies correctly.
>> 150
>> 151 COMPILING the kernel:
>> 152
>> 153 - Make sure you have gcc 2.95.3 available. gcc 2.91.66 (egcs-1.1.2) may
>> 154 also work but is not as safe, and *gcc 2.7.2.3 is no longer supported*.
>> 155 gcc 4 is *not* supported.
>> 156 Also remember to upgrade your binutils package (for as/ld/nm and company)
>> 157 if necessary. For more information, refer to ./Documentation/Changes.
>> 158
>> 159 Please note that you can still run a.out user programs with this kernel.
>> 160
>> 161 - Do a "make bzImage" to create a compressed kernel image. If you want
>> 162 to make a boot disk (without root filesystem or LILO), insert a floppy
>> 163 in your A: drive, and do a "make bzdisk". It is also possible to do
>> 164 "make install" if you have lilo installed to suit the kernel makefiles,
>> 165 but you may want to check your particular lilo setup first.
>> 166
>> 167 To do the actual install you have to be root, but none of the normal
>> 168 build should require that. Don't take the name of root in vain.
>> 169
>> 170 - In the unlikely event that your system cannot boot bzImage kernels you
>> 171 can still compile your kernel as zImage. However, since zImage support
>> 172 will be removed at some point in the future in favor of bzImage we
>> 173 encourage people having problems with booting bzImage kernels to report
>> 174 these, with detailed hardware configuration information, to the
>> 175 linux-kernel mailing list and to H. Peter Anvin <hpa+linux@zytor.com>.
>> 176
>> 177 - If you configured any of the parts of the kernel as `modules', you
>> 178 will have to do "make modules" followed by "make modules_install".
>> 179 Read Documentation/modules.txt for more information. For example,
>> 180 an explanation of how to use the modules is included there.
>> 181
>> 182 - Keep a backup kernel handy in case something goes wrong. This is
>> 183 especially true for the development releases, since each new release
>> 184 contains new code which has not been debugged. Make sure you keep a
>> 185 backup of the modules corresponding to that kernel, as well. If you
>> 186 are installing a new kernel with the same version number as your
>> 187 working kernel, make a backup of your modules directory before you
>> 188 do a "make modules_install".
>> 189
>> 190 - In order to boot your new kernel, you'll need to copy the kernel
>> 191 image (found in .../linux/arch/i386/boot/bzImage after compilation)
>> 192 to the place where your regular bootable kernel is found.
>> 193
>> 194 For some, this is on a floppy disk, in which case you can copy the
>> 195 kernel bzImage file to /dev/fd0 to make a bootable floppy.
>> 196
>> 197 If you boot Linux from the hard drive, chances are you use LILO which
>> 198 uses the kernel image as specified in the file /etc/lilo.conf. The
>> 199 kernel image file is usually /vmlinuz, /boot/vmlinuz, /bzImage or
>> 200 /boot/bzImage. To use the new kernel, save a copy of the old image
>> 201 and copy the new image over the old one. Then, you MUST RERUN LILO
>> 202 to update the loading map!! If you don't, you won't be able to boot
>> 203 the new kernel image.
>> 204
>> 205 Reinstalling LILO is usually a matter of running /sbin/lilo.
>> 206 You may wish to edit /etc/lilo.conf to specify an entry for your
>> 207 old kernel image (say, /vmlinux.old) in case the new one does not
>> 208 work. See the LILO docs for more information.
>> 209
>> 210 After reinstalling LILO, you should be all set. Shutdown the system,
>> 211 reboot, and enjoy!
>> 212
>> 213 If you ever need to change the default root device, video mode,
>> 214 ramdisk size, etc. in the kernel image, use the 'rdev' program (or
>> 215 alternatively the LILO boot options when appropriate). No need to
>> 216 recompile the kernel to change these parameters.
>> 217
>> 218 - Reboot with the new kernel and enjoy.
>> 219
>> 220 IF SOMETHING GOES WRONG:
>> 221
>> 222 - If you have problems that seem to be due to kernel bugs, please check
>> 223 the file MAINTAINERS to see if there is a particular person associated
>> 224 with the part of the kernel that you are having trouble with. If there
>> 225 isn't anyone listed there, then the second best thing is to mail
>> 226 them to me (torvalds@transmeta.com), and possibly to any other
>> 227 relevant mailing-list or to the newsgroup. The mailing-lists are
>> 228 useful especially for SCSI and networking problems, as I can't test
>> 229 either of those personally anyway.
>> 230
>> 231 - In all bug-reports, *please* tell what kernel you are talking about,
>> 232 how to duplicate the problem, and what your setup is (use your common
>> 233 sense). If the problem is new, tell me so, and if the problem is
>> 234 old, please try to tell me when you first noticed it.
>> 235
>> 236 - If the bug results in a message like
>> 237
>> 238 unable to handle kernel paging request at address C0000010
>> 239 Oops: 0002
>> 240 EIP: 0010:XXXXXXXX
>> 241 eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx
>> 242 esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx
>> 243 ds: xxxx es: xxxx fs: xxxx gs: xxxx
>> 244 Pid: xx, process nr: xx
>> 245 xx xx xx xx xx xx xx xx xx xx
>> 246
>> 247 or similar kernel debugging information on your screen or in your
>> 248 system log, please duplicate it *exactly*. The dump may look
>> 249 incomprehensible to you, but it does contain information that may
>> 250 help debugging the problem. The text above the dump is also
>> 251 important: it tells something about why the kernel dumped code (in
>> 252 the above example it's due to a bad kernel pointer). More information
>> 253 on making sense of the dump is in Documentation/oops-tracing.txt
>> 254
>> 255 - You can use the "ksymoops" program to make sense of the dump. This
>> 256 utility can be downloaded from
>> 257 ftp://ftp.<country>.kernel.org/pub/linux/utils/kernel/ksymoops.
>> 258 Alternately you can do the dump lookup by hand:
>> 259
>> 260 - In debugging dumps like the above, it helps enormously if you can
>> 261 look up what the EIP value means. The hex value as such doesn't help
>> 262 me or anybody else very much: it will depend on your particular
>> 263 kernel setup. What you should do is take the hex value from the EIP
>> 264 line (ignore the "0010:"), and look it up in the kernel namelist to
>> 265 see which kernel function contains the offending address.
>> 266
>> 267 To find out the kernel function name, you'll need to find the system
>> 268 binary associated with the kernel that exhibited the symptom. This is
>> 269 the file 'linux/vmlinux'. To extract the namelist and match it against
>> 270 the EIP from the kernel crash, do:
>> 271
>> 272 nm vmlinux | sort | less
>> 273
>> 274 This will give you a list of kernel addresses sorted in ascending
>> 275 order, from which it is simple to find the function that contains the
>> 276 offending address. Note that the address given by the kernel
>> 277 debugging messages will not necessarily match exactly with the
>> 278 function addresses (in fact, that is very unlikely), so you can't
>> 279 just 'grep' the list: the list will, however, give you the starting
>> 280 point of each kernel function, so by looking for the function that
>> 281 has a starting address lower than the one you are searching for but
>> 282 is followed by a function with a higher address you will find the one
>> 283 you want. In fact, it may be a good idea to include a bit of
>> 284 "context" in your problem report, giving a few lines around the
>> 285 interesting one.
>> 286
>> 287 If you for some reason cannot do the above (you have a pre-compiled
>> 288 kernel image or similar), telling me as much about your setup as
>> 289 possible will help.
>> 290
>> 291 - Alternately, you can use gdb on a running kernel. (read-only; i.e. you
>> 292 cannot change values or set break points.) To do this, first compile the
>> 293 kernel with -g; edit arch/i386/Makefile appropriately, then do a "make
>> 294 clean". You'll also need to enable CONFIG_PROC_FS (via "make config").
>> 295
>> 296 After you've rebooted with the new kernel, do "gdb vmlinux /proc/kcore".
>> 297 You can now use all the usual gdb commands. The command to look up the
>> 298 point where your system crashed is "l *0xXXXXXXXX". (Replace the XXXes
>> 299 with the EIP value.)
>> 300
>> 301 gdb'ing a non-running kernel currently fails because gdb (wrongly)
>> 302 disregards the starting offset for which the kernel is compiled.
15 303
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.