Documentation/core-api/padata.rst

1 .. SPDX-License-Identifier: GPL-2.0
4 The padata parallel execution mechanism
9 Padata is a mechanism by which the kernel can farm jobs out to be done in
10 parallel on multiple CPUs while optionally retaining their ordering.
23 ------------
25 The first step in using padata to run serialized jobs is to set up a
43 ------------------
45 The CPUs used to run jobs can be changed in two ways, programmatically with
52 parallel cpumask describes which processors will be used to execute jobs
53 submitted to this instance in parallel and a serial cpumask defines which
58 live in /sys/kernel/pcrypt/<instance-name>.  Within an instance's directory
64 Reading one of these files shows the user-supplied cpumask, which may be
67 Padata maintains two pairs of cpumasks internally, the user-supplied cpumasks
68 and the 'usable' cpumasks.  (Each pair consists of a parallel and a serial
69 cpumask.)  The user-supplied cpumasks default to all possible CPUs on instance
71 subset of the user-supplied cpumasks and contain only the online CPUs in the
72 user-supplied masks; these are the cpumasks padata actually uses.  So it is
74 offline CPU in the user-supplied cpumask comes online, padata is going to use
81 -------------
88 	void                    (*parallel)(struct padata_priv *padata);
95 parallel() and serial() functions should be provided.  Those functions will
96 be called in the process of getting the work done as we will see
106 done; it must be in the current instance's CPU mask (if not the cb_cpu pointer
108 padata_do_parallel() is zero on success, indicating that the job is in
109 progress. -EBUSY means that somebody, somewhere else is messing with the
110 instance's CPU mask, while -EINVAL is a complaint about cb_cpu not being in the
111 serial cpumask, no online CPUs in the parallel or serial cpumasks, or a stopped
114 Each job submitted to padata_do_parallel() will, in turn, be passed to
115 exactly one call to the above-mentioned parallel() function, on one CPU, so
116 true parallelism is achieved by submitting multiple jobs.  parallel() runs with
117 software interrupts disabled and thus cannot sleep.  The parallel()
122 Note that parallel() has no return value; the padata subsystem assumes that
123 parallel() will take responsibility for the job from this point.  The job
124 need not be completed during this call, but, if parallel() leaves work
129 ----------------
131 When a job does complete, parallel() (or whatever function actually finishes
136 At some point in the future, padata_do_serial() will trigger a call to the
137 serial() function in the padata_priv structure.  That call will happen on
138 the CPU requested in the initial call to padata_do_parallel(); it, too, is
141 pains to ensure that jobs are completed in the order in which they were
145 ----------
148 functions that correspond to the allocation in reverse::
160 main thread participating in the job and then waiting until all helpers have
162 piece of the job that one thread completes in one call to the thread function.
165 job by defining a padata_mt_job structure, which is explained in the Interface
177 .. kernel-doc:: include/linux/padata.h
178 .. kernel-doc:: kernel/padata.c