Commit 9d2cccdd authored by Jonathan Corbet's avatar Jonathan Corbet

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.
parents 2797cd03 67972a53
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
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.
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:: .. toctree::
:maxdepth: 2 :maxdepth: 1
:numbered:
README 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 reporting-bugs
security-bugs
bug-hunting bug-hunting
oops-tracing oops-tracing
ramoops ramoops
initrd
init
dynamic-debug-howto dynamic-debug-howto
security-bugs init
kernel-parameters
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 serial-console
braille-console braille-console
parport parport
...@@ -25,13 +55,9 @@ Contents: ...@@ -25,13 +55,9 @@ Contents:
sysrq sysrq
unicode unicode
vga-softcursor vga-softcursor
sysfs-rules
devices
binfmt-misc binfmt-misc
mono mono
java java
bad-memory
basic-profiling
.. only:: subproject and html .. only:: subproject and html
...@@ -39,4 +65,3 @@ Contents: ...@@ -39,4 +65,3 @@ Contents:
======= =======
* :ref:`genindex` * :ref:`genindex`
Kernel Parameters The kernel's command-line parameters
~~~~~~~~~~~~~~~~~ ====================================
The following is a consolidated list of the kernel parameters as The following is a consolidated list of the kernel parameters as
implemented by the __setup(), core_param() and module_param() macros implemented by the __setup(), core_param() and module_param() macros
......
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 The kernel-exported sysfs exports internal kernel implementation details
and depends on internal kernel structures and layout. It is agreed upon and depends on internal kernel structures and layout. It is agreed upon
......
...@@ -50,8 +50,8 @@ third parameter ...@@ -50,8 +50,8 @@ third parameter
.. [#f1] see ``#define TRIDENT_GLITCH`` in ``drivers/video/vgacon.c``. .. [#f1] see ``#define TRIDENT_GLITCH`` in ``drivers/video/vgacon.c``.
Examples: Examples
========= --------
To get normal blinking underline, use:: To get normal blinking underline, use::
......
...@@ -3,18 +3,55 @@ ...@@ -3,18 +3,55 @@
You can adapt this file completely to your liking, but it should at least You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive. 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:: .. toctree::
:maxdepth: 2 :maxdepth: 2
admin-guide/index 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 process/index
dev-tools/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 driver-api/index
media/index media/index
gpu/index gpu/index
......
========================== =================================
Linux Kernel Documentation How to write kernel documentation
========================== =================================
Introduction Introduction
============ ============
......
...@@ -9,6 +9,10 @@ Original by: ...@@ -9,6 +9,10 @@ Original by:
Last update: Last update:
2016-09-14 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 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 a patch to the kernel or, more specifically, what base kernel a patch for
......
.. _changes: .. _changes:
Minimal requerements to compile the Kernel Minimal requirements to compile the Kernel
++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++
Intro Intro
......
...@@ -4,34 +4,51 @@ ...@@ -4,34 +4,51 @@
\renewcommand\thesubsection* \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:: .. toctree::
:maxdepth: 2 :maxdepth: 1
howto howto
changes code-of-conflict
coding-style development-process
submitting-patches 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 submitting-drivers
stable-api-nonsense stable-api-nonsense
management-style management-style
stable-kernel-rules stable-kernel-rules
submit-checklist
kernel-docs 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 applying-patches
email-clients
submit-checklist
code-of-conflict
adding-syscalls adding-syscalls
magic-number magic-number
volatile-considered-harmful volatile-considered-harmful
development-process
.. only:: subproject and html .. only:: subproject and html
Indices Indices
......
...@@ -8,6 +8,14 @@ various kernel trees. Note that if you are interested in video card drivers ...@@ -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 you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org
(http://x.org/) instead. (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. Also read the Documentation/process/submitting-patches.rst document.
......
.. _submittingpatches: .. _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 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 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 ...@@ -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 and document a sensible set of patches. In general, use of ``git`` will make
your life as a kernel developer easier. your life as a kernel developer easier.
Creating and Sending your Change
********************************
0) Obtain a current source tree 0) Obtain a current source tree
------------------------------- -------------------------------
...@@ -417,8 +413,8 @@ e-mail discussions. ...@@ -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 To improve tracking of who did what, especially with patches that can
percolate to their final resting place in the kernel through several percolate to their final resting place in the kernel through several
...@@ -803,8 +799,8 @@ command like this will do the trick:: ...@@ -803,8 +799,8 @@ command like this will do the trick::
git request-pull master git://my.public.tree/linux.git my-signed-tag git request-pull master git://my.public.tree/linux.git my-signed-tag
REFERENCES References
********** ----------
Andrew Morton, "The perfect patch" (tpp). Andrew Morton, "The perfect patch" (tpp).
<http://www.ozlabs.org/~akpm/stuff/tpp.txt> <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment