diff options
| -rw-r--r-- | Documentation/admin-guide/bad-memory.rst | 50 | ||||
| -rw-r--r-- | Documentation/admin-guide/basic-profiling.rst | 68 | ||||
| -rw-r--r-- | Documentation/admin-guide/index.rst | 53 | ||||
| -rw-r--r-- | Documentation/admin-guide/kernel-parameters.rst | 4 | ||||
| -rw-r--r-- | Documentation/admin-guide/sysfs-rules.rst | 4 | ||||
| -rw-r--r-- | Documentation/admin-guide/vga-softcursor.rst | 4 | ||||
| -rw-r--r-- | Documentation/index.rst | 45 | ||||
| -rw-r--r-- | Documentation/kernel-documentation.rst | 6 | ||||
| -rw-r--r-- | Documentation/process/applying-patches.rst | 4 | ||||
| -rw-r--r-- | Documentation/process/changes.rst | 2 | ||||
| -rw-r--r-- | Documentation/process/index.rst | 41 | ||||
| -rw-r--r-- | Documentation/process/submitting-drivers.rst | 8 | ||||
| -rw-r--r-- | Documentation/process/submitting-patches.rst | 16 |
13 files changed, 137 insertions, 168 deletions
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/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 fb779e67097b..368845e9900a 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 @@ Contents: sysrq unicode vga-softcursor - sysfs-rules - devices binfmt-misc mono java - bad-memory - basic-profiling .. only:: subproject and html @@ -39,4 +65,3 @@ Contents: ======= * :ref:`genindex` - 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:: diff --git a/Documentation/index.rst b/Documentation/index.rst index 0f98823126f2..85a66270f96c 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 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 ============ 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 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 cddf580671e7..10aa6920709a 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 + 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: 1 + applying-patches - email-clients - submit-checklist - code-of-conflict 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 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. 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> |