Merge branch 'mauro-books' into docs-next

Merge Mauro's massive patch series creating the process and admin-guide
books.  I think there's a lot of stuff to clean up here, but there's no
point in holding things up for that.

Mauro sez:

This patch series continues the efforts of converting the Linux Kernel
documentation to Sphinx.

It contains text to ReST conversion of several files under Documentation,
and a few ones under the main dir (README, REPORTING-BUGS).

All patches on this series can be found on my development tree:
	https://git.linuxtv.org/mchehab/experimental.git/log/?h=lkml-books-v2

The Kernel docs html output after this series can be seen at:
	https://mchehab.fedorapeople.org/kernel_docs/

Documentation/00-INDEX

@@ -15,11 +15,11 @@ Following translations are available on the WWW:
 ABI/
 	- info on kernel <-> userspace ABI and relative interface stability.
 
-BUG-HUNTING
+admin-guide/bug-hunting.rst
 	- brute force method of doing binary search of patches to find bug.
-Changes
+process/changes.rst
 	- list of changes that break older software packages.
-CodingStyle
+process/coding-style.rst
 	- how the maintainers expect the C code in the kernel to look.
 DMA-API.txt
 	- DMA API, pci_ API & extensions for non-consistent memory machines.
@@ -33,7 +33,7 @@ DocBook/
 	- directory with DocBook templates etc. for kernel documentation.
 EDID/
 	- directory with info on customizing EDID for broken gfx/displays.
-HOWTO
+process/howto.rst
 	- the process and procedures of how to do Linux kernel development.
 IPMI.txt
 	- info on Linux Intelligent Platform Management Interface (IPMI) Driver.
@@ -48,7 +48,7 @@ Intel-IOMMU.txt
 Makefile
 	- This file does nothing. Removing it breaks make htmldocs and
 	  make distclean.
-ManagementStyle
+process/management-style.rst
 	- how to (attempt to) manage kernel hackers.
 RCU/
 	- directory with info on RCU (read-copy update).
@@ -56,13 +56,13 @@ SAK.txt
 	- info on Secure Attention Keys.
 SM501.txt
 	- Silicon Motion SM501 multimedia companion chip
-SecurityBugs
+admin-guide/security-bugs.rst
 	- procedure for reporting security bugs found in the kernel.
-SubmitChecklist
+process/submit-checklist.rst
 	- Linux kernel patch submission checklist.
-SubmittingDrivers
+process/submitting-drivers.rst
 	- procedure to get a new driver source included into the kernel tree.
-SubmittingPatches
+process/submitting-patches.rst
 	- procedure to get a source patch included into the kernel tree.
 VGA-softcursor.txt
 	- how to change your VGA cursor from a blinking underscore.
@@ -72,7 +72,7 @@ acpi/
 	- info on ACPI-specific hooks in the kernel.
 aoe/
 	- description of AoE (ATA over Ethernet) along with config examples.
-applying-patches.txt
+process/applying-patches.rst
 	- description of various trees and how to apply their patches.
 arm/
 	- directory with info about Linux on the ARM architecture.
@@ -86,7 +86,7 @@ auxdisplay/
 	- misc. LCD driver documentation (cfag12864b, ks0108).
 backlight/
 	- directory with info on controlling backlights in flat panel displays
-bad_memory.txt
+admin-guide/bad-memory.rst
 	- how to use kernel parameters to exclude bad RAM regions.
 basic_profiling.txt
 	- basic instructions for those who wants to profile Linux kernel.
@@ -150,11 +150,11 @@ debugging-via-ohci1394.txt
 	- how to use firewire like a hardware debugger memory reader.
 dell_rbu.txt
 	- document demonstrating the use of the Dell Remote BIOS Update driver.
-development-process/
+process/
 	- how to work with the mainline kernel development process.
 device-mapper/
 	- directory with info on Device Mapper.
-devices.txt
+admin-guide/devices.rst
 	- plain ASCII listing of all the nodes in /dev/ with major minor #'s.
 devicetree/
 	- directory with info on device tree files used by OF/PowerPC/ARM
@@ -166,8 +166,6 @@ dontdiff
 	- file containing a list of files that should never be diff'ed.
 driver-model/
 	- directory with info about Linux driver model.
-dvb/
-	- info on Linux Digital Video Broadcast (DVB) subsystem.
 dynamic-debug-howto.txt
 	- how to use the dynamic debug (dyndbg) feature.
 early-userspace/
@@ -178,7 +176,7 @@ efi-stub.txt
 	- How to use the EFI boot stub to bypass GRUB or elilo on EFI systems.
 eisa.txt
 	- info on EISA bus support.
-email-clients.txt
+process/email-clients.rst
 	- info on how to use e-mail to send un-mangled (git) patches.
 extcon/
 	- directory with porting guide for Android kernel switch driver.
@@ -226,9 +224,9 @@ ia64/
 	- directory with info about Linux on Intel 64 bit architecture.
 infiniband/
 	- directory with documents concerning Linux InfiniBand support.
-init.txt
+admin-guide/init.rst
 	- what to do when the kernel can't find the 1st process to run.
