Add guide for PDCP library. Signed-off-by: Anoob Joseph <ano...@marvell.com> Signed-off-by: Kiran Kumar K <kirankum...@marvell.com> Signed-off-by: Volodymyr Fialko <vfia...@marvell.com> --- 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 15dd88af3a..4345ae21b6 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1555,6 +1555,7 @@ M: Volodymyr Fialko <vfia...@marvell.com> T: git://dpdk.org/next/dpdk-next-crypto F: lib/pdcp/ F: app/test/test_pdcp* +F: doc/guides/prog_guide/pdcp_lib.rst Packet Framework diff --git a/doc/guides/prog_guide/img/pdcp_functional_overview.svg b/doc/guides/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="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 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/pdcp_lib.rst new file mode 100644 index 0000000000..8369c71600 --- /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 +================================ + +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. + +When upper layers request a PDCP entity suspend (``rte_pdcp_entity_suspend()``), +it would result in flushing out of all cached packets. 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/security +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 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. + +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 + +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 + */ + } + } 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. +* **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. + Removed Items ------------- -- 2.25.1
