redonkable
/
remarkable-linux
1
0
Fork 0
Code Releases Activity

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.
zero-colors
Jonathan Corbet 2016-10-27 17:05:10 -06:00
parent 2797cd03f5 67972a539e
commit 9d2cccdd6c
13 changed files with 138 additions and 169 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
Documentation/admin-guide/bad-memory.rst
View File

@ -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

68
Documentation/admin-guide/basic-profiling.rst
View File

@ -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.

53
Documentation/admin-guide/index.rst
View File

@ -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`

4
Documentation/admin-guide/kernel-parameters.rst
View File

@ -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

4
Documentation/admin-guide/sysfs-rules.rst
View File

@ -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

4
Documentation/admin-guide/vga-softcursor.rst
View File

@ -50,8 +50,8 @@ third parameter
.. [#f1] see ``#define TRIDENT_GLITCH`` in ``drivers/video/vgacon.c``.
Examples:
=========
Examples
--------
To get normal blinking underline, use::

45
Documentation/index.rst
View File

@ -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

6
Documentation/kernel-documentation.rst
View File

@ -1,6 +1,6 @@
==========================
Linux Kernel Documentation
==========================
=================================
How to write kernel documentation
=================================
Introduction
============

4
Documentation/process/applying-patches.rst
View File

@ -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

2
Documentation/process/changes.rst
View File

@ -1,6 +1,6 @@
.. _changes:
Minimal requerements to compile the Kernel
Minimal requirements to compile the Kernel
++++++++++++++++++++++++++++++++++++++++++
Intro

43
Documentation/process/index.rst
View File

@ -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
Documentation/process/submitting-drivers.rst
View File

@ -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.

16
Documentation/process/submitting-patches.rst
View File

@ -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>