lkml.org 
[lkml]   [2020]   [May]   [27]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v3 8/8] padata: document multithreaded jobs
    Date
    Add Documentation for multithreaded jobs.

    Signed-off-by: Daniel Jordan <daniel.m.jordan@oracle.com>
    Tested-by: Josh Triplett <josh@joshtriplett.org>
    ---
    Documentation/core-api/padata.rst | 41 +++++++++++++++++++++++--------
    1 file changed, 31 insertions(+), 10 deletions(-)

    diff --git a/Documentation/core-api/padata.rst b/Documentation/core-api/padata.rst
    index 9a24c111781d9..0830e5b0e8211 100644
    --- a/Documentation/core-api/padata.rst
    +++ b/Documentation/core-api/padata.rst
    @@ -4,23 +4,26 @@
    The padata parallel execution mechanism
    =======================================

    -:Date: December 2019
    +:Date: May 2020

    Padata is a mechanism by which the kernel can farm jobs out to be done in
    -parallel on multiple CPUs while retaining their ordering. It was developed for
    -use with the IPsec code, which needs to be able to perform encryption and
    -decryption on large numbers of packets without reordering those packets. The
    -crypto developers made a point of writing padata in a sufficiently general
    -fashion that it could be put to other uses as well.
    +parallel on multiple CPUs while optionally retaining their ordering.

    -Usage
    -=====
    +It was originally developed for IPsec, which needs to perform encryption and
    +decryption on large numbers of packets without reordering those packets. This
    +is currently the sole consumer of padata's serialized job support.
    +
    +Padata also supports multithreaded jobs, splitting up the job evenly while load
    +balancing and coordinating between threads.
    +
    +Running Serialized Jobs
    +=======================

    Initializing
    ------------

    -The first step in using padata is to set up a padata_instance structure for
    -overall control of how jobs are to be run::
    +The first step in using padata to run serialized jobs is to set up a
    +padata_instance structure for overall control of how jobs are to be run::

    #include <linux/padata.h>

    @@ -162,6 +165,24 @@ functions that correspond to the allocation in reverse::
    It is the user's responsibility to ensure all outstanding jobs are complete
    before any of the above are called.

    +Running Multithreaded Jobs
    +==========================
    +
    +A multithreaded job has a main thread and zero or more helper threads, with the
    +main thread participating in the job and then waiting until all helpers have
    +finished. padata splits the job into units called chunks, where a chunk is a
    +piece of the job that one thread completes in one call to the thread function.
    +
    +A user has to do three things to run a multithreaded job. First, describe the
    +job by defining a padata_mt_job structure, which is explained in the Interface
    +section. This includes a pointer to the thread function, which padata will
    +call each time it assigns a job chunk to a thread. Then, define the thread
    +function, which accepts three arguments, ``start``, ``end``, and ``arg``, where
    +the first two delimit the range that the thread operates on and the last is a
    +pointer to the job's shared state, if any. Prepare the shared state, which is
    +typically allocated on the main thread's stack. Last, call
    +padata_do_multithreaded(), which will return once the job is finished.
    +
    Interface
    =========

    --
    2.26.2
    \
     
     \ /
      Last update: 2020-05-27 19:38    [W:3.356 / U:0.048 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site