[PATCH 00/11] Organize and clean up the admin and process guides

[PATCH 00/11] Organize and clean up the admin and process guides

[Jonathan Corbet]

The creation of the admin and process guides is a great thing, but, without
care, we risk replacing a messy docs directory with a few messy Sphinx
books.  In an attempt to head that off and show what I'm thinking, here's a
set of tweaks that, I think, make the existing Sphinx-formatted docs a bit
more accessible.

Hopefully none of this is too controversial.  That's probably too much to
hope for in the case of the deleted documents, though, since deleting
anything seems to be an uphill battle.

Jonathan Corbet (11):
  docs: Tweak the top-level Sphinx page
  docs: retitle the kernel-documentation.rst
  docs: Clean up and organize the admin guide a bit
  docs: Get rid of the badRAM guide
  docs: Get rid of the "basic profiling" guide
  docs: Get rid of the "bug-hunting" guide
  docs: Apply some basic organization to the process guide
  docs: Tweak submitting-patches.rst formatting
  docs: Collapse the process guide TOC
  docs: add a warning to submitting-drivers.rst
  docs: Add a warning to applying-patches.rst

 Documentation/admin-guide/bad-memory.rst        |  50 -----
 Documentation/admin-guide/basic-profiling.rst   |  68 -------
 Documentation/admin-guide/bug-hunting.rst       | 249 ------------------------
 Documentation/admin-guide/index.rst             |  53 +++--
 Documentation/admin-guide/kernel-parameters.rst |   4 +-
 Documentation/admin-guide/sysfs-rules.rst       |   4 +-
 Documentation/admin-guide/vga-softcursor.rst    |   4 +-
 Documentation/index.rst                         |  45 ++++-
 Documentation/kernel-documentation.rst          |   6 +-
 Documentation/process/applying-patches.rst      |   4 +
 Documentation/process/changes.rst               |   2 +-
 Documentation/process/index.rst                 |  39 +++-
 Documentation/process/submitting-drivers.rst    |   8 +
 Documentation/process/submitting-patches.rst    |  16 +-
 14 files changed, 137 insertions(+), 415 deletions(-)
 delete mode 100644 Documentation/admin-guide/bad-memory.rst
 delete mode 100644 Documentation/admin-guide/basic-profiling.rst
 delete mode 100644 Documentation/admin-guide/bug-hunting.rst

-- 
2.7.4

[PATCH 01/11] docs: Tweak the top-level Sphinx page

[Jonathan Corbet]

This will be the initial landing point for readers, so give them a bit of
introductory material.  Also split the TOC into area-specific chunks to
make the whole thing a bit more approachable.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/index.rst | 45 +++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 41 insertions(+), 4 deletions(-)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index f6a3d4766495..7cec8432ce7a 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -3,18 +3,55 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to The Linux Kernel's documentation!
-============================================
+Welcome to The Linux Kernel's documentation
+===========================================
 
-Contents:
+This is the top level of the kernel's documentation tree.  Kernel
+documentation, like the kernel itself, is very much a work in progress;
+that is especially true as we work to integrate our many scattered
+documents into a coherent whole.  Please note that improvements to the
+documentation are welcome; join the linux-doc list at vger.kernel.org if
+you want to help out.
+
+User-oriented documentation
+---------------------------
+
+The following manuals are written for *users* of the kernel — those who are
+trying to get it to work optimally on a given system.
 
 .. toctree::
    :maxdepth: 2
 
    admin-guide/index
-   kernel-documentation
+
+Introduction to kernel development
+----------------------------------
+
+These manuals contain overall information about how to develop the kernel.
+The kernel community is quite large, with thousands of developers
+contributing over the course of a year.  As with any large community,
+knowing how things are done will make the process of getting your changes
+merged much easier.
+
+.. toctree::
+   :maxdepth: 2
+
    process/index
    dev-tools/tools
+   kernel-documentation
+
+Kernel API documentation
+------------------------
+
+These books get into the details of how specific kernel subsystems work
+from the point of view of a kernel developer.  Much of the information here
+is taken directly from the kernel source, with supplemental material added
+as needed (or at least as we managed to add it — probably *not* all that is
+needed). 
+
+.. toctree::
+   :maxdepth: 2
+
    driver-api/index
    media/index
    gpu/index
-- 
2.7.4

[PATCH 02/11] docs: retitle the kernel-documentation.rst

[Jonathan Corbet]

Let's make the title of this document (which shows up in the top page)
better describe its contents.

Cc: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/kernel-documentation.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
index 10cc7ddb6235..c66ab937c2ca 100644
--- a/Documentation/kernel-documentation.rst
+++ b/Documentation/kernel-documentation.rst
@@ -1,6 +1,6 @@
-==========================
-Linux Kernel Documentation
-==========================
+=================================
+How to write kernel documentation
+=================================
 
 Introduction
 ============
-- 
2.7.4

[PATCH 03/11] docs: Clean up and organize the admin guide a bit

[Jonathan Corbet]

The admin guide is a good start, but it's time to turn it into something
better than an unordered blob of files.  This is a first step in that
direction.  The TOC has been split up and annotated, the guides have been
reordered, and minor tweaks have been applied to a few of them.

One consequence of splitting up the TOC is that we don't really want to use
:numbered: anymore, since the count resets every time and there doesn't
seem to be a way to change that.  Eventually we probably want to group the
documents into sub-books, at which point we can go back to a single TOC,
but it's probably early to do that.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/admin-guide/index.rst             | 50 +++++++++++++++++++------
 Documentation/admin-guide/kernel-parameters.rst |  4 +-
 Documentation/admin-guide/sysfs-rules.rst       |  4 +-
 Documentation/admin-guide/vga-softcursor.rst    |  4 +-
 4 files changed, 45 insertions(+), 17 deletions(-)

diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 4e5abbb4bbd5..2ce2bf02824b 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -1,22 +1,52 @@
-Linux Kernel User's Documentation
-=================================
+The Linux kernel user's and administrator's guide
+=================================================
 
