Branch data Line data Source code
1 : : /* SPDX-License-Identifier: BSD-3-Clause
2 : : * Copyright(C) 2023 Marvell.
3 : : */
4 : :
5 : : #ifndef RTE_PDCP_H
6 : : #define RTE_PDCP_H
7 : :
8 : : /**
9 : : * @file rte_pdcp.h
10 : : *
11 : : * RTE PDCP support.
12 : : *
13 : : * A framework for PDCP protocol processing.
14 : : */
15 : :
16 : : #include <rte_compat.h>
17 : : #include <rte_common.h>
18 : : #include <rte_mempool.h>
19 : : #include <rte_pdcp_hdr.h>
20 : : #include <rte_security.h>
21 : :
22 : : #ifdef __cplusplus
23 : : extern "C" {
24 : : #endif
25 : :
26 : : /* Forward declarations. */
27 : : struct rte_pdcp_entity;
28 : :
29 : : /* PDCP pre-process function based on entity configuration. */
30 : : typedef uint16_t (*rte_pdcp_pre_p_t)(const struct rte_pdcp_entity *entity,
31 : : struct rte_mbuf *mb[],
32 : : struct rte_crypto_op *cop[],
33 : : uint16_t num, uint16_t *nb_err);
34 : :
35 : : /* PDCP post-process function based on entity configuration. */
36 : : typedef uint16_t (*rte_pdcp_post_p_t)(const struct rte_pdcp_entity *entity,
37 : : struct rte_mbuf *in_mb[],
38 : : struct rte_mbuf *out_mb[],
39 : : uint16_t num, uint16_t *nb_err);
40 : :
41 : : /**
42 : : * PDCP entity.
43 : : *
44 : : * 4.2.2 PDCP entities
45 : : *
46 : : * The PDCP entities are located in the PDCP sublayer.
47 : : * Several PDCP entities may be defined for a UE.
48 : : * Each PDCP entity is carrying the data of one radio bearer.
49 : : * A PDCP entity is associated either to the control plane or the user plane
50 : : * depending on which radio bearer it is carrying data for.
51 : : */
52 : : struct __rte_cache_aligned rte_pdcp_entity {
53 : : /** Entity specific pre-process handle. */
54 : : rte_pdcp_pre_p_t pre_process;
55 : : /** Entity specific post-process handle. */
56 : : rte_pdcp_post_p_t post_process;
57 : : /**
58 : : * PDCP entities may hold packets for purposes of in-order delivery
59 : : * (in case of receiving PDCP entity) and re-transmission
60 : : * (in case of transmitting PDCP entity).
61 : : *
62 : : * The field 'max_pkt_cache' would be used to indicate the maximum
63 : : * number of packets that may be cached in an entity at any point of time.
64 : : * When application provides buffers to receive packets from PDCP entity,
65 : : * the size of the buffer should be such that it can
66 : : * hold additionally 'max_pkt_cache' number of packets.
67 : : */
68 : : uint32_t max_pkt_cache;
69 : : };
70 : :
71 : : /**
72 : : * Callback function type for t-Reordering timer start, set during PDCP entity establish.
73 : : * This callback is invoked by PDCP library, during t-Reordering timer start event.
74 : : * Only one t-Reordering per receiving PDCP entity would be running at a given time.
75 : : *
76 : : * @see struct rte_pdcp_timer
77 : : * @see rte_pdcp_entity_establish()
78 : : *
79 : : * @param timer
80 : : * Pointer to timer.
81 : : * @param args
82 : : * Pointer to timer arguments.
83 : : */
84 : : typedef void (*rte_pdcp_t_reordering_start_cb_t)(void *timer, void *args);
85 : :
86 : : /**
87 : : * Callback function type for t-Reordering timer stop, set during PDCP entity establish.
88 : : * This callback will be invoked by PDCP library, during t-Reordering timer stop event.
89 : : *
90 : : * @see struct rte_pdcp_timer
91 : : * @see rte_pdcp_entity_establish()
92 : : *
93 : : * @param timer
94 : : * Pointer to timer.
95 : : * @param args
96 : : * Pointer to timer arguments.
97 : : */
98 : : typedef void (*rte_pdcp_t_reordering_stop_cb_t)(void *timer, void *args);
99 : :
100 : : /**
101 : : * PDCP t-Reordering timer interface
102 : : *
103 : : * Configuration provided by user, that PDCP library will invoke according to timer behaviour.
104 : : */
105 : : /* Structure rte_pdcp_t_reordering 8< */
106 : : struct rte_pdcp_t_reordering {
107 : : /** Timer pointer, to be used in callback functions. */
108 : : void *timer;
109 : : /** Timer arguments, to be used in callback functions. */
110 : : void *args;
111 : : /** Timer start callback handle. */
112 : : rte_pdcp_t_reordering_start_cb_t start;
113 : : /** Timer stop callback handle. */
114 : : rte_pdcp_t_reordering_stop_cb_t stop;
115 : : };
116 : : /* >8 End of structure rte_pdcp_t_reordering. */
117 : :
118 : : /**
119 : : * PDCP entity configuration to be used for establishing an entity.
120 : : */
121 : : /* Structure rte_pdcp_entity_conf 8< */
122 : : struct rte_pdcp_entity_conf {
123 : : /** PDCP transform for the entity. */
124 : : struct rte_security_pdcp_xform pdcp_xfrm;
125 : : /** Crypto transform applicable for the entity. */
126 : : struct rte_crypto_sym_xform *crypto_xfrm;
127 : : /** Mempool for crypto symmetric session. */
128 : : struct rte_mempool *sess_mpool;
129 : : /** Crypto op pool. */
130 : : struct rte_mempool *cop_pool;
131 : : /** Mbuf pool to be used for allocating control PDUs.*/
132 : : struct rte_mempool *ctrl_pdu_pool;
133 : : /**
134 : : * Sequence number value to be used.
135 : : * 32 bit count value to be used for the first packet
136 : : * would be derived based on HFN (`rte_security_pdcp_xform.hfn`) and SN.
137 : : */
138 : : uint32_t sn;
139 : : /** Indicate whether the PDCP entity belongs to Side Link Radio Bearer. */
140 : : bool is_slrb;
141 : : /** Enable security offload on the device specified. */
142 : : bool en_sec_offload;
143 : : /** Device on which security/crypto session need to be created. */
144 : : uint8_t dev_id;
145 : : /**
146 : : * Reverse direction during IV generation.
147 : : * Can be used to simulate UE crypto processing.
148 : : */
149 : : bool reverse_iv_direction;
150 : : /**
151 : : * Status report required (specified in TS 38.331).
152 : : *
153 : : * If PDCP entity is configured to send a PDCP status report,
154 : : * the upper layer application may request a receiving PDCP entity
155 : : * to generate a PDCP status report using ``rte_pdcp_control_pdu_create``.
156 : : * In addition, PDCP status reports may be generated during operations
157 : : * such as entity re-establishment.
158 : : */
159 : : bool status_report_required;
160 : : /** Enable out of order delivery. */
161 : : bool out_of_order_delivery;
162 : : /** t-Reordering timer configuration. */
163 : : struct rte_pdcp_t_reordering t_reordering;
164 : : };
165 : : /* >8 End of structure rte_pdcp_entity_conf. */
166 : :
167 : : /**
168 : : * @warning
169 : : * @b EXPERIMENTAL: this API may change without prior notice.
170 : : *
171 : : * 5.1.1 PDCP entity establishment
172 : : *
173 : : * Establish PDCP entity based on provided input configuration.
174 : : *
175 : : * @param conf
176 : : * Parameters to be used for initializing PDCP entity object.
177 : : * @return
178 : : * - Valid handle if success
179 : : * - NULL in case of failure. rte_errno will be set to error code.
180 : : */
181 : : __rte_experimental
182 : : struct rte_pdcp_entity *
183 : : rte_pdcp_entity_establish(const struct rte_pdcp_entity_conf *conf);
184 : :
185 : : /**
186 : : * @warning
187 : : * @b EXPERIMENTAL: this API may change without prior notice.
188 : : *
189 : : * 5.1.3 PDCP entity release
190 : : *
191 : : * Release PDCP entity.
192 : : *
193 : : * For UL/transmitting PDCP entity, all stored PDCP SDUs would be dropped.
194 : : * For DL/receiving PDCP entity, the stored PDCP SDUs would be returned in
195 : : * *out_mb* buffer. The buffer should be large enough to hold all cached
196 : : * packets in the entity.
197 : : *
198 : : * Entity release would result in freeing all memory associated with the PDCP
199 : : * entity as well as any crypto/security sessions created.
200 : : *
201 : : * @param pdcp_entity
202 : : * Pointer to the PDCP entity to be released.
203 : : * @param[out] out_mb
204 : : * The address of an array that can hold up to *rte_pdcp_entity.max_pkt_cache*
205 : : * pointers to *rte_mbuf* structures.
206 : : * @return
207 : : * - 0: Success and no cached packets to return
208 : : * - >0: Success and the number of packets returned in out_mb
209 : : * - <0: Error code in case of failures
210 : : */
211 : : __rte_experimental
212 : : int
213 : : rte_pdcp_entity_release(struct rte_pdcp_entity *pdcp_entity,
214 : : struct rte_mbuf *out_mb[]);
215 : :
216 : : /**
217 : : * @warning
218 : : * @b EXPERIMENTAL: this API may change without prior notice.
219 : : *
220 : : * 5.1.4 PDCP entity suspend
221 : : *
222 : : * Suspend PDCP entity.
223 : : *
224 : : * For DL/receiving PDCP entity, the stored PDCP SDUs would be returned in
225 : : * *out_mb* buffer. The buffer should be large enough to hold all cached
226 : : * packets in the entity.
227 : : *
228 : : * For UL/transmitting PDCP entity, *out_mb* buffer would be unused.
229 : : *
230 : : * @param pdcp_entity
231 : : * Pointer to the PDCP entity to be suspended.
232 : : * @param[out] out_mb
233 : : * The address of an array that can hold up to *rte_pdcp_entity.max_pkt_cache*
234 : : * pointers to *rte_mbuf* structures.
235 : : * @return
236 : : * - 0: Success and no cached packets to return.
237 : : * - >0: Success and the number of packets returned in out_mb.
238 : : * - <0: Error code in case of failures.
239 : : */
240 : : __rte_experimental
241 : : int
242 : : rte_pdcp_entity_suspend(struct rte_pdcp_entity *pdcp_entity,
243 : : struct rte_mbuf *out_mb[]);
244 : :
245 : : /**
246 : : * @warning
247 : : * @b EXPERIMENTAL: this API may change without prior notice.
248 : : *
249 : : * Create control PDU packet of the `type` specified. The control PDU packet
250 : : * would be allocated from *rte_pdcp_entity_conf.ctrl_pdu_pool* by lib PDCP.
251 : : *
252 : : * @param pdcp_entity
253 : : * Pointer to the PDCP entity for which the control PDU need to be generated.
254 : : * @param type
255 : : * Type of control PDU to be generated.
256 : : * @return
257 : : * - Control PDU generated, in case of success.
258 : : * - NULL in case of failure. rte_errno will be set to error code.
259 : : */
260 : : __rte_experimental
261 : : struct rte_mbuf *
262 : : rte_pdcp_control_pdu_create(struct rte_pdcp_entity *pdcp_entity,
263 : : enum rte_pdcp_ctrl_pdu_type type);
264 : :
265 : : /**
266 : : * @warning
267 : : * @b EXPERIMENTAL: this API may change without prior notice.
268 : : *
269 : : * For input mbufs and given PDCP entity pre-process the mbufs and prepare
270 : : * crypto ops that can be enqueued to the cryptodev associated with given
271 : : * session. Only error packets would be moved returned in the input buffer,
272 : : * *mb*, and it is the responsibility of the application to free the same.
273 : : *
274 : : * @param entity
275 : : * Pointer to the *rte_pdcp_entity* object the packets belong to.
276 : : * @param[in, out] mb
277 : : * The address of an array of *num* pointers to *rte_mbuf* structures
278 : : * which contain the input packets.
279 : : * Any error packets would be returned in the same buffer.
280 : : * @param[out] cop
281 : : * The address of an array that can hold up to *num* pointers to
282 : : * *rte_crypto_op* structures. Crypto ops would be allocated by
283 : : * ``rte_pdcp_pkt_pre_process`` API.
284 : : * @param num
285 : : * The maximum number of packets to process.
286 : : * @param[out] nb_err
287 : : * Pointer to return the number of error packets returned in *mb*.
288 : : * @return
289 : : * Count of crypto_ops prepared.
290 : : */
291 : : __rte_experimental
292 : : static inline uint16_t
293 : : rte_pdcp_pkt_pre_process(const struct rte_pdcp_entity *entity,
294 : : struct rte_mbuf *mb[], struct rte_crypto_op *cop[],
295 : : uint16_t num, uint16_t *nb_err)
296 : : {
297 : 0 : return entity->pre_process(entity, mb, cop, num, nb_err);
298 : : }
299 : :
300 : : /**
301 : : * @warning
302 : : * @b EXPERIMENTAL: this API may change without prior notice.
303 : : *
304 : : * For input mbufs and given PDCP entity, perform PDCP post-processing of the mbufs.
305 : : *
306 : : * Input mbufs are the ones retrieved from rte_crypto_ops dequeued from cryptodev
307 : : * and grouped by *rte_pdcp_pkt_crypto_group()*.
308 : : *
309 : : * The post-processed packets would be returned in the *out_mb* buffer.
310 : : * The resultant mbufs would be grouped into success packets and error packets.
311 : : * Error packets would be grouped in the end of the array and
312 : : * it is the responsibility of the application to handle the same.
313 : : *
314 : : * When in-order delivery is enabled, PDCP entity may buffer packets and would
315 : : * deliver packets only when all prior packets have been post-processed.
316 : : * That would result in returning more/less packets than enqueued.
317 : : *
318 : : * @param entity
319 : : * Pointer to the *rte_pdcp_entity* object the packets belong to.
320 : : * @param in_mb
321 : : * The address of an array of *num* pointers to *rte_mbuf* structures.
322 : : * @param[out] out_mb
323 : : * The address of an array that can hold up to *rte_pdcp_entity.max_pkt_cache*
324 : : * pointers to *rte_mbuf* structures to output packets after PDCP post-processing.
325 : : * @param num
326 : : * The maximum number of packets to process.
327 : : * @param[out] nb_err
328 : : * The number of error packets returned in *out_mb* buffer.
329 : : * @return
330 : : * Count of packets returned in *out_mb* buffer.
331 : : */
332 : : __rte_experimental
333 : : static inline uint16_t
334 : : rte_pdcp_pkt_post_process(const struct rte_pdcp_entity *entity,
335 : : struct rte_mbuf *in_mb[],
336 : : struct rte_mbuf *out_mb[],
337 : : uint16_t num, uint16_t *nb_err)
338 : : {
339 : 0 : return entity->post_process(entity, in_mb, out_mb, num, nb_err);
340 : : }
341 : :
342 : : /**
343 : : * @warning
344 : : * @b EXPERIMENTAL: this API may change without prior notice
345 : : *
346 : : * 5.2.2.2 Actions when a t-Reordering expires
347 : : *
348 : : * When t-Reordering timer expires, PDCP is required to slide the reception
349 : : * window by updating state variables such as RX_REORD & RX_DELIV.
350 : : * PDCP would need to deliver some of the buffered packets
351 : : * based on the state variables and conditions described.
352 : : *
353 : : * The expiry handle need to be invoked by the application when t-Reordering
354 : : * timer expires. In addition to returning buffered packets, it may also restart
355 : : * timer based on the state variables.
356 : : *
357 : : * @param entity
358 : : * Pointer to the *rte_pdcp_entity* for which the timer expired.
359 : : * @param[out] out_mb
360 : : * The address of an array that can hold up to *rte_pdcp_entity.max_pkt_cache*
361 : : * pointers to *rte_mbuf* structures. Used to return buffered packets that are expired.
362 : : * @return
363 : : * Number of packets returned in *out_mb* buffer.
364 : : */
365 : : __rte_experimental
366 : : uint16_t
367 : : rte_pdcp_t_reordering_expiry_handle(const struct rte_pdcp_entity *entity,
368 : : struct rte_mbuf *out_mb[]);
369 : :
370 : : /**
371 : : * The header 'rte_pdcp_group.h' depends on defines in 'rte_pdcp.h'.
372 : : * So include in the end.
373 : : */
374 : : #include <rte_pdcp_group.h>
375 : :
376 : : #ifdef __cplusplus
377 : : }
378 : : #endif
379 : :
380 : : #endif /* RTE_PDCP_H */
|