-initrd.txt
+admin-guide/initrd.rst
 	- how to use the RAM disk as an initial/temporary root filesystem.
 input/
 	- info on Linux input device support.
@@ -248,7 +246,7 @@ isapnp.txt
 	- info on Linux ISA Plug & Play support.
 isdn/
 	- directory with info on the Linux ISDN support, and supported cards.
-java.txt
+admin-guide/java.rst
 	- info on the in-kernel binary support for Java(tm).
 ja_JP/
 	- directory with Japanese translations of various documents
@@ -256,11 +254,11 @@ kbuild/
 	- directory with info about the kernel build process.
 kdump/
 	- directory with mini HowTo on getting the crash dump code to work.
-kernel-docs.txt
+process/kernel-docs.rst
 	- listing of various WWW + books that document kernel internals.
 kernel-documentation.rst
 	- how to write and format reStructuredText kernel documentation
-kernel-parameters.txt
+admin-guide/kernel-parameters.rst
 	- summary listing of command line / boot prompt args for the kernel.
 kernel-per-CPU-kthreads.txt
 	- List of all per-CPU kthreads and how they introduce jitter.
@@ -302,7 +300,7 @@ magic-number.txt
 	- list of magic numbers used to mark/protect kernel data structures.
 mailbox.txt
 	- How to write drivers for the common mailbox framework (IPC).
-md.txt
+admin-guide/md.rst
 	- info on boot arguments for the multiple devices driver.
 media-framework.txt
 	- info on media framework, its data structures, functions and usage.
@@ -326,7 +324,7 @@ module-signing.txt
 	- Kernel module signing for increased security when loading modules.
 mtd/
 	- directory with info about memory technology devices (flash)
-mono.txt
+admin-guide/mono.rst
 	- how to execute Mono-based .NET binaries with the help of BINFMT_MISC.
 namespaces/
 	- directory with various information about namespaces
@@ -340,7 +338,7 @@ nommu-mmap.txt
 	- documentation about no-mmu memory mapping support.
 numastat.txt
 	- info on how to read Numa policy hit/miss statistics in sysfs.
-oops-tracing.txt
+admin-guide/oops-tracing.rst
 	- how to decode those nasty internal kernel error dump messages.
 padata.txt
 	- An introduction to the "padata" parallel execution API
@@ -378,7 +376,7 @@ ptp/
 	- directory with info on support for IEEE 1588 PTP clocks in Linux.
 pwm.txt
 	- info on the pulse width modulation driver subsystem
-ramoops.txt
+admin-guide/ramoops.rst
 	- documentation of the ramoops oops/panic logging module.
 rapidio/
 	- directory with info on RapidIO packet-based fabric interconnect
@@ -406,7 +404,7 @@ security/
 	- directory that contains security-related info
 serial/
 	- directory with info on the low level serial API.
-serial-console.txt
+admin-guide/serial-console.rst
 	- how to set up Linux with a serial line console as the default.
 sgi-ioc4.txt
 	- description of the SGI IOC4 PCI (multi function) device.
@@ -420,9 +418,9 @@ sparse.txt
 	- info on how to obtain and use the sparse tool for typechecking.
 spi/
 	- overview of Linux kernel Serial Peripheral Interface (SPI) support.
-stable_api_nonsense.txt
+process/stable-api-nonsense.rst
 	- info on why the kernel does not have a stable in-kernel api or abi.
-stable_kernel_rules.txt
+process/stable-kernel-rules.rst
 	- rules and procedures for the -stable kernel releases.
 static-keys.txt
 	- info on how static keys allow debug code in hotpaths via patching
@@ -444,7 +442,7 @@ trace/
 	- directory with info on tracing technologies within linux
 unaligned-memory-access.txt
 	- info on how to avoid arch breaking unaligned memory access in code.
-unicode.txt
+admin-guide/unicode.rst
 	- info on the Unicode character/font mapping used in Linux.
 unshare.txt
 	- description of the Linux unshare system call.
@@ -458,15 +456,13 @@ vgaarbiter.txt
 	- info on enable/disable the legacy decoding on different VGA devices
 video-output.txt
 	- sysfs class driver interface to enable/disable a video output device.
-video4linux/
-	- directory with info regarding video/TV/radio cards and linux.
 virtual/
 	- directory with information on the various linux virtualizations.
 vm/
 	- directory with info on the Linux vm code.
 vme_api.txt
 	- file relating info on the VME bus API in linux
-volatile-considered-harmful.txt
+process/volatile-considered-harmful.rst
 	- Why the "volatile" type class should not be used
 w1/
 	- directory with documents regarding the 1-wire (w1) subsystem.

Documentation/ABI/README

@@ -84,4 +84,4 @@ stable:
 
 - Kernel-internal symbols.  Do not rely on the presence, absence, location, or
   type of any kernel symbol, either in System.map files or the kernel binary
-  itself.  See Documentation/stable_api_nonsense.txt.
+  itself.  See Documentation/process/stable-api-nonsense.rst.

Documentation/ABI/testing/sysfs-kernel-slab

@@ -347,7 +347,7 @@ Description:
 		because of fragmentation, SLUB will retry with the minimum order
 		possible depending on its characteristics.
 		When debug_guardpage_minorder=N (N > 0) parameter is specified
