4 * Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
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
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.
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.
34 #ifndef __INCLUDE_RTE_PIPELINE_H__
35 #define __INCLUDE_RTE_PIPELINE_H__
45 * This tool is part of the Intel 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.
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.
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.
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)
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.
89 #include <rte_table.h>
97 /** Opaque data type for pipeline */
100 /** Parameters for pipeline creation */
101 struct rte_pipeline_params {
105 /** CPU socket ID where memory for the pipeline and its elements (ports
106 and tables) should be allocated */
109 /** Offset within packet meta-data to port_id to be used by action
110 "Send packet to output port read from packet meta-data". Has to be
112 uint32_t offset_port_id;
115 /** Pipeline port in stats. */
116 struct rte_pipeline_port_in_stats {
117 /** Port in stats. */
118 struct rte_port_in_stats stats;
120 /** Number of packets dropped by action handler. */
121 uint64_t n_pkts_dropped_by_ah;
125 /** Pipeline port out stats. */
126 struct rte_pipeline_port_out_stats {
127 /** Port out stats. */
128 struct rte_port_out_stats stats;
130 /** Number of packets dropped by action handler. */
131 uint64_t n_pkts_dropped_by_ah;
134 /** Pipeline table stats. */
135 struct rte_pipeline_table_stats {
137 struct rte_table_stats stats;
139 /** Number of packets dropped by lookup hit action handler. */
140 uint64_t n_pkts_dropped_by_lkp_hit_ah;
142 /** Number of packets dropped by lookup miss action handler. */
143 uint64_t n_pkts_dropped_by_lkp_miss_ah;
145 /** Number of packets dropped by pipeline in behalf of this table based on
146 * on action specified in table entry. */
147 uint64_t n_pkts_dropped_lkp_hit;
149 /** Number of packets dropped by pipeline in behalf of this table based on
150 * on action specified in table entry. */
151 uint64_t n_pkts_dropped_lkp_miss;
158 * Parameters for pipeline creation
160 * Handle to pipeline instance on success or NULL otherwise
162 struct rte_pipeline *rte_pipeline_create(struct rte_pipeline_params *params);
168 * Handle to pipeline instance
170 * 0 on success, error code otherwise
172 int rte_pipeline_free(struct rte_pipeline *p);
175 * Pipeline consistency check
178 * Handle to pipeline instance
180 * 0 on success, error code otherwise
182 int rte_pipeline_check(struct rte_pipeline *p);
188 * Handle to pipeline instance
190 * 0 on success, error code otherwise
192 int rte_pipeline_run(struct rte_pipeline *p);
198 * Handle to pipeline instance
200 * 0 on success, error code otherwise
202 int rte_pipeline_flush(struct rte_pipeline *p);
208 /** Reserved actions */
209 enum rte_pipeline_action {
210 /** Drop the packet */
211 RTE_PIPELINE_ACTION_DROP = 0,
213 /** Send packet to output port */
214 RTE_PIPELINE_ACTION_PORT,
216 /** Send packet to output port read from packet meta-data */
217 RTE_PIPELINE_ACTION_PORT_META,
219 /** Send packet to table */
220 RTE_PIPELINE_ACTION_TABLE,
222 /** Number of reserved actions */
230 /** Maximum number of tables allowed for any given pipeline instance. The
231 value of this parameter cannot be changed. */
232 #define RTE_PIPELINE_TABLE_MAX 64
235 * Head format for the table entry of any pipeline table. For any given
236 * pipeline table, all table entries should have the same size and format. For
237 * any given pipeline table, the table entry has to start with a head of this
238 * structure, which contains the reserved actions and their associated
239 * meta-data, and then optionally continues with user actions and their
240 * associated meta-data. As all the currently defined reserved actions are
241 * mutually exclusive, only one reserved action can be set per table entry.
243 struct rte_pipeline_table_entry {
244 /** Reserved action */
245 enum rte_pipeline_action action;
248 /** Output port ID (meta-data for "Send packet to output port"
251 /** Table ID (meta-data for "Send packet to table" action) */
254 /** Start of table entry area for user defined actions and meta-data */
255 uint8_t action_data[0];
259 * Pipeline table action handler on lookup hit
261 * The action handler can decide to drop packets by resetting the associated
262 * packet bit in the pkts_mask parameter. In this case, the action handler is
263 * required not to free the packet buffer, which will be freed eventually by
267 * Burst of input packets specified as array of up to 64 pointers to struct
270 * 64-bit bitmask specifying which packets in the input burst are valid. When
271 * pkts_mask bit n is set, then element n of pkts array is pointing to a
272 * valid packet and element n of entries array is pointing to a valid table
273 * entry associated with the packet, with the association typically done by
274 * the table lookup operation. Otherwise, element n of pkts array and element
275 * n of entries array will not be accessed.
277 * Set of table entries specified as array of up to 64 pointers to struct
278 * rte_pipeline_table_entry
280 * Opaque parameter registered by the user at the pipeline table creation
283 * 0 on success, error code otherwise
285 typedef int (*rte_pipeline_table_action_handler_hit)(
286 struct rte_mbuf **pkts,
288 struct rte_pipeline_table_entry **entries,
292 * Pipeline table action handler on lookup miss
294 * The action handler can decide to drop packets by resetting the associated
295 * packet bit in the pkts_mask parameter. In this case, the action handler is
296 * required not to free the packet buffer, which will be freed eventually by
300 * Burst of input packets specified as array of up to 64 pointers to struct
303 * 64-bit bitmask specifying which packets in the input burst are valid. When
304 * pkts_mask bit n is set, then element n of pkts array is pointing to a
305 * valid packet. Otherwise, element n of pkts array will not be accessed.
307 * Single table entry associated with all the valid packets from the input
308 * burst, specified as pointer to struct rte_pipeline_table_entry.
309 * This entry is the pipeline table default entry that is associated by the
310 * table lookup operation with the input packets that have resulted in lookup
313 * Opaque parameter registered by the user at the pipeline table creation
316 * 0 on success, error code otherwise
318 typedef int (*rte_pipeline_table_action_handler_miss)(
319 struct rte_mbuf **pkts,
321 struct rte_pipeline_table_entry *entry,
324 /** Parameters for pipeline table creation. Action handlers have to be either
325 both enabled or both disabled (they can be disabled by setting them to
327 struct rte_pipeline_table_params {
328 /** Table operations (specific to each table type) */
329 struct rte_table_ops *ops;
330 /** Opaque param to be passed to the table create operation when
333 /** Callback function to execute the user actions on input packets in
334 case of lookup hit */
335 rte_pipeline_table_action_handler_hit f_action_hit;
336 /** Callback function to execute the user actions on input packets in
337 case of lookup miss */
338 rte_pipeline_table_action_handler_miss f_action_miss;
340 /** Opaque parameter to be passed to lookup hit and/or lookup miss
341 action handlers when invoked */
343 /** Memory size to be reserved per table entry for storing the user
344 actions and their meta-data */
345 uint32_t action_data_size;
349 * Pipeline table create
352 * Handle to pipeline instance
354 * Parameters for pipeline table creation
356 * Table ID. Valid only within the scope of table IDs of the current
357 * pipeline. Only returned after a successful invocation.
359 * 0 on success, error code otherwise
361 int rte_pipeline_table_create(struct rte_pipeline *p,
362 struct rte_pipeline_table_params *params,
366 * Pipeline table default entry add
368 * The contents of the table default entry is updated with the provided actions
369 * and meta-data. When the default entry is not configured (by using this
370 * function), the built-in default entry has the action "Drop" and meta-data
374 * Handle to pipeline instance
376 * Table ID (returned by previous invocation of pipeline table create)
377 * @param default_entry
378 * New contents for the table default entry
379 * @param default_entry_ptr
380 * On successful invocation, pointer to the default table entry which can be
381 * used for further read-write accesses to this table entry. This pointer
382 * is valid until the default entry is deleted or re-added.
384 * 0 on success, error code otherwise
386 int rte_pipeline_table_default_entry_add(struct rte_pipeline *p,
388 struct rte_pipeline_table_entry *default_entry,
389 struct rte_pipeline_table_entry **default_entry_ptr);
392 * Pipeline table default entry delete
394 * The new contents of the table default entry is set to reserved action "Drop
395 * the packet" with meta-data cleared (i.e. set to all-zeros).
398 * Handle to pipeline instance
400 * Table ID (returned by previous invocation of pipeline table create)
402 * On successful invocation, when entry points to a valid buffer, the
403 * previous contents of the table default entry (as it was just before the
404 * delete operation) is copied to this buffer
406 * 0 on success, error code otherwise
408 int rte_pipeline_table_default_entry_delete(struct rte_pipeline *p,
410 struct rte_pipeline_table_entry *entry);
413 * Pipeline table entry add
416 * Handle to pipeline instance
418 * Table ID (returned by previous invocation of pipeline table create)
422 * New contents for the table entry identified by key
424 * On successful invocation, set to TRUE (value different than 0) if key was
425 * already present in the table before the add operation and to FALSE (value
428 * On successful invocation, pointer to the table entry associated with key.
429 * This can be used for further read-write accesses to this table entry and
430 * is valid until the key is deleted from the table or re-added (usually for
431 * associating different actions and/or action meta-data to the current key)
433 * 0 on success, error code otherwise
435 int rte_pipeline_table_entry_add(struct rte_pipeline *p,
438 struct rte_pipeline_table_entry *entry,
440 struct rte_pipeline_table_entry **entry_ptr);
443 * Pipeline table entry delete
446 * Handle to pipeline instance
448 * Table ID (returned by previous invocation of pipeline table create)
452 * On successful invocation, set to TRUE (value different than 0) if key was
453 * found in the table before the delete operation and to FALSE (value 0) if
456 * On successful invocation, when key is found in the table and entry points
457 * to a valid buffer, the table entry contents (as it was before the delete
458 * was performed) is copied to this buffer
460 * 0 on success, error code otherwise
462 int rte_pipeline_table_entry_delete(struct rte_pipeline *p,
466 struct rte_pipeline_table_entry *entry);
469 * Read pipeline table stats.
471 * This function reads table statistics identified by *table_id* of given
475 * Handle to pipeline instance.
477 * Port ID what stats will be returned.
481 * If not 0 clear stats after reading.
483 * 0 on success, error code otherwise
485 int rte_pipeline_table_stats_read(struct rte_pipeline *p, uint32_t table_id,
486 struct rte_pipeline_table_stats *stats, int clear);
492 /** Maximum number of input ports allowed for any given pipeline instance. The
493 value of this parameter cannot be changed. */
494 #define RTE_PIPELINE_PORT_IN_MAX 64
497 * Pipeline input port action handler
499 * The action handler can decide to drop packets by resetting the associated
500 * packet bit in the pkts_mask parameter. In this case, the action handler is
501 * required not to free the packet buffer, which will be freed eventually by
505 * Burst of input packets specified as array of up to 64 pointers to struct
508 * Number of packets in the input burst. This parameter specifies that
509 * elements 0 to (n-1) of pkts array are valid.
511 * 64-bit bitmask specifying which packets in the input burst are still valid
512 * after the action handler is executed. When pkts_mask bit n is set, then
513 * element n of pkts array is pointing to a valid packet.
515 * Opaque parameter registered by the user at the pipeline table creation
518 * 0 on success, error code otherwise
520 typedef int (*rte_pipeline_port_in_action_handler)(
521 struct rte_mbuf **pkts,
526 /** Parameters for pipeline input port creation */
527 struct rte_pipeline_port_in_params {
528 /** Input port operations (specific to each table type) */
529 struct rte_port_in_ops *ops;
530 /** Opaque parameter to be passed to create operation when invoked */
533 /** Callback function to execute the user actions on input packets.
534 Disabled if set to NULL. */
535 rte_pipeline_port_in_action_handler f_action;
536 /** Opaque parameter to be passed to the action handler when invoked */
539 /** Recommended burst size for the RX operation(in number of pkts) */
544 * Pipeline input port create
547 * Handle to pipeline instance
549 * Parameters for pipeline input port creation
551 * Input port ID. Valid only within the scope of input port IDs of the
552 * current pipeline. Only returned after a successful invocation.
554 * 0 on success, error code otherwise
556 int rte_pipeline_port_in_create(struct rte_pipeline *p,
557 struct rte_pipeline_port_in_params *params,
561 * Pipeline input port connect to table
564 * Handle to pipeline instance
566 * Port ID (returned by previous invocation of pipeline input port create)
568 * Table ID (returned by previous invocation of pipeline table create)
570 * 0 on success, error code otherwise
572 int rte_pipeline_port_in_connect_to_table(struct rte_pipeline *p,
577 * Pipeline input port enable
580 * Handle to pipeline instance
582 * Port ID (returned by previous invocation of pipeline input port create)
584 * 0 on success, error code otherwise
586 int rte_pipeline_port_in_enable(struct rte_pipeline *p,
590 * Pipeline input port disable
593 * Handle to pipeline instance
595 * Port ID (returned by previous invocation of pipeline input port create)
597 * 0 on success, error code otherwise
599 int rte_pipeline_port_in_disable(struct rte_pipeline *p,
603 * Read pipeline port in stats.
605 * This function reads port in statistics identified by *port_id* of given
609 * Handle to pipeline instance.
611 * Port ID what stats will be returned.
615 * If not 0 clear stats after reading.
617 * 0 on success, error code otherwise
619 int rte_pipeline_port_in_stats_read(struct rte_pipeline *p, uint32_t port_id,
620 struct rte_pipeline_port_in_stats *stats, int clear);
626 /** Maximum number of output ports allowed for any given pipeline instance. The
627 value of this parameter cannot be changed. */
628 #define RTE_PIPELINE_PORT_OUT_MAX 64
631 * Pipeline output port action handler for single packet
633 * The action handler can decide to drop packets by resetting the pkt_mask
634 * argument. In this case, the action handler is required not to free the
635 * packet buffer, which will be freed eventually by the pipeline.
640 * Output argument set to 0 when the action handler decides to drop the input
641 * packet and to 1LLU otherwise
643 * Opaque parameter registered by the user at the pipeline table creation
646 * 0 on success, error code otherwise
648 typedef int (*rte_pipeline_port_out_action_handler)(
649 struct rte_mbuf *pkt,
654 * Pipeline output port action handler bulk
656 * The action handler can decide to drop packets by resetting the associated
657 * packet bit in the pkts_mask parameter. In this case, the action handler is
658 * required not to free the packet buffer, which will be freed eventually by
662 * Burst of input packets specified as array of up to 64 pointers to struct
665 * 64-bit bitmask specifying which packets in the input burst are valid. When
666 * pkts_mask bit n is set, then element n of pkts array is pointing to a
667 * valid packet. Otherwise, element n of pkts array will not be accessed.
669 * Opaque parameter registered by the user at the pipeline table creation
672 * 0 on success, error code otherwise
674 typedef int (*rte_pipeline_port_out_action_handler_bulk)(
675 struct rte_mbuf **pkts,
679 /** Parameters for pipeline output port creation. The action handlers have to
680 be either both enabled or both disabled (by setting them to NULL). When
681 enabled, the pipeline selects between them at different moments, based on the
682 number of packets that have to be sent to the same output port. */
683 struct rte_pipeline_port_out_params {
684 /** Output port operations (specific to each table type) */
685 struct rte_port_out_ops *ops;
686 /** Opaque parameter to be passed to create operation when invoked */
689 /** Callback function executing the user actions on single input
691 rte_pipeline_port_out_action_handler f_action;
692 /** Callback function executing the user actions on bust of input
694 rte_pipeline_port_out_action_handler_bulk f_action_bulk;
695 /** Opaque parameter to be passed to the action handler when invoked */
700 * Pipeline output port create
703 * Handle to pipeline instance
705 * Parameters for pipeline output port creation
707 * Output port ID. Valid only within the scope of output port IDs of the
708 * current pipeline. Only returned after a successful invocation.
710 * 0 on success, error code otherwise
712 int rte_pipeline_port_out_create(struct rte_pipeline *p,
713 struct rte_pipeline_port_out_params *params,
717 * Pipeline output port packet insert
719 * This function is called by the table action handler whenever it generates a
720 * new packet to be sent out though one of the pipeline output ports. This
721 * packet is not part of the burst of input packets read from any of the
722 * pipeline input ports, so it is not an element of the pkts array input
723 * parameter of the table action handler. This packet can be dropped by the
724 * output port action handler.
727 * Handle to pipeline instance
729 * Output port ID (returned by previous invocation of pipeline output port
730 * create) to send the packet specified by pkt
732 * New packet generated by the table action handler
734 * 0 on success, error code otherwise
736 int rte_pipeline_port_out_packet_insert(struct rte_pipeline *p,
738 struct rte_mbuf *pkt);
741 * Read pipeline port out stats.
743 * This function reads port out statistics identified by *port_id* of given
747 * Handle to pipeline instance.
749 * Port ID what stats will be returned.
753 * If not 0 clear stats after reading.
755 * 0 on success, error code otherwise
757 int rte_pipeline_port_out_stats_read(struct rte_pipeline *p, uint32_t port_id,
758 struct rte_pipeline_port_out_stats *stats, int clear);