From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 47B9F42BE2; Tue, 30 May 2023 12:03:27 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id F37E042BDA; Tue, 30 May 2023 12:02:54 +0200 (CEST) Received: from mx0b-0016f401.pphosted.com (mx0b-0016f401.pphosted.com [67.231.156.173]) by mails.dpdk.org (Postfix) with ESMTP id 5B49440F18 for ; Tue, 30 May 2023 12:02:53 +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 34U8wV93010724; Tue, 30 May 2023 03:02:52 -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=iHi7eZrvs8H4zpZJ51JLguUMGA491VcWOXV7nOOn8HE=; b=jjFhwjek7m3Me74kxiRJ/2Oe/3Z8jOV1mA3YnlIrcB4rdIRTBylF54c5rHa1VtEYJ+Zt 0ijtDPGxBsjNTZFta+yzJrvFI4W8iaJ2cfiehFUTt+I7OFIEksqip1bonc3PcudSfNHc ZmjJ/Xi7W+51d/Hko78yyTkHLLKGYQpUvotFM3PJFK0RMit/NAPS5tGeldCSyfrKfyef 548smKN9i8dwEOCLupZ7JOm4edMc11SNK+XBDJTe53MHV7gwevAvQscZE9dkRSFrreoD kfAwPtKFC4LblOTGiDFM0He8B42YHF106xDKuCqJDMT9JRGtBokeZuQ9Brhxj8M+pnQs tA== Received: from dc5-exch01.marvell.com ([199.233.59.181]) by mx0b-0016f401.pphosted.com (PPS) with ESMTPS id 3quhcm7ty2-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-SHA384 bits=256 verify=NOT); Tue, 30 May 2023 03:02:52 -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; Tue, 30 May 2023 03:02:50 -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; Tue, 30 May 2023 03:02:50 -0700 Received: from BG-LT92004.corp.innovium.com (unknown [10.193.69.246]) by maili.marvell.com (Postfix) with ESMTP id 4B4CE3F7050; Tue, 30 May 2023 03:02:46 -0700 (PDT) From: Anoob Joseph To: Thomas Monjalon , Akhil Goyal , Jerin Jacob , Konstantin Ananyev CC: Hemant Agrawal , =?UTF-8?q?Mattias=20R=C3=B6nnblom?= , "Kiran Kumar K" , Volodymyr Fialko , , Olivier Matz , Stephen Hemminger Subject: [PATCH v6 11/21] doc: add PDCP library guide Date: Tue, 30 May 2023 15:31:48 +0530 Message-ID: <20230530100158.1428-12-anoobj@marvell.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20230530100158.1428-1-anoobj@marvell.com> References: <20230527085910.972-1-anoobj@marvell.com> <20230530100158.1428-1-anoobj@marvell.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain X-Proofpoint-GUID: bwv2R_Svch-Eu5iMz_Y10OTi1_mqVZYJ X-Proofpoint-ORIG-GUID: bwv2R_Svch-Eu5iMz_Y10OTi1_mqVZYJ X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.254,Aquarius:18.0.957,Hydra:6.0.573,FMLib:17.11.176.26 definitions=2023-05-30_06,2023-05-29_02,2023-05-22_02 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Add guide for PDCP library. Signed-off-by: Anoob Joseph Signed-off-by: Kiran Kumar K Signed-off-by: Volodymyr Fialko --- MAINTAINERS | 1 + .../img/pdcp_functional_overview.svg | 1 + doc/guides/prog_guide/index.rst | 1 + doc/guides/prog_guide/pdcp_lib.rst | 254 ++++++++++++++++++ doc/guides/rel_notes/release_23_07.rst | 12 + 5 files changed, 269 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/MAINTAINERS b/MAINTAINERS index ca684dde83..11ecb153bc 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1557,6 +1557,7 @@ M: Volodymyr Fialko T: git://dpdk.org/next/dpdk-next-crypto F: lib/pdcp/ F: app/test/test_pdcp* +F: doc/guides/prog_guide/pdcp_lib.rst =20 =20 Packet Framework 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 @@ +Radio Interf= ace (Uu/PC5)UE/NG-RAN/UE ANG-RAN/UE/UE BTransmitting PDCP entityReceiving PDCP entityTransmission buffer:Se= quencenumberin= gHeader or uplin= k dataCompressionHeader or uplink data= Decompression= Routing / Duplication<= 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 headerCipheringIntegrity protection= Packet= s associated to a PDCP SDUPackets not associated to a PDCP SDURemove PDCP HeaderDecipheringReception buffer:Reo= rderingDuplicate di= scardingPackets associated to a PDCP SDUPackets not associated to = a PDCP SDU<= 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)"/>= \ 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..2eefabf45c --- /dev/null +++ b/doc/guides/prog_guide/pdcp_lib.rst @@ -0,0 +1,254 @@ +.. 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. + +When upper layers request a PDCP entity suspend (``rte_pdcp_entity_suspend= ()``), +it would result in flushing out of all cached packets and +internal state variables are updated as described in 5.1.4. + +When upper layers request a PDCP entity release (``rte_pdcp_entity_release= ()``), +it would result in flushing out of all cached packets and releasing of all +memory associated with the entity. It would internally free any crypto/sec= urity +sessions created. All procedures mentioned in 5.1.3 would be performed. + +PDCP PDU (Protocol Data Unit) API +--------------------------------- + +PDCP PDUs can be categorized as, + +1. Control PDU +2. Data PDU + +Control PDUs are used for signalling between entities on either end and +can 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 would 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 ``rte_crypto_op`` allocat= ion +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 PDUs are received, no cryptodev enqueue-dequeue = is +expected for the same and lib PDCP is expected to handle it differently. + +Supported features +------------------ + +- 12 bit & 18 bit sequence numbers +- Uplink & downlink traffic +- HFN increment +- IV generation as required per algorithm + +Supported ciphering algorithms +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- RTE_CRYPTO_CIPHER_NULL +- RTE_CRYPTO_CIPHER_AES_CTR +- RTE_CRYPTO_CIPHER_SNOW3G_UEA2 +- RTE_CRYPTO_CIPHER_ZUC_EEA3 + +Supported integrity protection algorithms +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- RTE_CRYPTO_AUTH_NULL +- RTE_CRYPTO_AUTH_AES_CMAC +- RTE_CRYPTO_AUTH_SNOW3G_UIA2 +- RTE_CRYPTO_AUTH_ZUC_EIA3 + +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 be 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 + */ + } + } diff --git a/doc/guides/rel_notes/release_23_07.rst b/doc/guides/rel_notes/= release_23_07.rst index 75079ca7d6..bb48514637 100644 --- a/doc/guides/rel_notes/release_23_07.rst +++ b/doc/guides/rel_notes/release_23_07.rst @@ -65,6 +65,18 @@ New Features * Added support for SM3 hash operations. * Added support for AES-CCM in cn9k and cn10k drivers. =20 +* **Added PDCP Library.** + + Added an experimental library ``lib_pdcp`` to provide PDCP UL and DL + processing of packets. + + The library supports all PDCP algorithms and leverages lookaside crypto + offloads to cryptodevs for crypto processing. PDCP features such as IV + generation, sequence number handling etc are supported. It is planned to= add + more features such as packet caching in future releases. + + See :doc:`../prog_guide/pdcp_lib` for more information. + =20 Removed Items ------------- --=20 2.25.1