-		(see Documentation/kernel-parameters.txt), the minimum possible
+		(see Documentation/admin-guide/kernel-parameters.rst), the minimum possible
 		order is used and this sysfs entry can not be used to change
 		the order at run time.
 

Documentation/DocBook/kernel-hacking.tmpl

@@ -1208,8 +1208,8 @@ static struct block_device_operations opt_fops = {
    
    <listitem>
     <para>
-     Finally, don't forget to read <filename>Documentation/SubmittingPatches</filename>
-     and possibly <filename>Documentation/SubmittingDrivers</filename>.
+     Finally, don't forget to read <filename>Documentation/process/submitting-patches.rst</filename>
+     and possibly <filename>Documentation/process/submitting-drivers.rst</filename>.
     </para>
    </listitem>
   </itemizedlist>

Documentation/VGA-softcursor.txt

-Software cursor for VGA    by Pavel Machek <pavel@atrey.karlin.mff.cuni.cz>
-=======================    and Martin Mares <mj@atrey.karlin.mff.cuni.cz>
-
-   Linux now has some ability to manipulate cursor appearance. Normally, you
-can set the size of hardware cursor (and also work around some ugly bugs in
-those miserable Trident cards--see #define TRIDENT_GLITCH in drivers/video/
-vgacon.c). You can now play a few new tricks:  you can make your cursor look
-like a non-blinking red block, make it inverse background of the character it's
-over or to highlight that character and still choose whether the original
-hardware cursor should remain visible or not.  There may be other things I have
-never thought of.
-
-   The cursor appearance is controlled by a "<ESC>[?1;2;3c" escape sequence
-where 1, 2 and 3 are parameters described below. If you omit any of them,
-they will default to zeroes.
-
-   Parameter 1 specifies cursor size (0=default, 1=invisible, 2=underline, ...,
-8=full block) + 16 if you want the software cursor to be applied + 32 if you
-want to always change the background color + 64 if you dislike having the
-background the same as the foreground.  Highlights are ignored for the last two
-flags.
-
-   The second parameter selects character attribute bits you want to change
-(by simply XORing them with the value of this parameter). On standard VGA,
-the high four bits specify background and the low four the foreground. In both
-groups, low three bits set color (as in normal color codes used by the console)
-and the most significant one turns on highlight (or sometimes blinking--it
-depends on the configuration of your VGA).
-
-   The third parameter consists of character attribute bits you want to set.
-Bit setting takes place before bit toggling, so you can simply clear a bit by 
-including it in both the set mask and the toggle mask.
-
-Examples:
-=========
-
-To get normal blinking underline, use: echo -e '\033[?2c'
-To get blinking block, use:            echo -e '\033[?6c'
-To get red non-blinking block, use:    echo -e '\033[?17;0;64c'

Documentation/acpi/video_extension.txt

@@ -101,6 +101,6 @@ received a notification, it will set the backlight level accordingly. This does
 not affect the sending of event to user space, they are always sent to user
 space regardless of whether or not the video module controls the backlight level
 directly. This behaviour can be controlled through the brightness_switch_enabled
-module parameter as documented in kernel-parameters.txt. It is recommended to
+module parameter as documented in admin-guide/kernel-parameters.rst. It is recommended to
 disable this behaviour once a GUI environment starts up and wants to have full
 control of the backlight level.

Documentation/bad_memory.txt → Documentation/admin-guide/bad-memory.rst

+How to deal with bad memory e.g. reported by memtest86+ ?
+=========================================================
+
 March 2008
 Jan-Simon Moeller, dl9pf@gmx.de
 
 
-How to deal with bad memory e.g. reported by memtest86+ ?
-#########################################################
 
 There are three possibilities I know of:
 
@@ -19,6 +20,7 @@ This Howto is about number 3) .
 
 BadRAM
 ######
+
 BadRAM is the actively developed and available as kernel-patch
 here:  http://rick.vanrein.org/linux/badram/
 
@@ -31,15 +33,18 @@ memmap is already in the kernel and usable as kernel-parameter at
 boot-time.  Its syntax is slightly strange and you may need to
 calculate the values by yourself!
 
-Syntax to exclude a memory area (see kernel-parameters.txt for details):
-memmap=<size>$<address>
+Syntax to exclude a memory area (see admin-guide/kernel-parameters.rst for details)::
+
+	memmap=<size>$<address>
 
 Example: memtest86+ reported here errors at address 0x18691458, 0x18698424 and
-         some others. All had 0x1869xxxx in common, so I chose a pattern of
-         0x18690000,0xffff0000.
+some others. All had 0x1869xxxx in common, so I chose a pattern of
+0x18690000,0xffff0000.
+
+With the numbers of the example above::
+
+	memmap=64K$0x18690000
 
-With the numbers of the example above:
-memmap=64K$0x18690000
- or
-memmap=0x10000$0x18690000
+or::
 
+	memmap=0x10000$0x18690000

Documentation/basic_profiling.txt → Documentation/admin-guide/basic-profiling.rst

+Basic kernel profiling
+======================
+
+
 These instructions are deliberately very basic. If you want something clever,
