4 * Copyright(c) 2010-2016 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 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
146 * table based 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
150 * table based 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 * Number of packets read and processed
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 * Handle to pipeline instance
269 * Burst of input packets specified as array of up to 64 pointers to struct
272 * 64-bit bitmask specifying which packets in the input burst are valid. When
273 * pkts_mask bit n is set, then element n of pkts array is pointing to a
274 * valid packet and element n of entries array is pointing to a valid table
275 * entry associated with the packet, with the association typically done by
276 * the table lookup operation. Otherwise, element n of pkts array and element
277 * n of entries array will not be accessed.
279 * Set of table entries specified as array of up to 64 pointers to struct
280 * rte_pipeline_table_entry
282 * Opaque parameter registered by the user at the pipeline table creation
285 * 0 on success, error code otherwise
287 typedef int (*rte_pipeline_table_action_handler_hit)(
288 struct rte_pipeline *p,
289 struct rte_mbuf **pkts,
291 struct rte_pipeline_table_entry **entries,
295 * Pipeline table action handler on lookup miss
297 * The action handler can decide to drop packets by resetting the associated
298 * packet bit in the pkts_mask parameter. In this case, the action handler is
299 * required not to free the packet buffer, which will be freed eventually by
303 * Handle to pipeline instance
305 * Burst of input packets specified as array of up to 64 pointers to struct
308 * 64-bit bitmask specifying which packets in the input burst are valid. When
309 * pkts_mask bit n is set, then element n of pkts array is pointing to a
310 * valid packet. Otherwise, element n of pkts array will not be accessed.
312 * Single table entry associated with all the valid packets from the input
313 * burst, specified as pointer to struct rte_pipeline_table_entry.
314 * This entry is the pipeline table default entry that is associated by the
315 * table lookup operation with the input packets that have resulted in lookup
318 * Opaque parameter registered by the user at the pipeline table creation
321 * 0 on success, error code otherwise
323 typedef int (*rte_pipeline_table_action_handler_miss)(
324 struct rte_pipeline *p,
325 struct rte_mbuf **pkts,
327 struct rte_pipeline_table_entry *entry,
330 /** Parameters for pipeline table creation. Action handlers have to be either
331 both enabled or both disabled (they can be disabled by setting them to
333 struct rte_pipeline_table_params {
334 /** Table operations (specific to each table type) */
335 struct rte_table_ops *ops;
336 /** Opaque param to be passed to the table create operation when
339 /** Callback function to execute the user actions on input packets in
340 case of lookup hit */
341 rte_pipeline_table_action_handler_hit f_action_hit;
342 /** Callback function to execute the user actions on input packets in
343 case of lookup miss */
344 rte_pipeline_table_action_handler_miss f_action_miss;
346 /** Opaque parameter to be passed to lookup hit and/or lookup miss
347 action handlers when invoked */
349 /** Memory size to be reserved per table entry for storing the user
350 actions and their meta-data */
351 uint32_t action_data_size;
355 * Pipeline table create
358 * Handle to pipeline instance
360 * Parameters for pipeline table creation
362 * Table ID. Valid only within the scope of table IDs of the current
363 * pipeline. Only returned after a successful invocation.
365 * 0 on success, error code otherwise
367 int rte_pipeline_table_create(struct rte_pipeline *p,
368 struct rte_pipeline_table_params *params,
372 * Pipeline table default entry add
374 * The contents of the table default entry is updated with the provided actions
375 * and meta-data. When the default entry is not configured (by using this
376 * function), the built-in default entry has the action "Drop" and meta-data
380 * Handle to pipeline instance
382 * Table ID (returned by previous invocation of pipeline table create)
383 * @param default_entry
384 * New contents for the table default entry
385 * @param default_entry_ptr
386 * On successful invocation, pointer to the default table entry which can be
387 * used for further read-write accesses to this table entry. This pointer
388 * is valid until the default entry is deleted or re-added.
390 * 0 on success, error code otherwise
392 int rte_pipeline_table_default_entry_add(struct rte_pipeline *p,
394 struct rte_pipeline_table_entry *default_entry,
395 struct rte_pipeline_table_entry **default_entry_ptr);
398 * Pipeline table default entry delete
400 * The new contents of the table default entry is set to reserved action "Drop
401 * the packet" with meta-data cleared (i.e. set to all-zeros).
404 * Handle to pipeline instance
406 * Table ID (returned by previous invocation of pipeline table create)
408 * On successful invocation, when entry points to a valid buffer, the
409 * previous contents of the table default entry (as it was just before the
410 * delete operation) is copied to this buffer
412 * 0 on success, error code otherwise
414 int rte_pipeline_table_default_entry_delete(struct rte_pipeline *p,
416 struct rte_pipeline_table_entry *entry);
419 * Pipeline table entry add
422 * Handle to pipeline instance
424 * Table ID (returned by previous invocation of pipeline table create)
428 * New contents for the table entry identified by key
430 * On successful invocation, set to TRUE (value different than 0) if key was
431 * already present in the table before the add operation and to FALSE (value
434 * On successful invocation, pointer to the table entry associated with key.
435 * This can be used for further read-write accesses to this table entry and
436 * is valid until the key is deleted from the table or re-added (usually for
437 * associating different actions and/or action meta-data to the current key)
439 * 0 on success, error code otherwise
441 int rte_pipeline_table_entry_add(struct rte_pipeline *p,
444 struct rte_pipeline_table_entry *entry,
446 struct rte_pipeline_table_entry **entry_ptr);
449 * Pipeline table entry delete
452 * Handle to pipeline instance
454 * Table ID (returned by previous invocation of pipeline table create)
458 * On successful invocation, set to TRUE (value different than 0) if key was
459 * found in the table before the delete operation and to FALSE (value 0) if
462 * On successful invocation, when key is found in the table and entry points
463 * to a valid buffer, the table entry contents (as it was before the delete
464 * was performed) is copied to this buffer
466 * 0 on success, error code otherwise
468 int rte_pipeline_table_entry_delete(struct rte_pipeline *p,
472 struct rte_pipeline_table_entry *entry);
475 * Pipeline table entry add bulk
478 * Handle to pipeline instance
480 * Table ID (returned by previous invocation of pipeline table create)
482 * Array containing table entry keys
484 * Array containung new contents for every table entry identified by key
486 * Number of keys to add
488 * On successful invocation, key_found for every item in the array is set to
489 * TRUE (value different than 0) if key was already present in the table
490 * before the add operation and to FALSE (value 0) if not
492 * On successful invocation, array *entries_ptr stores pointer to every table
493 * entry associated with key. This can be used for further read-write accesses
494 * to this table entry and is valid until the key is deleted from the table or
495 * re-added (usually for associating different actions and/or action meta-data
496 * to the current key)
498 * 0 on success, error code otherwise
500 int rte_pipeline_table_entry_add_bulk(struct rte_pipeline *p,
503 struct rte_pipeline_table_entry **entries,
506 struct rte_pipeline_table_entry **entries_ptr);
509 * Pipeline table entry delete bulk
512 * Handle to pipeline instance
514 * Table ID (returned by previous invocation of pipeline table create)
516 * Array containing table entry keys
518 * Number of keys to delete
520 * On successful invocation, key_found for every item in the array is set to
521 * TRUE (value different than 0) if key was found in the table before the
522 * delete operation and to FALSE (value 0) if not
524 * If entries pointer is NULL, this pointer is ignored for every entry found.
525 * Else, after successful invocation, if specific key is found in the table
526 * and entry points to a valid buffer, the table entry contents (as it was
527 * before the delete was performed) is copied to this buffer.
529 * 0 on success, error code otherwise
531 int rte_pipeline_table_entry_delete_bulk(struct rte_pipeline *p,
536 struct rte_pipeline_table_entry **entries);
539 * Read pipeline table stats.
541 * This function reads table statistics identified by *table_id* of given
545 * Handle to pipeline instance.
547 * Port ID what stats will be returned.
551 * If not 0 clear stats after reading.
553 * 0 on success, error code otherwise
555 int rte_pipeline_table_stats_read(struct rte_pipeline *p, uint32_t table_id,
556 struct rte_pipeline_table_stats *stats, int clear);
562 /** Maximum number of input ports allowed for any given pipeline instance. The
563 value of this parameter cannot be changed. */
564 #define RTE_PIPELINE_PORT_IN_MAX 64
567 * Pipeline input port action handler
569 * The action handler can decide to drop packets by resetting the associated
570 * packet bit in the pkts_mask parameter. In this case, the action handler is
571 * required not to free the packet buffer, which will be freed eventually by
575 * Handle to pipeline instance
577 * Burst of input packets specified as array of up to 64 pointers to struct
580 * Number of packets in the input burst. This parameter specifies that
581 * elements 0 to (n-1) of pkts array are valid.
583 * Opaque parameter registered by the user at the pipeline table creation
586 * 0 on success, error code otherwise
588 typedef int (*rte_pipeline_port_in_action_handler)(
589 struct rte_pipeline *p,
590 struct rte_mbuf **pkts,
594 /** Parameters for pipeline input port creation */
595 struct rte_pipeline_port_in_params {
596 /** Input port operations (specific to each table type) */
597 struct rte_port_in_ops *ops;
598 /** Opaque parameter to be passed to create operation when invoked */
601 /** Callback function to execute the user actions on input packets.
602 Disabled if set to NULL. */
603 rte_pipeline_port_in_action_handler f_action;
604 /** Opaque parameter to be passed to the action handler when invoked */
607 /** Recommended burst size for the RX operation(in number of pkts) */
612 * Pipeline input port create
615 * Handle to pipeline instance
617 * Parameters for pipeline input port creation
619 * Input port ID. Valid only within the scope of input port IDs of the
620 * current pipeline. Only returned after a successful invocation.
622 * 0 on success, error code otherwise
624 int rte_pipeline_port_in_create(struct rte_pipeline *p,
625 struct rte_pipeline_port_in_params *params,
629 * Pipeline input port connect to table
632 * Handle to pipeline instance
634 * Port ID (returned by previous invocation of pipeline input port create)
636 * Table ID (returned by previous invocation of pipeline table create)
638 * 0 on success, error code otherwise
640 int rte_pipeline_port_in_connect_to_table(struct rte_pipeline *p,
645 * Pipeline input port enable
648 * Handle to pipeline instance
650 * Port ID (returned by previous invocation of pipeline input port create)
652 * 0 on success, error code otherwise
654 int rte_pipeline_port_in_enable(struct rte_pipeline *p,
658 * Pipeline input port disable
661 * Handle to pipeline instance
663 * Port ID (returned by previous invocation of pipeline input port create)
665 * 0 on success, error code otherwise
667 int rte_pipeline_port_in_disable(struct rte_pipeline *p,
671 * Read pipeline port in stats.
673 * This function reads port in statistics identified by *port_id* of given
677 * Handle to pipeline instance.
679 * Port ID what stats will be returned.
683 * If not 0 clear stats after reading.
685 * 0 on success, error code otherwise
687 int rte_pipeline_port_in_stats_read(struct rte_pipeline *p, uint32_t port_id,
688 struct rte_pipeline_port_in_stats *stats, int clear);
694 /** Maximum number of output ports allowed for any given pipeline instance. The
695 value of this parameter cannot be changed. */
696 #define RTE_PIPELINE_PORT_OUT_MAX 64
699 * Pipeline output port action handler
701 * The action handler can decide to drop packets by resetting the associated
702 * packet bit in the pkts_mask parameter. In this case, the action handler is
703 * required not to free the packet buffer, which will be freed eventually by
707 * Handle to pipeline instance
709 * Burst of input packets specified as array of up to 64 pointers to struct
712 * 64-bit bitmask specifying which packets in the input burst are valid. When
713 * pkts_mask bit n is set, then element n of pkts array is pointing to a
714 * valid packet. Otherwise, element n of pkts array will not be accessed.
716 * Opaque parameter registered by the user at the pipeline table creation
719 * 0 on success, error code otherwise
721 typedef int (*rte_pipeline_port_out_action_handler)(
722 struct rte_pipeline *p,
723 struct rte_mbuf **pkts,
727 /** Parameters for pipeline output port creation. The action handlers have to
728 be either both enabled or both disabled (by setting them to NULL). When
729 enabled, the pipeline selects between them at different moments, based on the
730 number of packets that have to be sent to the same output port. */
731 struct rte_pipeline_port_out_params {
732 /** Output port operations (specific to each table type) */
733 struct rte_port_out_ops *ops;
734 /** Opaque parameter to be passed to create operation when invoked */
737 /** Callback function executing the user actions on bust of input
739 rte_pipeline_port_out_action_handler f_action;
740 /** Opaque parameter to be passed to the action handler when invoked */
745 * Pipeline output port create
748 * Handle to pipeline instance
750 * Parameters for pipeline output port creation
752 * Output port ID. Valid only within the scope of output port IDs of the
753 * current pipeline. Only returned after a successful invocation.
755 * 0 on success, error code otherwise
757 int rte_pipeline_port_out_create(struct rte_pipeline *p,
758 struct rte_pipeline_port_out_params *params,
762 * Read pipeline port out stats.
764 * This function reads port out statistics identified by *port_id* of given
768 * Handle to pipeline instance.
770 * Port ID what stats will be returned.
774 * If not 0 clear stats after reading.
776 * 0 on success, error code otherwise
778 int rte_pipeline_port_out_stats_read(struct rte_pipeline *p, uint32_t port_id,
779 struct rte_pipeline_port_out_stats *stats, int clear);
782 * Functions to be called as part of the port IN/OUT or table action handlers
786 * Action handler packet insert to output port
788 * This function can be called by any input/output port or table action handler
789 * to send a packet out through one of the pipeline output ports. This packet is
790 * generated by the action handler, i.e. this packet is not part of the burst of
791 * packets read from one of the pipeline input ports and currently processed by
792 * the pipeline (this packet is not an element of the pkts array input parameter
793 * of the action handler).
796 * Handle to pipeline instance
798 * Output port ID (returned by previous invocation of pipeline output port
799 * create) to send the packet specified by pkt
801 * New packet generated by the action handler
803 * 0 on success, error code otherwise
805 int rte_pipeline_port_out_packet_insert(struct rte_pipeline *p,
807 struct rte_mbuf *pkt);
809 #define rte_pipeline_ah_port_out_packet_insert \
810 rte_pipeline_port_out_packet_insert
813 * Action handler packet hijack
815 * This function can be called by any input/output port or table action handler
816 * to hijack selected packets from the burst of packets read from one of the
817 * pipeline input ports and currently processed by the pipeline. The hijacked
818 * packets are removed from any further pipeline processing, with the action
819 * handler now having the full ownership for these packets.
821 * The action handler can further send the hijacked packets out through any
822 * pipeline output port by calling the rte_pipeline_ah_port_out_packet_insert()
823 * function. The action handler can also drop these packets by calling the
824 * rte_pktmbuf_free() function, although a better alternative is provided by
825 * the action handler using the rte_pipeline_ah_packet_drop() function.
828 * Handle to pipeline instance
830 * 64-bit bitmask specifying which of the packets handed over for processing
831 * to the action handler is to be hijacked by the action handler. When
832 * pkts_mask bit n is set, then element n of the pkts array (input argument to
833 * the action handler) is hijacked.
835 * 0 on success, error code otherwise
837 int rte_pipeline_ah_packet_hijack(struct rte_pipeline *p,
841 * Action handler packet drop
843 * This function is called by the pipeline action handlers (port in/out, table)
844 * to drop the packets selected using packet mask.
846 * This function can be called by any input/output port or table action handler
847 * to drop selected packets from the burst of packets read from one of the
848 * pipeline input ports and currently processed by the pipeline. The dropped
849 * packets are removed from any further pipeline processing and the packet
850 * buffers are eventually freed to their buffer pool.
852 * This function updates the drop statistics counters correctly, therefore the
853 * recommended approach for dropping packets by the action handlers is to call
854 * this function as opposed to the action handler hijacking the packets first
855 * and then dropping them invisibly to the pipeline (by using the
856 * rte_pktmbuf_free() function).
859 * Handle to pipeline instance
861 * 64-bit bitmask specifying which of the packets handed over for processing
862 * to the action handler is to be dropped by the action handler. When
863 * pkts_mask bit n is set, then element n of the pkts array (input argument to
864 * the action handler) is dropped.
866 * 0 on success, error code otherwise
868 int rte_pipeline_ah_packet_drop(struct rte_pipeline *p,