From b51208d41c6a4e7fc2f05e63df49f1834cd3c208 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 15:43:00 -0600 Subject: [PATCH 01/10] docs: Tweak the top-level Sphinx page 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. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 From 555af62431e69105b4d20628181acf414759a70d Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 15:55:20 -0600 Subject: [PATCH 02/10] docs: retitle the kernel-documentation.rst Let's make the title of this document (which shows up in the top page) better describe its contents. Cc: Jani Nikula Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 ============ From 7358bb2f3293461737a61850c56523695f5b2219 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:14:52 -0600 Subject: [PATCH 03/10] docs: Clean up and organize the admin guide a bit 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. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/index.rst | 50 +++++++++++++++---- .../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..abad33526aca 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:: From 2c79dcafd8ecdfd44ee4c509a9c55785b022eba9 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:20:27 -0600 Subject: [PATCH 04/10] docs: Get rid of the badRAM guide 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 --- 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=$
- -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 From 5700d1974818a98983e018efa01da9bc81b84e1a Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:22:01 -0600 Subject: [PATCH 05/10] docs: Get rid of the "basic profiling" guide 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 --- 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. - -```` 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 - - 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 - - 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 From 9b4ebd98da9112f974a6db58555a33eb1bd7c0b0 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:34:09 -0600 Subject: [PATCH 06/10] docs: Apply some basic organization to the process guide Put like documents together, with the essential ones at the top, and split the TOC into sections. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/process/changes.rst | 2 +- Documentation/process/index.rst | 39 +++++++++++++++++++++++-------- 2 files changed, 30 insertions(+), 11 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 - 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: 2 + + applying-patches adding-syscalls magic-number volatile-considered-harmful - development-process From 89edeedd61e8faa4e092f3797606739317abeb6c Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:37:53 -0600 Subject: [PATCH 07/10] docs: Tweak submitting-patches.rst formatting 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. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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). From be4612447b3721a9a9f14ea5189217d69bc83078 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:41:05 -0600 Subject: [PATCH 08/10] docs: Collapse the process guide TOC I believe this makes the page as a whole more approachable. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 From 31b24bee33572031632c33091bb73ed0e949c53a Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:45:29 -0600 Subject: [PATCH 09/10] docs: add a warning to submitting-drivers.rst This is crufty stuff and should maybe just be deleted, but I'm not quite ready to do that yet. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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. From 67972a539e9ff1a3ed794c463c4e544442df693e Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:48:36 -0600 Subject: [PATCH 10/10] docs: Add a warning to applying-patches.rst 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. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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