-go read the real docs ;-) Please don't add more stuff, but feel free to 
+go read the real docs ;-)
+
+Please don't add more stuff, but feel free to
 correct my mistakes ;-)    (mbligh@aracnet.com)
+
 Thanks to John Levon, Dave Hansen, et al. for help writing this.
 
-<test> is the thing you're trying to measure.
-Make sure you have the correct System.map / vmlinux referenced!
+``<test>`` is the thing you're trying to measure.
+Make sure you have the correct ``System.map`` / ``vmlinux`` referenced!
 
-It is probably easiest to use "make install" for linux and hack
-/sbin/installkernel to copy vmlinux to /boot, in addition to vmlinuz,
-config, System.map, which are usually installed by default.
+It is probably easiest to use ``make install`` for linux and hack
+``/sbin/installkernel`` to copy ``vmlinux`` to ``/boot``, in addition to
+``vmlinuz``, ``config``, ``System.map``, which are usually installed by default.
 
 Readprofile
 -----------
-A recent readprofile command is needed for 2.6, such as found in util-linux
+
+A recent ``readprofile`` command is needed for 2.6, such as found in util-linux
 2.12a, which can be downloaded from:
 
-http://www.kernel.org/pub/linux/utils/util-linux/
+	http://www.kernel.org/pub/linux/utils/util-linux/
 
 Most distributions will ship it already.
 
-Add "profile=2" to the kernel command line.
+Add ``profile=2`` to the kernel command line.
 
-clear		readprofile -r
-		<test>
-dump output	readprofile -m /boot/System.map > captured_profile
+Some ``readprofile`` commands::
+
+	clear		readprofile -r
+			<test>
+	dump output	readprofile -m /boot/System.map > captured_profile
 
 Oprofile
 --------
 
 Get the source (see Changes for required version) from
-http://oprofile.sourceforge.net/ and add "idle=poll" to the kernel command
+http://oprofile.sourceforge.net/ and add ``idle=poll`` to the kernel command
 line.
 
-Configure with CONFIG_PROFILING=y and CONFIG_OPROFILE=y & reboot on new kernel
+Configure with ``CONFIG_PROFILING=y`` and ``CONFIG_OPROFILE=y`` & reboot on new kernel::
 
-./configure --with-kernel-support
-make install
+	./configure --with-kernel-support
+	make install
 
 For superior results, be sure to enable the local APIC. If opreport sees
 a 0Hz CPU, APIC was not on. Be aware that idle=poll may mean a performance
 penalty.
 
-One time setup:
-		opcontrol --setup --vmlinux=/boot/vmlinux
+One time setup::
+
+			opcontrol --setup --vmlinux=/boot/vmlinux
 
-clear		opcontrol --reset
-start		opcontrol --start
+Some ``opcontrol`` commands::
+
+	clear		opcontrol --reset
+	start		opcontrol --start
 		<test>
-stop		opcontrol --stop
-dump output	opreport >  output_file
+	stop		opcontrol --stop
+	dump output	opreport >  output_file
 
-To only report on the kernel, run opreport -l /boot/vmlinux > output_file
+To only report on the kernel, run ``opreport -l /boot/vmlinux > output_file``
 
 A reset is needed to clear old statistics, which survive a reboot.
-

Documentation/braille-console.txt → Documentation/admin-guide/braille-console.rst

-                       Linux Braille Console
+Linux Braille Console
+=====================
 
 To get early boot messages on a braille device (before userspace screen
 readers can start), you first need to compile the support for the usual serial
-console (see serial-console.txt), and for braille device (in Device Drivers -
-Accessibility).
+console (see :ref:`Documentation/admin-guide/serial-console.rst <serial_console>`), and
+for braille device
+(in :menuselection:`Device Drivers --> Accessibility support --> Console on braille device`).
 
-Then you need to specify a console=brl, option on the kernel command line, the
-format is:
+Then you need to specify a ``console=brl``, option on the kernel command line, the
+format is::
 
 	console=brl,serial_options...
 
-where serial_options... are the same as described in serial-console.txt
+where ``serial_options...`` are the same as described in
+:ref:`Documentation/admin-guide/serial-console.rst <serial_console>`.
 
-So for instance you can use console=brl,ttyS0 if the braille device is connected
-to the first serial port, and console=brl,ttyS0,115200 to override the baud rate
-to 115200, etc.
+So for instance you can use ``console=brl,ttyS0`` if the braille device is connected to the first serial port, and ``console=brl,ttyS0,115200`` to
+override the baud rate to 115200, etc.
 
 By default, the braille device will just show the last kernel message (console
 mode).  To review previous messages, press the Insert key to switch to the VT
 review mode.  In review mode, the arrow keys permit to browse in the VT content,
-page up/down keys go at the top/bottom of the screen, and the home key goes back
+:kbd:`PAGE-UP`/:kbd:`PAGE-DOWN` keys go at the top/bottom of the screen, and
+the :kbd:`HOME` key goes back
 to the cursor, hence providing very basic screen reviewing facility.
 
