rte_pdcp.h(3)

📦
version 25.11.3 · 11 versions
, in ubuntu resolute, ubuntu stonking

🦋 rte_pdcp.h — the vibe check 💖

okay bestie, sit down, hydrate, because we're about to get into rte_pdcp.h, a header from the good people at DPDK. it's giving "RTE PDCP support" energy — like, a whole framework for PDCP protocol processing. fr fr. the manual name is literally rte_pdcp.h and it lives in section 3 (library functions), so act accordingly. 💅

✨ SYNOPSIS ✨

#include <rte_compat.h>
#include <rte_common.h>
#include <rte_mempool.h>
#include <rte_pdcp_hdr.h>
#include <rte_security.h>
#include <rte_pdcp_group.h>

🎀 Data Structures

okay so we have three structs and they're all kinda iconic:

  • struct rte_pdcp_entity
  • struct rte_pdcp_t_reordering
  • struct rte_pdcp_entity_conf

🌸 Typedefs

the callback girlies:

  • typedef void(* rte_pdcp_t_reordering_start_cb_t)(void *timer, void *args)
  • typedef void(* rte_pdcp_t_reordering_stop_cb_t)(void *timer, void *args)

💖 Functions

every one of these is __rte_experimental btw, so note that:

  • __rte_experimental struct rte_pdcp_entity *rte_pdcp_entity_establish(const struct rte_pdcp_entity_conf *conf)
  • __rte_experimental int rte_pdcp_entity_release(struct rte_pdcp_entity *pdcp_entity, struct rte_mbuf *out_mb[])
  • __rte_experimental int rte_pdcp_entity_suspend(struct rte_pdcp_entity *pdcp_entity, struct rte_mbuf *out_mb[])
  • __rte_experimental struct rte_mbuf *rte_pdcp_control_pdu_create(struct rte_pdcp_entity *pdcp_entity, enum rte_pdcp_ctrl_pdu_type type)
  • static __rte_experimental uint16_t rte_pdcp_pkt_pre_process(const struct rte_pdcp_entity *entity, struct rte_mbuf *mb[], struct rte_crypto_op *cop[], uint16_t num, uint16_t *nb_err)
  • static __rte_experimental uint16_t rte_pdcp_pkt_post_process(const struct rte_pdcp_entity *entity, struct rte_mbuf *in_mb[], struct rte_mbuf *out_mb[], uint16_t num, uint16_t *nb_err)
  • __rte_experimental uint16_t rte_pdcp_t_reordering_expiry_handle(const struct rte_pdcp_entity *entity, struct rte_mbuf *out_mb[])

🔥 DESCRIPTION 🔥

RTE PDCP support. periodt.

it's a whole framework for PDCP protocol processing. that's the tea. 🍓

Definition in file rte_pdcp.h.

👑 TYPEDEFS 👑

🌈 typedef void(* rte_pdcp_t_reordering_start_cb_t) (void *timer, void *args)

this is the callback function type for the t-Reordering timer start — you set it during PDCP entity establish, and then the PDCP library calls it for you whenever a t-Reordering timer start event happens. and listen: only one t-Reordering per receiving PDCP entity would be running at a given time. no cap. 🙅‍♀️

See also: struct rte_pdcp_timer, rte_pdcp_entity_establish()

Parameters:

  • timer — Pointer to timer.
  • args — Pointer to timer arguments.
Definition at line 80 of file rte_pdcp.h.

🌈 typedef void(* rte_pdcp_t_reordering_stop_cb_t) (void *timer, void *args)

same energy, different event: this is the callback function type for the t-Reordering timer stop, also set during PDCP entity establish, and the PDCP library invokes it when a t-Reordering timer stop event goes down.

See also: struct rte_pdcp_timer, rte_pdcp_entity_establish()

Parameters:

  • timer — Pointer to timer.
  • args — Pointer to timer arguments.
Definition at line 94 of file rte_pdcp.h.