-Contents:
+The following is a collection of user-oriented documents that have been
+added to the kernel over time.  There is, as yet, little overall order or
+organization here — this material was not written to be a single, coherent
+document!  With luck things will improve quickly over time.
+
+This initial section contains overall information, including the README
+file describing the kernel as a whole, documentation on kernel parameters,
+etc. 
 
 .. toctree::
-   :maxdepth: 2
-   :numbered:
+   :maxdepth: 1
 
    README
+   kernel-parameters
+   devices
+
+Here is a set of documents aimed at users who are trying to track down
+problems and bugs in particular.
+
+.. toctree::
+   :maxdepth: 1
+   
    reporting-bugs
+   security-bugs
    bug-hunting
    oops-tracing
    ramoops
-   initrd
-   init
    dynamic-debug-howto
-   security-bugs
-   kernel-parameters
+   init
+
+This is the beginning of a section with information of interest to
+application developers.  Documents covering various aspects of the kernel
+ABI will be found here.
+
+.. toctree::
+   :maxdepth: 1
+   
+   sysfs-rules
+
+The rest of this manual consists of various unordered guides on how to
+configure specific aspects of kernel behavior to your liking.
+
+.. toctree::
+   :maxdepth: 1
+   
+   initrd
    serial-console
    braille-console
    parport
@@ -25,8 +55,6 @@ Contents:
    sysrq
    unicode
    vga-softcursor
-   sysfs-rules
-   devices
    binfmt-misc
    mono
    java
diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst
index d2f2725f032e..37105aedb2e4 100644
--- a/Documentation/admin-guide/kernel-parameters.rst
+++ b/Documentation/admin-guide/kernel-parameters.rst
@@ -1,5 +1,5 @@
-Kernel Parameters
-~~~~~~~~~~~~~~~~~
+The kernel's command-line parameters
+====================================
 
 The following is a consolidated list of the kernel parameters as
 implemented by the __setup(), core_param() and module_param() macros
diff --git a/Documentation/admin-guide/sysfs-rules.rst b/Documentation/admin-guide/sysfs-rules.rst
index 04bdd52cba1d..8273bb1de105 100644
--- a/Documentation/admin-guide/sysfs-rules.rst
+++ b/Documentation/admin-guide/sysfs-rules.rst
@@ -1,5 +1,5 @@
-Rules on how to access information in the Linux kernel sysfs
-============================================================
+Rules on how to access information in  sysfs
+============================================
 
 The kernel-exported sysfs exports internal kernel implementation details
 and depends on internal kernel structures and layout. It is agreed upon
diff --git a/Documentation/admin-guide/vga-softcursor.rst b/Documentation/admin-guide/vga-softcursor.rst
index 9eac6744b3a1..a663a745cff4 100644
--- a/Documentation/admin-guide/vga-softcursor.rst
+++ b/Documentation/admin-guide/vga-softcursor.rst
@@ -50,8 +50,8 @@ third parameter
 
 .. [#f1] see ``#define TRIDENT_GLITCH`` in ``drivers/video/vgacon.c``.
 
-Examples:
-=========
+Examples
+--------
 
 To get normal blinking underline, use::
 
-- 
2.7.4

[PATCH 04/11] docs: Get rid of the badRAM guide

[Jonathan Corbet]

The last release of this tool was for 2.6.28; it's hard to see how it has
any relevance to current kernels.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/admin-guide/bad-memory.rst | 50 --------------------------------
 Documentation/admin-guide/index.rst      |  1 -
 2 files changed, 51 deletions(-)
 delete mode 100644 Documentation/admin-guide/bad-memory.rst

diff --git a/Documentation/admin-guide/bad-memory.rst b/Documentation/admin-guide/bad-memory.rst
deleted file mode 100644
index a5c0e25e496f..000000000000
--- a/Documentation/admin-guide/bad-memory.rst
+++ /dev/null
@@ -1,50 +0,0 @@
-How to deal with bad memory e.g. reported by memtest86+ ?
-=========================================================
-
-March 2008
-Jan-Simon Moeller, dl9pf@gmx.de
-
-
-
-There are three possibilities I know of:
-
-1) Reinsert/swap the memory modules
-
-2) Buy new modules (best!) or try to exchange the memory
-   if you have spare-parts
-
-3) Use BadRAM or memmap
-
-This Howto is about number 3) .
-
-
-BadRAM
-######
-
-BadRAM is the actively developed and available as kernel-patch
-here:  http://rick.vanrein.org/linux/badram/
-
-For more details see the BadRAM documentation.
-
-memmap
-######
-
-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 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.
-
-With the numbers of the example above::
-
-	memmap=64K$0x18690000
-
-or::
-
-	memmap=0x10000$0x18690000
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 2ce2bf02824b..d737ae71efc6 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -58,5 +58,4 @@ configure specific aspects of kernel behavior to your liking.
    binfmt-misc
    mono
    java
-   bad-memory
    basic-profiling
-- 
2.7.4

[PATCH 05/11] docs: Get rid of the "basic profiling" guide

[Jonathan Corbet]

The document has not been touched in over 11 years and doesn't reflect how
profiling is done in the perf era.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/admin-guide/basic-profiling.rst | 68 ---------------------------
 Documentation/admin-guide/index.rst           |  1 -
 2 files changed, 69 deletions(-)
 delete mode 100644 Documentation/admin-guide/basic-profiling.rst

