|
| 1 | +.. SPDX-License-Identifier: GPL-2.0 |
| 2 | +
|
| 3 | +======================================= |
| 4 | +The padata parallel execution mechanism |
| 5 | +======================================= |
| 6 | + |
| 7 | +:Date: December 2019 |
| 8 | + |
| 9 | +Padata is a mechanism by which the kernel can farm jobs out to be done in |
| 10 | +parallel on multiple CPUs while retaining their ordering. It was developed for |
| 11 | +use with the IPsec code, which needs to be able to perform encryption and |
| 12 | +decryption on large numbers of packets without reordering those packets. The |
| 13 | +crypto developers made a point of writing padata in a sufficiently general |
| 14 | +fashion that it could be put to other uses as well. |
| 15 | + |
| 16 | +Usage |
| 17 | +===== |
| 18 | + |
| 19 | +Initializing |
| 20 | +------------ |
| 21 | + |
| 22 | +The first step in using padata is to set up a padata_instance structure for |
| 23 | +overall control of how jobs are to be run:: |
| 24 | + |
| 25 | + #include <linux/padata.h> |
| 26 | + |
| 27 | + struct padata_instance *padata_alloc_possible(const char *name); |
| 28 | + |
| 29 | +'name' simply identifies the instance. |
| 30 | + |
| 31 | +There are functions for enabling and disabling the instance:: |
| 32 | + |
| 33 | + int padata_start(struct padata_instance *pinst); |
| 34 | + void padata_stop(struct padata_instance *pinst); |
| 35 | + |
| 36 | +These functions are setting or clearing the "PADATA_INIT" flag; if that flag is |
| 37 | +not set, other functions will refuse to work. padata_start() returns zero on |
| 38 | +success (flag set) or -EINVAL if the padata cpumask contains no active CPU |
| 39 | +(flag not set). padata_stop() clears the flag and blocks until the padata |
| 40 | +instance is unused. |
| 41 | + |
| 42 | +Finally, complete padata initialization by allocating a padata_shell:: |
| 43 | + |
| 44 | + struct padata_shell *padata_alloc_shell(struct padata_instance *pinst); |
| 45 | + |
| 46 | +A padata_shell is used to submit a job to padata and allows a series of such |
| 47 | +jobs to be serialized independently. A padata_instance may have one or more |
| 48 | +padata_shells associated with it, each allowing a separate series of jobs. |
| 49 | + |
| 50 | +Modifying cpumasks |
| 51 | +------------------ |
| 52 | + |
| 53 | +The CPUs used to run jobs can be changed in two ways, programatically with |
| 54 | +padata_set_cpumask() or via sysfs. The former is defined:: |
| 55 | + |
| 56 | + int padata_set_cpumask(struct padata_instance *pinst, int cpumask_type, |
| 57 | + cpumask_var_t cpumask); |
| 58 | + |
| 59 | +Here cpumask_type is one of PADATA_CPU_PARALLEL or PADATA_CPU_SERIAL, where a |
| 60 | +parallel cpumask describes which processors will be used to execute jobs |
| 61 | +submitted to this instance in parallel and a serial cpumask defines which |
| 62 | +processors are allowed to be used as the serialization callback processor. |
| 63 | +cpumask specifies the new cpumask to use. |
| 64 | + |
| 65 | +There may be sysfs files for an instance's cpumasks. For example, pcrypt's |
| 66 | +live in /sys/kernel/pcrypt/<instance-name>. Within an instance's directory |
| 67 | +there are two files, parallel_cpumask and serial_cpumask, and either cpumask |
| 68 | +may be changed by echoing a bitmask into the file, for example:: |
| 69 | + |
| 70 | + echo f > /sys/kernel/pcrypt/pencrypt/parallel_cpumask |
| 71 | + |
| 72 | +Reading one of these files shows the user-supplied cpumask, which may be |
| 73 | +different from the 'usable' cpumask. |
| 74 | + |
| 75 | +Padata maintains two pairs of cpumasks internally, the user-supplied cpumasks |
| 76 | +and the 'usable' cpumasks. (Each pair consists of a parallel and a serial |
| 77 | +cpumask.) The user-supplied cpumasks default to all possible CPUs on instance |
| 78 | +allocation and may be changed as above. The usable cpumasks are always a |
| 79 | +subset of the user-supplied cpumasks and contain only the online CPUs in the |
| 80 | +user-supplied masks; these are the cpumasks padata actually uses. So it is |
| 81 | +legal to supply a cpumask to padata that contains offline CPUs. Once an |
| 82 | +offline CPU in the user-supplied cpumask comes online, padata is going to use |
| 83 | +it. |
| 84 | + |
| 85 | +Changing the CPU masks are expensive operations, so it should not be done with |
| 86 | +great frequency. |
| 87 | + |
| 88 | +Running A Job |
| 89 | +------------- |
| 90 | + |
| 91 | +Actually submitting work to the padata instance requires the creation of a |
| 92 | +padata_priv structure, which represents one job:: |
| 93 | + |
| 94 | + struct padata_priv { |
| 95 | + /* Other stuff here... */ |
| 96 | + void (*parallel)(struct padata_priv *padata); |
| 97 | + void (*serial)(struct padata_priv *padata); |
| 98 | + }; |
| 99 | + |
| 100 | +This structure will almost certainly be embedded within some larger |
| 101 | +structure specific to the work to be done. Most of its fields are private to |
| 102 | +padata, but the structure should be zeroed at initialisation time, and the |
| 103 | +parallel() and serial() functions should be provided. Those functions will |
| 104 | +be called in the process of getting the work done as we will see |
| 105 | +momentarily. |
| 106 | + |
| 107 | +The submission of the job is done with:: |
| 108 | + |
| 109 | + int padata_do_parallel(struct padata_shell *ps, |
| 110 | + struct padata_priv *padata, int *cb_cpu); |
| 111 | + |
| 112 | +The ps and padata structures must be set up as described above; cb_cpu |
| 113 | +points to the preferred CPU to be used for the final callback when the job is |
| 114 | +done; it must be in the current instance's CPU mask (if not the cb_cpu pointer |
| 115 | +is updated to point to the CPU actually chosen). The return value from |
| 116 | +padata_do_parallel() is zero on success, indicating that the job is in |
| 117 | +progress. -EBUSY means that somebody, somewhere else is messing with the |
| 118 | +instance's CPU mask, while -EINVAL is a complaint about cb_cpu not being in the |
| 119 | +serial cpumask, no online CPUs in the parallel or serial cpumasks, or a stopped |
| 120 | +instance. |
| 121 | + |
| 122 | +Each job submitted to padata_do_parallel() will, in turn, be passed to |
| 123 | +exactly one call to the above-mentioned parallel() function, on one CPU, so |
| 124 | +true parallelism is achieved by submitting multiple jobs. parallel() runs with |
| 125 | +software interrupts disabled and thus cannot sleep. The parallel() |
| 126 | +function gets the padata_priv structure pointer as its lone parameter; |
| 127 | +information about the actual work to be done is probably obtained by using |
| 128 | +container_of() to find the enclosing structure. |
| 129 | + |
| 130 | +Note that parallel() has no return value; the padata subsystem assumes that |
| 131 | +parallel() will take responsibility for the job from this point. The job |
| 132 | +need not be completed during this call, but, if parallel() leaves work |
| 133 | +outstanding, it should be prepared to be called again with a new job before |
| 134 | +the previous one completes. |
| 135 | + |
| 136 | +Serializing Jobs |
| 137 | +---------------- |
| 138 | + |
| 139 | +When a job does complete, parallel() (or whatever function actually finishes |
| 140 | +the work) should inform padata of the fact with a call to:: |
| 141 | + |
| 142 | + void padata_do_serial(struct padata_priv *padata); |
| 143 | + |
| 144 | +At some point in the future, padata_do_serial() will trigger a call to the |
| 145 | +serial() function in the padata_priv structure. That call will happen on |
| 146 | +the CPU requested in the initial call to padata_do_parallel(); it, too, is |
| 147 | +run with local software interrupts disabled. |
| 148 | +Note that this call may be deferred for a while since the padata code takes |
| 149 | +pains to ensure that jobs are completed in the order in which they were |
| 150 | +submitted. |
| 151 | + |
| 152 | +Destroying |
| 153 | +---------- |
| 154 | + |
| 155 | +Cleaning up a padata instance predictably involves calling the three free |
| 156 | +functions that correspond to the allocation in reverse:: |
| 157 | + |
| 158 | + void padata_free_shell(struct padata_shell *ps); |
| 159 | + void padata_stop(struct padata_instance *pinst); |
| 160 | + void padata_free(struct padata_instance *pinst); |
| 161 | + |
| 162 | +It is the user's responsibility to ensure all outstanding jobs are complete |
| 163 | +before any of the above are called. |
| 164 | + |
| 165 | +Interface |
| 166 | +========= |
| 167 | + |
| 168 | +.. kernel-doc:: include/linux/padata.h |
| 169 | +.. kernel-doc:: kernel/padata.c |
0 commit comments