-Sound feedback can be obtained by adding the braille_console.sound=1 kernel
+Sound feedback can be obtained by adding the ``braille_console.sound=1`` kernel
 parameter.
 
 For simplicity, only one braille console can be enabled, other uses of
-console=brl,... will be discarded.  Also note that it does not interfere with
-the console selection mechanism described in serial-console.txt
+``console=brl,...`` will be discarded.  Also note that it does not interfere with
+the console selection mechanism described in
+:ref:`Documentation/admin-guide/serial-console.rst <serial_console>`.
 
 For now, only the VisioBraille device is supported.
 

Documentation/BUG-HUNTING → Documentation/admin-guide/bug-hunting.rst

-Table of contents
-=================
+Bug hunting
++++++++++++
 
 Last updated: 20 December 2005
 
-Contents
-========
-
-- Introduction
-- Devices not appearing
-- Finding patch that caused a bug
--- Finding using git-bisect
--- Finding it the old way
-- Fixing the bug
-
 Introduction
 ============
 
@@ -24,7 +14,8 @@ Finding bugs is not always easy. Have a go though. If you can't find it don't
 give up. Report as much as you have found to the relevant maintainer. See
 MAINTAINERS for who that is for the subsystem you have worked on.
 
-Before you submit a bug report read REPORTING-BUGS.
+Before you submit a bug report read
+:ref:`Documentation/admin-guide/reporting-bugs.rst <reportingbugs>`.
 
 Devices not appearing
 =====================
@@ -37,15 +28,16 @@ Finding patch that caused a bug
 
 
 
-Finding using git-bisect
-------------------------
+Finding using ``git-bisect``
+----------------------------
 
-Using the provided tools with git makes finding bugs easy provided the bug is
-reproducible.
+Using the provided tools with ``git`` makes finding bugs easy provided the bug
+is reproducible.
 
 Steps to do it:
+
 - start using git for the kernel source
-- read the man page for git-bisect
+- read the man page for ``git-bisect``
 - have fun
 
 Finding it the old way
@@ -58,22 +50,22 @@ It's a brute force approach but it works pretty well.
 
 You need:
 
-        . A reproducible bug - it has to happen predictably (sorry)
-        . All the kernel tar files from a revision that worked to the
+        - A reproducible bug - it has to happen predictably (sorry)
+        - All the kernel tar files from a revision that worked to the
           revision that doesn't
 
 You will then do:
 
-        . Rebuild a revision that you believe works, install, and verify that.
-        . Do a binary search over the kernels to figure out which one
+        - Rebuild a revision that you believe works, install, and verify that.
+        - Do a binary search over the kernels to figure out which one
           introduced the bug.  I.e., suppose 1.3.28 didn't have the bug, but
           you know that 1.3.69 does.  Pick a kernel in the middle and build
           that, like 1.3.50.  Build & test; if it works, pick the mid point
           between .50 and .69, else the mid point between .28 and .50.
-        . You'll narrow it down to the kernel that introduced the bug.  You
+        - You'll narrow it down to the kernel that introduced the bug.  You
           can probably do better than this but it gets tricky.
 
-        . Narrow it down to a subdirectory
+        - Narrow it down to a subdirectory
 
           - Copy kernel that works into "test".  Let's say that 3.62 works,
             but 3.63 doesn't.  So you diff -r those two kernels and come
@@ -83,7 +75,7 @@ You will then do:
                 Copy the non-working directory next to the working directory
                 as "dir.63".
                 One directory at time, try moving the working directory to
-                "dir.62" and mv dir.63 dir"time, try
+                "dir.62" and mv dir.63 dir"time, try::
 
                         mv dir dir.62
                         mv dir.63 dir
@@ -97,15 +89,15 @@ You will then do:
                 found in my case that they were self explanatory - you may
                 or may not want to give up when that happens.
 
-        . Narrow it down to a file
+        - Narrow it down to a file
 
           - You can apply the same technique to each file in the directory,
             hoping that the changes in that file are self contained.
 
-        . Narrow it down to a routine
+        - Narrow it down to a routine
 
           - You can take the old file and the new file and manually create
-            a merged file that has
+            a merged file that has::
 
                 #ifdef VER62
                 routine()
@@ -120,7 +112,7 @@ You will then do:
                 #endif
 
             And then walk through that file, one routine at a time and
-            prefix it with
+            prefix it with::
 
                 #define VER62
                 /* both routines here */
@@ -153,94 +145,105 @@ To debug a kernel, use objdump and look for the hex offset from the crash
 output to find the valid line of code/assembler. Without debug symbols, you
 will see the assembler code for the routine shown, but if your kernel has
 debug symbols the C code will also be available. (Debug symbols can be enabled
-in the kernel hacking menu of the menu configuration.) For example:
+in the kernel hacking menu of the menu configuration.) For example::
 
     objdump -r -S -l --disassemble net/dccp/ipv4.o
 
-NB.: you need to be at the top level of the kernel tree for this to pick up
-your C files.
+.. note::
+
+   You need to be at the top level of the kernel tree for this to pick up
+   your C files.
 
 If you don't have access to the code you can also debug on some crash dumps
