Version:  2.0.40 2.2.26 2.4.37 3.13 3.14 3.15 3.16 3.17 3.18 3.19 4.0 4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8 4.9 4.10

Linux/README

Diff markup

Differences between /README (Version 4.10) and /README (Version 2.4.37)


  1 Linux kernel                                   !!   1         Linux kernel release 2.4.xx
  2 ============                                   << 
  3                                                     2 
  4 This file was moved to Documentation/admin-gui !!   3 These are the release notes for Linux version 2.4.  Read them carefully,
                                                   >>   4 as they tell you what this is all about, explain how to install the
                                                   >>   5 kernel, and what to do if something goes wrong. 
  5                                                     6 
  6 Please notice that there are several guides fo !!   7 WHAT IS LINUX?
  7 These guides can be rendered in a number of fo << 
  8                                                     8 
  9 In order to build the documentation, use ``mak !!   9   Linux is a Unix clone written from scratch by Linus Torvalds with
 10 ``make pdfdocs``.                              !!  10   assistance from a loosely-knit team of hackers across the Net.
                                                   >>  11   It aims towards POSIX compliance. 
 11                                                    12 
 12 There are various text files in the Documentat !!  13   It has all the features you would expect in a modern fully-fledged
 13 several of them using the Restructured Text ma !!  14   Unix, including true multitasking, virtual memory, shared libraries,
 14 See Documentation/00-INDEX for a list of what  !!  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 << 
                                                      

This page was automatically generated by LXR 0.3.1 (source).  •  Linux is a registered trademark of Linus Torvalds  •  Contact us