[v2,11/22] doc: add PDCP library guide
Checks
Commit Message
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
Comments
> diff --git a/doc/guides/prog_guide/pdcp_lib.rst
> b/doc/guides/prog_guide/pdcp_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
> +================================
> +
> +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_
> 138323v170100p.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 created/
> +destroyed while corresponding PDCP entity operations are performed.
Please explain the difference between suspend and release here.
> +
> +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 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.
> +
Please move the PDCP PDU section above PDCP entity API section.
So that all APIs are together.
> +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 crypto
> +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 entity 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 PDUs
> are
> +received, no cryptodev enqueue-dequeue is expected for the same and lib
> PDCP
> +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 = 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 = pdcp_entity->max_pkt_cache + MAX_BURST_SIZE;
> + out_mb = rte_malloc(NULL, nb_max_out_mb * sizeof(uintptr_t), 0);
> + if (out_mb == 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 = rte_pdcp_pkt_pre_process(pdcp_entity, pkts, cop,
> + nb_rx, &nb_err);
> + if (nb_err != 0) {
> + /* Handle error packets */
> + }
> +
> + if ((rte_cryptodev_enqueue_burst(dev_id, qp_id, cop,
> nb_success)
> + != nb_success) {
> + /* Retry for enqueue failure packets */
> + }
> +
> + ...
> +
> + nb_ops = rte_cryptodev_dequeue_burst(dev_id, qp_id, cop,
> + MAX_BURST_SIZE);
> + if (nb_ops == 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 = rte_pdcp_pkt_crypto_group(cop, pkts, grp, ret);
> +
> + for (i = 0; i != 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 = rte_pdcp_pkt_post_process(grp[i].id.ptr,
> + grp[i].m, out_mb,
> + grp[i].cnt,
> + &nb_err);
> + if (nb_err != 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
> --
Move Supported features and algos after PDCP PDU explanation.
Sample sequence should be in the end.
Hi Akhil,
Please see inline.
Thanks,
Anoob
> -----Original Message-----
> From: Akhil Goyal <gakhil@marvell.com>
> Sent: Thursday, May 18, 2023 1:56 PM
> To: Anoob Joseph <anoobj@marvell.com>; Thomas Monjalon
> <thomas@monjalon.net>; Jerin Jacob Kollanukkaran <jerinj@marvell.com>;
> Konstantin Ananyev <konstantin.v.ananyev@yandex.ru>; Bernard
> Iremonger <bernard.iremonger@intel.com>
> Cc: Hemant Agrawal <hemant.agrawal@nxp.com>; Mattias Rönnblom
> <mattias.ronnblom@ericsson.com>; Kiran Kumar Kokkilagadda
> <kirankumark@marvell.com>; Volodymyr Fialko <vfialko@marvell.com>;
> dev@dpdk.org; Olivier Matz <olivier.matz@6wind.com>
> Subject: RE: [PATCH v2 11/22] doc: add PDCP library guide
>
> > diff --git a/doc/guides/prog_guide/pdcp_lib.rst
> > b/doc/guides/prog_guide/pdcp_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
> > +================================
> > +
> > +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_
> > 138323v170100p.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
> > +created/ destroyed while corresponding PDCP entity operations are
> performed.
>
> Please explain the difference between suspend and release here.
[Anoob] Sure. Will do in next version.
>
> > +
> > +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 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.
> > +
> Please move the PDCP PDU section above PDCP entity API section.
> So that all APIs are together.
[Anoob] PDCP PDU section is also talking about APIs. I'll rename above title from 'PDCP PDU(Protocol Data Unit)' to 'PDCP PDU(Protocol Data Unit) API' to make it more uniform.
>
>
> > +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
> > +crypto 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
> > +entity 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 PDUs
> > are
> > +received, no cryptodev enqueue-dequeue is expected for the same and
> > +lib
> > PDCP
> > +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 = 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 = pdcp_entity->max_pkt_cache +
> MAX_BURST_SIZE;
> > + out_mb = rte_malloc(NULL, nb_max_out_mb * sizeof(uintptr_t), 0);
> > + if (out_mb == 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 = rte_pdcp_pkt_pre_process(pdcp_entity, pkts,
> cop,
> > + nb_rx, &nb_err);
> > + if (nb_err != 0) {
> > + /* Handle error packets */
> > + }
> > +
> > + if ((rte_cryptodev_enqueue_burst(dev_id, qp_id, cop,
> > nb_success)
> > + != nb_success) {
> > + /* Retry for enqueue failure packets */
> > + }
> > +
> > + ...
> > +
> > + nb_ops = rte_cryptodev_dequeue_burst(dev_id, qp_id, cop,
> > + MAX_BURST_SIZE);
> > + if (nb_ops == 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 = rte_pdcp_pkt_crypto_group(cop, pkts, grp, ret);
> > +
> > + for (i = 0; i != 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 =
> rte_pdcp_pkt_post_process(grp[i].id.ptr,
> > + grp[i].m, out_mb,
> > + grp[i].cnt,
> > + &nb_err);
> > + if (nb_err != 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
> > --
> Move Supported features and algos after PDCP PDU explanation.
> Sample sequence should be in the end.
[Anoob] Agreed. Will make this change in next version.
new file mode 100644
@@ -0,0 +1 @@
+<svg width="1280" height="720" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" overflow="hidden"><defs><clipPath id="clip0"><rect x="0" y="0" width="1280" height="720"/></clipPath></defs><g clip-path="url(#clip0)"><rect x="0" y="0" width="1280" height="720" fill="#FFFFFF"/><rect x="202" y="100" width="369" height="457" fill="#A5A5A5" fill-opacity="0.501961"/><rect x="640" y="100" width="369" height="457" fill="#A5A5A5" fill-opacity="0.501961"/><path d="M605.5 73.5001 605.5 590.633" stroke="#000000" stroke-width="1.33333" stroke-miterlimit="8" fill="none" fill-rule="evenodd"/><path d="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="#787878" stroke-width="1.33333" stroke-miterlimit="8" fill="#A5A5A5" fill-rule="evenodd"/><rect x="362.5" y="557.5" width="28" height="102" stroke="#787878" stroke-width="1.33333" stroke-miterlimit="8" fill="#A5A5A5"/><rect x="412.5" y="671.5" width="370" height="32" stroke="#000000" stroke-linejoin="round" stroke-miterlimit="10" fill="none"/><text font-family="Arial,Arial_MSFontService,sans-serif" font-weight="400" font-size="19" transform="translate(492.364 694)">Radio Interface (<tspan font-size="19" x="137.5" y="0">Uu</tspan><tspan font-size="19" x="161.333" y="0">/PC5)</tspan><tspan font-size="19" x="-282.121" y="-653">UE/NG</tspan><tspan font-size="19" x="-222.955" y="-653">-</tspan><tspan font-size="19" x="-216.788" y="-653">RAN/UE A</tspan><tspan font-size="19" x="375.54" y="-653">NG</tspan>-<tspan font-size="19" x="409.706" y="-653">RAN/UE/UE B</tspan><tspan font-size="14" x="0.896851" y="-647">Transmitting </tspan><tspan font-size="14" x="1.31018" y="-631">PDCP entity</tspan><tspan font-size="14" x="167.401" y="-647">Receiving </tspan><tspan font-size="14" x="160.148" y="-631">PDCP entity</tspan></text><path d="M314.5 71.5001 431.364 71.6549" stroke="#000000" stroke-width="0.666667" stroke-miterlimit="8" fill="none" fill-rule="evenodd"/><path d="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.5001 412.5 77.0229 394.368 81.5001 372 81.5001 349.633 81.5001 331.5 77.0229 331.5 71.5001Z" stroke="#000000" stroke-width="1.33333" stroke-miterlimit="8" fill="#FFFFFF" fill-rule="evenodd"/><path d="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="#000000" stroke-width="1.33333" stroke-miterlimit="8" fill="#FFFFFF" fill-rule="evenodd"/><path d="M877.364 82.6549 760.5 82.5001" stroke="#000000" stroke-width="0.666667" stroke-miterlimit="8" fill="none" fill-rule="evenodd"/><path d="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.5001 779.5 77.9772 797.633 73.5001 820 73.5001 842.368 73.5001 860.5 77.9772 860.5 83.5001Z" stroke="#000000" stroke-width="1.33333" stroke-miterlimit="8" fill="#FFFFFF" fill-rule="evenodd"/><path d="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" stroke="#000000" stroke-width="1.33333" stroke-miterlimit="8" fill="#FFFFFF" fill-rule="evenodd"/><rect x="244.5" y="128.5" width="285" height="55" stroke="#000000" stroke-width="1.33333" stroke-miterlimit="8" fill="#FFFFFF"/><text font-family="Arial,Arial_MSFontService,sans-serif" font-weight="400" font-size="19" transform="translate(302.494 150)">Transmission buffer:<tspan font-size="19" x="-4.67999" y="23">Sequence</tspan><tspan font-size="19" x="84.32" y="23">numberin</tspan>g</text><rect x="244.5" y="199.5" width="285" height="55" stroke="#000000" stroke-width="1.33333" stroke-miterlimit="8" fill="#FFFFFF"/><text font-family="Arial,Arial_MSFontService,sans-serif" font-weight="400" font-size="19" transform="translate(297.314 222)">Header or uplink data<tspan font-size="19" x="34.08" y="23">Compressio</tspan>n</text><rect x="682.5" y="141.5" width="285" height="55" stroke="#000000" stroke-width="1.33333" stroke-miterlimit="8" fill="#FFFFFF"/><text font-family="Arial,Arial_MSFontService,sans-serif" font-weight="400" font-size="19" transform="translate(735.782 164)">Header or uplink data<tspan font-size="19" x="24.2466" y="23">Decompressio</tspan>n</text><rect x="244.5" y="482.5" width="285" height="33" stroke="#000000" stroke-width="1.33333" stroke-miterlimit="8" fill="#FFFFFF"/><text font-family="Arial,Arial_MSFontService,sans-serif" font-weight="400" font-size="19" transform="translate(300.314 505)">Routing / Duplication</text><rect x="244.5" y="437.5" width="285" height="32" stroke="#000000" stroke-width="1.33333" stroke-miterlimit="8" fill="#FFFFFF"/><text font-family="Arial,Arial_MSFontService,sans-serif" font-weight="400" font-size="19" transform="translate(309.734 460)">Add PDCP header</text><rect x="244.5" y="383.5" width="189" height="33" stroke="#000000" stroke-width="1.33333" stroke-miterlimit="8" fill="#FFFFFF"/><text font-family="Arial,Arial_MSFontService,sans-serif" font-weight="400" font-size="19" transform="translate(298.62 406)">Ciphering</text><rect x="244.5" y="333.5" width="189" height="32" stroke="#000000" stroke-width="1.33333" stroke-miterlimit="8" fill="#FFFFFF"/><text font-family="Arial,Arial_MSFontService,sans-serif" font-weight="400" font-size="19" transform="translate(261.953 356)">Integrity protection</text><path d="M472.167 267.5 472.167 409.802 470.833 409.802 470.833 267.5ZM475.5 408.468 471.5 416.468 467.5 408.468Z"/><path d="M332.167 267.5 332.167 319.552 330.833 319.552 330.833 267.5ZM335.5 318.218 331.5 326.218 327.5 318.219Z"/><text font-family="Arial,Arial_MSFontService,sans-serif" font-weight="400" font-size="19" transform="translate(253.644 291)">Packets associated <tspan font-size="19" x="14.0067" y="23">to a PDCP SDU</tspan></text><text font-family="Arial,Arial_MSFontService,sans-serif" font-weight="400" font-size="19" transform="matrix(6.12323e-17 1 -1 6.12323e-17 499.312 299)">Packets not <tspan font-size="19" x="-14" y="23">associated to a </tspan><tspan font-size="19" x="-2.75546e-15" y="45">PDCP SDU</tspan></text><rect x="682.5" y="482.5" width="285" height="33" stroke="#000000" stroke-width="1.33333" stroke-miterlimit="8" fill="#FFFFFF"/><text font-family="Arial,Arial_MSFontService,sans-serif" font-weight="400" font-size="19" transform="translate(728.535 505)">Remove PDCP Header</text><rect x="682.5" y="437.5" width="203" height="32" stroke="#000000" stroke-width="1.33333" stroke-miterlimit="8" fill="#FFFFFF"/><text font-family="Arial,Arial_MSFontService,sans-serif" font-weight="400" font-size="19" transform="translate(733.729 460)">Deciphering</text><rect x="682.5" y="389.5" width="203" height="33" stroke="#000000" stroke-width="1.33333" stroke-miterlimit="8" fill="#FFFFFF"/><text font-family="Arial,Arial_MSFontService,sans-serif" font-weight="400" font-size="19" transform="translate(702.159 412)">Integrity Verification</text><rect x="682.5" y="303.5" width="203" height="77" stroke="#000000" stroke-width="1.33333" stroke-miterlimit="8" fill="#FFFFFF"/><text font-family="Arial,Arial_MSFontService,sans-serif" font-weight="400" font-size="19" transform="translate(712.729 325)">Reception buffer:<tspan font-size="19" x="24.6667" y="23">Reordering</tspan><tspan font-size="19" x="-13.1667" y="45">Duplicate discardin</tspan><tspan font-size="19" x="144.167" y="45">g</tspan><tspan font-size="19" x="-10.0989" y="-84">Packets associated </tspan><tspan font-size="19" x="3.90784" y="-61">to a PDCP SDU</tspan></text><text font-family="Arial,Arial_MSFontService,sans-serif" font-weight="400" font-size="19" transform="matrix(6.12323e-17 1 -1 6.12323e-17 960.34 294)">Packets not <tspan font-size="19" x="-14" y="23">associated to a </tspan><tspan font-size="19" x="1" y="45">PDCP SDU</tspan></text><path d="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="matrix(1 0 0 -1 779.5 296.778)"/><path d="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="matrix(1 0 0 -1 931.5 453.901)"/></g></svg>
\ No newline at end of file
@@ -77,4 +77,5 @@ Programmer's Guide
lto
profile_app
asan
+ pdcp_lib
glossary
new file mode 100644
@@ -0,0 +1,246 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(C) 2023 Marvell.
+
+PDCP Protocol Processing Library
+================================
+
+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_138323v170100p.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 created/
+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 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 crypto
+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 entity 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 PDUs are
+received, no cryptodev enqueue-dequeue is expected for the same and lib PDCP
+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 = 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 = pdcp_entity->max_pkt_cache + MAX_BURST_SIZE;
+ out_mb = rte_malloc(NULL, nb_max_out_mb * sizeof(uintptr_t), 0);
+ if (out_mb == 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 = rte_pdcp_pkt_pre_process(pdcp_entity, pkts, cop,
+ nb_rx, &nb_err);
+ if (nb_err != 0) {
+ /* Handle error packets */
+ }
+
+ if ((rte_cryptodev_enqueue_burst(dev_id, qp_id, cop, nb_success)
+ != nb_success) {
+ /* Retry for enqueue failure packets */
+ }
+
+ ...
+
+ nb_ops = rte_cryptodev_dequeue_burst(dev_id, qp_id, cop,
+ MAX_BURST_SIZE);
+ if (nb_ops == 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 = rte_pdcp_pkt_crypto_group(cop, pkts, grp, ret);
+
+ for (i = 0; i != 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 = rte_pdcp_pkt_post_process(grp[i].id.ptr,
+ grp[i].m, out_mb,
+ grp[i].cnt,
+ &nb_err);
+ if (nb_err != 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