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.0.40)


  1 Linux kernel                                   << 
  2 ============                                   << 
  3                                                     1 
  4 This file was moved to Documentation/admin-gui !!   2         Linux kernel release 2.0.xx
  5                                                     3 
  6 Please notice that there are several guides fo !!   4 These are the release notes for linux version 2.0.  Read them carefully,
  7 These guides can be rendered in a number of fo !!   5 as they tell you what this is all about, explain how to install the
                                                   >>   6 kernel, and what to do if something goes wrong. 
  8                                                     7 
  9 In order to build the documentation, use ``mak !!   8 WHAT IS LINUX?
 10 ``make pdfdocs``.                              << 
 11                                                     9 
 12 There are various text files in the Documentat !!  10   Linux is a Unix clone written from scratch by Linus Torvalds with
 13 several of them using the Restructured Text ma !!  11   assistance from a loosely-knit team of hackers across the Net.
 14 See Documentation/00-INDEX for a list of what  !!  12   It aims towards POSIX compliance. 
                                                   >>  13 
                                                   >>  14   It has all the features you would expect in a modern fully-fledged
                                                   >>  15   Unix, including true multitasking, virtual memory, shared libraries,
                                                   >>  16   demand loading, shared copy-on-write executables, proper memory
                                                   >>  17   management and TCP/IP networking. 
                                                   >>  18 
                                                   >>  19   It is distributed under the GNU General Public License - see the
                                                   >>  20   accompanying COPYING file for more details. 
                                                   >>  21 
                                                   >>  22 ON WHAT HARDWARE DOES IT RUN?
                                                   >>  23 
                                                   >>  24   Linux was first developed for 386/486-based PCs.  These days it also
                                                   >>  25   runs on DEC Alphas, SUN Sparcs, M68000 machines (like Atari and Amiga),
                                                   >>  26   MIPS and PowerPC.
                                                   >>  27 
                                                   >>  28 DOCUMENTATION:
                                                   >>  29 
                                                   >>  30  - there is a lot of documentation available both in electronic form on
                                                   >>  31    the internet and in books, both Linux-specific and pertaining to
                                                   >>  32    general UNIX questions.  I'd recommend looking into the documentation
                                                   >>  33    subdirectories on any Linux ftp site for the LDP (Linux Documentation
                                                   >>  34    Project) books.  This README is not meant to be documentation on the
                                                   >>  35    system: there are much better sources available.
                                                   >>  36 
                                                   >>  37  - There are various readme's in the kernel Documentation/ subdirectory:
                                                   >>  38    these typically contain kernel-specific installation notes for some 
                                                   >>  39    drivers for example. See ./Documentation/00-INDEX for a list of what
                                                   >>  40    is contained in each file.
                                                   >>  41 
                                                   >>  42 INSTALLING the kernel:
                                                   >>  43 
                                                   >>  44  - If you install the full sources, do a
                                                   >>  45 
                                                   >>  46                 cd /usr/src
                                                   >>  47                 gzip -cd linux-2.0.XX.tar.gz | tar xfv -
                                                   >>  48 
                                                   >>  49    to get it all put in place. Replace "XX" with the version number of the
                                                   >>  50    latest kernel. If you use GNU tar, 
                                                   >>  51 
                                                   >>  52                 cd /usr/src
                                                   >>  53                 tar -xzvf linux-2.0.XX.tar.gz
                                                   >>  54 
                                                   >>  55    is equivalent.
                                                   >>  56 
                                                   >>  57  - You can also upgrade between 2.0.xx releases by patching.  Each
                                                   >>  58    patch that is released for 2.0.xx contains only bugfixes.  No
                                                   >>  59    new features will be added to the Linux kernel 2.0 any more. If
                                                   >>  60    you are interested in new kernel features, you may want to
                                                   >>  61    help developing a more recent kernel.
                                                   >>  62 
                                                   >>  63    To patch to a newer 2.0 kernel version, get all the newer files
                                                   >>  64    (you will find these patches at the kernel FTP servers:
                                                   >>  65     <URL:ftp://ftp.xx.kernel.org/pub/linux/kernel/v2.0/>, replace
                                                   >>  66     xx with your two letter country code here, e.g. se for Sweden),
                                                   >>  67    then do:
                                                   >>  68 
                                                   >>  69                 cd /usr/src/linux
                                                   >>  70                 gzip -cd patchXX.gz | patch -p0
                                                   >>  71 
                                                   >>  72    (repeat xx for all versions bigger than the version of your current
                                                   >>  73    source tree, _in_order_) and you should be ok.  You may want to remove
                                                   >>  74    the backup files (xxx~ or xxx.orig), and make sure that there are no
                                                   >>  75    failed patches (xxx# or xxx.rej). If there are, either you or me has
                                                   >>  76    made a mistake.
                                                   >>  77 
                                                   >>  78    Alternatively, the script patch-kernel can be used to automate this
                                                   >>  79    process.  It determines the current kernel version and applies any
                                                   >>  80    patches found.
                                                   >>  81 
                                                   >>  82                 cd /usr/src
                                                   >>  83                 linux/scripts/patch-kernel
                                                   >>  84 
                                                   >>  85    The default directory for the kernel source is /usr/src/linux, but
                                                   >>  86    can be specified as the first argument.  Patches are applied from
                                                   >>  87    the current directory, but an alternative directory can be specified
                                                   >>  88    as the second argument.
                                                   >>  89 
                                                   >>  90  - make sure you have no stale .o files and dependencies lying around:
                                                   >>  91 
                                                   >>  92                 cd /usr/src/linux
                                                   >>  93                 make mrproper
                                                   >>  94 
                                                   >>  95    You should now have the sources correctly installed.
                                                   >>  96 
                                                   >>  97 CONFIGURING the kernel:
                                                   >>  98 
                                                   >>  99  - do a "make config" to configure the basic kernel.  "make config"
                                                   >> 100    needs bash to work: it will search for bash in $BASH, /bin/bash and
                                                   >> 101    /bin/sh (in that order), so hopefully one of those is correct. 
                                                   >> 102 
                                                   >> 103  - Alternate configuration commands are:
                                                   >> 104         "make menuconfig"  Text based color menus, radiolists & dialogs.
                                                   >> 105         "make xconfig"     X window system based configuration tool.
                                                   >> 106    
                                                   >> 107         NOTES on "make config":
                                                   >> 108         - having unnecessary drivers will make the kernel bigger, and can
                                                   >> 109           under some circumstances lead to problems: probing for a
                                                   >> 110           nonexistent controller card may confuse your other controllers
                                                   >> 111         - compiling the kernel with "Processor type" set higher than 386
                                                   >> 112           will result in a kernel that does NOT work on a 386.  The
                                                   >> 113           kernel will detect this on bootup, and give up.
                                                   >> 114         - A kernel with math-emulation compiled in will still use the
                                                   >> 115           coprocessor if one is present: the math emulation will just
                                                   >> 116           never get used in that case.  The kernel will be slightly larger,
                                                   >> 117           but will work on different machines regardless of whether they
                                                   >> 118           have a math coprocessor or not. 
                                                   >> 119         - the "kernel hacking" configuration details usually result in a
                                                   >> 120           bigger or slower kernel (or both), and can even make the kernel
                                                   >> 121           less stable by configuring some routines to actively try to
                                                   >> 122           break bad code to find kernel problems (kmalloc()).  Thus you
                                                   >> 123           should probably answer 'n' to the questions for a "production"
                                                   >> 124           kernel. 
                                                   >> 125 
                                                   >> 126  - Check the top Makefile for further site-dependent configuration
                                                   >> 127    (default SVGA mode etc). 
                                                   >> 128 
                                                   >> 129  - Finally, do a "make dep" to set up all the dependencies correctly. 
                                                   >> 130 
                                                   >> 131 COMPILING the kernel:
                                                   >> 132 
                                                   >> 133  - make sure you have gcc-2.6.3 or newer available.  It seems older gcc
                                                   >> 134    versions can have problems compiling newer versions of linux.  If you
                                                   >> 135    upgrade your compiler, remember to get the new binutils package too
                                                   >> 136    (for as/ld/nm and company).
                                                   >> 137 
                                                   >> 138  - do a "make zImage" to create a compressed kernel image.  If you want
                                                   >> 139    to make a bootdisk (without root filesystem or lilo), insert a floppy
                                                   >> 140    in your A: drive, and do a "make zdisk".  It is also possible to do
                                                   >> 141    "make zlilo" if you have lilo installed to suit the kernel makefiles,
                                                   >> 142    but you may want to check your particular lilo setup first. 
                                                   >> 143 
                                                   >> 144  - if your kernel is too large for "make zImage", use "make bzImage"
                                                   >> 145    instead.
                                                   >> 146 
                                                   >> 147  - if you configured any of the parts of the kernel as `modules', you
                                                   >> 148    will have to do "make modules" followed by "make modules_install".
                                                   >> 149    Read Documentation/modules.txt for more information.  For example,
                                                   >> 150    an explanation of how to use the modules is included there.
                                                   >> 151 
                                                   >> 152  - keep a backup kernel handy in case something goes wrong.  This is 
                                                   >> 153    especially true for the development releases, since each new release
                                                   >> 154    contains new code which has not been debugged. 
                                                   >> 155 
                                                   >> 156  - In order to boot your new kernel, you'll need to copy the kernel
                                                   >> 157    image (found in /usr/src/linux/arch/i386/boot/zImage after compilation)
                                                   >> 158    to the place where your regular bootable kernel is found. 
                                                   >> 159 
                                                   >> 160    For some, this is on a floppy disk, in which case you can "cp
                                                   >> 161    /usr/src/linux/arch/i386/boot/zImage /dev/fd0" to make a bootable
                                                   >> 162    floppy.  Note that as of Linux 2.0.0, a kernel copied to a 720k
                                                   >> 163    double-density 3.5" floppy disk no longer boots.  In this case,
                                                   >> 164    it is highly recommended that you install LILO on your
                                                   >> 165    double-density bootfloppy or switch to high-density floppies.
                                                   >> 166 
                                                   >> 167    If you boot Linux from the hard drive, chances are you use LILO which
                                                   >> 168    uses the kernel image as specified in the file /etc/lilo.conf.  The
                                                   >> 169    kernel image file is usually /vmlinuz, /zImage, or /boot/vmlinuz. 
                                                   >> 170    To use the new kernel, copy the new image over the old one (save a
                                                   >> 171    backup of the original!).  Then, you MUST RERUN LILO to update the
                                                   >> 172    loading map!! If you don't, you won't be able to boot the new kernel
                                                   >> 173    image. 
                                                   >> 174 
                                                   >> 175    Reinstalling LILO is usually a matter of running /sbin/lilo. 
                                                   >> 176    You may wish to edit /etc/lilo.conf to specify an entry for your
                                                   >> 177    old kernel image (say, /vmlinux.old) in case the new one does not
                                                   >> 178    work.  See the LILO docs for more information. 
                                                   >> 179 
                                                   >> 180    After reinstalling LILO, you should be all set.  Shutdown the system,
                                                   >> 181    reboot, and enjoy!
                                                   >> 182 
                                                   >> 183    If you ever need to change the default root device, video mode,
                                                   >> 184    ramdisk size, etc.  in the kernel image, use the 'rdev' program (or
                                                   >> 185    alternatively the LILO boot options when appropriate).  No need to
                                                   >> 186    recompile the kernel to change these parameters. 
                                                   >> 187 
                                                   >> 188  - reboot with the new kernel and enjoy. 
                                                   >> 189 
                                                   >> 190 IF SOMETHING GOES WRONG:
                                                   >> 191 
                                                   >> 192  - if you have problems that seem to be due to kernel bugs, please check
                                                   >> 193    the file MAINTAINERS to see if there is a particular person associated
                                                   >> 194    with the part of the kernel that you are having trouble with. If there
                                                   >> 195    isn't anyone listed there, then the second best thing is to mail
                                                   >> 196    them to me (David Weinehall, tao@kernel.org), and possibly to any other
                                                   >> 197    relevant mailing-list or to the newsgroup.
                                                   >> 198 
                                                   >> 199  - In all bug-reports, *please* tell what kernel you are talking about,
                                                   >> 200    how to duplicate the problem, and what your setup is (use your common
                                                   >> 201    sense).  If the problem is new, tell me so, and if the problem is
                                                   >> 202    old, please try to tell me when you first noticed it.
                                                   >> 203 
                                                   >> 204  - if the bug results in a message like
                                                   >> 205 
                                                   >> 206         unable to handle kernel paging request at address C0000010
                                                   >> 207         Oops: 0002
                                                   >> 208         EIP:   0010:XXXXXXXX
                                                   >> 209         eax: xxxxxxxx   ebx: xxxxxxxx   ecx: xxxxxxxx   edx: xxxxxxxx
                                                   >> 210         esi: xxxxxxxx   edi: xxxxxxxx   ebp: xxxxxxxx
                                                   >> 211         ds: xxxx  es: xxxx  fs: xxxx  gs: xxxx
                                                   >> 212         Pid: xx, process nr: xx
                                                   >> 213         xx xx xx xx xx xx xx xx xx xx
                                                   >> 214 
                                                   >> 215    or similar kernel debugging information on your screen or in your
                                                   >> 216    system log, please duplicate it *exactly*.  The dump may look
                                                   >> 217    incomprehensible to you, but it does contain information that may
                                                   >> 218    help debugging the problem.  The text above the dump is also
                                                   >> 219    important: it tells something about why the kernel dumped code (in
                                                   >> 220    the above example it's due to a bad kernel pointer). More information
                                                   >> 221    on making sense of the dump is in Documentation/oops-tracing.txt
                                                   >> 222 
                                                   >> 223  - You can use the "ksymoops" program to make sense of the dump.  Find
                                                   >> 224    the C++ sources under the scripts/ directory to avoid having to do
                                                   >> 225    the dump lookup by hand:
                                                   >> 226 
                                                   >> 227  - in debugging dumps like the above, it helps enormously if you can
                                                   >> 228    look up what the EIP value means.  The hex value as such doesn't help
                                                   >> 229    me or anybody else very much: it will depend on your particular
                                                   >> 230    kernel setup.  What you should do is take the hex value from the EIP
                                                   >> 231    line (ignore the "0010:"), and look it up in the kernel namelist to
                                                   >> 232    see which kernel function contains the offending address.
                                                   >> 233 
                                                   >> 234    To find out the kernel function name, you'll need to find the system
                                                   >> 235    binary associated with the kernel that exhibited the symptom.  This is
                                                   >> 236    the file 'linux/vmlinux'.  To extract the namelist and match it against
                                                   >> 237    the EIP from the kernel crash, do:
                                                   >> 238 
                                                   >> 239                 nm vmlinux | sort | less
                                                   >> 240 
                                                   >> 241    This will give you a list of kernel addresses sorted in ascending
                                                   >> 242    order, from which it is simple to find the function that contains the
                                                   >> 243    offending address.  Note that the address given by the kernel
                                                   >> 244    debugging messages will not necessarily match exactly with the
                                                   >> 245    function addresses (in fact, that is very unlikely), so you can't
                                                   >> 246    just 'grep' the list: the list will, however, give you the starting
                                                   >> 247    point of each kernel function, so by looking for the function that
                                                   >> 248    has a starting address lower than the one you are searching for but
                                                   >> 249    is followed by a function with a higher address you will find the one
                                                   >> 250    you want.  In fact, it may be a good idea to include a bit of
                                                   >> 251    "context" in your problem report, giving a few lines around the
                                                   >> 252    interesting one. 
                                                   >> 253 
                                                   >> 254    If you for some reason cannot do the above (you have a pre-compiled
                                                   >> 255    kernel image or similar), telling me as much about your setup as
                                                   >> 256    possible will help. 
                                                   >> 257 
                                                   >> 258  - alternately, you can use gdb on a running kernel. (read-only; i.e. you
                                                   >> 259    cannot change values or set break points.) To do this, first compile the
                                                   >> 260    kernel with -g; edit arch/i386/Makefile appropriately, then do a "make
                                                   >> 261    clean". You'll also need to enable CONFIG_PROC_FS (via "make config").
                                                   >> 262 
                                                   >> 263    After you've rebooted with the new kernel, do "gdb vmlinux /proc/kcore".
                                                   >> 264    You can now use all the usual gdb commands. The command to look up the
                                                   >> 265    point where your system crashed is "l *0xXXXXXXXX". (Replace the XXXes
                                                   >> 266    with the EIP value.)
                                                   >> 267 
                                                   >> 268    gdb'ing a non-running kernel currently fails because gdb (wrongly)
                                                   >> 269    disregards the starting offset for which the kernel is compiled.
 15                                                   270 
 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