From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-9.5 required=3.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI,SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,UNPARSEABLE_RELAY,URIBL_BLOCKED,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 6EAE4C433DF for ; Wed, 27 May 2020 17:37:26 +0000 (UTC) Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.kernel.org (Postfix) with ESMTP id 2A7BB20707 for ; Wed, 27 May 2020 17:37:26 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=oracle.com header.i=@oracle.com header.b="aYPx7daN" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 2A7BB20707 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=oracle.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=owner-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix) id CA415800BB; Wed, 27 May 2020 13:37:25 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id C563C800B6; Wed, 27 May 2020 13:37:25 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id B69F5800BB; Wed, 27 May 2020 13:37:25 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0103.hostedemail.com [216.40.44.103]) by kanga.kvack.org (Postfix) with ESMTP id 9E335800B6 for ; Wed, 27 May 2020 13:37:25 -0400 (EDT) Received: from smtpin06.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay05.hostedemail.com (Postfix) with ESMTP id 63280181AC9B6 for ; Wed, 27 May 2020 17:37:25 +0000 (UTC) X-FDA: 76863205650.06.suit32_210cff626d54 Received: from filter.hostedemail.com (10.5.16.251.rfc1918.com [10.5.16.251]) by smtpin06.hostedemail.com (Postfix) with ESMTP id 4C12A100F63E7 for ; Wed, 27 May 2020 17:37:25 +0000 (UTC) X-HE-Tag: suit32_210cff626d54 X-Filterd-Recvd-Size: 7711 Received: from aserp2120.oracle.com (aserp2120.oracle.com [141.146.126.78]) by imf39.hostedemail.com (Postfix) with ESMTP for ; Wed, 27 May 2020 17:37:24 +0000 (UTC) Received: from pps.filterd (aserp2120.oracle.com [127.0.0.1]) by aserp2120.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 04RHSRtE066275; Wed, 27 May 2020 17:36:36 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=from : to : cc : subject : date : message-id : in-reply-to : references : mime-version : content-transfer-encoding; s=corp-2020-01-29; bh=i/6XgwHHHOgoW5TU+a/aVclmsApnQYa1z6EDveHJZOY=; b=aYPx7daNvdWh1SteBGYuCo3aP0mPn56fA8eCky3L0YZ3J+CXbm344uPti2Pcb930sz/m aD18jOEtXBMLjiCLVBuqTch+QKSTWWX5GyG2aK6xiFFlWgwqDhC+nAG/qNOhBLbVst1C 36bhTB/wrIuLgdLKibdqUXXEtbOHHOR5ZIfRSTA30cvhiRQSJywhRcuh3lgvpeBWgyld 0fszqEapBamiaE+VOApwXSwqnVvl4iruf/RuJlZRHO1TLTJbKF/EPwPGimUjZl4COvnx XhB9u1wf72kFAwRgIMcDHlEOyCIHtSTVlo1MMaOeKmG874IqN07GmRFCBICOrj+QQJ7E nQ== Received: from aserp3030.oracle.com (aserp3030.oracle.com [141.146.126.71]) by aserp2120.oracle.com with ESMTP id 318xe1gubs-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Wed, 27 May 2020 17:36:36 +0000 Received: from pps.filterd (aserp3030.oracle.com [127.0.0.1]) by aserp3030.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 04RHX4lq195410; Wed, 27 May 2020 17:36:36 GMT Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by aserp3030.oracle.com with ESMTP id 317ddr6jyg-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Wed, 27 May 2020 17:36:36 +0000 Received: from abhmp0002.oracle.com (abhmp0002.oracle.com [141.146.116.8]) by aserv0121.oracle.com (8.14.4/8.13.8) with ESMTP id 04RHaYCm012759; Wed, 27 May 2020 17:36:34 GMT Received: from localhost.localdomain (/98.229.125.203) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Wed, 27 May 2020 10:36:33 -0700 From: Daniel Jordan To: Andrew Morton , Herbert Xu , Steffen Klassert Cc: Alex Williamson , Alexander Duyck , Dan Williams , Dave Hansen , David Hildenbrand , Jason Gunthorpe , Jonathan Corbet , Josh Triplett , Kirill Tkhai , Michal Hocko , Pavel Machek , Pavel Tatashin , Peter Zijlstra , Randy Dunlap , Robert Elliott , Shile Zhang , Steven Sistare , Tejun Heo , Zi Yan , linux-crypto@vger.kernel.org, linux-mm@kvack.org, linux-kernel@vger.kernel.org, linux-s390@vger.kernel.org, linuxppc-dev@lists.ozlabs.org, Daniel Jordan Subject: [PATCH v3 8/8] padata: document multithreaded jobs Date: Wed, 27 May 2020 13:36:08 -0400 Message-Id: <20200527173608.2885243-9-daniel.m.jordan@oracle.com> X-Mailer: git-send-email 2.26.2 In-Reply-To: <20200527173608.2885243-1-daniel.m.jordan@oracle.com> References: <20200527173608.2885243-1-daniel.m.jordan@oracle.com> MIME-Version: 1.0 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9633 signatures=668686 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 mlxlogscore=999 bulkscore=0 mlxscore=0 phishscore=0 adultscore=0 suspectscore=0 spamscore=0 malwarescore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2004280000 definitions=main-2005270137 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9633 signatures=668686 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 spamscore=0 mlxlogscore=999 adultscore=0 cotscore=-2147483648 mlxscore=0 bulkscore=0 priorityscore=1501 phishscore=0 lowpriorityscore=0 malwarescore=0 clxscore=1015 impostorscore=0 suspectscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2004280000 definitions=main-2005270136 X-Rspamd-Queue-Id: 4C12A100F63E7 X-Spamd-Result: default: False [0.00 / 100.00] X-Rspamd-Server: rspam05 Content-Transfer-Encoding: quoted-printable X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: Add Documentation for multithreaded jobs. Signed-off-by: Daniel Jordan Tested-by: Josh Triplett --- 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/p= adata.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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -:Date: December 2019 +:Date: May 2020 =20 Padata is a mechanism by which the kernel can farm jobs out to be done i= n -parallel on multiple CPUs while retaining their ordering. It was develo= ped for -use with the IPsec code, which needs to be able to perform encryption an= d -decryption on large numbers of packets without reordering those packets.= The -crypto developers made a point of writing padata in a sufficiently gener= al -fashion that it could be put to other uses as well. +parallel on multiple CPUs while optionally retaining their ordering. =20 -Usage -=3D=3D=3D=3D=3D +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 whi= le load +balancing and coordinating between threads. + +Running Serialized Jobs +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 Initializing ------------ =20 -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:= : =20 #include =20 @@ -162,6 +165,24 @@ functions that correspond to the allocation in rever= se:: It is the user's responsibility to ensure all outstanding jobs are compl= ete before any of the above are called. =20 +Running Multithreaded Jobs +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D + +A multithreaded job has a main thread and zero or more helper threads, w= ith 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 fun= ction. + +A user has to do three things to run a multithreaded job. First, descri= be the +job by defining a padata_mt_job structure, which is explained in the Int= erface +section. This includes a pointer to the thread function, which padata w= ill +call each time it assigns a job chunk to a thread. Then, define the thr= ead +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, wh= ich is +typically allocated on the main thread's stack. Last, call +padata_do_multithreaded(), which will return once the job is finished. + Interface =3D=3D=3D=3D=3D=3D=3D=3D=3D =20 --=20 2.26.2