💜 FUNCTION DOCUMENTATION 💜

✨ __rte_experimental struct rte_pdcp_entity * rte_pdcp_entity_establish (const struct rte_pdcp_entity_conf * conf)

🚨 Warning: EXPERIMENTAL: this API may change without prior notice. (yes bestie, she's experimental — she's still figuring herself out 💀)

5.1.1 PDCP entity establishment

Establish the PDCP entity based on the input configuration you hand her. she needs a lil config to become her full self. ✨

Parameters:

  • conf — Parameters to be used for initializing PDCP entity object.

Returns:

  • Valid handle if success ✅
  • NULL in case of failure. rte_errno will be set to error code. 😭

✨ __rte_experimental int rte_pdcp_entity_release (struct rte_pdcp_entity * pdcp_entity, struct rte_mbuf * out_mb[])

🚨 Warning: EXPERIMENTAL: this API may change without prior notice.

5.1.3 PDCP entity release

Release the PDCP entity. she's done, she's leaving, she said no more. 💅

here's the breakdown:

  • for UL/transmitting PDCP entity: all stored PDCP SDUs would be dropped. yeah. dropped dropped. 🙈
  • for DL/receiving PDCP entity: the stored PDCP SDUs would be returned in the out_mb buffer.
⚠️ the buffer needs to be large enough to hold all cached packets in the entity, okay? don't play yourself.

Entity release would result in freeing all memory associated with the PDCP entity, as well as any crypto/security sessions created. like, everything. gone. ✨

Parameters:

  • pdcp_entity — Pointer to the PDCP entity to be released.
  • out_mb — The address of an array that can hold up to rte_pdcp_entity.max_pkt_cache pointers to rte_mbuf structures.

Returns:

  • 0: Success and no cached packets to return
  • >0: Success and the number of packets returned in out_mb
  • <0: Error code in case of failures

✨ __rte_experimental int rte_pdcp_entity_suspend (struct rte_pdcp_entity * pdcp_entity, struct rte_mbuf * out_mb[])

🚨 Warning: EXPERIMENTAL: this API may change without prior notice.

5.1.4 PDCP entity suspend

Suspend the PDCP entity. she's not gone, she's just on a lil break. 🧚

  • for DL/receiving PDCP entity: the stored PDCP SDUs would be returned in the out_mb buffer, and again — that buffer should be large enough to hold all cached packets in the entity.
  • for UL/transmitting PDCP entity: the out_mb buffer would be unused. literally just sitting there.

Parameters:

  • pdcp_entity — Pointer to the PDCP entity to be suspended.
  • out_mb — The address of an array that can hold up to rte_pdcp_entity.max_pkt_cache pointers to rte_mbuf structures.

Returns:

  • 0: Success and no cached packets to return.
  • >0: Success and the number of packets returned in out_mb.
  • <0: Error code in case of failures.

✨ __rte_experimental struct rte_mbuf * rte_pdcp_control_pdu_create (struct rte_pdcp_entity * pdcp_entity, enum rte_pdcp_ctrl_pdu_type type)

🚨 Warning: EXPERIMENTAL: this API may change without prior notice.

Create a control PDU packet of the type you specified. and here's the cute part: the control PDU packet would be allocated from rte_pdcp_entity_conf.ctrl_pdu_pool by lib PDCP. she's self-sufficient. 💅

Parameters:

  • pdcp_entity — Pointer to the PDCP entity for which the control PDU need to be generated.
  • type — Type of control PDU to be generated.

Returns:

  • Control PDU generated, in case of success. 🎉
  • NULL in case of failure. rte_errno will be set to error code.

✨ __rte_experimental uint16_t rte_pdcp_pkt_pre_process (const struct rte_pdcp_entity * entity, struct rte_mbuf * mb[], struct rte_crypto_op * cop[], uint16_t num, uint16_t * nb_err) [inline], [static]

🚨 Warning: EXPERIMENTAL: this API may change without prior notice.