diff --git a/Documentation/admin-guide/basic-profiling.rst b/Documentation/admin-guide/basic-profiling.rst
deleted file mode 100644
index 72babc71b771..000000000000
--- a/Documentation/admin-guide/basic-profiling.rst
+++ /dev/null
@@ -1,68 +0,0 @@
-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
-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!
-
-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
-2.12a, which can be downloaded from:
-
-	http://www.kernel.org/pub/linux/utils/util-linux/
-
-Most distributions will ship it already.
-
-Add ``profile=2`` to the kernel command line.
-
-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
-line.
-
-Configure with ``CONFIG_PROFILING=y`` and ``CONFIG_OPROFILE=y`` & reboot on new kernel::
-
-	./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
-
-Some ``opcontrol`` commands::
-
-	clear		opcontrol --reset
-	start		opcontrol --start
-		<test>
-	stop		opcontrol --stop
-	dump output	opreport >  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.
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index d737ae71efc6..2872c0c70ea4 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -58,4 +58,3 @@ configure specific aspects of kernel behavior to your liking.
    binfmt-misc
    mono
    java
-   basic-profiling
-- 
2.7.4

[PATCH 06/11] docs: Get rid of the "bug-hunting" guide

[Jonathan Corbet]

Larry McVoy's advice on how to manually bisect 1.3.x kernel bugs is of
historical interest, but that's what the repository is for.  It is not
useful to users now.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/admin-guide/bug-hunting.rst | 249 ------------------------------
 Documentation/admin-guide/index.rst       |   1 -
 2 files changed, 250 deletions(-)
 delete mode 100644 Documentation/admin-guide/bug-hunting.rst

diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst
deleted file mode 100644
index d35dd9fd1af0..000000000000
--- a/Documentation/admin-guide/bug-hunting.rst
+++ /dev/null
@@ -1,249 +0,0 @@
-Bug hunting
-+++++++++++
-
-Last updated: 20 December 2005
-
-Introduction
-============
-
-Always try the latest kernel from kernel.org and build from source. If you are
-not confident in doing that please report the bug to your distribution vendor
-instead of to a kernel developer.
-
-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
-:ref:`Documentation/admin-guide/reporting-bugs.rst <reportingbugs>`.
-
-Devices not appearing
-=====================
-
-Often this is caused by udev. Check that first before blaming it on the
-kernel.
-
-Finding patch that caused a bug
-===============================
-
-
-
-Finding using ``git-bisect``
-----------------------------
-
-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``
-- have fun
-
-Finding it the old way
-----------------------
-
-[Sat Mar  2 10:32:33 PST 1996 KERNEL_BUG-HOWTO lm@sgi.com (Larry McVoy)]
-
-This is how to track down a bug if you know nothing about kernel hacking.
-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
-          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
-          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
-          can probably do better than this but it gets tricky.
-
-        - 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
-            up with a list of directories that changed.  For each of those
-            directories:
-
-                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::
-
-                        mv dir dir.62
-                        mv dir.63 dir
-                        find dir -name '*.[oa]' -print | xargs rm -f
-
-                And then rebuild and retest.  Assuming that all related
-                changes were contained in the sub directory, this should
-                isolate the change to a directory.
-
-                Problems: changes in header files may have occurred; I've
-                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
-
-          - 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
-
-          - You can take the old file and the new file and manually create
-            a merged file that has::
-
-                #ifdef VER62
-                routine()
-                {
-                        ...
-                }
-                #else
-                routine()
-                {
-                        ...
-                }
-                #endif
-
-            And then walk through that file, one routine at a time and
-            prefix it with::
-
-                #define VER62
-                /* both routines here */
-                #undef VER62
-
-            Then recompile, retest, move the ifdefs until you find the one
-            that makes the difference.
-
-Finally, you take all the info that you have, kernel revisions, bug
-description, the extent to which you have narrowed it down, and pass
-that off to whomever you believe is the maintainer of that section.
-A post to linux.dev.kernel isn't such a bad idea if you've done some
-work to narrow it down.
-
-If you get it down to a routine, you'll probably get a fix in 24 hours.
-
-My apologies to Linus and the other kernel hackers for describing this
-brute force approach, it's hardly what a kernel hacker would do.  However,
-it does work and it lets non-hackers help fix bugs.  And it is cool
-because Linux snapshots will let you do this - something that you can't
-do with vendor supplied releases.
-
-Fixing the bug
-==============
-
-Nobody is going to tell you how to fix bugs. Seriously. You need to work it
-out. But below are some hints on how to use the tools.
-
-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::
-
-    objdump -r -S -l --disassemble net/dccp/ipv4.o
-
-.. 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
-
-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::
-
- EIP:    0060:[<c021e50e>]    Not tainted VLI
-
-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::
-
- EIP is at vt_ioctl+0xda8/0x1482
-
-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::
-
-  (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
-      ...
-
-this shows the problem in the :jbd: module. You can load that module in gdb
-and list the relevant code::
-
-  gdb fs/jbd/jbd.ko
-  (gdb) p log_wait_commit
-  (gdb) l *(0x<address> + 0xa3)
-
-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.
-
-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
-ref:`Documentation/process/submitting-patches.rst <submittingpatches>` though
-to help your code get accepted.
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 2872c0c70ea4..2d0a302e8773 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -25,7 +25,6 @@ problems and bugs in particular.
    
    reporting-bugs
    security-bugs
-   bug-hunting
    oops-tracing
    ramoops
    dynamic-debug-howto
-- 
2.7.4

[PATCH 07/11] docs: Apply some basic organization to the process guide

[Jonathan Corbet]

Put like documents together, with the essential ones at the top, and split
the TOC into sections.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/process/changes.rst |  2 +-
 Documentation/process/index.rst   | 37 ++++++++++++++++++++++++++++---------
 2 files changed, 29 insertions(+), 10 deletions(-)

diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index 22797a15dc24..56ce66114665 100644
--- a/Documentation/process/changes.rst
+++ b/Documentation/process/changes.rst
@@ -1,6 +1,6 @@
 .. _changes:
 
-Minimal requerements to compile the Kernel
+Minimal requirements to compile the Kernel
 ++++++++++++++++++++++++++++++++++++++++++
 
 Intro
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index 6ee818752474..0cbc62adbbb1 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -4,29 +4,48 @@
 	\renewcommand\thesubsection*
 
 
-Linux Kernel Development Documentation
-======================================
+Working with the kernel development community
+=============================================
 
-Contents:
+So you want to be a Linux kernel developer?  Welcome!  While there is a lot
+to be learned about the kernel in a technical sense, it is also important
+to learn about how our community works.  Reading these documents will make
+it much easier for you to get your changes merged with a minimum of
+trouble.
+
+Below are the essential guides that every developer should read.
 
 .. toctree::
    :maxdepth: 2
 
    howto
-   changes
-   coding-style
+   code-of-conflict
+   development-process
    submitting-patches
+   coding-style
+   email-clients
+
+Other guides to the community that are of interest to most developers are: 
+
+.. toctree::
+   :maxdepth: 2
+
+   changes
    submitting-drivers
    stable-api-nonsense
    management-style
    stable-kernel-rules
+   submit-checklist
    kernel-docs
+
+These are some overall technical guides that have been put here for now for
+lack of a better place.
+
+.. toctree::
+   :maxdepth: 2
+
    applying-patches
-   email-clients
-   submit-checklist
-   code-of-conflict
    adding-syscalls
    magic-number
    volatile-considered-harmful
 
-   development-process
-- 
2.7.4

[PATCH 08/11] docs: Tweak submitting-patches.rst formatting

[Jonathan Corbet]

The main goal here was to get the subsections to show in the TOC as they do
for all the other documents.  Also call out the DCO in the section title
since it's important.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/process/submitting-patches.rst | 16 ++++++----------
 1 file changed, 6 insertions(+), 10 deletions(-)

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index b4cf8f375184..3e10719fee35 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -1,7 +1,7 @@
 .. _submittingpatches:
 
-How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds
-=========================================================================================
+Submitting patches: the essential guide to getting your code into the kernel
+============================================================================
 
 For a person or company who wishes to submit a change to the Linux
 kernel, the process can sometimes be daunting if you're not familiar
@@ -24,10 +24,6 @@ of the mechanical work done for you, though you'll still need to prepare
 and document a sensible set of patches.  In general, use of ``git`` will make
 your life as a kernel developer easier.
 
-Creating and Sending your Change
-********************************
-
-
 0) Obtain a current source tree
 -------------------------------
 
