[RFC,0/1] lib: add pdcp protocol

  Add Packet Data Convergence Protocol (PDCP) processing library.

The library is similar to lib_ipsec which provides IPsec processing
capabilities in DPDK.

PDCP would involve roughly the following options,
1. Transfer of user plane data
2. Transfer of control plane data
3. Header compression
4. Uplink data compression
5. Ciphering and integrity protection

PDCP library provides following control path APIs that is used to
configure various PDCP entities,
1. rte_pdcp_establish()
2. rte_pdcp_suspend()
3. rte_pdcp_release()

PDCP process is split into 2 parts. One before crypto processing
(rte_pdcp_pkt_pre_process()) and one after crypto 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 entity.

Similar to lib IPsec, 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.

Changes planned for next version
- Add APIs for rte_pdcp_entity_re_establish, rte_pdcp_entity_reconfigure
- Implementation for all APIs covering basic control plane & user plane packets
- Framework to handle control PDUs
- Unit test leveraging existing PDCP vectors available in test_cryptodev
- Eventdev based timer integration for t-Reordering & discardTimer
- Integration with reorder library to handle in-order delivery

Sample application sequence:

	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;

	/* 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 + 1;
	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,
		 *
		 * Transmiting 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 */
		}

		...

		ret = rte_cryptodev_dequeue_burst(dev_id, qp_id, cop,
						  MAX_BURST_SIZE);
		if (ret == 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,
			 *
			 *  Transmiting 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 */

			/**
			 * Tranmitting 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
			 */
		}
	}

Anoob Joseph (1):
  lib: add pdcp protocol

 doc/api/doxy-api-index.md |   3 +-
 doc/api/doxy-api.conf.in  |   1 +
 lib/meson.build           |   1 +
 lib/pdcp/meson.build      |   7 ++
 lib/pdcp/rte_pdcp.h       | 244 ++++++++++++++++++++++++++++++++++++++
 lib/pdcp/rte_pdcp_group.h | 134 +++++++++++++++++++++
 lib/pdcp/version.map      |  13 ++
 7 files changed, 402 insertions(+), 1 deletion(-)
 create mode 100644 lib/pdcp/meson.build
 create mode 100644 lib/pdcp/rte_pdcp.h
 create mode 100644 lib/pdcp/rte_pdcp_group.h
 create mode 100644 lib/pdcp/version.map

--
2.28.0
  

> Subject: [RFC 0/1] lib: add pdcp protocol
> 
> Add Packet Data Convergence Protocol (PDCP) processing library.
> 
> The library is similar to lib_ipsec which provides IPsec processing
> capabilities in DPDK.
> 
> PDCP would involve roughly the following options,
> 1. Transfer of user plane data
> 2. Transfer of control plane data
> 3. Header compression
> 4. Uplink data compression
> 5. Ciphering and integrity protection
> 
> PDCP library provides following control path APIs that is used to
> configure various PDCP entities,
> 1. rte_pdcp_establish()
> 2. rte_pdcp_suspend()
> 3. rte_pdcp_release()
> 
> PDCP process is split into 2 parts. One before crypto processing
> (rte_pdcp_pkt_pre_process()) and one after crypto 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 entity.
> 
> Similar to lib IPsec, 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.
> 
> Changes planned for next version
> - Add APIs for rte_pdcp_entity_re_establish, rte_pdcp_entity_reconfigure
> - Implementation for all APIs covering basic control plane & user plane packets
> - Framework to handle control PDUs
> - Unit test leveraging existing PDCP vectors available in test_cryptodev
> - Eventdev based timer integration for t-Reordering & discardTimer
> - Integration with reorder library to handle in-order delivery
> 

Can you send the next version rebased over v22.11?
Also add documentation (pdcp.rst) file explaining about the new library.
Add sample sequence also in that.

Do you also plan to add, header compression? I see that it is mentioned above,
But there is no API as of now?


> Sample application sequence:
> 
> 	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;
> 
> 	/* 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 + 1;
> 	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,
> 		 *
> 		 * Transmiting 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 */
> 		}
> 
> 		...
> 
> 		ret = rte_cryptodev_dequeue_burst(dev_id, qp_id, cop,
> 						  MAX_BURST_SIZE);
> 		if (ret == 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,
> 			 *
> 			 *  Transmiting 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 */
> 
> 			/**
> 			 * Tranmitting 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
> 			 */
> 		}
> 	}
> 
> Anoob Joseph (1):
>   lib: add pdcp protocol
> 
>  doc/api/doxy-api-index.md |   3 +-
>  doc/api/doxy-api.conf.in  |   1 +
>  lib/meson.build           |   1 +
>  lib/pdcp/meson.build      |   7 ++
>  lib/pdcp/rte_pdcp.h       | 244 ++++++++++++++++++++++++++++++++++++++
>  lib/pdcp/rte_pdcp_group.h | 134 +++++++++++++++++++++
>  lib/pdcp/version.map      |  13 ++
>  7 files changed, 402 insertions(+), 1 deletion(-)
>  create mode 100644 lib/pdcp/meson.build
>  create mode 100644 lib/pdcp/rte_pdcp.h
>  create mode 100644 lib/pdcp/rte_pdcp_group.h
>  create mode 100644 lib/pdcp/version.map
> 
> --
> 2.28.0
  