okay so for the input mbufs and a given PDCP entity, this bad girl pre-processes the mbufs and prepares crypto ops that can be enqueued to the cryptodev associated with the given session. ❤️‍🔥

heads up: only error packets would be moved and returned in the input buffer, mb, and it is the responsibility of the application to free the same. that's on you, bestie. no takebacks.

Parameters:

  • entity — Pointer to the rte_pdcp_entity object the packets belong to.
  • mb — The address of an array of num pointers to rte_mbuf structures which contain the input packets. Any error packets would be returned in the same buffer.
  • cop — The address of an array that can hold up to num pointers to rte_crypto_op structures. Crypto ops would be allocated by rte_pdcp_pkt_pre_process API.
  • num — The maximum number of packets to process.
  • nb_err — Pointer to return the number of error packets returned in mb.

Returns: Count of crypto_ops prepared.

Definition at line 289 of file rte_pdcp.h.

✨ __rte_experimental uint16_t rte_pdcp_pkt_post_process (const struct rte_pdcp_entity * entity, struct rte_mbuf * in_mb[], struct rte_mbuf * out_mb[], uint16_t num, uint16_t * nb_err) [inline], [static]

🚨 Warning: EXPERIMENTAL: this API may change without prior notice.

for input mbufs and a given PDCP entity, perform PDCP post-processing of the mbufs. the sequel. the second act. 🦋

the input mbufs are the ones retrieved from rte_crypto_ops dequeued from cryptodev and grouped by rte_pdcp_pkt_crypto_group().

the post-processed packets would be returned in the out_mb buffer. and listen — the resultant mbufs would be grouped into success packets and error packets. the error packets get grouped at the end of the array, and it is the responsibility of the application to handle the same. (again: you. it's you. 🙈)

also very important: when in-order delivery is enabled, the PDCP entity may buffer packets and would deliver packets only when all prior packets have been post-processed. which means you could get more or fewer packets back than you enqueued. that's not a bug, that's the in-order life. 💀

Parameters:

  • entity — Pointer to the rte_pdcp_entity object the packets belong to.
  • in_mb — The address of an array of num pointers to rte_mbuf structures.
  • out_mb — The address of an array that can hold up to rte_pdcp_entity.max_pkt_cache pointers to rte_mbuf structures to output packets after PDCP post-processing.
  • num — The maximum number of packets to process.
  • nb_err — The number of error packets returned in out_mb buffer.

Returns: Count of packets returned in out_mb buffer.

Definition at line 330 of file rte_pdcp.h.

✨ __rte_experimental uint16_t rte_pdcp_t_reordering_expiry_handle (const struct rte_pdcp_entity * entity, struct rte_mbuf * out_mb[])

🚨 Warning: EXPERIMENTAL: this API may change without prior notice

5.2.2.2 Actions when a t-Reordering expires

when the t-Reordering timer expires, PDCP is required to slide the reception window by updating state variables such as RX_REORD & RX_DELIV. and PDCP would need to deliver some of the buffered packets based on the state variables and conditions described. she's shuffling the lineup. 👑

the expiry handle needs to be invoked by the application when the t-Reordering timer expires. and get this — in addition to returning buffered packets, it may also restart the timer based on the state variables. multitasking icon. ✨

Parameters:

  • entity — Pointer to the rte_pdcp_entity for which the timer expired.
  • out_mb — The address of an array that can hold up to rte_pdcp_entity.max_pkt_cache pointers to rte_mbuf structures. Used to return buffered packets that are expired.

Returns: Number of packets returned in out_mb buffer.

🌟 AUTHOR 🌟

Generated automatically by Doxygen for DPDK from the source code. (not a human, not a group chat, just Doxygen doing its lil thing 🫶)

and that's the whole page bestie, no crumbs left. this masterpiece was served to you by DPDK, Version 25.11.3, dated rte_pdcp.h(3) — go forth and establish some PDCP entities, you absolute main character. 💅💖✨🌈

📦 where this page comes from