From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
by inbox.dpdk.org (Postfix) with ESMTP id 7215E42943;
Fri, 14 Apr 2023 19:47:11 +0200 (CEST)
Received: from mails.dpdk.org (localhost [127.0.0.1])
by mails.dpdk.org (Postfix) with ESMTP id 6298141144;
Fri, 14 Apr 2023 19:47:11 +0200 (CEST)
Received: from mx0b-0016f401.pphosted.com (mx0b-0016f401.pphosted.com
[67.231.156.173])
by mails.dpdk.org (Postfix) with ESMTP id D2FBF410F6
for <dev@dpdk.org>; Fri, 14 Apr 2023 19:47:09 +0200 (CEST)
Received: from pps.filterd (m0045851.ppops.net [127.0.0.1])
by mx0b-0016f401.pphosted.com (8.17.1.19/8.17.1.19) with ESMTP id
33EGOBul013729; Fri, 14 Apr 2023 10:47:09 -0700
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=marvell.com;
h=from : to : cc :
subject : date : message-id : in-reply-to : references : mime-version :
content-transfer-encoding : content-type; s=pfpt0220;
bh=OU4yvsktD8wK43wNBu/mdXbGvCR2c5IOGpX+6vMHGSU=;
b=QZk6/VEc++2eD0TpR9lLBaf2sbDhyCn9qzhS/ZUc8AX8meJZYGu5tksuI+UkMkZOWFVH
sHoxPfPXrd4p+hXNC6Xw6i+HB6CWxHrlOAmxJbgLHHMz23uLhgfZ9OW2law4jWojkqOu
YrbfPKqbov5moThbZnHKqXM4KSk/XHqkug5/2K/gHtswlsiQ24Fb6wsuJDIA/YKMH5og
LVqgrJ/BEgARiB0MEejWs+bPUrvnbJg1c0bXj14s3aDOdkNxsKxa/GYKvyLez1ohHKDq
ruexEhOj23ugUemiuVfSBE/oCtpdS7atqnxt/TUstICVU/TX76FYbRu3VHsQrWkCWs5h kw==
Received: from dc5-exch01.marvell.com ([199.233.59.181])
by mx0b-0016f401.pphosted.com (PPS) with ESMTPS id 3py646s6rf-1
(version=TLSv1.2 cipher=ECDHE-RSA-AES256-SHA384 bits=256 verify=NOT);
Fri, 14 Apr 2023 10:47:08 -0700
Received: from DC5-EXCH01.marvell.com (10.69.176.38) by DC5-EXCH01.marvell.com
(10.69.176.38) with Microsoft SMTP Server (TLS) id 15.0.1497.48;
Fri, 14 Apr 2023 10:47:06 -0700
Received: from maili.marvell.com (10.69.176.80) by DC5-EXCH01.marvell.com
(10.69.176.38) with Microsoft SMTP Server id 15.0.1497.48 via Frontend
Transport; Fri, 14 Apr 2023 10:47:06 -0700
Received: from BG-LT92004.corp.innovium.com (unknown [10.28.161.183])
by maili.marvell.com (Postfix) with ESMTP id 199613F7081;
Fri, 14 Apr 2023 10:46:43 -0700 (PDT)
From: Anoob Joseph <anoobj@marvell.com>
To: Thomas Monjalon <thomas@monjalon.net>, Akhil Goyal <gakhil@marvell.com>,
Jerin Jacob <jerinj@marvell.com>, Konstantin Ananyev
<konstantin.v.ananyev@yandex.ru>, Bernard Iremonger
<bernard.iremonger@intel.com>
CC: Hemant Agrawal <hemant.agrawal@nxp.com>,
=?UTF-8?q?Mattias=20R=C3=B6nnblom?= <mattias.ronnblom@ericsson.com>, "Kiran
Kumar K" <kirankumark@marvell.com>,
Volodymyr Fialko <vfialko@marvell.com>, <dev@dpdk.org>,
Olivier Matz <olivier.matz@6wind.com>
Subject: [PATCH v2 11/22] doc: add PDCP library guide
Date: Fri, 14 Apr 2023 23:15:01 +0530
Message-ID: <20230414174512.642-12-anoobj@marvell.com>
X-Mailer: git-send-email 2.25.1
In-Reply-To: <20230414174512.642-1-anoobj@marvell.com>
References: <20221222092522.1628-1-anoobj@marvell.com>
<20230414174512.642-1-anoobj@marvell.com>
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain
X-Proofpoint-GUID: sB-DdTFfHs1avS79skPm5SIDtbCGfjUB
X-Proofpoint-ORIG-GUID: sB-DdTFfHs1avS79skPm5SIDtbCGfjUB
X-Proofpoint-Virus-Version: vendor=baseguard
engine=ICAP:2.0.254,Aquarius:18.0.942,Hydra:6.0.573,FMLib:17.11.170.22
definitions=2023-04-14_10,2023-04-14_01,2023-02-09_01
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
Add guide for PDCP library.
Signed-off-by: Anoob Joseph <anoobj@marvell.com>
Signed-off-by: Kiran Kumar K <kirankumark@marvell.com>
Signed-off-by: Volodymyr Fialko <vfialko@marvell.com>
---
.../img/pdcp_functional_overview.svg | 1 +
doc/guides/prog_guide/index.rst | 1 +
doc/guides/prog_guide/pdcp_lib.rst | 246 ++++++++++++++++++
3 files changed, 248 insertions(+)
create mode 100644 doc/guides/prog_guide/img/pdcp_functional_overview.svg
create mode 100644 doc/guides/prog_guide/pdcp_lib.rst
diff --git a/doc/guides/prog_guide/img/pdcp_functional_overview.svg b/doc/g=
uides/prog_guide/img/pdcp_functional_overview.svg
new file mode 100644
index 0000000000..287daafc21
--- /dev/null
+++ b/doc/guides/prog_guide/img/pdcp_functional_overview.svg
@@ -0,0 +1 @@
+<svg width=3D"1280" height=3D"720" xmlns=3D"http://www.w3.org/2000/svg" xm=
lns:xlink=3D"http://www.w3.org/1999/xlink" overflow=3D"hidden"><defs><clipP=
ath id=3D"clip0"><rect x=3D"0" y=3D"0" width=3D"1280" height=3D"720"/></cli=
pPath></defs><g clip-path=3D"url(#clip0)"><rect x=3D"0" y=3D"0" width=3D"12=
80" height=3D"720" fill=3D"#FFFFFF"/><rect x=3D"202" y=3D"100" width=3D"369=
" height=3D"457" fill=3D"#A5A5A5" fill-opacity=3D"0.501961"/><rect x=3D"640=
" y=3D"100" width=3D"369" height=3D"457" fill=3D"#A5A5A5" fill-opacity=3D"0=
.501961"/><path d=3D"M605.5 73.5001 605.5 590.633" stroke=3D"#000000" strok=
e-width=3D"1.33333" stroke-miterlimit=3D"8" fill=3D"none" fill-rule=3D"even=
odd"/><path d=3D"M380.5 634 803.25 634 803.25 585.907 790.5 585.907 816 557=
.5 841.5 585.907 828.75 585.907 828.75 659.5 380.5 659.5Z" stroke=3D"#78787=
8" stroke-width=3D"1.33333" stroke-miterlimit=3D"8" fill=3D"#A5A5A5" fill-r=
ule=3D"evenodd"/><rect x=3D"362.5" y=3D"557.5" width=3D"28" height=3D"102" =
stroke=3D"#787878" stroke-width=3D"1.33333" stroke-miterlimit=3D"8" fill=3D=
"#A5A5A5"/><rect x=3D"412.5" y=3D"671.5" width=3D"370" height=3D"32" stroke=
=3D"#000000" stroke-linejoin=3D"round" stroke-miterlimit=3D"10" fill=3D"non=
e"/><text font-family=3D"Arial,Arial_MSFontService,sans-serif" font-weight=
=3D"400" font-size=3D"19" transform=3D"translate(492.364 694)">Radio Interf=
ace (<tspan font-size=3D"19" x=3D"137.5" y=3D"0">Uu</tspan><tspan font-size=
=3D"19" x=3D"161.333" y=3D"0">/PC5)</tspan><tspan font-size=3D"19" x=3D"-28=
2.121" y=3D"-653">UE/NG</tspan><tspan font-size=3D"19" x=3D"-222.955" y=3D"=
-653">-</tspan><tspan font-size=3D"19" x=3D"-216.788" y=3D"-653">RAN/UE A</=
tspan><tspan font-size=3D"19" x=3D"375.54" y=3D"-653">NG</tspan>-<tspan fon=
t-size=3D"19" x=3D"409.706" y=3D"-653">RAN/UE/UE B</tspan><tspan font-size=
=3D"14" x=3D"0.896851" y=3D"-647">Transmitting </tspan><tspan font-size=3D"=
14" x=3D"1.31018" y=3D"-631">PDCP entity</tspan><tspan font-size=3D"14" x=
=3D"167.401" y=3D"-647">Receiving </tspan><tspan font-size=3D"14" x=3D"160.=
148" y=3D"-631">PDCP entity</tspan></text><path d=3D"M314.5 71.5001 431.364=
71.6549" stroke=3D"#000000" stroke-width=3D"0.666667" stroke-miterlimit=3D=
"8" fill=3D"none" fill-rule=3D"evenodd"/><path d=3D"M331.5 71.5001C331.5 65=
.9772 349.633 61.5001 372 61.5001 394.368 61.5001 412.5 65.9772 412.5 71.50=
01 412.5 77.0229 394.368 81.5001 372 81.5001 349.633 81.5001 331.5 77.0229 =
331.5 71.5001Z" stroke=3D"#000000" stroke-width=3D"1.33333" stroke-miterlim=
it=3D"8" fill=3D"#FFFFFF" fill-rule=3D"evenodd"/><path d=3D"M353.5 90.5001 =
363.5 90.5001 363.5 48.5001 383.5 48.5001 383.5 90.5001 393.5 90.5001 373.5=
110.5Z" stroke=3D"#000000" stroke-width=3D"1.33333" stroke-miterlimit=3D"8=
" fill=3D"#FFFFFF" fill-rule=3D"evenodd"/><path d=3D"M877.364 82.6549 760.5=
82.5001" stroke=3D"#000000" stroke-width=3D"0.666667" stroke-miterlimit=3D=
"8" fill=3D"none" fill-rule=3D"evenodd"/><path d=3D"M860.5 83.5001C860.5 89=
.0229 842.368 93.5001 820 93.5001 797.633 93.5001 779.5 89.0229 779.5 83.50=
01 779.5 77.9772 797.633 73.5001 820 73.5001 842.368 73.5001 860.5 77.9772 =
860.5 83.5001Z" stroke=3D"#000000" stroke-width=3D"1.33333" stroke-miterlim=
it=3D"8" fill=3D"#FFFFFF" fill-rule=3D"evenodd"/><path d=3D"M838.5 64.5 828=
.5 64.5 828.5 106.5 808.5 106.5 808.5 64.5 798.5 64.5 818.5 44.5001Z" strok=
e=3D"#000000" stroke-width=3D"1.33333" stroke-miterlimit=3D"8" fill=3D"#FFF=
FFF" fill-rule=3D"evenodd"/><rect x=3D"244.5" y=3D"128.5" width=3D"285" hei=
ght=3D"55" stroke=3D"#000000" stroke-width=3D"1.33333" stroke-miterlimit=3D=
"8" fill=3D"#FFFFFF"/><text font-family=3D"Arial,Arial_MSFontService,sans-s=
erif" font-weight=3D"400" font-size=3D"19" transform=3D"translate(302.494 1=
50)">Transmission buffer:<tspan font-size=3D"19" x=3D"-4.67999" y=3D"23">Se=
quence</tspan><tspan font-size=3D"19" x=3D"84.32" y=3D"23">numberin</tspan>=
g</text><rect x=3D"244.5" y=3D"199.5" width=3D"285" height=3D"55" stroke=3D=
"#000000" stroke-width=3D"1.33333" stroke-miterlimit=3D"8" fill=3D"#FFFFFF"=
/><text font-family=3D"Arial,Arial_MSFontService,sans-serif" font-weight=3D=
"400" font-size=3D"19" transform=3D"translate(297.314 222)">Header or uplin=
k data<tspan font-size=3D"19" x=3D"34.08" y=3D"23">Compressio</tspan>n</tex=
t><rect x=3D"682.5" y=3D"141.5" width=3D"285" height=3D"55" stroke=3D"#0000=
00" stroke-width=3D"1.33333" stroke-miterlimit=3D"8" fill=3D"#FFFFFF"/><tex=
t font-family=3D"Arial,Arial_MSFontService,sans-serif" font-weight=3D"400" =
font-size=3D"19" transform=3D"translate(735.782 164)">Header or uplink data=
<tspan font-size=3D"19" x=3D"24.2466" y=3D"23">Decompressio</tspan>n</text>=
<rect x=3D"244.5" y=3D"482.5" width=3D"285" height=3D"33" stroke=3D"#000000=
" stroke-width=3D"1.33333" stroke-miterlimit=3D"8" fill=3D"#FFFFFF"/><text =
font-family=3D"Arial,Arial_MSFontService,sans-serif" font-weight=3D"400" fo=
nt-size=3D"19" transform=3D"translate(300.314 505)">Routing / Duplication</=
text><rect x=3D"244.5" y=3D"437.5" width=3D"285" height=3D"32" stroke=3D"#0=
00000" stroke-width=3D"1.33333" stroke-miterlimit=3D"8" fill=3D"#FFFFFF"/><=
text font-family=3D"Arial,Arial_MSFontService,sans-serif" font-weight=3D"40=
0" font-size=3D"19" transform=3D"translate(309.734 460)">Add PDCP header</t=
ext><rect x=3D"244.5" y=3D"383.5" width=3D"189" height=3D"33" stroke=3D"#00=
0000" stroke-width=3D"1.33333" stroke-miterlimit=3D"8" fill=3D"#FFFFFF"/><t=
ext font-family=3D"Arial,Arial_MSFontService,sans-serif" font-weight=3D"400=
" font-size=3D"19" transform=3D"translate(298.62 406)">Ciphering</text><rec=
t x=3D"244.5" y=3D"333.5" width=3D"189" height=3D"32" stroke=3D"#000000" st=
roke-width=3D"1.33333" stroke-miterlimit=3D"8" fill=3D"#FFFFFF"/><text font=
-family=3D"Arial,Arial_MSFontService,sans-serif" font-weight=3D"400" font-s=
ize=3D"19" transform=3D"translate(261.953 356)">Integrity protection</text>=
<path d=3D"M472.167 267.5 472.167 409.802 470.833 409.802 470.833 267.5ZM47=
5.5 408.468 471.5 416.468 467.5 408.468Z"/><path d=3D"M332.167 267.5 332.16=
7 319.552 330.833 319.552 330.833 267.5ZM335.5 318.218 331.5 326.218 327.5 =
318.219Z"/><text font-family=3D"Arial,Arial_MSFontService,sans-serif" font-=
weight=3D"400" font-size=3D"19" transform=3D"translate(253.644 291)">Packet=
s associated <tspan font-size=3D"19" x=3D"14.0067" y=3D"23">to a PDCP SDU</=
tspan></text><text font-family=3D"Arial,Arial_MSFontService,sans-serif" fon=
t-weight=3D"400" font-size=3D"19" transform=3D"matrix(6.12323e-17 1 -1 6.12=
323e-17 499.312 299)">Packets not <tspan font-size=3D"19" x=3D"-14" y=3D"23=
">associated to a </tspan><tspan font-size=3D"19" x=3D"-2.75546e-15" y=3D"4=
5">PDCP SDU</tspan></text><rect x=3D"682.5" y=3D"482.5" width=3D"285" heigh=
t=3D"33" stroke=3D"#000000" stroke-width=3D"1.33333" stroke-miterlimit=3D"8=
" fill=3D"#FFFFFF"/><text font-family=3D"Arial,Arial_MSFontService,sans-ser=
if" font-weight=3D"400" font-size=3D"19" transform=3D"translate(728.535 505=
)">Remove PDCP Header</text><rect x=3D"682.5" y=3D"437.5" width=3D"203" hei=
ght=3D"32" stroke=3D"#000000" stroke-width=3D"1.33333" stroke-miterlimit=3D=
"8" fill=3D"#FFFFFF"/><text font-family=3D"Arial,Arial_MSFontService,sans-s=
erif" font-weight=3D"400" font-size=3D"19" transform=3D"translate(733.729 4=
60)">Deciphering</text><rect x=3D"682.5" y=3D"389.5" width=3D"203" height=
=3D"33" stroke=3D"#000000" stroke-width=3D"1.33333" stroke-miterlimit=3D"8"=
fill=3D"#FFFFFF"/><text font-family=3D"Arial,Arial_MSFontService,sans-seri=
f" font-weight=3D"400" font-size=3D"19" transform=3D"translate(702.159 412)=
">Integrity Verification</text><rect x=3D"682.5" y=3D"303.5" width=3D"203" =
height=3D"77" stroke=3D"#000000" stroke-width=3D"1.33333" stroke-miterlimit=
=3D"8" fill=3D"#FFFFFF"/><text font-family=3D"Arial,Arial_MSFontService,san=
s-serif" font-weight=3D"400" font-size=3D"19" transform=3D"translate(712.72=
9 325)">Reception buffer:<tspan font-size=3D"19" x=3D"24.6667" y=3D"23">Reo=
rdering</tspan><tspan font-size=3D"19" x=3D"-13.1667" y=3D"45">Duplicate di=
scardin</tspan><tspan font-size=3D"19" x=3D"144.167" y=3D"45">g</tspan><tsp=
an font-size=3D"19" x=3D"-10.0989" y=3D"-84">Packets associated </tspan><ts=
pan font-size=3D"19" x=3D"3.90784" y=3D"-61">to a PDCP SDU</tspan></text><t=
ext font-family=3D"Arial,Arial_MSFontService,sans-serif" font-weight=3D"400=
" font-size=3D"19" transform=3D"matrix(6.12323e-17 1 -1 6.12323e-17 960.34 =
294)">Packets not <tspan font-size=3D"19" x=3D"-14" y=3D"23">associated to =
a </tspan><tspan font-size=3D"19" x=3D"1" y=3D"45">PDCP SDU</tspan></text><=
path d=3D"M0.666667-8.2074e-07 0.666763 78.6116-0.66657 78.6116-0.666667 8.=
2074e-07ZM4.00009 77.2782 0.000104987 85.2782-3.9999 77.2782Z" transform=3D=
"matrix(1 0 0 -1 779.5 296.778)"/><path d=3D"M0.666667-2.88742e-07 0.666769=
235.734-0.666565 235.734-0.666667 2.88742e-07ZM4.0001 234.401 0.000104987 =
242.401-3.9999 234.401Z" transform=3D"matrix(1 0 0 -1 931.5 453.901)"/></g>=
</svg>
\ No newline at end of file
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.=
rst
index 87333ee84a..6099ff63cd 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -77,4 +77,5 @@ Programmer's Guide
lto
profile_app
asan
+ pdcp_lib
glossary
diff --git a/doc/guides/prog_guide/pdcp_lib.rst b/doc/guides/prog_guide/pdc=
p_lib.rst
new file mode 100644
index 0000000000..abd874f2cc
--- /dev/null
+++ b/doc/guides/prog_guide/pdcp_lib.rst
@@ -0,0 +1,246 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(C) 2023 Marvell.
+
+PDCP Protocol Processing Library
+=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
+
+DPDK provides a library for PDCP protocol processing. The library utilizes
+other DPDK libraries such as cryptodev, reorder, etc., to provide the
+application with a transparent and high performant PDCP protocol processing
+library.
+
+The library abstracts complete PDCP protocol processing conforming to
+``ETSI TS 138 323 V17.1.0 (2022-08)``.
+https://www.etsi.org/deliver/etsi_ts/138300_138399/138323/17.01.00_60/ts_1=
38323v170100p.pdf
+
+PDCP would involve the following operations,
+
+1. Transfer of user plane data
+2. Transfer of control plane data
+3. Header compression
+4. Uplink data compression
+5. Ciphering and integrity protection
+
+.. _figure_pdcp_functional_overview:
+
+.. figure:: img/pdcp_functional_overview.*
+
+ PDCP functional overview new
+
+PDCP library would abstract the protocol offload features of the cryptodev=
and
+would provide a uniform interface and consistent API usage to work with
+cryptodev irrespective of the protocol offload features supported.
+
+PDCP entity API
+---------------
+
+PDCP library provides following control path APIs that is used to
+configure various PDCP entities,
+
+1. ``rte_pdcp_entity_establish()``
+2. ``rte_pdcp_entity_suspend()``
+3. ``rte_pdcp_entity_release()``
+
+A PDCP entity would translate to one ``rte_cryptodev_sym_session`` or
+``rte_security_session`` based on the config. The sessions would be create=
d/
+destroyed while corresponding PDCP entity operations are performed.
+
+PDCP PDU (Protocol Data Unit)
+-----------------------------
+
+PDCP PDUs can be categorized as,
+
+1. Control PDU
+2. Data PDU
+
+Control PDUs are used for signalling between entities on either end and ca=
n be
+one of the following,
+
+1. PDCP status report
+2. ROHC feedback
+3. EHC feedback
+
+Control PDUs are not ciphered or authenticated, and so such packets are not
+submitted to cryptodev for processing.
+
+Data PDUs are regular packets submitted by upper layers for transmission to
+other end. Such packets would need to be ciphered and authenticated based =
on
+the entity configuration.
+
+PDCP packet processing API for data PDU
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+PDCP processing is split into 2 parts. One before cryptodev processing
+(``rte_pdcp_pkt_pre_process()``) and one after cryptodev processing
+(``rte_pdcp_pkt_post_process()``). Since cryptodev dequeue can return cryp=
to
+operations belonging to multiple entities, ``rte_pdcp_pkt_crypto_group()``
+is added to help grouping crypto operations belonging to same PDCP entity.
+
+Lib PDCP would allow application to use same API sequence while leveraging
+protocol offload features enabled by ``rte_security`` library. Lib PDCP wo=
uld
+internally change the handles registered for ``pre_process`` and
+``post_process`` based on features enabled in the entity.
+
+Lib PDCP would create the required sessions on the device provided in enti=
ty to
+minimize the application requirements. Also, the crypto_op allocation and =
free
+would also be done internally by lib PDCP to allow the library to create
+crypto ops as required for the input packets. For example, when control PD=
Us are
+received, no cryptodev enqueue-dequeue is expected for the same and lib PD=
CP
+is expected to handle it differently.
+
+Sample API usage
+----------------
+
+The ``rte_pdcp_entity_conf`` structure is used to pass the configuration
+parameters for entity creation.
+
+.. literalinclude:: ../../../lib/pdcp/rte_pdcp.h
+ :language: c
+ :start-after: Structure rte_pdcp_entity_conf 8<
+ :end-before: >8 End of structure rte_pdcp_entity_conf.
+
+.. code-block:: c
+
+ struct rte_mbuf **out_mb, *pkts[MAX_BURST_SIZE];
+ struct rte_crypto_op *cop[MAX_BURST_SIZE];
+ struct rte_pdcp_group grp[MAX_BURST_SIZE];
+ struct rte_pdcp_entity *pdcp_entity;
+ int nb_max_out_mb, ret, nb_grp;
+ uint16_t nb_ops;
+
+ /* Create PDCP entity */
+ pdcp_entity =3D rte_pdcp_entity_establish(&conf);
+
+ /**
+ * Allocate buffer for holding mbufs returned during PDCP suspend,
+ * release & post-process APIs.
+ */
+
+ /* Max packets that can be cached in entity + burst size */
+ nb_max_out_mb =3D pdcp_entity->max_pkt_cache + MAX_BURST_SIZE;
+ out_mb =3D rte_malloc(NULL, nb_max_out_mb * sizeof(uintptr_t), 0);
+ if (out_mb =3D=3D NULL) {
+ /* Handle error */
+ }
+
+ while (1) {
+ /* Receive packet and form mbuf */
+
+ /**
+ * Prepare packets for crypto operation. Following operations
+ * would be done,
+ *
+ * Transmitting entity/UL (only data PDUs):
+ * - Perform compression
+ * - Assign sequence number
+ * - Add PDCP header
+ * - Create & prepare crypto_op
+ * - Prepare IV for crypto operation (auth_gen, encrypt)
+ * - Save original PDCP SDU (during PDCP re-establishment,
+ * unconfirmed PDCP SDUs need to crypto processed again and
+ * transmitted/re-transmitted)
+ *
+ * Receiving entity/DL:
+ * - Any control PDUs received would be processed and
+ * appropriate actions taken. If data PDU, continue.
+ * - Determine sequence number (based on HFN & per packet SN)
+ * - Prepare crypto_op
+ * - Prepare IV for crypto operation (decrypt, auth_verify)
+ */
+ nb_success =3D rte_pdcp_pkt_pre_process(pdcp_entity, pkts, cop,
+ nb_rx, &nb_err);
+ if (nb_err !=3D 0) {
+ /* Handle error packets */
+ }
+
+ if ((rte_cryptodev_enqueue_burst(dev_id, qp_id, cop, nb_success)
+ !=3D nb_success) {
+ /* Retry for enqueue failure packets */
+ }
+
+ ...
+
+ nb_ops =3D rte_cryptodev_dequeue_burst(dev_id, qp_id, cop,
+ MAX_BURST_SIZE);
+ if (nb_ops =3D=3D 0)
+ continue;
+
+ /**
+ * Received a burst of completed crypto ops from cryptodev. It
+ * may belong to various entities. Group similar ones together
+ * for entity specific post-processing.
+ */
+
+ /**
+ * Groups similar entities together. Frees crypto op and based
+ * on crypto_op status, set mbuf->ol_flags which would be
+ * checked in rte_pdcp_pkt_post_process().
+ */
+ nb_grp =3D rte_pdcp_pkt_crypto_group(cop, pkts, grp, ret);
+
+ for (i =3D 0; i !=3D nb_grp; i++) {
+
+ /**
+ * Post process packets after crypto completion.
+ * Following operations would be done,
+ *
+ * Transmitting entity/UL:
+ * - Check crypto result
+ *
+ * Receiving entity/DL:
+ * - Check crypto operation status
+ * - Check for duplication (if yes, drop duplicate)
+ * - Perform decompression
+ * - Trim PDCP header
+ * - Hold packet (SDU) for in-order delivery (return
+ * completed packets as and when sequence is
+ * completed)
+ * - If not in sequence, cache the packet and start
+ * t-Reordering timer. When timer expires, the
+ * packets need to delivered to upper layers (not
+ * treated as error packets).
+ */
+ nb_success =3D rte_pdcp_pkt_post_process(grp[i].id.ptr,
+ grp[i].m, out_mb,
+ grp[i].cnt,
+ &nb_err);
+ if (nb_err !=3D 0) {
+ /* Handle error packets */
+ }
+
+ /* Perform additional operations */
+
+ /**
+ * Transmitting entity/UL
+ * - If duplication is enabled, duplicate PDCP PDUs
+ * - When lower layers confirm reception of a PDCP PDU,
+ * it should be communicated to PDCP layer so that
+ * PDCP can drop the corresponding SDU
+ */
+ }
+ }
+
+
+Supported features
+------------------
+
+- 12 bit & 18 bit sequence numbers
+- Uplink & downlink traffic
+- HFN increment
+- IV generation as required per algorithm
+
+Supported ciphering algorithms
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- NULL
+- AES-CTR
+- SNOW3G-CIPHER
+- ZUC-CIPHER
+
+Supported integrity protection algorithms
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- NULL
+- AES-CMAC
+- SNOW3G-AUTH
+- ZUC-AUTH
--=20
2.25.1