]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | /*- |
2 | * BSD LICENSE | |
3 | * | |
4 | * Copyright(c) 2010-2016 Intel Corporation. All rights reserved. | |
5 | * All rights reserved. | |
6 | * | |
7 | * Redistribution and use in source and binary forms, with or without | |
8 | * modification, are permitted provided that the following conditions | |
9 | * are met: | |
10 | * | |
11 | * * Redistributions of source code must retain the above copyright | |
12 | * notice, this list of conditions and the following disclaimer. | |
13 | * * Redistributions in binary form must reproduce the above copyright | |
14 | * notice, this list of conditions and the following disclaimer in | |
15 | * the documentation and/or other materials provided with the | |
16 | * distribution. | |
17 | * * Neither the name of Intel Corporation nor the names of its | |
18 | * contributors may be used to endorse or promote products derived | |
19 | * from this software without specific prior written permission. | |
20 | * | |
21 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
22 | * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
23 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | |
24 | * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | |
25 | * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
26 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
27 | * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | |
28 | * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | |
29 | * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
30 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
31 | * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
32 | */ | |
33 | ||
34 | #ifndef __INCLUDE_RTE_PIPELINE_H__ | |
35 | #define __INCLUDE_RTE_PIPELINE_H__ | |
36 | ||
37 | #ifdef __cplusplus | |
38 | extern "C" { | |
39 | #endif | |
40 | ||
41 | /** | |
42 | * @file | |
43 | * RTE Pipeline | |
44 | * | |
45 | * This tool is part of the DPDK Packet Framework tool suite and provides | |
46 | * a standard methodology (logically similar to OpenFlow) for rapid development | |
47 | * of complex packet processing pipelines out of ports, tables and actions. | |
48 | * | |
49 | * <B>Basic operation.</B> A pipeline is constructed by connecting its input | |
50 | * ports to its output ports through a chain of lookup tables. As result of | |
51 | * lookup operation into the current table, one of the table entries (or the | |
52 | * default table entry, in case of lookup miss) is identified to provide the | |
53 | * actions to be executed on the current packet and the associated action | |
54 | * meta-data. The behavior of user actions is defined through the configurable | |
55 | * table action handler, while the reserved actions define the next hop for the | |
56 | * current packet (either another table, an output port or packet drop) and are | |
57 | * handled transparently by the framework. | |
58 | * | |
59 | * <B>Initialization and run-time flows.</B> Once all the pipeline elements | |
60 | * (input ports, tables, output ports) have been created, input ports connected | |
61 | * to tables, table action handlers configured, tables populated with the | |
62 | * initial set of entries (actions and action meta-data) and input ports | |
63 | * enabled, the pipeline runs automatically, pushing packets from input ports | |
64 | * to tables and output ports. At each table, the identified user actions are | |
65 | * being executed, resulting in action meta-data (stored in the table entry) | |
66 | * and packet meta-data (stored with the packet descriptor) being updated. The | |
67 | * pipeline tables can have further updates and input ports can be disabled or | |
68 | * enabled later on as required. | |
69 | * | |
70 | * <B>Multi-core scaling.</B> Typically, each CPU core will run its own | |
71 | * pipeline instance. Complex application-level pipelines can be implemented by | |
72 | * interconnecting multiple CPU core-level pipelines in tree-like topologies, | |
73 | * as the same port devices (e.g. SW rings) can serve as output ports for the | |
74 | * pipeline running on CPU core A, as well as input ports for the pipeline | |
75 | * running on CPU core B. This approach enables the application development | |
76 | * using the pipeline (CPU cores connected serially), cluster/run-to-completion | |
77 | * (CPU cores connected in parallel) or mixed (pipeline of CPU core clusters) | |
78 | * programming models. | |
79 | * | |
80 | * <B>Thread safety.</B> It is possible to have multiple pipelines running on | |
81 | * the same CPU core, but it is not allowed (for thread safety reasons) to have | |
82 | * multiple CPU cores running the same pipeline instance. | |
83 | * | |
84 | ***/ | |
85 | ||
86 | #include <stdint.h> | |
87 | ||
88 | #include <rte_port.h> | |
89 | #include <rte_table.h> | |
90 | #include <rte_common.h> | |
91 | ||
92 | struct rte_mbuf; | |
93 | ||
94 | /* | |
95 | * Pipeline | |
96 | * | |
97 | */ | |
98 | /** Opaque data type for pipeline */ | |
99 | struct rte_pipeline; | |
100 | ||
101 | /** Parameters for pipeline creation */ | |
102 | struct rte_pipeline_params { | |
103 | /** Pipeline name */ | |
104 | const char *name; | |
105 | ||
106 | /** CPU socket ID where memory for the pipeline and its elements (ports | |
107 | and tables) should be allocated */ | |
108 | int socket_id; | |
109 | ||
110 | /** Offset within packet meta-data to port_id to be used by action | |
111 | "Send packet to output port read from packet meta-data". Has to be | |
112 | 4-byte aligned. */ | |
113 | uint32_t offset_port_id; | |
114 | }; | |
115 | ||
116 | /** Pipeline port in stats. */ | |
117 | struct rte_pipeline_port_in_stats { | |
118 | /** Port in stats. */ | |
119 | struct rte_port_in_stats stats; | |
120 | ||
121 | /** Number of packets dropped by action handler. */ | |
122 | uint64_t n_pkts_dropped_by_ah; | |
123 | ||
124 | }; | |
125 | ||
126 | /** Pipeline port out stats. */ | |
127 | struct rte_pipeline_port_out_stats { | |
128 | /** Port out stats. */ | |
129 | struct rte_port_out_stats stats; | |
130 | ||
131 | /** Number of packets dropped by action handler. */ | |
132 | uint64_t n_pkts_dropped_by_ah; | |
133 | }; | |
134 | ||
135 | /** Pipeline table stats. */ | |
136 | struct rte_pipeline_table_stats { | |
137 | /** Table stats. */ | |
138 | struct rte_table_stats stats; | |
139 | ||
140 | /** Number of packets dropped by lookup hit action handler. */ | |
141 | uint64_t n_pkts_dropped_by_lkp_hit_ah; | |
142 | ||
143 | /** Number of packets dropped by lookup miss action handler. */ | |
144 | uint64_t n_pkts_dropped_by_lkp_miss_ah; | |
145 | ||
146 | /** Number of packets dropped by pipeline in behalf of this | |
147 | * table based on action specified in table entry. */ | |
148 | uint64_t n_pkts_dropped_lkp_hit; | |
149 | ||
150 | /** Number of packets dropped by pipeline in behalf of this | |
151 | * table based on action specified in table entry. */ | |
152 | uint64_t n_pkts_dropped_lkp_miss; | |
153 | }; | |
154 | ||
155 | /** | |
156 | * Pipeline create | |
157 | * | |
158 | * @param params | |
159 | * Parameters for pipeline creation | |
160 | * @return | |
161 | * Handle to pipeline instance on success or NULL otherwise | |
162 | */ | |
163 | struct rte_pipeline *rte_pipeline_create(struct rte_pipeline_params *params); | |
164 | ||
165 | /** | |
166 | * Pipeline free | |
167 | * | |
168 | * @param p | |
169 | * Handle to pipeline instance | |
170 | * @return | |
171 | * 0 on success, error code otherwise | |
172 | */ | |
173 | int rte_pipeline_free(struct rte_pipeline *p); | |
174 | ||
175 | /** | |
176 | * Pipeline consistency check | |
177 | * | |
178 | * @param p | |
179 | * Handle to pipeline instance | |
180 | * @return | |
181 | * 0 on success, error code otherwise | |
182 | */ | |
183 | int rte_pipeline_check(struct rte_pipeline *p); | |
184 | ||
185 | /** | |
186 | * Pipeline run | |
187 | * | |
188 | * @param p | |
189 | * Handle to pipeline instance | |
190 | * @return | |
191 | * Number of packets read and processed | |
192 | */ | |
193 | int rte_pipeline_run(struct rte_pipeline *p); | |
194 | ||
195 | /** | |
196 | * Pipeline flush | |
197 | * | |
198 | * @param p | |
199 | * Handle to pipeline instance | |
200 | * @return | |
201 | * 0 on success, error code otherwise | |
202 | */ | |
203 | int rte_pipeline_flush(struct rte_pipeline *p); | |
204 | ||
205 | /* | |
206 | * Actions | |
207 | * | |
208 | */ | |
209 | /** Reserved actions */ | |
210 | enum rte_pipeline_action { | |
211 | /** Drop the packet */ | |
212 | RTE_PIPELINE_ACTION_DROP = 0, | |
213 | ||
214 | /** Send packet to output port */ | |
215 | RTE_PIPELINE_ACTION_PORT, | |
216 | ||
217 | /** Send packet to output port read from packet meta-data */ | |
218 | RTE_PIPELINE_ACTION_PORT_META, | |
219 | ||
220 | /** Send packet to table */ | |
221 | RTE_PIPELINE_ACTION_TABLE, | |
222 | ||
223 | /** Number of reserved actions */ | |
224 | RTE_PIPELINE_ACTIONS | |
225 | }; | |
226 | ||
227 | /* | |
228 | * Table | |
229 | * | |
230 | */ | |
231 | /** Maximum number of tables allowed for any given pipeline instance. The | |
232 | value of this parameter cannot be changed. */ | |
233 | #define RTE_PIPELINE_TABLE_MAX 64 | |
234 | ||
235 | /** | |
236 | * Head format for the table entry of any pipeline table. For any given | |
237 | * pipeline table, all table entries should have the same size and format. For | |
238 | * any given pipeline table, the table entry has to start with a head of this | |
239 | * structure, which contains the reserved actions and their associated | |
240 | * meta-data, and then optionally continues with user actions and their | |
241 | * associated meta-data. As all the currently defined reserved actions are | |
242 | * mutually exclusive, only one reserved action can be set per table entry. | |
243 | */ | |
244 | struct rte_pipeline_table_entry { | |
245 | /** Reserved action */ | |
246 | enum rte_pipeline_action action; | |
247 | ||
248 | RTE_STD_C11 | |
249 | union { | |
250 | /** Output port ID (meta-data for "Send packet to output port" | |
251 | action) */ | |
252 | uint32_t port_id; | |
253 | /** Table ID (meta-data for "Send packet to table" action) */ | |
254 | uint32_t table_id; | |
255 | }; | |
256 | /** Start of table entry area for user defined actions and meta-data */ | |
257 | __extension__ uint8_t action_data[0]; | |
258 | }; | |
259 | ||
260 | /** | |
261 | * Pipeline table action handler on lookup hit | |
262 | * | |
263 | * The action handler can decide to drop packets by resetting the associated | |
264 | * packet bit in the pkts_mask parameter. In this case, the action handler is | |
265 | * required not to free the packet buffer, which will be freed eventually by | |
266 | * the pipeline. | |
267 | * | |
268 | * @param p | |
269 | * Handle to pipeline instance | |
270 | * @param pkts | |
271 | * Burst of input packets specified as array of up to 64 pointers to struct | |
272 | * rte_mbuf | |
273 | * @param pkts_mask | |
274 | * 64-bit bitmask specifying which packets in the input burst are valid. When | |
275 | * pkts_mask bit n is set, then element n of pkts array is pointing to a | |
276 | * valid packet and element n of entries array is pointing to a valid table | |
277 | * entry associated with the packet, with the association typically done by | |
278 | * the table lookup operation. Otherwise, element n of pkts array and element | |
279 | * n of entries array will not be accessed. | |
280 | * @param entries | |
281 | * Set of table entries specified as array of up to 64 pointers to struct | |
282 | * rte_pipeline_table_entry | |
283 | * @param arg | |
284 | * Opaque parameter registered by the user at the pipeline table creation | |
285 | * time | |
286 | * @return | |
287 | * 0 on success, error code otherwise | |
288 | */ | |
289 | typedef int (*rte_pipeline_table_action_handler_hit)( | |
290 | struct rte_pipeline *p, | |
291 | struct rte_mbuf **pkts, | |
292 | uint64_t pkts_mask, | |
293 | struct rte_pipeline_table_entry **entries, | |
294 | void *arg); | |
295 | ||
296 | /** | |
297 | * Pipeline table action handler on lookup miss | |
298 | * | |
299 | * The action handler can decide to drop packets by resetting the associated | |
300 | * packet bit in the pkts_mask parameter. In this case, the action handler is | |
301 | * required not to free the packet buffer, which will be freed eventually by | |
302 | * the pipeline. | |
303 | * | |
304 | * @param p | |
305 | * Handle to pipeline instance | |
306 | * @param pkts | |
307 | * Burst of input packets specified as array of up to 64 pointers to struct | |
308 | * rte_mbuf | |
309 | * @param pkts_mask | |
310 | * 64-bit bitmask specifying which packets in the input burst are valid. When | |
311 | * pkts_mask bit n is set, then element n of pkts array is pointing to a | |
312 | * valid packet. Otherwise, element n of pkts array will not be accessed. | |
313 | * @param entry | |
314 | * Single table entry associated with all the valid packets from the input | |
315 | * burst, specified as pointer to struct rte_pipeline_table_entry. | |
316 | * This entry is the pipeline table default entry that is associated by the | |
317 | * table lookup operation with the input packets that have resulted in lookup | |
318 | * miss. | |
319 | * @param arg | |
320 | * Opaque parameter registered by the user at the pipeline table creation | |
321 | * time | |
322 | * @return | |
323 | * 0 on success, error code otherwise | |
324 | */ | |
325 | typedef int (*rte_pipeline_table_action_handler_miss)( | |
326 | struct rte_pipeline *p, | |
327 | struct rte_mbuf **pkts, | |
328 | uint64_t pkts_mask, | |
329 | struct rte_pipeline_table_entry *entry, | |
330 | void *arg); | |
331 | ||
332 | /** Parameters for pipeline table creation. Action handlers have to be either | |
333 | both enabled or both disabled (they can be disabled by setting them to | |
334 | NULL). */ | |
335 | struct rte_pipeline_table_params { | |
336 | /** Table operations (specific to each table type) */ | |
337 | struct rte_table_ops *ops; | |
338 | /** Opaque param to be passed to the table create operation when | |
339 | invoked */ | |
340 | void *arg_create; | |
341 | /** Callback function to execute the user actions on input packets in | |
342 | case of lookup hit */ | |
343 | rte_pipeline_table_action_handler_hit f_action_hit; | |
344 | /** Callback function to execute the user actions on input packets in | |
345 | case of lookup miss */ | |
346 | rte_pipeline_table_action_handler_miss f_action_miss; | |
347 | ||
348 | /** Opaque parameter to be passed to lookup hit and/or lookup miss | |
349 | action handlers when invoked */ | |
350 | void *arg_ah; | |
351 | /** Memory size to be reserved per table entry for storing the user | |
352 | actions and their meta-data */ | |
353 | uint32_t action_data_size; | |
354 | }; | |
355 | ||
356 | /** | |
357 | * Pipeline table create | |
358 | * | |
359 | * @param p | |
360 | * Handle to pipeline instance | |
361 | * @param params | |
362 | * Parameters for pipeline table creation | |
363 | * @param table_id | |
364 | * Table ID. Valid only within the scope of table IDs of the current | |
365 | * pipeline. Only returned after a successful invocation. | |
366 | * @return | |
367 | * 0 on success, error code otherwise | |
368 | */ | |
369 | int rte_pipeline_table_create(struct rte_pipeline *p, | |
370 | struct rte_pipeline_table_params *params, | |
371 | uint32_t *table_id); | |
372 | ||
373 | /** | |
374 | * Pipeline table default entry add | |
375 | * | |
376 | * The contents of the table default entry is updated with the provided actions | |
377 | * and meta-data. When the default entry is not configured (by using this | |
378 | * function), the built-in default entry has the action "Drop" and meta-data | |
379 | * set to all-zeros. | |
380 | * | |
381 | * @param p | |
382 | * Handle to pipeline instance | |
383 | * @param table_id | |
384 | * Table ID (returned by previous invocation of pipeline table create) | |
385 | * @param default_entry | |
386 | * New contents for the table default entry | |
387 | * @param default_entry_ptr | |
388 | * On successful invocation, pointer to the default table entry which can be | |
389 | * used for further read-write accesses to this table entry. This pointer | |
390 | * is valid until the default entry is deleted or re-added. | |
391 | * @return | |
392 | * 0 on success, error code otherwise | |
393 | */ | |
394 | int rte_pipeline_table_default_entry_add(struct rte_pipeline *p, | |
395 | uint32_t table_id, | |
396 | struct rte_pipeline_table_entry *default_entry, | |
397 | struct rte_pipeline_table_entry **default_entry_ptr); | |
398 | ||
399 | /** | |
400 | * Pipeline table default entry delete | |
401 | * | |
402 | * The new contents of the table default entry is set to reserved action "Drop | |
403 | * the packet" with meta-data cleared (i.e. set to all-zeros). | |
404 | * | |
405 | * @param p | |
406 | * Handle to pipeline instance | |
407 | * @param table_id | |
408 | * Table ID (returned by previous invocation of pipeline table create) | |
409 | * @param entry | |
410 | * On successful invocation, when entry points to a valid buffer, the | |
411 | * previous contents of the table default entry (as it was just before the | |
412 | * delete operation) is copied to this buffer | |
413 | * @return | |
414 | * 0 on success, error code otherwise | |
415 | */ | |
416 | int rte_pipeline_table_default_entry_delete(struct rte_pipeline *p, | |
417 | uint32_t table_id, | |
418 | struct rte_pipeline_table_entry *entry); | |
419 | ||
420 | /** | |
421 | * Pipeline table entry add | |
422 | * | |
423 | * @param p | |
424 | * Handle to pipeline instance | |
425 | * @param table_id | |
426 | * Table ID (returned by previous invocation of pipeline table create) | |
427 | * @param key | |
428 | * Table entry key | |
429 | * @param entry | |
430 | * New contents for the table entry identified by key | |
431 | * @param key_found | |
432 | * On successful invocation, set to TRUE (value different than 0) if key was | |
433 | * already present in the table before the add operation and to FALSE (value | |
434 | * 0) if not | |
435 | * @param entry_ptr | |
436 | * On successful invocation, pointer to the table entry associated with key. | |
437 | * This can be used for further read-write accesses to this table entry and | |
438 | * is valid until the key is deleted from the table or re-added (usually for | |
439 | * associating different actions and/or action meta-data to the current key) | |
440 | * @return | |
441 | * 0 on success, error code otherwise | |
442 | */ | |
443 | int rte_pipeline_table_entry_add(struct rte_pipeline *p, | |
444 | uint32_t table_id, | |
445 | void *key, | |
446 | struct rte_pipeline_table_entry *entry, | |
447 | int *key_found, | |
448 | struct rte_pipeline_table_entry **entry_ptr); | |
449 | ||
450 | /** | |
451 | * Pipeline table entry delete | |
452 | * | |
453 | * @param p | |
454 | * Handle to pipeline instance | |
455 | * @param table_id | |
456 | * Table ID (returned by previous invocation of pipeline table create) | |
457 | * @param key | |
458 | * Table entry key | |
459 | * @param key_found | |
460 | * On successful invocation, set to TRUE (value different than 0) if key was | |
461 | * found in the table before the delete operation and to FALSE (value 0) if | |
462 | * not | |
463 | * @param entry | |
464 | * On successful invocation, when key is found in the table and entry points | |
465 | * to a valid buffer, the table entry contents (as it was before the delete | |
466 | * was performed) is copied to this buffer | |
467 | * @return | |
468 | * 0 on success, error code otherwise | |
469 | */ | |
470 | int rte_pipeline_table_entry_delete(struct rte_pipeline *p, | |
471 | uint32_t table_id, | |
472 | void *key, | |
473 | int *key_found, | |
474 | struct rte_pipeline_table_entry *entry); | |
475 | ||
476 | /** | |
477 | * Pipeline table entry add bulk | |
478 | * | |
479 | * @param p | |
480 | * Handle to pipeline instance | |
481 | * @param table_id | |
482 | * Table ID (returned by previous invocation of pipeline table create) | |
483 | * @param keys | |
484 | * Array containing table entry keys | |
485 | * @param entries | |
486 | * Array containung new contents for every table entry identified by key | |
487 | * @param n_keys | |
488 | * Number of keys to add | |
489 | * @param key_found | |
490 | * On successful invocation, key_found for every item in the array is set to | |
491 | * TRUE (value different than 0) if key was already present in the table | |
492 | * before the add operation and to FALSE (value 0) if not | |
493 | * @param entries_ptr | |
494 | * On successful invocation, array *entries_ptr stores pointer to every table | |
495 | * entry associated with key. This can be used for further read-write accesses | |
496 | * to this table entry and is valid until the key is deleted from the table or | |
497 | * re-added (usually for associating different actions and/or action meta-data | |
498 | * to the current key) | |
499 | * @return | |
500 | * 0 on success, error code otherwise | |
501 | */ | |
502 | int rte_pipeline_table_entry_add_bulk(struct rte_pipeline *p, | |
503 | uint32_t table_id, | |
504 | void **keys, | |
505 | struct rte_pipeline_table_entry **entries, | |
506 | uint32_t n_keys, | |
507 | int *key_found, | |
508 | struct rte_pipeline_table_entry **entries_ptr); | |
509 | ||
510 | /** | |
511 | * Pipeline table entry delete bulk | |
512 | * | |
513 | * @param p | |
514 | * Handle to pipeline instance | |
515 | * @param table_id | |
516 | * Table ID (returned by previous invocation of pipeline table create) | |
517 | * @param keys | |
518 | * Array containing table entry keys | |
519 | * @param n_keys | |
520 | * Number of keys to delete | |
521 | * @param key_found | |
522 | * On successful invocation, key_found for every item in the array is set to | |
523 | * TRUE (value different than 0) if key was found in the table before the | |
524 | * delete operation and to FALSE (value 0) if not | |
525 | * @param entries | |
526 | * If entries pointer is NULL, this pointer is ignored for every entry found. | |
527 | * Else, after successful invocation, if specific key is found in the table | |
528 | * and entry points to a valid buffer, the table entry contents (as it was | |
529 | * before the delete was performed) is copied to this buffer. | |
530 | * @return | |
531 | * 0 on success, error code otherwise | |
532 | */ | |
533 | int rte_pipeline_table_entry_delete_bulk(struct rte_pipeline *p, | |
534 | uint32_t table_id, | |
535 | void **keys, | |
536 | uint32_t n_keys, | |
537 | int *key_found, | |
538 | struct rte_pipeline_table_entry **entries); | |
539 | ||
540 | /** | |
541 | * Read pipeline table stats. | |
542 | * | |
543 | * This function reads table statistics identified by *table_id* of given | |
544 | * pipeline *p*. | |
545 | * | |
546 | * @param p | |
547 | * Handle to pipeline instance. | |
548 | * @param table_id | |
549 | * Port ID what stats will be returned. | |
550 | * @param stats | |
551 | * Statistics buffer. | |
552 | * @param clear | |
553 | * If not 0 clear stats after reading. | |
554 | * @return | |
555 | * 0 on success, error code otherwise | |
556 | */ | |
557 | int rte_pipeline_table_stats_read(struct rte_pipeline *p, uint32_t table_id, | |
558 | struct rte_pipeline_table_stats *stats, int clear); | |
559 | ||
560 | /* | |
561 | * Port IN | |
562 | * | |
563 | */ | |
564 | /** Maximum number of input ports allowed for any given pipeline instance. The | |
565 | value of this parameter cannot be changed. */ | |
566 | #define RTE_PIPELINE_PORT_IN_MAX 64 | |
567 | ||
568 | /** | |
569 | * Pipeline input port action handler | |
570 | * | |
571 | * The action handler can decide to drop packets by resetting the associated | |
572 | * packet bit in the pkts_mask parameter. In this case, the action handler is | |
573 | * required not to free the packet buffer, which will be freed eventually by | |
574 | * the pipeline. | |
575 | * | |
576 | * @param p | |
577 | * Handle to pipeline instance | |
578 | * @param pkts | |
579 | * Burst of input packets specified as array of up to 64 pointers to struct | |
580 | * rte_mbuf | |
581 | * @param n | |
582 | * Number of packets in the input burst. This parameter specifies that | |
583 | * elements 0 to (n-1) of pkts array are valid. | |
584 | * @param arg | |
585 | * Opaque parameter registered by the user at the pipeline table creation | |
586 | * time | |
587 | * @return | |
588 | * 0 on success, error code otherwise | |
589 | */ | |
590 | typedef int (*rte_pipeline_port_in_action_handler)( | |
591 | struct rte_pipeline *p, | |
592 | struct rte_mbuf **pkts, | |
593 | uint32_t n, | |
594 | void *arg); | |
595 | ||
596 | /** Parameters for pipeline input port creation */ | |
597 | struct rte_pipeline_port_in_params { | |
598 | /** Input port operations (specific to each table type) */ | |
599 | struct rte_port_in_ops *ops; | |
600 | /** Opaque parameter to be passed to create operation when invoked */ | |
601 | void *arg_create; | |
602 | ||
603 | /** Callback function to execute the user actions on input packets. | |
604 | Disabled if set to NULL. */ | |
605 | rte_pipeline_port_in_action_handler f_action; | |
606 | /** Opaque parameter to be passed to the action handler when invoked */ | |
607 | void *arg_ah; | |
608 | ||
609 | /** Recommended burst size for the RX operation(in number of pkts) */ | |
610 | uint32_t burst_size; | |
611 | }; | |
612 | ||
613 | /** | |
614 | * Pipeline input port create | |
615 | * | |
616 | * @param p | |
617 | * Handle to pipeline instance | |
618 | * @param params | |
619 | * Parameters for pipeline input port creation | |
620 | * @param port_id | |
621 | * Input port ID. Valid only within the scope of input port IDs of the | |
622 | * current pipeline. Only returned after a successful invocation. | |
623 | * @return | |
624 | * 0 on success, error code otherwise | |
625 | */ | |
626 | int rte_pipeline_port_in_create(struct rte_pipeline *p, | |
627 | struct rte_pipeline_port_in_params *params, | |
628 | uint32_t *port_id); | |
629 | ||
630 | /** | |
631 | * Pipeline input port connect to table | |
632 | * | |
633 | * @param p | |
634 | * Handle to pipeline instance | |
635 | * @param port_id | |
636 | * Port ID (returned by previous invocation of pipeline input port create) | |
637 | * @param table_id | |
638 | * Table ID (returned by previous invocation of pipeline table create) | |
639 | * @return | |
640 | * 0 on success, error code otherwise | |
641 | */ | |
642 | int rte_pipeline_port_in_connect_to_table(struct rte_pipeline *p, | |
643 | uint32_t port_id, | |
644 | uint32_t table_id); | |
645 | ||
646 | /** | |
647 | * Pipeline input port enable | |
648 | * | |
649 | * @param p | |
650 | * Handle to pipeline instance | |
651 | * @param port_id | |
652 | * Port ID (returned by previous invocation of pipeline input port create) | |
653 | * @return | |
654 | * 0 on success, error code otherwise | |
655 | */ | |
656 | int rte_pipeline_port_in_enable(struct rte_pipeline *p, | |
657 | uint32_t port_id); | |
658 | ||
659 | /** | |
660 | * Pipeline input port disable | |
661 | * | |
662 | * @param p | |
663 | * Handle to pipeline instance | |
664 | * @param port_id | |
665 | * Port ID (returned by previous invocation of pipeline input port create) | |
666 | * @return | |
667 | * 0 on success, error code otherwise | |
668 | */ | |
669 | int rte_pipeline_port_in_disable(struct rte_pipeline *p, | |
670 | uint32_t port_id); | |
671 | ||
672 | /** | |
673 | * Read pipeline port in stats. | |
674 | * | |
675 | * This function reads port in statistics identified by *port_id* of given | |
676 | * pipeline *p*. | |
677 | * | |
678 | * @param p | |
679 | * Handle to pipeline instance. | |
680 | * @param port_id | |
681 | * Port ID what stats will be returned. | |
682 | * @param stats | |
683 | * Statistics buffer. | |
684 | * @param clear | |
685 | * If not 0 clear stats after reading. | |
686 | * @return | |
687 | * 0 on success, error code otherwise | |
688 | */ | |
689 | int rte_pipeline_port_in_stats_read(struct rte_pipeline *p, uint32_t port_id, | |
690 | struct rte_pipeline_port_in_stats *stats, int clear); | |
691 | ||
692 | /* | |
693 | * Port OUT | |
694 | * | |
695 | */ | |
696 | /** Maximum number of output ports allowed for any given pipeline instance. The | |
697 | value of this parameter cannot be changed. */ | |
698 | #define RTE_PIPELINE_PORT_OUT_MAX 64 | |
699 | ||
700 | /** | |
701 | * Pipeline output port action handler | |
702 | * | |
703 | * The action handler can decide to drop packets by resetting the associated | |
704 | * packet bit in the pkts_mask parameter. In this case, the action handler is | |
705 | * required not to free the packet buffer, which will be freed eventually by | |
706 | * the pipeline. | |
707 | * | |
708 | * @param p | |
709 | * Handle to pipeline instance | |
710 | * @param pkts | |
711 | * Burst of input packets specified as array of up to 64 pointers to struct | |
712 | * rte_mbuf | |
713 | * @param pkts_mask | |
714 | * 64-bit bitmask specifying which packets in the input burst are valid. When | |
715 | * pkts_mask bit n is set, then element n of pkts array is pointing to a | |
716 | * valid packet. Otherwise, element n of pkts array will not be accessed. | |
717 | * @param arg | |
718 | * Opaque parameter registered by the user at the pipeline table creation | |
719 | * time | |
720 | * @return | |
721 | * 0 on success, error code otherwise | |
722 | */ | |
723 | typedef int (*rte_pipeline_port_out_action_handler)( | |
724 | struct rte_pipeline *p, | |
725 | struct rte_mbuf **pkts, | |
726 | uint64_t pkts_mask, | |
727 | void *arg); | |
728 | ||
729 | /** Parameters for pipeline output port creation. The action handlers have to | |
730 | be either both enabled or both disabled (by setting them to NULL). When | |
731 | enabled, the pipeline selects between them at different moments, based on the | |
732 | number of packets that have to be sent to the same output port. */ | |
733 | struct rte_pipeline_port_out_params { | |
734 | /** Output port operations (specific to each table type) */ | |
735 | struct rte_port_out_ops *ops; | |
736 | /** Opaque parameter to be passed to create operation when invoked */ | |
737 | void *arg_create; | |
738 | ||
739 | /** Callback function executing the user actions on bust of input | |
740 | packets */ | |
741 | rte_pipeline_port_out_action_handler f_action; | |
742 | /** Opaque parameter to be passed to the action handler when invoked */ | |
743 | void *arg_ah; | |
744 | }; | |
745 | ||
746 | /** | |
747 | * Pipeline output port create | |
748 | * | |
749 | * @param p | |
750 | * Handle to pipeline instance | |
751 | * @param params | |
752 | * Parameters for pipeline output port creation | |
753 | * @param port_id | |
754 | * Output port ID. Valid only within the scope of output port IDs of the | |
755 | * current pipeline. Only returned after a successful invocation. | |
756 | * @return | |
757 | * 0 on success, error code otherwise | |
758 | */ | |
759 | int rte_pipeline_port_out_create(struct rte_pipeline *p, | |
760 | struct rte_pipeline_port_out_params *params, | |
761 | uint32_t *port_id); | |
762 | ||
763 | /** | |
764 | * Read pipeline port out stats. | |
765 | * | |
766 | * This function reads port out statistics identified by *port_id* of given | |
767 | * pipeline *p*. | |
768 | * | |
769 | * @param p | |
770 | * Handle to pipeline instance. | |
771 | * @param port_id | |
772 | * Port ID what stats will be returned. | |
773 | * @param stats | |
774 | * Statistics buffer. | |
775 | * @param clear | |
776 | * If not 0 clear stats after reading. | |
777 | * @return | |
778 | * 0 on success, error code otherwise | |
779 | */ | |
780 | int rte_pipeline_port_out_stats_read(struct rte_pipeline *p, uint32_t port_id, | |
781 | struct rte_pipeline_port_out_stats *stats, int clear); | |
782 | ||
783 | /* | |
784 | * Functions to be called as part of the port IN/OUT or table action handlers | |
785 | * | |
786 | */ | |
787 | /** | |
788 | * Action handler packet insert to output port | |
789 | * | |
790 | * This function can be called by any input/output port or table action handler | |
791 | * to send a packet out through one of the pipeline output ports. This packet is | |
792 | * generated by the action handler, i.e. this packet is not part of the burst of | |
793 | * packets read from one of the pipeline input ports and currently processed by | |
794 | * the pipeline (this packet is not an element of the pkts array input parameter | |
795 | * of the action handler). | |
796 | * | |
797 | * @param p | |
798 | * Handle to pipeline instance | |
799 | * @param port_id | |
800 | * Output port ID (returned by previous invocation of pipeline output port | |
801 | * create) to send the packet specified by pkt | |
802 | * @param pkt | |
803 | * New packet generated by the action handler | |
804 | * @return | |
805 | * 0 on success, error code otherwise | |
806 | */ | |
807 | int rte_pipeline_port_out_packet_insert(struct rte_pipeline *p, | |
808 | uint32_t port_id, | |
809 | struct rte_mbuf *pkt); | |
810 | ||
811 | #define rte_pipeline_ah_port_out_packet_insert \ | |
812 | rte_pipeline_port_out_packet_insert | |
813 | ||
814 | /** | |
815 | * Action handler packet hijack | |
816 | * | |
817 | * This function can be called by any input/output port or table action handler | |
818 | * to hijack selected packets from the burst of packets read from one of the | |
819 | * pipeline input ports and currently processed by the pipeline. The hijacked | |
820 | * packets are removed from any further pipeline processing, with the action | |
821 | * handler now having the full ownership for these packets. | |
822 | * | |
823 | * The action handler can further send the hijacked packets out through any | |
824 | * pipeline output port by calling the rte_pipeline_ah_port_out_packet_insert() | |
825 | * function. The action handler can also drop these packets by calling the | |
826 | * rte_pktmbuf_free() function, although a better alternative is provided by | |
827 | * the action handler using the rte_pipeline_ah_packet_drop() function. | |
828 | * | |
829 | * @param p | |
830 | * Handle to pipeline instance | |
831 | * @param pkts_mask | |
832 | * 64-bit bitmask specifying which of the packets handed over for processing | |
833 | * to the action handler is to be hijacked by the action handler. When | |
834 | * pkts_mask bit n is set, then element n of the pkts array (input argument to | |
835 | * the action handler) is hijacked. | |
836 | * @return | |
837 | * 0 on success, error code otherwise | |
838 | */ | |
839 | int rte_pipeline_ah_packet_hijack(struct rte_pipeline *p, | |
840 | uint64_t pkts_mask); | |
841 | ||
842 | /** | |
843 | * Action handler packet drop | |
844 | * | |
845 | * This function is called by the pipeline action handlers (port in/out, table) | |
846 | * to drop the packets selected using packet mask. | |
847 | * | |
848 | * This function can be called by any input/output port or table action handler | |
849 | * to drop selected packets from the burst of packets read from one of the | |
850 | * pipeline input ports and currently processed by the pipeline. The dropped | |
851 | * packets are removed from any further pipeline processing and the packet | |
852 | * buffers are eventually freed to their buffer pool. | |
853 | * | |
854 | * This function updates the drop statistics counters correctly, therefore the | |
855 | * recommended approach for dropping packets by the action handlers is to call | |
856 | * this function as opposed to the action handler hijacking the packets first | |
857 | * and then dropping them invisibly to the pipeline (by using the | |
858 | * rte_pktmbuf_free() function). | |
859 | * | |
860 | * @param p | |
861 | * Handle to pipeline instance | |
862 | * @param pkts_mask | |
863 | * 64-bit bitmask specifying which of the packets handed over for processing | |
864 | * to the action handler is to be dropped by the action handler. When | |
865 | * pkts_mask bit n is set, then element n of the pkts array (input argument to | |
866 | * the action handler) is dropped. | |
867 | * @return | |
868 | * 0 on success, error code otherwise | |
869 | */ | |
870 | int rte_pipeline_ah_packet_drop(struct rte_pipeline *p, | |
871 | uint64_t pkts_mask); | |
872 | ||
873 | #ifdef __cplusplus | |
874 | } | |
875 | #endif | |
876 | ||
877 | #endif |