Hi Akhil,

Thanks for the review. Please see inline.

Thanks
Anoob

> -----Original Message-----
> From: Akhil Goyal <gakhil@marvell.com>
> Sent: Tuesday, December 13, 2022 12:32 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
> Subject: RE: [RFC 0/1] lib: add pdcp protocol
> 
> > Subject: [RFC 0/1] lib: add pdcp protocol
> >
> > Add Packet Data Convergence Protocol (PDCP) processing library.
> >
> > The library is similar to lib_ipsec which provides IPsec processing
> > capabilities in DPDK.
> >
> > PDCP would involve roughly the following options, 1. Transfer of user
> > plane data 2. Transfer of control plane data 3. Header compression 4.
> > Uplink data compression 5. Ciphering and integrity protection
> >
> > PDCP library provides following control path APIs that is used to
> > configure various PDCP entities, 1. rte_pdcp_establish() 2.
> > rte_pdcp_suspend() 3. rte_pdcp_release()
> >
> > PDCP process is split into 2 parts. One before crypto processing
> > (rte_pdcp_pkt_pre_process()) and one after crypto 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 entity.
> >
> > Similar to lib IPsec, 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.
> >
> > Changes planned for next version
> > - Add APIs for rte_pdcp_entity_re_establish,
> > rte_pdcp_entity_reconfigure
> > - Implementation for all APIs covering basic control plane & user
> > plane packets
> > - Framework to handle control PDUs
> > - Unit test leveraging existing PDCP vectors available in
> > test_cryptodev
> > - Eventdev based timer integration for t-Reordering & discardTimer
> > - Integration with reorder library to handle in-order delivery
> >
> 
> Can you send the next version rebased over v22.11?
> Also add documentation (pdcp.rst) file explaining about the new library.
> Add sample sequence also in that.

[Anoob] Sure. Will send v1 with test application in another couple of days.

> 
> Do you also plan to add, header compression? I see that it is mentioned
> above, But there is no API as of now?

There are 2 kinds of compression when dealing with PDCP. 
1. Header compression (which is more like a dictionary lookup)
2. UDC compression (which uses standard compression methods).

[Anoob] We have plans to support Item 1, ie, header compression. For item 2, we are evaluating the practical usage requirements to decide on whether PDCP lib would need to natively support it. Adding an interface to compressdev would increase the API requirements, but since it would come outside (& before) any of the proposed APIs, the feature can be added as a standalone item.

> 
> 
> > Sample application sequence:
> >
> > 	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;
> >
> > 	/* 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 + 1;
> > 	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,
> > 		 *
> > 		 * Transmiting 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 */
> > 		}
> >
> > 		...
> >
> > 		ret = rte_cryptodev_dequeue_burst(dev_id, qp_id, cop,
> > 						  MAX_BURST_SIZE);
> > 		if (ret == 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,
> > 			 *
> > 			 *  Transmiting 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 */
> >
> > 			/**
> > 			 * Tranmitting 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
> > 			 */
> > 		}
> > 	}
> >
> > Anoob Joseph (1):
> >   lib: add pdcp protocol
> >
> >  doc/api/doxy-api-index.md |   3 +-
> >  doc/api/doxy-api.conf.in  |   1 +
> >  lib/meson.build           |   1 +
> >  lib/pdcp/meson.build      |   7 ++
> >  lib/pdcp/rte_pdcp.h       | 244
> ++++++++++++++++++++++++++++++++++++++
> >  lib/pdcp/rte_pdcp_group.h | 134 +++++++++++++++++++++
> >  lib/pdcp/version.map      |  13 ++
> >  7 files changed, 402 insertions(+), 1 deletion(-)  create mode 100644
> > lib/pdcp/meson.build  create mode 100644 lib/pdcp/rte_pdcp.h  create
> > mode 100644 lib/pdcp/rte_pdcp_group.h  create mode 100644
> > lib/pdcp/version.map
> >
> > --
> > 2.28.0