-e.g. crash dump output as shown by Dave Miller.
-
->    EIP is at ip_queue_xmit+0x14/0x4c0
->     ...
->    Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00
->    00 00 55 57  56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08
->    <8b> 83 3c 01 00 00 89 44  24 14 8b 45 28 85 c0 89 44 24 18 0f 85
->
->    Put the bytes into a "foo.s" file like this:
->
->           .text
->           .globl foo
->    foo:
->           .byte  .... /* bytes from Code: part of OOPS dump */
->
->    Compile it with "gcc -c -o foo.o foo.s" then look at the output of
->    "objdump --disassemble foo.o".
->
->    Output:
->
->    ip_queue_xmit:
->        push       %ebp
->        push       %edi
->        push       %esi
->        push       %ebx
->        sub        $0xbc, %esp
->        mov        0xd0(%esp), %ebp        ! %ebp = arg0 (skb)
->        mov        0x8(%ebp), %ebx         ! %ebx = skb->sk
->        mov        0x13c(%ebx), %eax       ! %eax = inet_sk(sk)->opt
+e.g. crash dump output as shown by Dave Miller::
+
+     EIP is at ip_queue_xmit+0x14/0x4c0
+      ...
+     Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00
+     00 00 55 57  56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08
+     <8b> 83 3c 01 00 00 89 44  24 14 8b 45 28 85 c0 89 44 24 18 0f 85
+
+     Put the bytes into a "foo.s" file like this:
+
+            .text
+            .globl foo
+     foo:
+            .byte  .... /* bytes from Code: part of OOPS dump */
+
+     Compile it with "gcc -c -o foo.o foo.s" then look at the output of
+     "objdump --disassemble foo.o".
+
+     Output:
+
+     ip_queue_xmit:
+         push       %ebp
+         push       %edi
+         push       %esi
+         push       %ebx
+         sub        $0xbc, %esp
+         mov        0xd0(%esp), %ebp        ! %ebp = arg0 (skb)
+         mov        0x8(%ebp), %ebx         ! %ebx = skb->sk
+         mov        0x13c(%ebx), %eax       ! %eax = inet_sk(sk)->opt
 
 In addition, you can use GDB to figure out the exact file and line
-number of the OOPS from the vmlinux file. If you have
-CONFIG_DEBUG_INFO enabled, you can simply copy the EIP value from the
-OOPS:
+number of the OOPS from the ``vmlinux`` file. If you have
+``CONFIG_DEBUG_INFO`` enabled, you can simply copy the EIP value from the
+OOPS::
 
  EIP:    0060:[<c021e50e>]    Not tainted VLI
 
-And use GDB to translate that to human-readable form:
+And use GDB to translate that to human-readable form::
 
   gdb vmlinux
   (gdb) l *0xc021e50e
 
-If you don't have CONFIG_DEBUG_INFO enabled, you use the function
-offset from the OOPS:
+If you don't have ``CONFIG_DEBUG_INFO`` enabled, you use the function
+offset from the OOPS::
 
  EIP is at vt_ioctl+0xda8/0x1482
 
-And recompile the kernel with CONFIG_DEBUG_INFO enabled:
+And recompile the kernel with ``CONFIG_DEBUG_INFO`` enabled::
 
   make vmlinux
   gdb vmlinux
   (gdb) p vt_ioctl
   (gdb) l *(0x<address of vt_ioctl> + 0xda8)
-or, as one command
+
+or, as one command::
+
   (gdb) l *(vt_ioctl + 0xda8)
 
-If you have a call trace, such as :-
->Call Trace:
-> [<ffffffff8802c8e9>] :jbd:log_wait_commit+0xa3/0xf5
-> [<ffffffff810482d9>] autoremove_wake_function+0x0/0x2e
-> [<ffffffff8802770b>] :jbd:journal_stop+0x1be/0x1ee
-> ...
+If you have a call trace, such as::
+
+     Call Trace:
+      [<ffffffff8802c8e9>] :jbd:log_wait_commit+0xa3/0xf5
+      [<ffffffff810482d9>] autoremove_wake_function+0x0/0x2e
+      [<ffffffff8802770b>] :jbd:journal_stop+0x1be/0x1ee
+      ...
+
 this shows the problem in the :jbd: module. You can load that module in gdb
-and list the relevant code.
+and list the relevant code::
+
   gdb fs/jbd/jbd.ko
   (gdb) p log_wait_commit
   (gdb) l *(0x<address> + 0xa3)
-or
+
+or::
+
   (gdb) l *(log_wait_commit + 0xa3)
 
 
 Another very useful option of the Kernel Hacking section in menuconfig is
 Debug memory allocations. This will help you see whether data has been
 initialised and not set before use etc. To see the values that get assigned
-with this look at mm/slab.c and search for POISON_INUSE. When using this an
-Oops will often show the poisoned data instead of zero which is the default.
+with this look at ``mm/slab.c`` and search for ``POISON_INUSE``. When using
+this an Oops will often show the poisoned data instead of zero which is the
+default.
 
 Once you have worked out a fix please submit it upstream. After all open
 source is about sharing what you do and don't you want to be recognised for
 your genius?
 
