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;
119 * Parameters for pipeline creation
121 * Handle to pipeline instance on success or NULL otherwise
123 struct rte_pipeline *rte_pipeline_create(struct rte_pipeline_params *params);
129 * Handle to pipeline instance
131 * 0 on success, error code otherwise
133 int rte_pipeline_free(struct rte_pipeline *p);
136 * Pipeline consistency check
139 * Handle to pipeline instance
141 * 0 on success, error code otherwise
143 int rte_pipeline_check(struct rte_pipeline *p);
149 * Handle to pipeline instance
151 * 0 on success, error code otherwise
153 int rte_pipeline_run(struct rte_pipeline *p);
159 * Handle to pipeline instance
161 * 0 on success, error code otherwise
163 int rte_pipeline_flush(struct rte_pipeline *p);
169 /** Reserved actions */
170 enum rte_pipeline_action {
171 /** Drop the packet */
172 RTE_PIPELINE_ACTION_DROP = 0,
174 /** Send packet to output port */
175 RTE_PIPELINE_ACTION_PORT,
177 /** Send packet to output port read from packet meta-data */
178 RTE_PIPELINE_ACTION_PORT_META,
180 /** Send packet to table */
181 RTE_PIPELINE_ACTION_TABLE,
183 /** Number of reserved actions */
191 /** Maximum number of tables allowed for any given pipeline instance. The
192 value of this parameter cannot be changed. */
193 #define RTE_PIPELINE_TABLE_MAX 64
196 * Head format for the table entry of any pipeline table. For any given
197 * pipeline table, all table entries should have the same size and format. For
198 * any given pipeline table, the table entry has to start with a head of this
199 * structure, which contains the reserved actions and their associated
200 * meta-data, and then optionally continues with user actions and their
201 * associated meta-data. As all the currently defined reserved actions are
202 * mutually exclusive, only one reserved action can be set per table entry.
204 struct rte_pipeline_table_entry {
205 /** Reserved action */
206 enum rte_pipeline_action action;
209 /** Output port ID (meta-data for "Send packet to output port"
212 /** Table ID (meta-data for "Send packet to table" action) */
215 /** Start of table entry area for user defined actions and meta-data */
216 uint8_t action_data[0];
220 * Pipeline table action handler on lookup hit
222 * The action handler can decide to drop packets by resetting the associated
223 * packet bit in the pkts_mask parameter. In this case, the action handler is
224 * required not to free the packet buffer, which will be freed eventually by
228 * Burst of input packets specified as array of up to 64 pointers to struct
231 * 64-bit bitmask specifying which packets in the input burst are valid. When
232 * pkts_mask bit n is set, then element n of pkts array is pointing to a
233 * valid packet and element n of entries array is pointing to a valid table
234 * entry associated with the packet, with the association typically done by
235 * the table lookup operation. Otherwise, element n of pkts array and element
236 * n of entries array will not be accessed.
238 * Set of table entries specified as array of up to 64 pointers to struct
239 * rte_pipeline_table_entry
241 * Opaque parameter registered by the user at the pipeline table creation
244 * 0 on success, error code otherwise
246 typedef int (*rte_pipeline_table_action_handler_hit)(
247 struct rte_mbuf **pkts,
249 struct rte_pipeline_table_entry **entries,
253 * Pipeline table action handler on lookup miss
255 * The action handler can decide to drop packets by resetting the associated
256 * packet bit in the pkts_mask parameter. In this case, the action handler is
257 * required not to free the packet buffer, which will be freed eventually by
261 * Burst of input packets specified as array of up to 64 pointers to struct
264 * 64-bit bitmask specifying which packets in the input burst are valid. When
265 * pkts_mask bit n is set, then element n of pkts array is pointing to a
266 * valid packet. Otherwise, element n of pkts array will not be accessed.
268 * Single table entry associated with all the valid packets from the input
269 * burst, specified as pointer to struct rte_pipeline_table_entry.
270 * This entry is the pipeline table default entry that is associated by the
271 * table lookup operation with the input packets that have resulted in lookup
274 * Opaque parameter registered by the user at the pipeline table creation
277 * 0 on success, error code otherwise
279 typedef int (*rte_pipeline_table_action_handler_miss)(
280 struct rte_mbuf **pkts,
282 struct rte_pipeline_table_entry *entry,
285 /** Parameters for pipeline table creation. Action handlers have to be either
286 both enabled or both disabled (they can be disabled by setting them to
288 struct rte_pipeline_table_params {
289 /** Table operations (specific to each table type) */
290 struct rte_table_ops *ops;
291 /** Opaque param to be passed to the table create operation when
294 /** Callback function to execute the user actions on input packets in
295 case of lookup hit */
296 rte_pipeline_table_action_handler_hit f_action_hit;
297 /** Callback function to execute the user actions on input packets in
298 case of lookup miss */
299 rte_pipeline_table_action_handler_miss f_action_miss;
301 /** Opaque parameter to be passed to lookup hit and/or lookup miss
302 action handlers when invoked */
304 /** Memory size to be reserved per table entry for storing the user
305 actions and their meta-data */
306 uint32_t action_data_size;
310 * Pipeline table create
313 * Handle to pipeline instance
315 * Parameters for pipeline table creation
317 * Table ID. Valid only within the scope of table IDs of the current
318 * pipeline. Only returned after a successful invocation.
320 * 0 on success, error code otherwise
322 int rte_pipeline_table_create(struct rte_pipeline *p,
323 struct rte_pipeline_table_params *params,
327 * Pipeline table default entry add
329 * The contents of the table default entry is updated with the provided actions
330 * and meta-data. When the default entry is not configured (by using this
331 * function), the built-in default entry has the action "Drop" and meta-data
335 * Handle to pipeline instance
337 * Table ID (returned by previous invocation of pipeline table create)
338 * @param default_entry
339 * New contents for the table default entry
340 * @param default_entry_ptr
341 * On successful invocation, pointer to the default table entry which can be
342 * used for further read-write accesses to this table entry. This pointer
343 * is valid until the default entry is deleted or re-added.
345 * 0 on success, error code otherwise
347 int rte_pipeline_table_default_entry_add(struct rte_pipeline *p,
349 struct rte_pipeline_table_entry *default_entry,
350 struct rte_pipeline_table_entry **default_entry_ptr);
353 * Pipeline table default entry delete
355 * The new contents of the table default entry is set to reserved action "Drop
356 * the packet" with meta-data cleared (i.e. set to all-zeros).
359 * Handle to pipeline instance
361 * Table ID (returned by previous invocation of pipeline table create)
363 * On successful invocation, when entry points to a valid buffer, the
364 * previous contents of the table default entry (as it was just before the
365 * delete operation) is copied to this buffer
367 * 0 on success, error code otherwise
369 int rte_pipeline_table_default_entry_delete(struct rte_pipeline *p,
371 struct rte_pipeline_table_entry *entry);
374 * Pipeline table entry add
377 * Handle to pipeline instance
379 * Table ID (returned by previous invocation of pipeline table create)
383 * New contents for the table entry identified by key
385 * On successful invocation, set to TRUE (value different than 0) if key was
386 * already present in the table before the add operation and to FALSE (value
389 * On successful invocation, pointer to the table entry associated with key.
390 * This can be used for further read-write accesses to this table entry and
391 * is valid until the key is deleted from the table or re-added (usually for
392 * associating different actions and/or action meta-data to the current key)
394 * 0 on success, error code otherwise
396 int rte_pipeline_table_entry_add(struct rte_pipeline *p,
399 struct rte_pipeline_table_entry *entry,
401 struct rte_pipeline_table_entry **entry_ptr);
404 * Pipeline table entry delete
407 * Handle to pipeline instance
409 * Table ID (returned by previous invocation of pipeline table create)
413 * On successful invocation, set to TRUE (value different than 0) if key was
414 * found in the table before the delete operation and to FALSE (value 0) if
417 * On successful invocation, when key is found in the table and entry points
418 * to a valid buffer, the table entry contents (as it was before the delete
419 * was performed) is copied to this buffer
421 * 0 on success, error code otherwise
423 int rte_pipeline_table_entry_delete(struct rte_pipeline *p,
427 struct rte_pipeline_table_entry *entry);
433 /** Maximum number of input ports allowed for any given pipeline instance. The
434 value of this parameter cannot be changed. */
435 #define RTE_PIPELINE_PORT_IN_MAX 64
438 * Pipeline input port action handler
440 * The action handler can decide to drop packets by resetting the associated
441 * packet bit in the pkts_mask parameter. In this case, the action handler is
442 * required not to free the packet buffer, which will be freed eventually by
446 * Burst of input packets specified as array of up to 64 pointers to struct
449 * Number of packets in the input burst. This parameter specifies that
450 * elements 0 to (n-1) of pkts array are valid.
452 * 64-bit bitmask specifying which packets in the input burst are still valid
453 * after the action handler is executed. When pkts_mask bit n is set, then
454 * element n of pkts array is pointing to a valid packet.
456 * Opaque parameter registered by the user at the pipeline table creation
459 * 0 on success, error code otherwise
461 typedef int (*rte_pipeline_port_in_action_handler)(
462 struct rte_mbuf **pkts,
467 /** Parameters for pipeline input port creation */
468 struct rte_pipeline_port_in_params {
469 /** Input port operations (specific to each table type) */
470 struct rte_port_in_ops *ops;
471 /** Opaque parameter to be passed to create operation when invoked */
474 /** Callback function to execute the user actions on input packets.
475 Disabled if set to NULL. */
476 rte_pipeline_port_in_action_handler f_action;
477 /** Opaque parameter to be passed to the action handler when invoked */
480 /** Recommended burst size for the RX operation(in number of pkts) */
485 * Pipeline input port create
488 * Handle to pipeline instance
490 * Parameters for pipeline input port creation
492 * Input port ID. Valid only within the scope of input port IDs of the
493 * current pipeline. Only returned after a successful invocation.
495 * 0 on success, error code otherwise
497 int rte_pipeline_port_in_create(struct rte_pipeline *p,
498 struct rte_pipeline_port_in_params *params,
502 * Pipeline input port connect to table
505 * Handle to pipeline instance
507 * Port ID (returned by previous invocation of pipeline input port create)
509 * Table ID (returned by previous invocation of pipeline table create)
511 * 0 on success, error code otherwise
513 int rte_pipeline_port_in_connect_to_table(struct rte_pipeline *p,
518 * Pipeline input port enable
521 * Handle to pipeline instance
523 * Port ID (returned by previous invocation of pipeline input port create)
525 * 0 on success, error code otherwise
527 int rte_pipeline_port_in_enable(struct rte_pipeline *p,
531 * Pipeline input port disable
534 * Handle to pipeline instance
536 * Port ID (returned by previous invocation of pipeline input port create)
538 * 0 on success, error code otherwise
540 int rte_pipeline_port_in_disable(struct rte_pipeline *p,
547 /** Maximum number of output ports allowed for any given pipeline instance. The
548 value of this parameter cannot be changed. */
549 #define RTE_PIPELINE_PORT_OUT_MAX 64
552 * Pipeline output port action handler for single packet
554 * The action handler can decide to drop packets by resetting the pkt_mask
555 * argument. In this case, the action handler is required not to free the
556 * packet buffer, which will be freed eventually by the pipeline.
561 * Output argument set to 0 when the action handler decides to drop the input
562 * packet and to 1LLU otherwise
564 * Opaque parameter registered by the user at the pipeline table creation
567 * 0 on success, error code otherwise
569 typedef int (*rte_pipeline_port_out_action_handler)(
570 struct rte_mbuf *pkt,
575 * Pipeline output port action handler bulk
577 * The action handler can decide to drop packets by resetting the associated
578 * packet bit in the pkts_mask parameter. In this case, the action handler is
579 * required not to free the packet buffer, which will be freed eventually by
583 * Burst of input packets specified as array of up to 64 pointers to struct
586 * 64-bit bitmask specifying which packets in the input burst are valid. When
587 * pkts_mask bit n is set, then element n of pkts array is pointing to a
588 * valid packet. Otherwise, element n of pkts array will not be accessed.
590 * Opaque parameter registered by the user at the pipeline table creation
593 * 0 on success, error code otherwise
595 typedef int (*rte_pipeline_port_out_action_handler_bulk)(
596 struct rte_mbuf **pkts,
600 /** Parameters for pipeline output port creation. The action handlers have to
601 be either both enabled or both disabled (by setting them to NULL). When
602 enabled, the pipeline selects between them at different moments, based on the
603 number of packets that have to be sent to the same output port. */
604 struct rte_pipeline_port_out_params {
605 /** Output port operations (specific to each table type) */
606 struct rte_port_out_ops *ops;
607 /** Opaque parameter to be passed to create operation when invoked */
610 /** Callback function executing the user actions on single input
612 rte_pipeline_port_out_action_handler f_action;
613 /** Callback function executing the user actions on bust of input
615 rte_pipeline_port_out_action_handler_bulk f_action_bulk;
616 /** Opaque parameter to be passed to the action handler when invoked */
621 * Pipeline output port create
624 * Handle to pipeline instance
626 * Parameters for pipeline output port creation
628 * Output port ID. Valid only within the scope of output port IDs of the
629 * current pipeline. Only returned after a successful invocation.
631 * 0 on success, error code otherwise
633 int rte_pipeline_port_out_create(struct rte_pipeline *p,
634 struct rte_pipeline_port_out_params *params,
638 * Pipeline output port packet insert
640 * This function is called by the table action handler whenever it generates a
641 * new packet to be sent out though one of the pipeline output ports. This
642 * packet is not part of the burst of input packets read from any of the
643 * pipeline input ports, so it is not an element of the pkts array input
644 * parameter of the table action handler. This packet can be dropped by the
645 * output port action handler.
648 * Handle to pipeline instance
650 * Output port ID (returned by previous invocation of pipeline output port
651 * create) to send the packet specified by pkt
653 * New packet generated by the table action handler
655 * 0 on success, error code otherwise
657 int rte_pipeline_port_out_packet_insert(struct rte_pipeline *p,
659 struct rte_mbuf *pkt);