linux-kernel - Re: [PATCH 7/7] padata: update API documentation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Message-Id: <20100803105312.953f42c2.randy.dunlap@oracle.com>
Date:	Tue, 3 Aug 2010 10:53:12 -0700
From:	Randy Dunlap <randy.dunlap@...cle.com>
To:	Steffen Klassert <steffen.klassert@...unet.com>
Cc:	Herbert Xu <herbert@...dor.hengli.com.au>,
	Dan Kruchinin <dkruchinin@....org>,
	Andrew Morton <akpm@...ux-foundation.org>,
	linux-crypto@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [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@...unet.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 ***
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/