-Please do read Documentation/SubmittingPatches though to help your code get
-accepted.
+Please do read
+ref:`Documentation/process/submitting-patches.rst <submittingpatches>` though
+to help your code get accepted.

Documentation/admin-guide/conf.py

+# -*- coding: utf-8; mode: python -*-
+
+project = 'Linux Kernel User Documentation'
+
+tags.add("subproject")
+
+latex_documents = [
+    ('index', 'linux-user.tex', 'Linux Kernel User Documentation',
+     'The kernel development community', 'manual'),
+]

Documentation/admin-guide/index.rst

+Linux Kernel User's Documentation
+=================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   README
+   reporting-bugs
+   bug-hunting
+   oops-tracing
+   ramoops
+   initrd
+   init
+   dynamic-debug-howto
+   security-bugs
+   kernel-parameters
+   serial-console
+   braille-console
+   parport
+   md
+   module-signing
+   sysrq
+   unicode
+   vga-softcursor
+   sysfs-rules
+   devices
+   binfmt-misc
+   mono
+   java
+   bad-memory
+   basic-profiling

Documentation/init.txt → Documentation/admin-guide/init.rst

@@ -5,6 +5,7 @@ OK, so you've got this pretty unintuitive message (currently located
 in init/main.c) and are wondering what the H*** went wrong.
 Some high-level reasons for failure (listed roughly in order of execution)
 to load the init binary are:
+
 A) Unable to mount root FS
 B) init binary doesn't exist on rootfs
 C) broken console device
@@ -12,37 +13,39 @@ D) binary exists but dependencies not available
 E) binary cannot be loaded
 
 Detailed explanations:
-0) Set "debug" kernel parameter (in bootloader config file or CONFIG_CMDLINE)
+
+A) Set "debug" kernel parameter (in bootloader config file or CONFIG_CMDLINE)
    to get more detailed kernel messages.
-A) make sure you have the correct root FS type
-   (and root= kernel parameter points to the correct partition),
+B) make sure you have the correct root FS type
+   (and ``root=`` kernel parameter points to the correct partition),
    required drivers such as storage hardware (such as SCSI or USB!)
    and filesystem (ext3, jffs2 etc.) are builtin (alternatively as modules,
    to be pre-loaded by an initrd)
-C) Possibly a conflict in console= setup --> initial console unavailable.
+C) Possibly a conflict in ``console= setup`` --> initial console unavailable.
    E.g. some serial consoles are unreliable due to serial IRQ issues (e.g.
    missing interrupt-based configuration).
-   Try using a different console= device or e.g. netconsole= .
+   Try using a different ``console= device`` or e.g. ``netconsole=``.
 D) e.g. required library dependencies of the init binary such as
-   /lib/ld-linux.so.2 missing or broken. Use readelf -d <INIT>|grep NEEDED
-   to find out which libraries are required.
+   ``/lib/ld-linux.so.2`` missing or broken. Use
+   ``readelf -d <INIT>|grep NEEDED`` to find out which libraries are required.
 E) make sure the binary's architecture matches your hardware.
    E.g. i386 vs. x86_64 mismatch, or trying to load x86 on ARM hardware.
    In case you tried loading a non-binary file here (shell script?),
    you should make sure that the script specifies an interpreter in its shebang
