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.
90 #include <rte_table.h>
96 /** Opaque data type for pipeline */
99 /** Parameters for pipeline creation */
100 struct rte_pipeline_params {
104 /** CPU socket ID where memory for the pipeline and its elements (ports
105 and tables) should be allocated */
108 /** Offset within packet meta-data to port_id to be used by action
109 "Send packet to output port read from packet meta-data". Has to be
111 uint32_t offset_port_id;
118 * Parameters for pipeline creation
120 * Handle to pipeline instance on success or NULL otherwise
122 struct rte_pipeline *rte_pipeline_create(struct rte_pipeline_params *params);
128 * Handle to pipeline instance
130 * 0 on success, error code otherwise
132 int rte_pipeline_free(struct rte_pipeline *p);
135 * Pipeline consistency check
138 * Handle to pipeline instance
140 * 0 on success, error code otherwise
142 int rte_pipeline_check(struct rte_pipeline *p);
148 * Handle to pipeline instance
150 * 0 on success, error code otherwise
152 int rte_pipeline_run(struct rte_pipeline *p);
158 * Handle to pipeline instance
160 * 0 on success, error code otherwise
162 int rte_pipeline_flush(struct rte_pipeline *p);
168 /** Reserved actions */
169 enum rte_pipeline_action {
170 /** Drop the packet */
171 RTE_PIPELINE_ACTION_DROP = 0,
173 /** Send packet to output port */
174 RTE_PIPELINE_ACTION_PORT,
176 /** Send packet to output port read from packet meta-data */
177 RTE_PIPELINE_ACTION_PORT_META,
179 /** Send packet to table */
180 RTE_PIPELINE_ACTION_TABLE,
182 /** Number of reserved actions */
190 /** Maximum number of tables allowed for any given pipeline instance. The
191 value of this parameter cannot be changed. */
192 #define RTE_PIPELINE_TABLE_MAX 64
195 * Head format for the table entry of any pipeline table. For any given
196 * pipeline table, all table entries should have the same size and format. For
197 * any given pipeline table, the table entry has to start with a head of this
198 * structure, which contains the reserved actions and their associated
199 * meta-data, and then optionally continues with user actions and their
200 * associated meta-data. As all the currently defined reserved actions are
201 * mutually exclusive, only one reserved action can be set per table entry.
203 struct rte_pipeline_table_entry {
204 /** Reserved action */
205 enum rte_pipeline_action action;
208 /** Output port ID (meta-data for "Send packet to output port"
211 /** Table ID (meta-data for "Send packet to table" action) */
214 /** Start of table entry area for user defined actions and meta-data */
215 uint8_t action_data[0];
219 * Pipeline table action handler on lookup hit
221 * The action handler can decide to drop packets by resetting the associated
222 * packet bit in the pkts_mask parameter. In this case, the action handler is
223 * required not to free the packet buffer, which will be freed eventually by
227 * Burst of input packets specified as array of up to 64 pointers to struct
230 * 64-bit bitmask specifying which packets in the input burst are valid. When
231 * pkts_mask bit n is set, then element n of pkts array is pointing to a
232 * valid packet and element n of entries array is pointing to a valid table
233 * entry associated with the packet, with the association typically done by
234 * the table lookup operation. Otherwise, element n of pkts array and element
235 * n of entries array will not be accessed.
237 * Set of table entries specified as array of up to 64 pointers to struct
238 * rte_pipeline_table_entry
240 * Opaque parameter registered by the user at the pipeline table creation
243 * 0 on success, error code otherwise
245 typedef int (*rte_pipeline_table_action_handler_hit)(
246 struct rte_mbuf **pkts,
248 struct rte_pipeline_table_entry **entries,
252 * Pipeline table action handler on lookup miss
254 * The action handler can decide to drop packets by resetting the associated
255 * packet bit in the pkts_mask parameter. In this case, the action handler is
256 * required not to free the packet buffer, which will be freed eventually by
260 * Burst of input packets specified as array of up to 64 pointers to struct
263 * 64-bit bitmask specifying which packets in the input burst are valid. When
264 * pkts_mask bit n is set, then element n of pkts array is pointing to a
265 * valid packet. Otherwise, element n of pkts array will not be accessed.
267 * Single table entry associated with all the valid packets from the input
268 * burst, specified as pointer to struct rte_pipeline_table_entry.
269 * This entry is the pipeline table default entry that is associated by the
270 * table lookup operation with the input packets that have resulted in lookup
273 * Opaque parameter registered by the user at the pipeline table creation
276 * 0 on success, error code otherwise
278 typedef int (*rte_pipeline_table_action_handler_miss)(
279 struct rte_mbuf **pkts,
281 struct rte_pipeline_table_entry *entry,
284 /** Parameters for pipeline table creation. Action handlers have to be either
285 both enabled or both disabled (they can be disabled by setting them to
287 struct rte_pipeline_table_params {
288 /** Table operations (specific to each table type) */
289 struct rte_table_ops *ops;
290 /** Opaque param to be passed to the table create operation when
293 /** Callback function to execute the user actions on input packets in
294 case of lookup hit */
295 rte_pipeline_table_action_handler_hit f_action_hit;
296 /** Callback function to execute the user actions on input packets in
297 case of lookup miss */
298 rte_pipeline_table_action_handler_miss f_action_miss;
300 /** Opaque parameter to be passed to lookup hit and/or lookup miss
301 action handlers when invoked */
303 /** Memory size to be reserved per table entry for storing the user
304 actions and their meta-data */
305 uint32_t action_data_size;
309 * Pipeline table create
312 * Handle to pipeline instance
314 * Parameters for pipeline table creation
316 * Table ID. Valid only within the scope of table IDs of the current
317 * pipeline. Only returned after a successful invocation.
319 * 0 on success, error code otherwise
321 int rte_pipeline_table_create(struct rte_pipeline *p,
322 struct rte_pipeline_table_params *params,
326 * Pipeline table default entry add
328 * The contents of the table default entry is updated with the provided actions
329 * and meta-data. When the default entry is not configured (by using this
330 * function), the built-in default entry has the action "Drop" and meta-data
334 * Handle to pipeline instance
336 * Table ID (returned by previous invocation of pipeline table create)
337 * @param default_entry
338 * New contents for the table default entry
339 * @param default_entry_ptr
340 * On successful invocation, pointer to the default table entry which can be
341 * used for further read-write accesses to this table entry. This pointer
342 * is valid until the default entry is deleted or re-added.
344 * 0 on success, error code otherwise
346 int rte_pipeline_table_default_entry_add(struct rte_pipeline *p,
348 struct rte_pipeline_table_entry *default_entry,
349 struct rte_pipeline_table_entry **default_entry_ptr);
352 * Pipeline table default entry delete
354 * The new contents of the table default entry is set to reserved action "Drop
355 * the packet" with meta-data cleared (i.e. set to all-zeros).
358 * Handle to pipeline instance
360 * Table ID (returned by previous invocation of pipeline table create)
362 * On successful invocation, when entry points to a valid buffer, the
363 * previous contents of the table default entry (as it was just before the
364 * delete operation) is copied to this buffer
366 * 0 on success, error code otherwise
368 int rte_pipeline_table_default_entry_delete(struct rte_pipeline *p,
370 struct rte_pipeline_table_entry *entry);
373 * Pipeline table entry add
376 * Handle to pipeline instance
378 * Table ID (returned by previous invocation of pipeline table create)
382 * New contents for the table entry identified by key
384 * On successful invocation, set to TRUE (value different than 0) if key was
385 * already present in the table before the add operation and to FALSE (value
388 * On successful invocation, pointer to the table entry associated with key.
389 * This can be used for further read-write accesses to this table entry and
390 * is valid until the key is deleted from the table or re-added (usually for
391 * associating different actions and/or action meta-data to the current key)
393 * 0 on success, error code otherwise
395 int rte_pipeline_table_entry_add(struct rte_pipeline *p,
398 struct rte_pipeline_table_entry *entry,
400 struct rte_pipeline_table_entry **entry_ptr);
403 * Pipeline table entry delete
406 * Handle to pipeline instance
408 * Table ID (returned by previous invocation of pipeline table create)
412 * On successful invocation, set to TRUE (value different than 0) if key was
413 * found in the table before the delete operation and to FALSE (value 0) if
416 * On successful invocation, when key is found in the table and entry points
417 * to a valid buffer, the table entry contents (as it was before the delete
418 * was performed) is copied to this buffer
420 * 0 on success, error code otherwise
422 int rte_pipeline_table_entry_delete(struct rte_pipeline *p,
426 struct rte_pipeline_table_entry *entry);
432 /** Maximum number of input ports allowed for any given pipeline instance. The
433 value of this parameter cannot be changed. */
434 #define RTE_PIPELINE_PORT_IN_MAX 64
437 * Pipeline input port action handler
439 * The action handler can decide to drop packets by resetting the associated
440 * packet bit in the pkts_mask parameter. In this case, the action handler is
441 * required not to free the packet buffer, which will be freed eventually by
445 * Burst of input packets specified as array of up to 64 pointers to struct
448 * Number of packets in the input burst. This parameter specifies that
449 * elements 0 to (n-1) of pkts array are valid.
451 * 64-bit bitmask specifying which packets in the input burst are still valid
452 * after the action handler is executed. When pkts_mask bit n is set, then
453 * element n of pkts array is pointing to a valid packet.
455 * Opaque parameter registered by the user at the pipeline table creation
458 * 0 on success, error code otherwise
460 typedef int (*rte_pipeline_port_in_action_handler)(
461 struct rte_mbuf **pkts,
466 /** Parameters for pipeline input port creation */
467 struct rte_pipeline_port_in_params {
468 /** Input port operations (specific to each table type) */
469 struct rte_port_in_ops *ops;
470 /** Opaque parameter to be passed to create operation when invoked */
473 /** Callback function to execute the user actions on input packets.
474 Disabled if set to NULL. */
475 rte_pipeline_port_in_action_handler f_action;
476 /** Opaque parameter to be passed to the action handler when invoked */
479 /** Recommended burst size for the RX operation(in number of pkts) */
484 * Pipeline input port create
487 * Handle to pipeline instance
489 * Parameters for pipeline input port creation
491 * Input port ID. Valid only within the scope of input port IDs of the
492 * current pipeline. Only returned after a successful invocation.
494 * 0 on success, error code otherwise
496 int rte_pipeline_port_in_create(struct rte_pipeline *p,
497 struct rte_pipeline_port_in_params *params,
501 * Pipeline input port connect to table
504 * Handle to pipeline instance
506 * Port ID (returned by previous invocation of pipeline input port create)
508 * Table ID (returned by previous invocation of pipeline table create)
510 * 0 on success, error code otherwise
512 int rte_pipeline_port_in_connect_to_table(struct rte_pipeline *p,
517 * Pipeline input port enable
520 * Handle to pipeline instance
522 * Port ID (returned by previous invocation of pipeline input port create)
524 * 0 on success, error code otherwise
526 int rte_pipeline_port_in_enable(struct rte_pipeline *p,
530 * Pipeline input port disable
533 * Handle to pipeline instance
535 * Port ID (returned by previous invocation of pipeline input port create)
537 * 0 on success, error code otherwise
539 int rte_pipeline_port_in_disable(struct rte_pipeline *p,
546 /** Maximum number of output ports allowed for any given pipeline instance. The
547 value of this parameter cannot be changed. */
548 #define RTE_PIPELINE_PORT_OUT_MAX 64
551 * Pipeline output port action handler for single packet
553 * The action handler can decide to drop packets by resetting the pkt_mask
554 * argument. In this case, the action handler is required not to free the
555 * packet buffer, which will be freed eventually by the pipeline.
560 * Output argument set to 0 when the action handler decides to drop the input
561 * packet and to 1LLU otherwise
563 * Opaque parameter registered by the user at the pipeline table creation
566 * 0 on success, error code otherwise
568 typedef int (*rte_pipeline_port_out_action_handler)(
569 struct rte_mbuf *pkt,
574 * Pipeline output port action handler bulk
576 * The action handler can decide to drop packets by resetting the associated
577 * packet bit in the pkts_mask parameter. In this case, the action handler is
578 * required not to free the packet buffer, which will be freed eventually by
582 * Burst of input packets specified as array of up to 64 pointers to struct
585 * 64-bit bitmask specifying which packets in the input burst are valid. When
586 * pkts_mask bit n is set, then element n of pkts array is pointing to a
587 * valid packet. Otherwise, element n of pkts array will not be accessed.
589 * Opaque parameter registered by the user at the pipeline table creation
592 * 0 on success, error code otherwise
594 typedef int (*rte_pipeline_port_out_action_handler_bulk)(
595 struct rte_mbuf **pkts,
599 /** Parameters for pipeline output port creation. The action handlers have to
600 be either both enabled or both disabled (by setting them to NULL). When
601 enabled, the pipeline selects between them at different moments, based on the
602 number of packets that have to be sent to the same output port. */
603 struct rte_pipeline_port_out_params {
604 /** Output port operations (specific to each table type) */
605 struct rte_port_out_ops *ops;
606 /** Opaque parameter to be passed to create operation when invoked */
609 /** Callback function executing the user actions on single input
611 rte_pipeline_port_out_action_handler f_action;
612 /** Callback function executing the user actions on bust of input
614 rte_pipeline_port_out_action_handler_bulk f_action_bulk;
615 /** Opaque parameter to be passed to the action handler when invoked */
620 * Pipeline output port create
623 * Handle to pipeline instance
625 * Parameters for pipeline output port creation
627 * Output port ID. Valid only within the scope of output port IDs of the
628 * current pipeline. Only returned after a successful invocation.
630 * 0 on success, error code otherwise
632 int rte_pipeline_port_out_create(struct rte_pipeline *p,
633 struct rte_pipeline_port_out_params *params,
637 * Pipeline output port packet insert
639 * This function is called by the table action handler whenever it generates a
640 * new packet to be sent out though one of the pipeline output ports. This
641 * packet is not part of the burst of input packets read from any of the
642 * pipeline input ports, so it is not an element of the pkts array input
643 * parameter of the table action handler. This packet can be dropped by the
644 * output port action handler.
647 * Handle to pipeline instance
649 * Output port ID (returned by previous invocation of pipeline output port
650 * create) to send the packet specified by pkt
652 * New packet generated by the table action handler
654 * 0 on success, error code otherwise
656 int rte_pipeline_port_out_packet_insert(struct rte_pipeline *p,
658 struct rte_mbuf *pkt);