Documentation/core-api/padata.rst

Source file repositories/reference/linux-study-clean/Documentation/core-api/padata.rst

File Facts

System
Linux kernel
Corpus path
Documentation/core-api/padata.rst
Extension
.rst
Size
7679 bytes
Lines
179
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct padata_priv {
        /* Other stuff here... */
	void                    (*parallel)(struct padata_priv *padata);
	void                    (*serial)(struct padata_priv *padata);
    };

This structure will almost certainly be embedded within some larger
structure specific to the work to be done.  Most of its fields are private to
padata, but the structure should be zeroed at initialisation time, and the
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.

The submission of the job is done with::

    int padata_do_parallel(struct padata_shell *ps,
		           struct padata_priv *padata, int *cb_cpu);

The ps and padata structures must be set up as described above; cb_cpu
points to the preferred CPU to be used for the final callback when the job is
done; it must be in the current instance's CPU mask (if not the cb_cpu pointer
is updated to point to the CPU actually chosen).  The return value from
padata_do_parallel() is zero on success, indicating that the job is in
progress. -EBUSY means that somebody, somewhere else is messing with the
instance's CPU mask, while -EINVAL is a complaint about cb_cpu not being in the
serial cpumask, no online CPUs in the parallel or serial cpumasks, or a stopped
instance.

Each job submitted to padata_do_parallel() will, in turn, be passed to
exactly one call to the above-mentioned parallel() function, on one CPU, so
true parallelism is achieved by submitting multiple jobs.  parallel() runs with
software interrupts disabled and thus cannot sleep.  The parallel()
function gets the padata_priv structure pointer as its lone parameter;
information about the actual work to be done is probably obtained by using
container_of() to find the enclosing structure.

Note that parallel() has no return value; the padata subsystem assumes that
parallel() will take responsibility for the job from this point.  The job
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
the previous one completes.

Serializing Jobs
----------------

When a job does complete, parallel() (or whatever function actually finishes
the work) should inform padata of the fact with a call to::

    void padata_do_serial(struct padata_priv *padata);

At some point in the future, padata_do_serial() will trigger a call to the
serial() function in the padata_priv structure.  That call will happen on
the CPU requested in the initial call to padata_do_parallel(); it, too, is
run with local software interrupts disabled.
Note that this call may be deferred for a while since the padata code takes
pains to ensure that jobs are completed in the order in which they were
submitted.

Destroying
----------

Cleaning up a padata instance predictably involves calling the two free
functions that correspond to the allocation in reverse::

    void padata_free_shell(struct padata_shell *ps);
    void padata_free(struct padata_instance *pinst);

It is the user's responsibility to ensure all outstanding jobs are complete
before any of the above are called.

Annotation

Implementation Notes