-   header line (#!/...) that is fully working (including its library
+   header line (``#!/...``) that is fully working (including its library
    dependencies). And before tackling scripts, better first test a simple
-   non-script binary such as /bin/sh and confirm its successful execution.
-   To find out more, add code to init/main.c to display kernel_execve()s
+   non-script binary such as ``/bin/sh`` and confirm its successful execution.
+   To find out more, add code ``to init/main.c`` to display kernel_execve()s
    return values.
 
 Please extend this explanation whenever you find new failure causes
 (after all loading the init binary is a CRITICAL and hard transition step
 which needs to be made as painless as possible), then submit patch to LKML.
 Further TODOs:
-- Implement the various run_init_process() invocations via a struct array
-  which can then store the kernel_execve() result value and on failure
-  log it all by iterating over _all_ results (very important usability fix).
+
+- Implement the various ``run_init_process()`` invocations via a struct array
+  which can then store the ``kernel_execve()`` result value and on failure
+  log it all by iterating over **all** results (very important usability fix).
 - try to make the implementation itself more helpful in general,
   e.g. by providing additional error messages at affected places.
 

Documentation/kernel-parameters.txt → Documentation/admin-guide/kernel-parameters.rst

-                          Kernel Parameters
-                          ~~~~~~~~~~~~~~~~~
+Kernel Parameters
+~~~~~~~~~~~~~~~~~
 
 The following is a consolidated list of the kernel parameters as
 implemented by the __setup(), core_param() and module_param() macros
@@ -14,7 +14,7 @@ environment, others are passed as command line arguments to init.
 Everything after "--" is passed as an argument to init.
 
 Module parameters can be specified in two ways: via the kernel command
-line with a module name prefix, or via modprobe, e.g.:
+line with a module name prefix, or via modprobe, e.g.::
 
 	(kernel command line) usbcore.blinkenlights=1
 	(modprobe command line) modprobe usbcore blinkenlights=1
@@ -25,12 +25,16 @@ kernel command line (/proc/cmdline) and collects module parameters
 when it loads a module, so the kernel command line can be used for
 loadable modules too.
 
-Hyphens (dashes) and underscores are equivalent in parameter names, so
+Hyphens (dashes) and underscores are equivalent in parameter names, so::
+
 	log_buf_len=1M print-fatal-signals=1
-can also be entered as
+
+can also be entered as::
+
 	log-buf-len=1M print_fatal_signals=1
 
-Double-quotes can be used to protect spaces in values, e.g.:
+Double-quotes can be used to protect spaces in values, e.g.::
+
 	param="spaces in here"
 
 cpu lists:
@@ -69,12 +73,12 @@ This document may not be entirely up to date and comprehensive. The command
 module. Loadable modules, after being loaded into the running kernel, also
 reveal their parameters in /sys/module/${modulename}/parameters/. Some of these
 parameters may be changed at runtime by the command
-"echo -n ${value} > /sys/module/${modulename}/parameters/${parm}".
+``echo -n ${value} > /sys/module/${modulename}/parameters/${parm}``.
 
 The parameters listed below are only valid if certain kernel build options were
 enabled and if respective hardware is present. The text in square brackets at
 the beginning of each description states the restrictions within which a
-parameter is applicable:
+parameter is applicable::
 
 	ACPI	ACPI support is enabled.
 	AGP	AGP (Accelerated Graphics Port) is enabled.
@@ -165,7 +169,7 @@ parameter is applicable:
 	X86_UV	SGI UV support is enabled.
 	XEN	Xen support is enabled
 
-In addition, the following text indicates that the option:
+In addition, the following text indicates that the option::
 
 	BUGS=	Relates to possible processor bugs on the said processor.
 	KNL	Is a kernel start-up parameter.
@@ -194,7 +198,7 @@ and is between 256 and 4096 characters. It is defined in the file
 Finally, the [KMG] suffix is commonly described after a number of kernel
 parameter values. These 'K', 'M', and 'G' letters represent the _binary_
 multipliers 'Kilo', 'Mega', and 'Giga', equalling 2^10, 2^20, and 2^30
-bytes respectively. Such letter suffixes can also be entirely omitted.
+bytes respectively. Such letter suffixes can also be entirely omitted::
 
 
 	acpi=		[HW,ACPI,X86,ARM64]
@@ -811,7 +815,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
 			bits, and "f" is flow control ("r" for RTS or
 			omit it).  Default is "9600n8".
 
-			See Documentation/serial-console.txt for more
+			See Documentation/admin-guide/serial-console.rst for more
 			information.  See
 			Documentation/networking/netconsole.txt for an
 			alternative.
@@ -2235,7 +2239,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
 	mce=option	[X86-64] See Documentation/x86/x86_64/boot-options.txt
 
 	md=		[HW] RAID subsystems devices and level
-			See Documentation/md.txt.
+			See Documentation/admin-guide/md.rst.
 
 	mdacon=		[MDA]
 			Format: <first>,<last>
@@ -2545,7 +2549,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
 			will be sent.
 			The default is to send the implementation identification
 			information.
-	
+
 	nfs.recover_lost_locks =
 			[NFSv4] Attempt to recover locks that were lost due
 			to a lease timeout on the server. Please note that
@@ -3318,7 +3322,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
 	r128=		[HW,DRM]
 
 	raid=		[HW,RAID]
-			See Documentation/md.txt.
+			See Documentation/admin-guide/md.rst.
 
 	ramdisk_size=	[RAM] Sizes of RAM disks in kilobytes
 			See Documentation/blockdev/ramdisk.txt.
@@ -4197,7 +4201,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
 			See also Documentation/input/joystick-parport.txt
 
 	udbg-immortal	[PPC] When debugging early kernel crashes that
-			happen after console_init() and before a proper 
+			happen after console_init() and before a proper
 			console driver takes over, this boot options might
 			help "seeing" what's going on.
 
@@ -4565,8 +4569,9 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
 			Format:
 			<irq>,<irq_mask>,<io>,<full_duplex>,<do_sound>,<lockup_hack>[,<irq2>[,<irq3>[,<irq4>]]]
 
-______________________________________________________________________
+------------------------
 
-TODO:
+Todo
+----
 
 	Add more DRM drivers.

Documentation/arm/Booting

@@ -51,7 +51,7 @@ As an alternative, the boot loader can pass the relevant 'console='
 option to the kernel via the tagged lists specifying the port, and
 serial format options as described in
 
-       Documentation/kernel-parameters.txt.
+       Documentation/admin-guide/kernel-parameters.rst.
 
 
 3. Detect the machine type

Documentation/atomic_ops.txt

@@ -16,7 +16,7 @@ will fail.  Something like the following should suffice:
 	typedef struct { long counter; } atomic_long_t;
 
 Historically, counter has been declared volatile.  This is now discouraged.
-See Documentation/volatile-considered-harmful.txt for the complete rationale.
+See Documentation/process/volatile-considered-harmful.rst for the complete rationale.
 
 local_t is very similar to atomic_t. If the counter is per CPU and only
 updated by one CPU, local_t is probably more appropriate. Please see