README: convert it to ReST markup · tjh.dev/kernel@44b1000

+58 -47

1 changed file

expand all

README

+58 -47

README

··· 1 - Linux kernel release 4.x <http://kernel.org/> 1 + Linux kernel release 4.x <http://kernel.org/> 2 + ============================================= 2 3 3 4 These are the release notes for Linux version 4. Read them carefully, 4 5 as they tell you what this is all about, explain how to install the 5 6 kernel, and what to do if something goes wrong. 6 7 7 - WHAT IS LINUX? 8 + What is Linux? 9 + -------------- 8 10 9 11 Linux is a clone of the operating system Unix, written from scratch by 10 12 Linus Torvalds with assistance from a loosely-knit team of hackers across ··· 20 18 It is distributed under the GNU General Public License - see the 21 19 accompanying COPYING file for more details. 22 20 23 - ON WHAT HARDWARE DOES IT RUN? 21 + On what hardware does it run? 22 + ----------------------------- 24 23 25 24 Although originally developed first for 32-bit x86-based PCs (386 or higher), 26 25 today Linux also runs on (at least) the Compaq Alpha AXP, Sun SPARC and ··· 37 34 Linux has also been ported to itself. You can now run the kernel as a 38 35 userspace application - this is called UserMode Linux (UML). 39 36 40 - DOCUMENTATION: 37 + Documentation 38 + ------------- 41 39 42 40 - There is a lot of documentation available both in electronic form on 43 41 the Internet and in books, both Linux-specific and pertaining to ··· 57 53 - The Documentation/DocBook/ subdirectory contains several guides for 58 54 kernel developers and users. These guides can be rendered in a 59 55 number of formats: PostScript (.ps), PDF, HTML, & man-pages, among others. 60 - After installation, "make psdocs", "make pdfdocs", "make htmldocs", 61 - or "make mandocs" will render the documentation in the requested format. 56 + After installation, ``make psdocs``, ``make pdfdocs``, ``make htmldocs``, 57 + or ``make mandocs`` will render the documentation in the requested format. 62 58 63 - INSTALLING the kernel source: 59 + Installing the kernel source 60 + ---------------------------- 64 61 65 62 - If you install the full sources, put the kernel tarball in a 66 63 directory where you have permissions (e.g. your home directory) and 67 - unpack it: 64 + unpack it:: 68 65 69 66 xz -cd linux-4.X.tar.xz | tar xvf - 70 67 ··· 79 74 - You can also upgrade between 4.x releases by patching. Patches are 80 75 distributed in the xz format. To install by patching, get all the 81 76 newer patch files, enter the top level directory of the kernel source 82 - (linux-4.X) and execute: 77 + (linux-4.X) and execute:: 83 78 84 79 xz -cd ../patch-4.x.xz | patch -p1 85 80 86 81 Replace "x" for all versions bigger than the version "X" of your current 87 - source tree, _in_order_, and you should be ok. You may want to remove 82 + source tree, **in_order**, and you should be ok. You may want to remove 88 83 the backup files (some-file-name~ or some-file-name.orig), and make sure 89 84 that there are no failed patches (some-file-name# or some-file-name.rej). 90 85 If there are, either you or I have made a mistake. ··· 95 90 and you want to apply the 4.0.3 patch, you must not first apply the 4.0.1 96 91 and 4.0.2 patches. Similarly, if you are running kernel version 4.0.2 and 97 92 want to jump to 4.0.3, you must first reverse the 4.0.2 patch (that is, 98 - patch -R) _before_ applying the 4.0.3 patch. You can read more on this in 99 - Documentation/applying-patches.txt 93 + patch -R) **before** applying the 4.0.3 patch. You can read more on this in 94 + :ref:`Documentation/applying-patches.txt <applying_patches>`. 100 95 101 96 Alternatively, the script patch-kernel can be used to automate this 102 97 process. It determines the current kernel version and applies any 103 - patches found. 98 + patches found:: 104 99 105 100 linux/scripts/patch-kernel linux 106 101 ··· 108 103 kernel source. Patches are applied from the current directory, but 109 104 an alternative directory can be specified as the second argument. 110 105 111 - - Make sure you have no stale .o files and dependencies lying around: 106 + - Make sure you have no stale .o files and dependencies lying around:: 112 107 113 108 cd linux 114 109 make mrproper 115 110 116 111 You should now have the sources correctly installed. 117 112 118 - SOFTWARE REQUIREMENTS 113 + Software requirements 114 + --------------------- 119 115 120 116 Compiling and running the 4.x kernels requires up-to-date 121 117 versions of various software packages. Consult 122 - Documentation/Changes for the minimum version numbers required 123 - and how to get updates for these packages. Beware that using 118 + :ref:`Documentation/Changes <changes>` for the minimum version numbers 119 + required and how to get updates for these packages. Beware that using 124 120 excessively old versions of these packages can cause indirect 125 121 errors that are very difficult to track down, so don't assume that 126 122 you can just update packages when obvious problems arise during 127 123 build or operation. 128 124 129 - BUILD directory for the kernel: 125 + Build directory for the kernel 126 + ------------------------------ 130 127 131 128 When compiling the kernel, all output files will per default be 132 129 stored together with the kernel source code. 133 - Using the option "make O=output/dir" allows you to specify an alternate 130 + Using the option ``make O=output/dir`` allows you to specify an alternate 134 131 place for the output files (including .config). 135 - Example: 132 + Example:: 136 133 137 134 kernel source code: /usr/src/linux-4.X 138 135 build directory: /home/name/build/kernel 139 136 140 - To configure and build the kernel, use: 137 + To configure and build the kernel, use:: 141 138 142 139 cd /usr/src/linux-4.X 143 140 make O=/home/name/build/kernel menuconfig 144 141 make O=/home/name/build/kernel 145 142 sudo make O=/home/name/build/kernel modules_install install 146 143 147 - Please note: If the 'O=output/dir' option is used, then it must be 144 + Please note: If the ``O=output/dir`` option is used, then it must be 148 145 used for all invocations of make. 149 146 150 - CONFIGURING the kernel: 147 + Configuring the kernel 148 + ---------------------- 151 149 152 150 Do not skip this step even if you are only upgrading one minor 153 151 version. New configuration options are added in each release, and 154 152 odd problems will turn up if the configuration files are not set up 155 153 as expected. If you want to carry your existing configuration to a 156 - new version with minimal work, use "make oldconfig", which will 154 + new version with minimal work, use ``make oldconfig``, which will 157 155 only ask you for the answers to new questions. 158 156 159 - - Alternative configuration commands are: 157 + - Alternative configuration commands are:: 160 158 161 159 "make config" Plain text interface. 162 160 ··· 231 223 You can find more information on using the Linux kernel config tools 232 224 in Documentation/kbuild/kconfig.txt. 233 225 234 - - NOTES on "make config": 226 + - NOTES on ``make config``: 235 227 236 228 - Having unnecessary drivers will make the kernel bigger, and can 237 229 under some circumstances lead to problems: probing for a ··· 250 242 should probably answer 'n' to the questions for "development", 251 243 "experimental", or "debugging" features. 252 244 253 - COMPILING the kernel: 245 + Compiling the kernel 246 + -------------------- 254 247 255 248 - Make sure you have at least gcc 3.2 available. 256 - For more information, refer to Documentation/Changes. 249 + For more information, refer to :ref:`Documentation/Changes <changes>`. 257 250 258 251 Please note that you can still run a.out user programs with this kernel. 259 252 260 - - Do a "make" to create a compressed kernel image. It is also 261 - possible to do "make install" if you have lilo installed to suit the 253 + - Do a ``make`` to create a compressed kernel image. It is also 254 + possible to do ``make install`` if you have lilo installed to suit the 262 255 kernel makefiles, but you may want to check your particular lilo setup first. 263 256 264 257 To do the actual install, you have to be root, but none of the normal 265 258 build should require that. Don't take the name of root in vain. 266 259 267 - - If you configured any of the parts of the kernel as `modules', you 268 - will also have to do "make modules_install". 260 + - If you configured any of the parts of the kernel as ``modules``, you 261 + will also have to do ``make modules_install``. 269 262 270 263 - Verbose kernel compile/build output: 271 264 ··· 274 265 totally silent). However, sometimes you or other kernel developers need 275 266 to see compile, link, or other commands exactly as they are executed. 276 267 For this, use "verbose" build mode. This is done by passing 277 - "V=1" to the "make" command, e.g. 268 + ``V=1`` to the ``make`` command, e.g.:: 278 269 279 270 make V=1 all 280 271 281 272 To have the build system also tell the reason for the rebuild of each 282 - target, use "V=2". The default is "V=0". 273 + target, use ``V=2``. The default is ``V=0``. 283 274 284 275 - Keep a backup kernel handy in case something goes wrong. This is 285 276 especially true for the development releases, since each new release ··· 287 278 backup of the modules corresponding to that kernel, as well. If you 288 279 are installing a new kernel with the same version number as your 289 280 working kernel, make a backup of your modules directory before you 290 - do a "make modules_install". 281 + do a ``make modules_install``. 291 282 292 283 Alternatively, before compiling, use the kernel config option 293 284 "LOCALVERSION" to append a unique suffix to the regular kernel version. ··· 317 308 reboot, and enjoy! 318 309 319 310 If you ever need to change the default root device, video mode, 320 - ramdisk size, etc. in the kernel image, use the 'rdev' program (or 311 + ramdisk size, etc. in the kernel image, use the ``rdev`` program (or 321 312 alternatively the LILO boot options when appropriate). No need to 322 313 recompile the kernel to change these parameters. 323 314 324 315 - Reboot with the new kernel and enjoy. 325 316 326 - IF SOMETHING GOES WRONG: 317 + If something goes wrong 318 + ----------------------- 327 319 328 320 - If you have problems that seem to be due to kernel bugs, please check 329 321 the file MAINTAINERS to see if there is a particular person associated ··· 338 328 sense). If the problem is new, tell me so, and if the problem is 339 329 old, please try to tell me when you first noticed it. 340 330 341 - - If the bug results in a message like 331 + - If the bug results in a message like:: 342 332 343 333 unable to handle kernel paging request at address C0000010 344 334 Oops: 0002 ··· 358 348 on making sense of the dump is in Documentation/oops-tracing.txt 359 349 360 350 - If you compiled the kernel with CONFIG_KALLSYMS you can send the dump 361 - as is, otherwise you will have to use the "ksymoops" program to make 351 + as is, otherwise you will have to use the ``ksymoops`` program to make 362 352 sense of the dump (but compiling with CONFIG_KALLSYMS is usually preferred). 363 353 This utility can be downloaded from 364 354 ftp://ftp.<country>.kernel.org/pub/linux/utils/kernel/ksymoops/ . ··· 368 358 look up what the EIP value means. The hex value as such doesn't help 369 359 me or anybody else very much: it will depend on your particular 370 360 kernel setup. What you should do is take the hex value from the EIP 371 - line (ignore the "0010:"), and look it up in the kernel namelist to 361 + line (ignore the ``0010:``), and look it up in the kernel namelist to 372 362 see which kernel function contains the offending address. 373 363 374 364 To find out the kernel function name, you'll need to find the system 375 365 binary associated with the kernel that exhibited the symptom. This is 376 366 the file 'linux/vmlinux'. To extract the namelist and match it against 377 - the EIP from the kernel crash, do: 367 + the EIP from the kernel crash, do:: 378 368 379 369 nm vmlinux | sort | less 380 370 ··· 393 383 394 384 If you for some reason cannot do the above (you have a pre-compiled 395 385 kernel image or similar), telling me as much about your setup as 396 - possible will help. Please read the REPORTING-BUGS document for details. 386 + possible will help. Please read the :ref:`REPORTING-BUGS <reportingbugs>` 387 + document for details. 397 388 398 389 - Alternatively, you can use gdb on a running kernel. (read-only; i.e. you 399 390 cannot change values or set break points.) To do this, first compile the 400 - kernel with -g; edit arch/x86/Makefile appropriately, then do a "make 401 - clean". You'll also need to enable CONFIG_PROC_FS (via "make config"). 391 + kernel with -g; edit arch/x86/Makefile appropriately, then do a ``make 392 + clean``. You'll also need to enable CONFIG_PROC_FS (via ``make config``). 402 393 403 - After you've rebooted with the new kernel, do "gdb vmlinux /proc/kcore". 394 + After you've rebooted with the new kernel, do ``gdb vmlinux /proc/kcore``. 404 395 You can now use all the usual gdb commands. The command to look up the 405 - point where your system crashed is "l *0xXXXXXXXX". (Replace the XXXes 396 + point where your system crashed is ``l *0xXXXXXXXX``. (Replace the XXXes 406 397 with the EIP value.) 407 398 408 - gdb'ing a non-running kernel currently fails because gdb (wrongly) 399 + gdb'ing a non-running kernel currently fails because ``gdb`` (wrongly) 409 400 disregards the starting offset for which the kernel is compiled. 410 401

Configure Feed

Configure Feed