Each document under Documentation/*.txt has its own format.
Some follow markup notations, some don't even have a title!
In order to try to get some order on it, change the document
style to the standard we're adopting after the adoption of
ReStructured Text.
The documents touched on this series now build fine with
Sphinx, if renamed to *.rst extension.
The main goal with this is to teach people by example about
what format is expected on newer documents. It also helps
to add those files to Kernel books.
In order to make things more palatable, I'm spliting the
conversion into three parts.
This is part 2.
Mauro Carvalho Chehab (30):
iostats.txt: update it to cover recent Kernels
IPMI.txt: standardize document format
IRQ-affinity.txt: standardize document format
IRQ-domain.txt: standardize document format
irqflags-tracing.txt: standardize document format
IRQ.txt: add a markup for its title
isapnp.txt: promote title level
isa.txt: standardize document format
kernel-per-CPU-kthreads.txt: standardize document format
kobject.txt: standardize document format
kprobes.txt: standardize document format
kref.txt: standardize document format
kselftest.txt: standardize document format
ldm.txt: standardize document format
lockup-watchdogs.txt: standardize document format
lzo.txt: standardize document format
mailbox.txt: standardize document format
memory-barriers.txt: standardize document format
memory-barriers.txt: use literals for variables
memory-hotplug.txt: standardize document format
men-chameleon-bus.txt: standardize document format
nommu-mmap.txt: standardize document format
nommu-mmap.txt: don't use all upper case on titles
ntb.txt: standardize document format
numastat.txt: standardize document format
padata.txt: standardize document format
parport-lowlevel.txt: standardize document format
percpu-rw-semaphore.txt: standardize document format
phy.txt: standardize document format
pi-futex.txt: standardize document format
Documentation/IPMI.txt | 76 +-
Documentation/IRQ-affinity.txt | 77 +-
Documentation/IRQ-domain.txt | 69 +-
Documentation/IRQ.txt | 2 +
Documentation/iostats.txt | 44 +-
Documentation/irqflags-tracing.txt | 10 +-
Documentation/isa.txt | 53 +-
Documentation/isapnp.txt | 1 +
Documentation/kernel-per-CPU-kthreads.txt | 156 +++-
Documentation/kobject.txt | 69 +-
Documentation/kprobes.txt | 450 ++++++----
Documentation/kref.txt | 285 ++++---
Documentation/kselftest.txt | 37 +-
Documentation/ldm.txt | 54 +-
Documentation/lockup-watchdogs.txt | 3 +-
Documentation/lzo.txt | 27 +-
Documentation/mailbox.txt | 181 ++--
Documentation/memory-barriers.txt | 794 +++++++++---------
Documentation/memory-hotplug.txt | 357 ++++----
Documentation/men-chameleon-bus.txt | 298 +++----
Documentation/nommu-mmap.txt | 68 +-
Documentation/ntb.txt | 55 +-
Documentation/numastat.txt | 5 +-
Documentation/padata.txt | 27 +-
Documentation/parport-lowlevel.txt | 1303 ++++++++++++++++++-----------
Documentation/percpu-rw-semaphore.txt | 3 +-
Documentation/phy.txt | 106 ++-
Documentation/pi-futex.txt | 15 +-
28 files changed, 2683 insertions(+), 1942 deletions(-)
--
2.9.4
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- mark document title;
- mark literal blocks.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/padata.txt | 27 +++++++++++++++------------
1 file changed, 15 insertions(+), 12 deletions(-)
diff --git a/Documentation/padata.txt b/Documentation/padata.txt
index 7ddfe216a0aa..b103d0c82000 100644
--- a/Documentation/padata.txt
+++ b/Documentation/padata.txt
@@ -1,5 +1,8 @@
+=======================================
The padata parallel execution mechanism
-Last updated for 2.6.36
+=======================================
+
+:Last updated: for 2.6.36
Padata is a mechanism by which the kernel can farm work out to be done in
parallel on multiple CPUs while retaining the ordering of tasks. It was
@@ -9,7 +12,7 @@ those packets. The crypto developers made a point of writing padata in a
sufficiently general fashion that it could be put to other uses as well.
The first step in using padata is to set up a padata_instance structure for
-overall control of how tasks are to be run:
+overall control of how tasks are to be run::
#include <linux/padata.h>
@@ -24,7 +27,7 @@ The workqueue wq is where the work will actually be done; it should be
a multithreaded queue, naturally.
To allocate a padata instance with the cpu_possible_mask for both
-cpumasks this helper function can be used:
+cpumasks this helper function can be used::
struct padata_instance *padata_alloc_possible(struct workqueue_struct *wq);
@@ -36,7 +39,7 @@ it is legal to supply a cpumask to padata that contains offline CPUs.
Once an offline CPU in the user supplied cpumask comes online, padata
is going to use it.
-There are functions for enabling and disabling the instance:
+There are functions for enabling and disabling the instance::
int padata_start(struct padata_instance *pinst);
void padata_stop(struct padata_instance *pinst);
@@ -48,7 +51,7 @@ padata cpumask contains no active CPU (flag not set).
padata_stop clears the flag and blocks until the padata instance
is unused.
-The list of CPUs to be used can be adjusted with these functions:
+The list of CPUs to be used can be adjusted with these functions::
int padata_set_cpumasks(struct padata_instance *pinst,
cpumask_var_t pcpumask,
@@ -71,12 +74,12 @@ padata_add_cpu/padata_remove_cpu are used. cpu specifies the CPU to add or
remove and mask is one of PADATA_CPU_SERIAL, PADATA_CPU_PARALLEL.
If a user is interested in padata cpumask changes, he can register to
-the padata cpumask change notifier:
+the padata cpumask change notifier::
int padata_register_cpumask_notifier(struct padata_instance *pinst,
struct notifier_block *nblock);
-To unregister from that notifier:
+To unregister from that notifier::
int padata_unregister_cpumask_notifier(struct padata_instance *pinst,
struct notifier_block *nblock);
@@ -84,7 +87,7 @@ To unregister from that notifier:
The padata cpumask change notifier notifies about changes of the usable
cpumasks, i.e. the subset of active CPUs in the user supplied cpumask.
-Padata calls the notifier chain with:
+Padata calls the notifier chain with::
blocking_notifier_call_chain(&pinst->cpumask_change_notifier,
notification_mask,
@@ -95,7 +98,7 @@ is one of PADATA_CPU_SERIAL, PADATA_CPU_PARALLEL and cpumask is a pointer
to a struct padata_cpumask that contains the new cpumask information.
Actually submitting work to the padata instance requires the creation of a
-padata_priv structure:
+padata_priv structure::
struct padata_priv {
/* Other stuff here... */
@@ -110,7 +113,7 @@ parallel() and serial() functions should be provided. Those functions will
be called in the process of getting the work done as we will see
momentarily.
-The submission of work is done with:
+The submission of work is done with::
int padata_do_parallel(struct padata_instance *pinst,
struct padata_priv *padata, int cb_cpu);
@@ -138,7 +141,7 @@ need not be completed during this call, but, if parallel() leaves work
outstanding, it should be prepared to be called again with a new job before
the previous one completes. When a task does complete, parallel() (or
whatever function actually finishes the job) should inform padata of the
-fact with a call to:
+fact with a call to::
void padata_do_serial(struct padata_priv *padata);
@@ -151,7 +154,7 @@ pains to ensure that tasks are completed in the order in which they were
submitted.
The one remaining function in the padata API should be called to clean up
-when a padata instance is no longer needed:
+when a padata instance is no longer needed::
void padata_free(struct padata_instance *pinst);
--
2.9.4