@@ -417,8 +413,8 @@ e-mail discussions.
 
 
 
-11) Sign your work
-------------------
+11) Sign your work — the Developer's Certificate of Origin
+----------------------------------------------------------
 
 To improve tracking of who did what, especially with patches that can
 percolate to their final resting place in the kernel through several
@@ -803,8 +799,8 @@ command like this will do the trick::
   git request-pull master git://my.public.tree/linux.git my-signed-tag
 
 
-REFERENCES
-**********
+References
+----------
 
 Andrew Morton, "The perfect patch" (tpp).
   <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
-- 
2.7.4

[PATCH 09/11] docs: Collapse the process guide TOC

[Jonathan Corbet]

I believe this makes the page as a whole more approachable.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/process/index.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index 0cbc62adbbb1..0557144cef2b 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -16,7 +16,7 @@ trouble.
 Below are the essential guides that every developer should read.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    howto
    code-of-conflict
@@ -28,7 +28,7 @@ Below are the essential guides that every developer should read.
 Other guides to the community that are of interest to most developers are: 
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    changes
    submitting-drivers
@@ -42,7 +42,7 @@ These are some overall technical guides that have been put here for now for
 lack of a better place.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    applying-patches
    adding-syscalls
-- 
2.7.4

[PATCH 10/11] docs: add a warning to submitting-drivers.rst

[Jonathan Corbet]

This is crufty stuff and should maybe just be deleted, but I'm not quite
ready to do that yet.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/process/submitting-drivers.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst
index 0939d018c289..afb82ee0cbea 100644
--- a/Documentation/process/submitting-drivers.rst
+++ b/Documentation/process/submitting-drivers.rst
@@ -8,6 +8,14 @@ various kernel trees. Note that if you are interested in video card drivers
 you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org
 (http://x.org/) instead.
 
+.. note::
+
+   This document is old and has seen little maintenance in recent years; it
+   should probably be updated or, perhaps better, just deleted.  Most of
+   what is here can be found in the other development documents anyway.
+
+   Oh, and we don't really recommend submitting changes to XFree86 :)
+
 Also read the Documentation/process/submitting-patches.rst document.
 
 
-- 
2.7.4

[PATCH 11/11] docs: Add a warning to applying-patches.rst

[Jonathan Corbet]

This is ancient stuff and we don't do things this way anymore.  In the
absence of simply deleting the document, at least add a warning to it.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/process/applying-patches.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/process/applying-patches.rst b/Documentation/process/applying-patches.rst
index abd7dc7ae240..87825cf96f33 100644
--- a/Documentation/process/applying-patches.rst
+++ b/Documentation/process/applying-patches.rst
@@ -9,6 +9,10 @@ Original by:
 Last update:
 	2016-09-14
 
+.. note::
+
+   This document is obsolete.  In most cases, rather than using ``patch``
+   manually, you'll almost certainly want to look at using Git instead.
 
 A frequently asked question on the Linux Kernel Mailing List is how to apply
 a patch to the kernel or, more specifically, what base kernel a patch for
-- 
2.7.4

Re: [PATCH 01/11] docs: Tweak the top-level Sphinx page

[Mauro Carvalho Chehab]

Em Wed, 26 Oct 2016 17:19:29 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> This will be the initial landing point for readers, so give them a bit of
> introductory material.  Also split the TOC into area-specific chunks to
> make the whole thing a bit more approachable.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Looks great!

Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

> ---
>  Documentation/index.rst | 45 +++++++++++++++++++++++++++++++++++++++++----
>  1 file changed, 41 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index f6a3d4766495..7cec8432ce7a 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -3,18 +3,55 @@
>     You can adapt this file completely to your liking, but it should at least
>     contain the root `toctree` directive.
>  
> -Welcome to The Linux Kernel's documentation!
> -============================================
> +Welcome to The Linux Kernel's documentation
> +===========================================
>  
> -Contents:
> +This is the top level of the kernel's documentation tree.  Kernel
> +documentation, like the kernel itself, is very much a work in progress;
> +that is especially true as we work to integrate our many scattered
> +documents into a coherent whole.  Please note that improvements to the
> +documentation are welcome; join the linux-doc list at vger.kernel.org if
> +you want to help out.
> +
> +User-oriented documentation
> +---------------------------
> +
> +The following manuals are written for *users* of the kernel — those who are
> +trying to get it to work optimally on a given system.
>  
>  .. toctree::
>     :maxdepth: 2
>  
>     admin-guide/index
> -   kernel-documentation
> +
> +Introduction to kernel development
> +----------------------------------
> +
> +These manuals contain overall information about how to develop the kernel.
> +The kernel community is quite large, with thousands of developers
> +contributing over the course of a year.  As with any large community,
> +knowing how things are done will make the process of getting your changes
> +merged much easier.
> +
> +.. toctree::
> +   :maxdepth: 2
> +
>     process/index
>     dev-tools/tools
> +   kernel-documentation
> +
> +Kernel API documentation
> +------------------------
> +
> +These books get into the details of how specific kernel subsystems work
> +from the point of view of a kernel developer.  Much of the information here
> +is taken directly from the kernel source, with supplemental material added
> +as needed (or at least as we managed to add it — probably *not* all that is
> +needed). 
> +
> +.. toctree::
> +   :maxdepth: 2
> +
>     driver-api/index
>     media/index
>     gpu/index



Thanks,
Mauro

Re: [PATCH 02/11] docs: retitle the kernel-documentation.rst

[Mauro Carvalho Chehab]

Em Wed, 26 Oct 2016 17:19:30 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Let's make the title of this document (which shows up in the top page)
> better describe its contents.
> 
> Cc: Jani Nikula <jani.nikula@intel.com>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

> ---
>  Documentation/kernel-documentation.rst | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
> index 10cc7ddb6235..c66ab937c2ca 100644
> --- a/Documentation/kernel-documentation.rst
> +++ b/Documentation/kernel-documentation.rst
> @@ -1,6 +1,6 @@
> -==========================
> -Linux Kernel Documentation
> -==========================
> +=================================
> +How to write kernel documentation
> +=================================
>  
>  Introduction
>  ============



Thanks,
Mauro

Re: [PATCH 03/11] docs: Clean up and organize the admin guide a bit

[Mauro Carvalho Chehab]

Em Wed, 26 Oct 2016 17:19:31 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> The admin guide is a good start, but it's time to turn it into something
> better than an unordered blob of files.  This is a first step in that
> direction.  The TOC has been split up and annotated, the guides have been
> reordered, and minor tweaks have been applied to a few of them.
> 
> One consequence of splitting up the TOC is that we don't really want to use
> :numbered: anymore, since the count resets every time and there doesn't
> seem to be a way to change that.  Eventually we probably want to group the
> documents into sub-books, at which point we can go back to a single TOC,
> but it's probably early to do that.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/admin-guide/index.rst             | 50 +++++++++++++++++++------
>  Documentation/admin-guide/kernel-parameters.rst |  4 +-
>  Documentation/admin-guide/sysfs-rules.rst       |  4 +-
>  Documentation/admin-guide/vga-softcursor.rst    |  4 +-
>  4 files changed, 45 insertions(+), 17 deletions(-)
> 
> diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
> index 4e5abbb4bbd5..2ce2bf02824b 100644
> --- a/Documentation/admin-guide/index.rst
> +++ b/Documentation/admin-guide/index.rst
> @@ -1,22 +1,52 @@
> -Linux Kernel User's Documentation
> -=================================
> +The Linux kernel user's and administrator's guide
> +=================================================
>  
> -Contents:
> +The following is a collection of user-oriented documents that have been
> +added to the kernel over time.  There is, as yet, little overall order or
> +organization here — this material was not written to be a single, coherent
> +document!  With luck things will improve quickly over time.
> +
> +This initial section contains overall information, including the README
> +file describing the kernel as a whole, documentation on kernel parameters,
> +etc. 
>  
>  .. toctree::
> -   :maxdepth: 2
> -   :numbered:
> +   :maxdepth: 1
>  
>     README
> +   kernel-parameters
> +   devices
> +
> +Here is a set of documents aimed at users who are trying to track down
> +problems and bugs in particular.
> +
> +.. toctree::
> +   :maxdepth: 1
> +   
>     reporting-bugs
> +   security-bugs
>     bug-hunting
>     oops-tracing
>     ramoops
> -   initrd
> -   init
>     dynamic-debug-howto
> -   security-bugs
> -   kernel-parameters
> +   init
> +
> +This is the beginning of a section with information of interest to
> +application developers.  Documents covering various aspects of the kernel
> +ABI will be found here.
> +
> +.. toctree::
> +   :maxdepth: 1
> +   
> +   sysfs-rules
> +
> +The rest of this manual consists of various unordered guides on how to
> +configure specific aspects of kernel behavior to your liking.
> +
> +.. toctree::
> +   :maxdepth: 1
> +   
> +   initrd
>     serial-console
>     braille-console
>     parport
> @@ -25,8 +55,6 @@ Contents:
>     sysrq
>     unicode
>     vga-softcursor
> -   sysfs-rules
> -   devices
>     binfmt-misc
>     mono
>     java
> diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst
> index d2f2725f032e..37105aedb2e4 100644
> --- a/Documentation/admin-guide/kernel-parameters.rst
> +++ b/Documentation/admin-guide/kernel-parameters.rst
> @@ -1,5 +1,5 @@
> -Kernel Parameters
> -~~~~~~~~~~~~~~~~~
> +The kernel's command-line parameters
> +====================================
>  
>  The following is a consolidated list of the kernel parameters as
>  implemented by the __setup(), core_param() and module_param() macros
> diff --git a/Documentation/admin-guide/sysfs-rules.rst b/Documentation/admin-guide/sysfs-rules.rst
> index 04bdd52cba1d..8273bb1de105 100644
> --- a/Documentation/admin-guide/sysfs-rules.rst
> +++ b/Documentation/admin-guide/sysfs-rules.rst
> @@ -1,5 +1,5 @@
> -Rules on how to access information in the Linux kernel sysfs
> -============================================================
> +Rules on how to access information in  sysfs
> +============================================

There is an extra space in the above.

Except for that, the remaining looks OK on my eyes.

With that fixed, feel free to add:
	Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Regards,
Mauro

Re: [PATCH 04/11] docs: Get rid of the badRAM guide

[Mauro Carvalho Chehab]

Em Wed, 26 Oct 2016 17:19:32 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> The last release of this tool was for 2.6.28; it's hard to see how it has
> any relevance to current kernels.

I suspect that only the BadRAM data there is obsolete.

Anyway, I'm fine if you want to remove this one.

> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/admin-guide/bad-memory.rst | 50 --------------------------------
>  Documentation/admin-guide/index.rst      |  1 -
>  2 files changed, 51 deletions(-)
>  delete mode 100644 Documentation/admin-guide/bad-memory.rst
> 
> diff --git a/Documentation/admin-guide/bad-memory.rst b/Documentation/admin-guide/bad-memory.rst
> deleted file mode 100644
> index a5c0e25e496f..000000000000
> --- a/Documentation/admin-guide/bad-memory.rst
> +++ /dev/null
> @@ -1,50 +0,0 @@
> -How to deal with bad memory e.g. reported by memtest86+ ?
> -=========================================================
> -
> -March 2008
> -Jan-Simon Moeller, dl9pf@gmx.de
> -
> -
> -
> -There are three possibilities I know of:
> -
> -1) Reinsert/swap the memory modules
> -
> -2) Buy new modules (best!) or try to exchange the memory
> -   if you have spare-parts
> -
> -3) Use BadRAM or memmap
> -
> -This Howto is about number 3) .
> -
> -
> -BadRAM
> -######
> -
> -BadRAM is the actively developed and available as kernel-patch
> -here:  http://rick.vanrein.org/linux/badram/
> -
> -For more details see the BadRAM documentation.
> -
> -memmap
> -######
> -
> -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 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.
> -
> -With the numbers of the example above::
> -
> -	memmap=64K$0x18690000
> -
> -or::
> -
> -	memmap=0x10000$0x18690000
> diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
> index 2ce2bf02824b..d737ae71efc6 100644
> --- a/Documentation/admin-guide/index.rst
> +++ b/Documentation/admin-guide/index.rst
> @@ -58,5 +58,4 @@ configure specific aspects of kernel behavior to your liking.
>     binfmt-misc
>     mono
>     java
> -   bad-memory
>     basic-profiling



Thanks,
Mauro

Re: [PATCH 05/11] docs: Get rid of the "basic profiling" guide

[Mauro Carvalho Chehab]

Em Wed, 26 Oct 2016 17:19:33 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> The document has not been touched in over 11 years and doesn't reflect how
> profiling is done in the perf era.

I sent you an alternative patch for this one, but I'm OK if you want to
just nuke this file.

> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/admin-guide/basic-profiling.rst | 68 ---------------------------
>  Documentation/admin-guide/index.rst           |  1 -
>  2 files changed, 69 deletions(-)
>  delete mode 100644 Documentation/admin-guide/basic-profiling.rst
> 
> diff --git a/Documentation/admin-guide/basic-profiling.rst b/Documentation/admin-guide/basic-profiling.rst
> deleted file mode 100644
> index 72babc71b771..000000000000
> --- a/Documentation/admin-guide/basic-profiling.rst
> +++ /dev/null
> @@ -1,68 +0,0 @@
> -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
> -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!
> -
> -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
> -2.12a, which can be downloaded from:
> -
> -	http://www.kernel.org/pub/linux/utils/util-linux/
> -
> -Most distributions will ship it already.
> -
> -Add ``profile=2`` to the kernel command line.
> -
> -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
> -line.
> -
> -Configure with ``CONFIG_PROFILING=y`` and ``CONFIG_OPROFILE=y`` & reboot on new kernel::
> -
> -	./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
> -
> -Some ``opcontrol`` commands::
> -
> -	clear		opcontrol --reset
> -	start		opcontrol --start
> -		<test>
> -	stop		opcontrol --stop
> -	dump output	opreport >  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.
> diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
> index d737ae71efc6..2872c0c70ea4 100644
> --- a/Documentation/admin-guide/index.rst
> +++ b/Documentation/admin-guide/index.rst
> @@ -58,4 +58,3 @@ configure specific aspects of kernel behavior to your liking.
>     binfmt-misc
>     mono
>     java
> -   basic-profiling



Thanks,
Mauro

Re: [PATCH 06/11] docs: Get rid of the "bug-hunting" guide

[Mauro Carvalho Chehab]

Em Wed, 26 Oct 2016 17:19:34 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Larry McVoy's advice on how to manually bisect 1.3.x kernel bugs is of
> historical interest, but that's what the repository is for.  It is not
> useful to users now.

In the specific case of this file, I think that the information there
about how to disassemble a file and how to use gdb and objdump to get the
error line associated with an OOPS very useful.

So, I prefer to keep this one. See the patch I sent you today.

> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/admin-guide/bug-hunting.rst | 249 ------------------------------
>  Documentation/admin-guide/index.rst       |   1 -
>  2 files changed, 250 deletions(-)
>  delete mode 100644 Documentation/admin-guide/bug-hunting.rst
> 
> diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst
> deleted file mode 100644
> index d35dd9fd1af0..000000000000
> --- a/Documentation/admin-guide/bug-hunting.rst
> +++ /dev/null
> @@ -1,249 +0,0 @@
> -Bug hunting
> -+++++++++++
> -
> -Last updated: 20 December 2005
> -
> -Introduction
> -============
> -
> -Always try the latest kernel from kernel.org and build from source. If you are
> -not confident in doing that please report the bug to your distribution vendor
> -instead of to a kernel developer.
> -
> -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
> -:ref:`Documentation/admin-guide/reporting-bugs.rst <reportingbugs>`.
> -
> -Devices not appearing
> -=====================
> -
> -Often this is caused by udev. Check that first before blaming it on the
> -kernel.
> -
> -Finding patch that caused a bug
> -===============================
> -
> -
> -
> -Finding using ``git-bisect``
> -----------------------------
> -
> -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``
> -- have fun
> -
> -Finding it the old way
> -----------------------
> -
> -[Sat Mar  2 10:32:33 PST 1996 KERNEL_BUG-HOWTO lm@sgi.com (Larry McVoy)]
> -
> -This is how to track down a bug if you know nothing about kernel hacking.
> -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
> -          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
> -          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
> -          can probably do better than this but it gets tricky.
> -
> -        - 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
> -            up with a list of directories that changed.  For each of those
> -            directories:
> -
> -                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::
> -
> -                        mv dir dir.62
> -                        mv dir.63 dir
> -                        find dir -name '*.[oa]' -print | xargs rm -f
> -
> -                And then rebuild and retest.  Assuming that all related
> -                changes were contained in the sub directory, this should
> -                isolate the change to a directory.
> -
> -                Problems: changes in header files may have occurred; I've
> -                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
> -
> -          - 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
> -
> -          - You can take the old file and the new file and manually create
> -            a merged file that has::
> -
> -                #ifdef VER62
> -                routine()
> -                {
> -                        ...
> -                }
> -                #else
> -                routine()
> -                {
> -                        ...
> -                }
> -                #endif
> -
> -            And then walk through that file, one routine at a time and
> -            prefix it with::
> -
> -                #define VER62
> -                /* both routines here */
> -                #undef VER62
> -
> -            Then recompile, retest, move the ifdefs until you find the one
> -            that makes the difference.
> -
> -Finally, you take all the info that you have, kernel revisions, bug
> -description, the extent to which you have narrowed it down, and pass
> -that off to whomever you believe is the maintainer of that section.
> -A post to linux.dev.kernel isn't such a bad idea if you've done some
> -work to narrow it down.
> -
> -If you get it down to a routine, you'll probably get a fix in 24 hours.
> -
> -My apologies to Linus and the other kernel hackers for describing this
> -brute force approach, it's hardly what a kernel hacker would do.  However,
> -it does work and it lets non-hackers help fix bugs.  And it is cool
> -because Linux snapshots will let you do this - something that you can't
> -do with vendor supplied releases.
> -
> -Fixing the bug
> -==============
> -
> -Nobody is going to tell you how to fix bugs. Seriously. You need to work it
> -out. But below are some hints on how to use the tools.
> -
> -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::
> -
> -    objdump -r -S -l --disassemble net/dccp/ipv4.o
> -
> -.. 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
> -
> -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::
> -
> - EIP:    0060:[<c021e50e>]    Not tainted VLI
> -
> -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::
> -
> - EIP is at vt_ioctl+0xda8/0x1482
> -
> -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::
> -
> -  (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
> -      ...
> -
> -this shows the problem in the :jbd: module. You can load that module in gdb
> -and list the relevant code::
> -
> -  gdb fs/jbd/jbd.ko
> -  (gdb) p log_wait_commit
> -  (gdb) l *(0x<address> + 0xa3)
> -
> -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.
> -
> -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
> -ref:`Documentation/process/submitting-patches.rst <submittingpatches>` though
> -to help your code get accepted.
> diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
> index 2872c0c70ea4..2d0a302e8773 100644
> --- a/Documentation/admin-guide/index.rst
> +++ b/Documentation/admin-guide/index.rst
> @@ -25,7 +25,6 @@ problems and bugs in particular.
>     
>     reporting-bugs
>     security-bugs
> -   bug-hunting
>     oops-tracing
>     ramoops
>     dynamic-debug-howto



Thanks,
Mauro

Re: [PATCH 07/11] docs: Apply some basic organization to the process guide

[Mauro Carvalho Chehab]

Em Wed, 26 Oct 2016 17:19:35 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Put like documents together, with the essential ones at the top, and split
> the TOC into sections.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Looks good to me.

Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

> ---
>  Documentation/process/changes.rst |  2 +-
>  Documentation/process/index.rst   | 37 ++++++++++++++++++++++++++++---------
>  2 files changed, 29 insertions(+), 10 deletions(-)
> 
> diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
> index 22797a15dc24..56ce66114665 100644
> --- a/Documentation/process/changes.rst
> +++ b/Documentation/process/changes.rst
> @@ -1,6 +1,6 @@
>  .. _changes:
>  
> -Minimal requerements to compile the Kernel
> +Minimal requirements to compile the Kernel
>  ++++++++++++++++++++++++++++++++++++++++++
>  
>  Intro
> diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
> index 6ee818752474..0cbc62adbbb1 100644
> --- a/Documentation/process/index.rst
> +++ b/Documentation/process/index.rst
> @@ -4,29 +4,48 @@
>  	\renewcommand\thesubsection*
>  
>  
> -Linux Kernel Development Documentation
> -======================================
> +Working with the kernel development community
> +=============================================
>  
> -Contents:
> +So you want to be a Linux kernel developer?  Welcome!  While there is a lot
> +to be learned about the kernel in a technical sense, it is also important
> +to learn about how our community works.  Reading these documents will make
> +it much easier for you to get your changes merged with a minimum of
> +trouble.
> +
> +Below are the essential guides that every developer should read.
>  
>  .. toctree::
>     :maxdepth: 2
>  
>     howto
> -   changes
> -   coding-style
> +   code-of-conflict
> +   development-process
>     submitting-patches
> +   coding-style
> +   email-clients
> +
> +Other guides to the community that are of interest to most developers are: 
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   changes
>     submitting-drivers
>     stable-api-nonsense
>     management-style
>     stable-kernel-rules
> +   submit-checklist
>     kernel-docs
> +
> +These are some overall technical guides that have been put here for now for
> +lack of a better place.
> +
> +.. toctree::
> +   :maxdepth: 2
> +
>     applying-patches
> -   email-clients
> -   submit-checklist
> -   code-of-conflict
>     adding-syscalls
>     magic-number
>     volatile-considered-harmful
>  
> -   development-process



Thanks,
Mauro

Re: [PATCH 08/11] docs: Tweak submitting-patches.rst formatting

[Mauro Carvalho Chehab]

Em Wed, 26 Oct 2016 17:19:36 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> The main goal here was to get the subsections to show in the TOC as they do
> for all the other documents.  Also call out the DCO in the section title
> since it's important.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Looks good to me.

Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

> ---
>  Documentation/process/submitting-patches.rst | 16 ++++++----------
>  1 file changed, 6 insertions(+), 10 deletions(-)
> 
> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
> index b4cf8f375184..3e10719fee35 100644
> --- a/Documentation/process/submitting-patches.rst
> +++ b/Documentation/process/submitting-patches.rst
> @@ -1,7 +1,7 @@
>  .. _submittingpatches:
>  
> -How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds
> -=========================================================================================
> +Submitting patches: the essential guide to getting your code into the kernel
> +============================================================================
>  
>  For a person or company who wishes to submit a change to the Linux
>  kernel, the process can sometimes be daunting if you're not familiar
> @@ -24,10 +24,6 @@ of the mechanical work done for you, though you'll still need to prepare
>  and document a sensible set of patches.  In general, use of ``git`` will make
>  your life as a kernel developer easier.
>  
> -Creating and Sending your Change
> -********************************
> -
> -
>  0) Obtain a current source tree
>  -------------------------------
>  
> @@ -417,8 +413,8 @@ e-mail discussions.
>  
>  
>  
> -11) Sign your work
> -------------------
> +11) Sign your work — the Developer's Certificate of Origin
> +----------------------------------------------------------
>  
>  To improve tracking of who did what, especially with patches that can
>  percolate to their final resting place in the kernel through several
> @@ -803,8 +799,8 @@ command like this will do the trick::
>    git request-pull master git://my.public.tree/linux.git my-signed-tag
>  
>  
> -REFERENCES
> -**********
> +References
> +----------
>  
>  Andrew Morton, "The perfect patch" (tpp).
>    <http://www.ozlabs.org/~akpm/stuff/tpp.txt>



