Merge branch 'doc-tweaks' into docs-next
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.
diff --git a/Documentation/admin-guide/bad-memory.rst b/Documentation/admin-guide/bad-memory.rst
deleted file mode 100644
index a5c0e25..0000000
--- 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/basic-profiling.rst b/Documentation/admin-guide/basic-profiling.rst
deleted file mode 100644
index 72babc7..0000000
--- 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 fb779e6..368845e 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,13 +55,9 @@
sysrq
unicode
vga-softcursor
- sysfs-rules
- devices
binfmt-misc
mono
java
- bad-memory
- basic-profiling
.. only:: subproject and html
@@ -39,4 +65,3 @@
=======
* :ref:`genindex`
-
diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst
index d2f2725..37105ae 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 04bdd52..abad335 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 9eac674..a663a74 100644
--- a/Documentation/admin-guide/vga-softcursor.rst
+++ b/Documentation/admin-guide/vga-softcursor.rst
@@ -50,8 +50,8 @@
.. [#f1] see ``#define TRIDENT_GLITCH`` in ``drivers/video/vgacon.c``.
-Examples:
-=========
+Examples
+--------
To get normal blinking underline, use::
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 0f98823..85a6627 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/index
+ 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
diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
index 10cc7dd..c66ab93 100644
--- a/Documentation/kernel-documentation.rst
+++ b/Documentation/kernel-documentation.rst
@@ -1,6 +1,6 @@
-==========================
-Linux Kernel Documentation
-==========================
+=================================
+How to write kernel documentation
+=================================
Introduction
============
diff --git a/Documentation/process/applying-patches.rst b/Documentation/process/applying-patches.rst
index abd7dc7..87825cf 100644
--- a/Documentation/process/applying-patches.rst
+++ b/Documentation/process/applying-patches.rst
@@ -9,6 +9,10 @@
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
diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index 22797a1..56ce661 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 cddf580..10aa692 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -4,34 +4,51 @@
\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
+ :maxdepth: 1
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: 1
+
+ changes
submitting-drivers
stable-api-nonsense
management-style
stable-kernel-rules
- kernel-docs
- applying-patches
- email-clients
submit-checklist
- code-of-conflict
+ kernel-docs
+
+These are some overall technical guides that have been put here for now for
+lack of a better place.
+
+.. toctree::
+ :maxdepth: 1
+
+ applying-patches
adding-syscalls
magic-number
volatile-considered-harmful
- development-process
-
-
.. only:: subproject and html
Indices
diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst
index 0939d01..afb82ee 100644
--- a/Documentation/process/submitting-drivers.rst
+++ b/Documentation/process/submitting-drivers.rst
@@ -8,6 +8,14 @@
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.
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index b4cf8f3..3e10719 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 @@
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 @@
-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 @@
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>