lkml.org 
[lkml]   [2010]   [Aug]   [3]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH 7/7] padata: update API documentation
On Tue, 27 Jul 2010 07:20:47 +0200 Steffen Klassert wrote:

>
> Signed-off-by: Steffen Klassert <steffen.klassert@secunet.com>
> ---
> Documentation/padata.txt | 76 ++++++++++++++++++++++++++++++++++++++-------
> 1 files changed, 64 insertions(+), 12 deletions(-)
>
> diff --git a/Documentation/padata.txt b/Documentation/padata.txt
> index 93dd4e6..ad2a0ff 100644
> --- a/Documentation/padata.txt
> +++ b/Documentation/padata.txt
> @@ -1,5 +1,5 @@
> The padata parallel execution mechanism
> -Last updated for 2.6.34
> +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
> @@ -13,12 +13,28 @@ overall control of how tasks are to be run:
>
> #include <linux/padata.h>
>
> - struct padata_instance *padata_alloc(const struct cpumask *cpumask,
> - struct workqueue_struct *wq);
> + struct padata_instance *padata_alloc(struct workqueue_struct *wq,
> + const struct cpumask *pcpumask,
> + const struct cpumask *cbcpumask);
>
> -The cpumask describes which processors will be used to execute work
> -submitted to this instance. The workqueue wq is where the work will
> -actually be done; it should be a multithreaded queue, naturally.
> +The pcpumask describes which processors will be used to execute work
> +submitted to this instance in parallel. The cbcpumask defines which
> +processors are allowed to use as the serialization callback processor.

to be used as

> +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:
> +
> + struct padata_instance *padata_alloc_possible(struct workqueue_struct *wq);
> +
> +Note: Padata maintains two kinds of cpumasks internally. The user supplied
> +cpumasks, submitted by padata_alloc/padata_alloc_possible and the 'usable'
> +cpumasks. The usable cpumasks are always the subset of active cpus in the

a subset of

> +user supplied cpumasks, these are the cpumasks padata actually use. So

cpumasks; uses.

> +it is legal to supply a cpumask to padata that contains offline cpus.
> +Once a offline cpu in the user supplied cpumask comes online, padata

an offline

and prefer s/cpu/CPU/ throughout (in text, but not when it is a function
parameter, of course)


> +is going to use it.
>
> There are functions for enabling and disabling the instance:
>
> @@ -34,13 +50,49 @@ is unused.
>
> The list of CPUs to be used can be adjusted with these functions:
>
> - int padata_set_cpumask(struct padata_instance *pinst,
> + int padata_set_cpumasks(struct padata_instance *pinst,
> + cpumask_var_t pcpumask,
> + cpumask_var_t cbcpumask);
> + int padata_set_cpumask(struct padata_instance *pinst, int cpumask_type,
> cpumask_var_t cpumask);
> - int padata_add_cpu(struct padata_instance *pinst, int cpu);
> - int padata_remove_cpu(struct padata_instance *pinst, int cpu);
> + int padata_add_cpu(struct padata_instance *pinst, int cpu, int mask);
> + int padata_remove_cpu(struct padata_instance *pinst, int cpu, int mask);
> +
> +Changing the CPU masks are expensive operations, though, so it should not be
> +done with great frequency.
> +
> +It's possible to change both cpumasks of a padata instance with
> +padata_set_cpumasks by specifying the cpumasks for parallel execution (pcpumask)
> +and for the serial callback function (cbcpumask). padata_set_cpumask is to

is used to

> +change just one of the cpumasks. Here cpumask_type is one of PADATA_CPU_SERIAL,
> +PADATA_CPU_PARALLEL and cpumask specifies the new cpumask to use.
> +To simply add or remove one cpu from a certain cpumask the functions
> +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:
> +
> + int padata_register_cpumask_notifier(struct padata_instance *pinst,
> + struct notifier_block *nblock);
> +
> +To unregister from that notifier:
> +
> + int padata_unregister_cpumask_notifier(struct padata_instance *pinst,
> + struct notifier_block *nblock);
> +
> +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:
> +
> + blocking_notifier_call_chain(&pinst->cpumask_change_notifier,
> + notification_mask,
> + &pd_new->cpumask);
>
> -Changing the CPU mask has the look of an expensive operation, though, so it
> -probably should not be done with great frequency.
> +Here cpumask_change_notifier is registered notifier, notification_mask
> +is one of PADATA_CPU_SERIAL, PADATA_CPU_PARALLEL and cpumask is a pointer
> +to a struct padata_cpumask that contains the new cpumask informations.

information.

>
> Actually submitting work to the padata instance requires the creation of a
> padata_priv structure:
> @@ -53,7 +105,7 @@ padata_priv structure:
>
> This structure will almost certainly be embedded within some larger
> structure specific to the work to be done. Most its fields are private to

Most of its

> -padata, but the structure should be zeroed at initialization time, and the
> +padata, but the structure should be zeroed at initialisation time, and the

^^either spelling is OK

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


---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

\
 
 \ /
  Last update: 2010-08-03 19:57    [from the cache]
©2003-2011 Jasper Spaans