mirror of
https://github.com/torvalds/linux.git
synced 2024-12-29 06:12:08 +00:00
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.
This commit is contained in:
Jonathan Corbet
commit
9d2cccdd6c
@ -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
|
||||
@ -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.
|
||||
@ -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`
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -50,8 +50,8 @@ third parameter
|
||||
|
||||
.. [#f1] see ``#define TRIDENT_GLITCH`` in ``drivers/video/vgacon.c``.
|
||||
|
||||
Examples:
|
||||
=========
|
||||
Examples
|
||||
--------
|
||||
|
||||
To get normal blinking underline, use::
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
==========================
|
||||
Linux Kernel Documentation
|
||||
==========================
|
||||
=================================
|
||||
How to write kernel documentation
|
||||
=================================
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
@ -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
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
.. _changes:
|
||||
|
||||
Minimal requerements to compile the Kernel
|
||||
Minimal requirements to compile the Kernel
|
||||
++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
Intro
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
|
||||
@ -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>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user