ia64/linux-2.6.18-xen.hg

annotate README @ 0:831230e53067

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