Commit 7576b2b9 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet

padata.txt: standardize document format

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: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent e4a5c33e
=======================================
The padata parallel execution mechanism 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 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 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 ...@@ -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. 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 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> #include <linux/padata.h>
...@@ -24,7 +27,7 @@ The workqueue wq is where the work will actually be done; it should be ...@@ -24,7 +27,7 @@ The workqueue wq is where the work will actually be done; it should be
a multithreaded queue, naturally. a multithreaded queue, naturally.
To allocate a padata instance with the cpu_possible_mask for both 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); 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. ...@@ -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 Once an offline CPU in the user supplied cpumask comes online, padata
is going to use it. 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); int padata_start(struct padata_instance *pinst);
void padata_stop(struct padata_instance *pinst); void padata_stop(struct padata_instance *pinst);
...@@ -48,7 +51,7 @@ padata cpumask contains no active CPU (flag not set). ...@@ -48,7 +51,7 @@ padata cpumask contains no active CPU (flag not set).
padata_stop clears the flag and blocks until the padata instance padata_stop clears the flag and blocks until the padata instance
is unused. 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, int padata_set_cpumasks(struct padata_instance *pinst,
cpumask_var_t pcpumask, cpumask_var_t pcpumask,
...@@ -71,12 +74,12 @@ padata_add_cpu/padata_remove_cpu are used. cpu specifies the CPU to add or ...@@ -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. 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 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, int padata_register_cpumask_notifier(struct padata_instance *pinst,
struct notifier_block *nblock); struct notifier_block *nblock);
To unregister from that notifier: To unregister from that notifier::
int padata_unregister_cpumask_notifier(struct padata_instance *pinst, int padata_unregister_cpumask_notifier(struct padata_instance *pinst,
struct notifier_block *nblock); struct notifier_block *nblock);
...@@ -84,7 +87,7 @@ To unregister from that notifier: ...@@ -84,7 +87,7 @@ To unregister from that notifier:
The padata cpumask change notifier notifies about changes of the usable The padata cpumask change notifier notifies about changes of the usable
cpumasks, i.e. the subset of active CPUs in the user supplied cpumask. 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, blocking_notifier_call_chain(&pinst->cpumask_change_notifier,
notification_mask, notification_mask,
...@@ -95,7 +98,7 @@ is one of PADATA_CPU_SERIAL, PADATA_CPU_PARALLEL and cpumask is a pointer ...@@ -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. to a struct padata_cpumask that contains the new cpumask information.
Actually submitting work to the padata instance requires the creation of a Actually submitting work to the padata instance requires the creation of a
padata_priv structure: padata_priv structure::
struct padata_priv { struct padata_priv {
/* Other stuff here... */ /* Other stuff here... */
...@@ -110,7 +113,7 @@ parallel() and serial() functions should be provided. Those functions will ...@@ -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 be called in the process of getting the work done as we will see
momentarily. momentarily.
The submission of work is done with: The submission of work is done with::
int padata_do_parallel(struct padata_instance *pinst, int padata_do_parallel(struct padata_instance *pinst,
struct padata_priv *padata, int cb_cpu); struct padata_priv *padata, int cb_cpu);
...@@ -138,7 +141,7 @@ need not be completed during this call, but, if parallel() leaves work ...@@ -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 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 the previous one completes. When a task does complete, parallel() (or
whatever function actually finishes the job) should inform padata of the 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); 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 ...@@ -151,7 +154,7 @@ pains to ensure that tasks are completed in the order in which they were
submitted. submitted.
The one remaining function in the padata API should be called to clean up 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); void padata_free(struct padata_instance *pinst);
......
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