Thanks,
Mauro

Re: [PATCH 09/11] docs: Collapse the process guide TOC

[Mauro Carvalho Chehab]

Em Wed, 26 Oct 2016 17:19:37 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> I believe this makes the page as a whole more approachable.

Makes sense.

Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/process/index.rst | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
> index 0cbc62adbbb1..0557144cef2b 100644
> --- a/Documentation/process/index.rst
> +++ b/Documentation/process/index.rst
> @@ -16,7 +16,7 @@ trouble.
>  Below are the essential guides that every developer should read.
>  
>  .. toctree::
> -   :maxdepth: 2
> +   :maxdepth: 1
>  
>     howto
>     code-of-conflict
> @@ -28,7 +28,7 @@ Below are the essential guides that every developer should read.
>  Other guides to the community that are of interest to most developers are: 
>  
>  .. toctree::
> -   :maxdepth: 2
> +   :maxdepth: 1
>  
>     changes
>     submitting-drivers
> @@ -42,7 +42,7 @@ These are some overall technical guides that have been put here for now for
>  lack of a better place.
>  
>  .. toctree::
> -   :maxdepth: 2
> +   :maxdepth: 1
>  
>     applying-patches
>     adding-syscalls



Thanks,
Mauro

Re: [PATCH 11/11] docs: Add a warning to applying-patches.rst

[Mauro Carvalho Chehab]

Em Wed, 26 Oct 2016 17:19:39 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> This is ancient stuff and we don't do things this way anymore.  In the
> absence of simply deleting the document, at least add a warning to it.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/process/applying-patches.rst | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/Documentation/process/applying-patches.rst b/Documentation/process/applying-patches.rst
> index abd7dc7ae240..87825cf96f33 100644
> --- a/Documentation/process/applying-patches.rst
> +++ b/Documentation/process/applying-patches.rst
> @@ -9,6 +9,10 @@ Original by:
>  Last update:
>  	2016-09-14
>  
> +.. note::
> +
> +   This document is obsolete.  In most cases, rather than using ``patch``
> +   manually, you'll almost certainly want to look at using Git instead.

Fair enough.

Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

>  
>  A frequently asked question on the Linux Kernel Mailing List is how to apply
>  a patch to the kernel or, more specifically, what base kernel a patch for



Thanks,
Mauro

Re: [PATCH 10/11] docs: add a warning to submitting-drivers.rst

[Mauro Carvalho Chehab]

Em Wed, 26 Oct 2016 17:19:38 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> This is crufty stuff and should maybe just be deleted, but I'm not quite
> ready to do that yet.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/process/submitting-drivers.rst | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 
> diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst
> index 0939d018c289..afb82ee0cbea 100644
> --- a/Documentation/process/submitting-drivers.rst
> +++ b/Documentation/process/submitting-drivers.rst
> @@ -8,6 +8,14 @@ various kernel trees. Note that if you are interested in video card drivers
>  you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org
>  (http://x.org/) instead.
>  
> +.. note::
> +
> +   This document is old and has seen little maintenance in recent years; it
> +   should probably be updated or, perhaps better, just deleted.  Most of
> +   what is here can be found in the other development documents anyway.
> +
> +   Oh, and we don't really recommend submitting changes to XFree86 :)

Yeah, at least the XFree86 part should be stripped ;)

I guess the other parts should be verified if they're all there at the
process book before nuking this one.

Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

> +
>  Also read the Documentation/process/submitting-patches.rst document.
>  
>  



Thanks,
Mauro