1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2018 Intel Corporation
5 #ifndef __INCLUDE_RTE_TABLE_ACTION_H__
6 #define __INCLUDE_RTE_TABLE_ACTION_H__
10 * RTE Pipeline Table Actions
12 * This API provides a common set of actions for pipeline tables to speed up
13 * application development.
15 * Each match-action rule added to a pipeline table has associated data that
16 * stores the action context. This data is input to the table action handler
17 * called for every input packet that hits the rule as part of the table lookup
18 * during the pipeline execution. The pipeline library allows the user to define
19 * his own table actions by providing customized table action handlers (table
20 * lookup) and complete freedom of setting the rules and their data (table rule
21 * add/delete). While the user can still follow this process, this API is
22 * intended to provide a quicker development alternative for a set of predefined
25 * The typical steps to use this API are:
26 * - Define a table action profile. This is a configuration template that can
27 * potentially be shared by multiple tables from the same or different
28 * pipelines, with different tables from the same pipeline likely to use
29 * different action profiles. For every table using a given action profile,
30 * the profile defines the set of actions and the action configuration to be
31 * implemented for all the table rules. API functions:
32 * rte_table_action_profile_create(),
33 * rte_table_action_profile_action_register(),
34 * rte_table_action_profile_freeze().
36 * - Instantiate the table action profile to create table action objects. Each
37 * pipeline table has its own table action object. API functions:
38 * rte_table_action_create().
40 * - Use the table action object to generate the pipeline table action handlers
41 * (invoked by the pipeline table lookup operation). API functions:
42 * rte_table_action_table_params_get().
44 * - Use the table action object to generate the rule data (for the pipeline
45 * table rule add operation) based on given action parameters. API functions:
46 * rte_table_action_apply().
48 * - Use the table action object to read action data (e.g. stats counters) for
49 * any given rule. API functions: rte_table_action_XYZ_read().
52 * @b EXPERIMENTAL: this API may change without prior notice
61 #include <rte_compat.h>
62 #include <rte_ether.h>
63 #include <rte_meter.h>
65 #include "rte_pipeline.h"
68 enum rte_table_action_type {
69 /** Forward to next pipeline table, output port or drop. */
70 RTE_TABLE_ACTION_FWD = 0,
72 /** Traffic Metering and Policing. */
75 /** Traffic Management. */
78 /** Packet encapsulations. */
79 RTE_TABLE_ACTION_ENCAP,
81 /** Network Address Translation (NAT). */
84 /** Time to Live (TTL) update. */
88 RTE_TABLE_ACTION_STATS,
91 RTE_TABLE_ACTION_TIME,
94 /** Common action configuration (per table action profile). */
95 struct rte_table_action_common_config {
96 /** Input packet Internet Protocol (IP) version. Non-zero for IPv4, zero
101 /** IP header offset within the input packet buffer. Offset 0 points to
102 * the first byte of the MBUF structure.
108 * RTE_TABLE_ACTION_FWD
110 /** Forward action parameters (per table rule). */
111 struct rte_table_action_fwd_params {
112 /** Forward action. */
113 enum rte_pipeline_action action;
115 /** Pipeline table ID or output port ID. */
120 * RTE_TABLE_ACTION_MTR
122 /** Max number of traffic classes (TCs). */
123 #define RTE_TABLE_ACTION_TC_MAX 4
125 /** Max number of queues per traffic class. */
126 #define RTE_TABLE_ACTION_TC_QUEUE_MAX 4
128 /** Differentiated Services Code Point (DSCP) translation table entry. */
129 struct rte_table_action_dscp_table_entry {
130 /** Traffic class. Used by the meter or the traffic management actions.
131 * Has to be strictly smaller than *RTE_TABLE_ACTION_TC_MAX*. Traffic
132 * class 0 is the highest priority.
136 /** Traffic class queue. Used by the traffic management action. Has to
137 * be strictly smaller than *RTE_TABLE_ACTION_TC_QUEUE_MAX*.
139 uint32_t tc_queue_id;
141 /** Packet color. Used by the meter action as the packet input color
142 * for the color aware mode of the traffic metering algorithm.
144 enum rte_meter_color color;
147 /** DSCP translation table. */
148 struct rte_table_action_dscp_table {
149 /** Array of DSCP table entries */
150 struct rte_table_action_dscp_table_entry entry[64];
153 /** Supported traffic metering algorithms. */
154 enum rte_table_action_meter_algorithm {
155 /** Single Rate Three Color Marker (srTCM) - IETF RFC 2697. */
156 RTE_TABLE_ACTION_METER_SRTCM,
158 /** Two Rate Three Color Marker (trTCM) - IETF RFC 2698. */
159 RTE_TABLE_ACTION_METER_TRTCM,
162 /** Traffic metering profile (configuration template). */
163 struct rte_table_action_meter_profile {
164 /** Traffic metering algorithm. */
165 enum rte_table_action_meter_algorithm alg;
169 /** Only valid when *alg* is set to srTCM - IETF RFC 2697. */
170 struct rte_meter_srtcm_params srtcm;
172 /** Only valid when *alg* is set to trTCM - IETF RFC 2698. */
173 struct rte_meter_trtcm_params trtcm;
177 /** Policer actions. */
178 enum rte_table_action_policer {
179 /** Recolor the packet as green. */
180 RTE_TABLE_ACTION_POLICER_COLOR_GREEN = 0,
182 /** Recolor the packet as yellow. */
183 RTE_TABLE_ACTION_POLICER_COLOR_YELLOW,
185 /** Recolor the packet as red. */
186 RTE_TABLE_ACTION_POLICER_COLOR_RED,
188 /** Drop the packet. */
189 RTE_TABLE_ACTION_POLICER_DROP,
191 /** Number of policer actions. */
192 RTE_TABLE_ACTION_POLICER_MAX
195 /** Meter action configuration per traffic class. */
196 struct rte_table_action_mtr_tc_params {
197 /** Meter profile ID. */
198 uint32_t meter_profile_id;
200 /** Policer actions. */
201 enum rte_table_action_policer policer[e_RTE_METER_COLORS];
204 /** Meter action statistics counters per traffic class. */
205 struct rte_table_action_mtr_counters_tc {
206 /** Number of packets per color at the output of the traffic metering
207 * and before the policer actions are executed. Only valid when
208 * *n_packets_valid* is non-zero.
210 uint64_t n_packets[e_RTE_METER_COLORS];
212 /** Number of packet bytes per color at the output of the traffic
213 * metering and before the policer actions are executed. Only valid when
214 * *n_bytes_valid* is non-zero.
216 uint64_t n_bytes[e_RTE_METER_COLORS];
218 /** When non-zero, the *n_packets* field is valid. */
221 /** When non-zero, the *n_bytes* field is valid. */
225 /** Meter action configuration (per table action profile). */
226 struct rte_table_action_mtr_config {
227 /** Meter algorithm. */
228 enum rte_table_action_meter_algorithm alg;
230 /** Number of traffic classes. Each traffic class has its own traffic
231 * meter and policer instances. Needs to be equal to either 1 or to
232 * *RTE_TABLE_ACTION_TC_MAX*.
236 /** When non-zero, the *n_packets* meter stats counter is enabled,
237 * otherwise it is disabled.
239 * @see struct rte_table_action_mtr_counters_tc
241 int n_packets_enabled;
243 /** When non-zero, the *n_bytes* meter stats counter is enabled,
244 * otherwise it is disabled.
246 * @see struct rte_table_action_mtr_counters_tc
251 /** Meter action parameters (per table rule). */
252 struct rte_table_action_mtr_params {
253 /** Traffic meter and policer parameters for each of the *tc_mask*
256 struct rte_table_action_mtr_tc_params mtr[RTE_TABLE_ACTION_TC_MAX];
258 /** Bit mask defining which traffic class parameters are valid in *mtr*.
259 * If bit N is set in *tc_mask*, then parameters for traffic class N are
265 /** Meter action statistics counters (per table rule). */
266 struct rte_table_action_mtr_counters {
267 /** Stats counters for each of the *tc_mask* traffic classes. */
268 struct rte_table_action_mtr_counters_tc stats[RTE_TABLE_ACTION_TC_MAX];
270 /** Bit mask defining which traffic class parameters are valid in *mtr*.
271 * If bit N is set in *tc_mask*, then parameters for traffic class N are
278 * RTE_TABLE_ACTION_TM
280 /** Traffic management action configuration (per table action profile). */
281 struct rte_table_action_tm_config {
282 /** Number of subports per port. */
283 uint32_t n_subports_per_port;
285 /** Number of pipes per subport. */
286 uint32_t n_pipes_per_subport;
289 /** Traffic management action parameters (per table rule). */
290 struct rte_table_action_tm_params {
299 * RTE_TABLE_ACTION_ENCAP
301 /** Supported packet encapsulation types. */
302 enum rte_table_action_encap_type {
303 /** IP -> { Ether | IP } */
304 RTE_TABLE_ACTION_ENCAP_ETHER = 0,
306 /** IP -> { Ether | VLAN | IP } */
307 RTE_TABLE_ACTION_ENCAP_VLAN,
309 /** IP -> { Ether | S-VLAN | C-VLAN | IP } */
310 RTE_TABLE_ACTION_ENCAP_QINQ,
312 /** IP -> { Ether | MPLS | IP } */
313 RTE_TABLE_ACTION_ENCAP_MPLS,
315 /** IP -> { Ether | PPPoE | PPP | IP } */
316 RTE_TABLE_ACTION_ENCAP_PPPOE,
319 /** Pre-computed Ethernet header fields for encapsulation action. */
320 struct rte_table_action_ether_hdr {
321 struct ether_addr da; /**< Destination address. */
322 struct ether_addr sa; /**< Source address. */
325 /** Pre-computed VLAN header fields for encapsulation action. */
326 struct rte_table_action_vlan_hdr {
327 uint8_t pcp; /**< Priority Code Point (PCP). */
328 uint8_t dei; /**< Drop Eligibility Indicator (DEI). */
329 uint16_t vid; /**< VLAN Identifier (VID). */
332 /** Pre-computed MPLS header fields for encapsulation action. */
333 struct rte_table_action_mpls_hdr {
334 uint32_t label; /**< Label. */
335 uint8_t tc; /**< Traffic Class (TC). */
336 uint8_t ttl; /**< Time to Live (TTL). */
339 /** Pre-computed PPPoE header fields for encapsulation action. */
340 struct rte_table_action_pppoe_hdr {
341 uint16_t session_id; /**< Session ID. */
344 /** Ether encap parameters. */
345 struct rte_table_action_encap_ether_params {
346 struct rte_table_action_ether_hdr ether; /**< Ethernet header. */
349 /** VLAN encap parameters. */
350 struct rte_table_action_encap_vlan_params {
351 struct rte_table_action_ether_hdr ether; /**< Ethernet header. */
352 struct rte_table_action_vlan_hdr vlan; /**< VLAN header. */
355 /** QinQ encap parameters. */
356 struct rte_table_action_encap_qinq_params {
357 struct rte_table_action_ether_hdr ether; /**< Ethernet header. */
358 struct rte_table_action_vlan_hdr svlan; /**< Service VLAN header. */
359 struct rte_table_action_vlan_hdr cvlan; /**< Customer VLAN header. */
362 /** Max number of MPLS labels per output packet for MPLS encapsulation. */
363 #ifndef RTE_TABLE_ACTION_MPLS_LABELS_MAX
364 #define RTE_TABLE_ACTION_MPLS_LABELS_MAX 4
367 /** MPLS encap parameters. */
368 struct rte_table_action_encap_mpls_params {
369 /** Ethernet header. */
370 struct rte_table_action_ether_hdr ether;
373 struct rte_table_action_mpls_hdr mpls[RTE_TABLE_ACTION_MPLS_LABELS_MAX];
375 /** Number of MPLS labels in MPLS header. */
378 /** Non-zero for MPLS unicast, zero for MPLS multicast. */
382 /** PPPoE encap parameters. */
383 struct rte_table_action_encap_pppoe_params {
384 struct rte_table_action_ether_hdr ether; /**< Ethernet header. */
385 struct rte_table_action_pppoe_hdr pppoe; /**< PPPoE/PPP headers. */
388 /** Encap action configuration (per table action profile). */
389 struct rte_table_action_encap_config {
390 /** Bit mask defining the set of packet encapsulations enabled for the
391 * current table action profile. If bit (1 << N) is set in *encap_mask*,
392 * then packet encapsulation N is enabled, otherwise it is disabled.
394 * @see enum rte_table_action_encap_type
399 /** Encap action parameters (per table rule). */
400 struct rte_table_action_encap_params {
401 /** Encapsulation type. */
402 enum rte_table_action_encap_type type;
406 /** Only valid when *type* is set to Ether. */
407 struct rte_table_action_encap_ether_params ether;
409 /** Only valid when *type* is set to VLAN. */
410 struct rte_table_action_encap_vlan_params vlan;
412 /** Only valid when *type* is set to QinQ. */
413 struct rte_table_action_encap_qinq_params qinq;
415 /** Only valid when *type* is set to MPLS. */
416 struct rte_table_action_encap_mpls_params mpls;
418 /** Only valid when *type* is set to PPPoE. */
419 struct rte_table_action_encap_pppoe_params pppoe;
424 * RTE_TABLE_ACTION_NAT
426 /** NAT action configuration (per table action profile). */
427 struct rte_table_action_nat_config {
428 /** When non-zero, the IP source address and L4 protocol source port are
429 * translated. When zero, the IP destination address and L4 protocol
430 * destination port are translated.
434 /** Layer 4 protocol, for example TCP (0x06) or UDP (0x11). The checksum
435 * field is computed differently and placed at different header offset
436 * by each layer 4 protocol.
441 /** NAT action parameters (per table rule). */
442 struct rte_table_action_nat_params {
443 /** IP version for *addr*: non-zero for IPv4, zero for IPv6. */
448 /** IPv4 address; only valid when *ip_version* is non-zero. */
451 /** IPv6 address; only valid when *ip_version* is set to 0. */
460 * RTE_TABLE_ACTION_TTL
462 /** TTL action configuration (per table action profile). */
463 struct rte_table_action_ttl_config {
464 /** When non-zero, the input packets whose updated IPv4 Time to Live
465 * (TTL) field or IPv6 Hop Limit (HL) field is zero are dropped.
466 * When zero, the input packets whose updated IPv4 TTL field or IPv6 HL
467 * field is zero are forwarded as usual (typically for debugging
472 /** When non-zero, the *n_packets* stats counter for TTL action is
473 * enabled, otherwise disabled.
475 * @see struct rte_table_action_ttl_counters
477 int n_packets_enabled;
480 /** TTL action parameters (per table rule). */
481 struct rte_table_action_ttl_params {
482 /** When non-zero, decrement the IPv4 TTL field and update the checksum
483 * field, or decrement the IPv6 HL field. When zero, the IPv4 TTL field
484 * or the IPv6 HL field is not changed.
489 /** TTL action statistics packets (per table rule). */
490 struct rte_table_action_ttl_counters {
491 /** Number of IPv4 packets whose updated TTL field is zero or IPv6
492 * packets whose updated HL field is zero.
498 * RTE_TABLE_ACTION_STATS
500 /** Stats action configuration (per table action profile). */
501 struct rte_table_action_stats_config {
502 /** When non-zero, the *n_packets* stats counter is enabled, otherwise
505 * @see struct rte_table_action_stats_counters
507 int n_packets_enabled;
509 /** When non-zero, the *n_bytes* stats counter is enabled, otherwise
512 * @see struct rte_table_action_stats_counters
517 /** Stats action parameters (per table rule). */
518 struct rte_table_action_stats_params {
519 /** Initial value for the *n_packets* stats counter. Typically set to 0.
521 * @see struct rte_table_action_stats_counters
525 /** Initial value for the *n_bytes* stats counter. Typically set to 0.
527 * @see struct rte_table_action_stats_counters
532 /** Stats action counters (per table rule). */
533 struct rte_table_action_stats_counters {
534 /** Number of packets. Valid only when *n_packets_valid* is non-zero. */
537 /** Number of bytes. Valid only when *n_bytes_valid* is non-zero. */
540 /** When non-zero, the *n_packets* field is valid, otherwise invalid. */
543 /** When non-zero, the *n_bytes* field is valid, otherwise invalid. */
548 * RTE_TABLE_ACTION_TIME
550 /** Timestamp action parameters (per table rule). */
551 struct rte_table_action_time_params {
552 /** Initial timestamp value. Typically set to current time. */
557 * Table action profile.
559 struct rte_table_action_profile;
562 * Table action profile create.
565 * Common action configuration.
567 * Table action profile handle on success, NULL otherwise.
569 struct rte_table_action_profile * __rte_experimental
570 rte_table_action_profile_create(struct rte_table_action_common_config *common);
573 * Table action profile free.
576 * Table profile action handle (needs to be valid).
578 * Zero on success, non-zero error code otherwise.
580 int __rte_experimental
581 rte_table_action_profile_free(struct rte_table_action_profile *profile);
584 * Table action profile action register.
587 * Table profile action handle (needs to be valid and not in frozen state).
589 * Specific table action to be registered for *profile*.
590 * @param[in] action_config
591 * Configuration for the *type* action.
592 * If struct rte_table_action_*type*_config is defined by the Table Action
593 * API, it needs to point to a valid instance of this structure, otherwise it
594 * needs to be set to NULL.
596 * Zero on success, non-zero error code otherwise.
598 int __rte_experimental
599 rte_table_action_profile_action_register(struct rte_table_action_profile *profile,
600 enum rte_table_action_type type,
601 void *action_config);
604 * Table action profile freeze.
606 * Once this function is called successfully, the given profile enters the
607 * frozen state with the following immediate effects: no more actions can be
608 * registered for this profile, so the profile can be instantiated to create
609 * table action objects.
612 * Table profile action handle (needs to be valid and not in frozen state).
614 * Zero on success, non-zero error code otherwise.
616 * @see rte_table_action_create()
618 int __rte_experimental
619 rte_table_action_profile_freeze(struct rte_table_action_profile *profile);
624 struct rte_table_action;
627 * Table action create.
629 * Instantiates the given table action profile to create a table action object.
632 * Table profile action handle (needs to be valid and in frozen state).
633 * @param[in] socket_id
634 * CPU socket ID where the internal data structures required by the new table
635 * action object should be allocated.
637 * Handle to table action object on success, NULL on error.
639 * @see rte_table_action_create()
641 struct rte_table_action * __rte_experimental
642 rte_table_action_create(struct rte_table_action_profile *profile,
649 * Handle to table action object (needs to be valid).
651 * Zero on success, non-zero error code otherwise.
653 int __rte_experimental
654 rte_table_action_free(struct rte_table_action *action);
657 * Table action table params get.
660 * Handle to table action object (needs to be valid).
661 * @param[inout] params
662 * Pipeline table parameters (needs to be pre-allocated).
664 * Zero on success, non-zero error code otherwise.
666 int __rte_experimental
667 rte_table_action_table_params_get(struct rte_table_action *action,
668 struct rte_pipeline_table_params *params);
671 * Table action apply.
674 * Handle to table action object (needs to be valid).
676 * Data byte array (typically table rule data) to apply action *type* on.
678 * Specific table action previously registered for the table action profile of
679 * the *action* object.
680 * @param[in] action_params
681 * Parameters for the *type* action.
682 * If struct rte_table_action_*type*_params is defined by the Table Action
683 * API, it needs to point to a valid instance of this structure, otherwise it
684 * needs to be set to NULL.
686 * Zero on success, non-zero error code otherwise.
688 int __rte_experimental
689 rte_table_action_apply(struct rte_table_action *action,
691 enum rte_table_action_type type,
692 void *action_params);
695 * Table action DSCP table update.
698 * Handle to table action object (needs to be valid).
699 * @param[in] dscp_mask
700 * 64-bit mask defining the DSCP table entries to be updated. If bit N is set
701 * in this bit mask, then DSCP table entry N is to be updated, otherwise not.
705 * Zero on success, non-zero error code otherwise.
707 int __rte_experimental
708 rte_table_action_dscp_table_update(struct rte_table_action *action,
710 struct rte_table_action_dscp_table *table);
713 * Table action meter profile add.
716 * Handle to table action object (needs to be valid).
717 * @param[in] meter_profile_id
718 * Meter profile ID to be used for the *profile* once it is successfully added
719 * to the *action* object (needs to be unused by the set of meter profiles
720 * currently registered for the *action* object).
722 * Meter profile to be added.
724 * Zero on success, non-zero error code otherwise.
726 int __rte_experimental
727 rte_table_action_meter_profile_add(struct rte_table_action *action,
728 uint32_t meter_profile_id,
729 struct rte_table_action_meter_profile *profile);
732 * Table action meter profile delete.
735 * Handle to table action object (needs to be valid).
736 * @param[in] meter_profile_id
737 * Meter profile ID of the meter profile to be deleted from the *action*
738 * object (needs to be valid for the *action* object).
740 * Zero on success, non-zero error code otherwise.
742 int __rte_experimental
743 rte_table_action_meter_profile_delete(struct rte_table_action *action,
744 uint32_t meter_profile_id);
747 * Table action meter read.
750 * Handle to table action object (needs to be valid).
752 * Data byte array (typically table rule data) with meter action previously
755 * Bit mask defining which traffic classes should have the meter stats
756 * counters read from *data* and stored into *stats*. If bit N is set in this
757 * bit mask, then traffic class N is part of this operation, otherwise it is
758 * not. If bit N is set in this bit mask, then traffic class N must be one of
759 * the traffic classes that are enabled for the meter action in the table
760 * action profile used by the *action* object.
761 * @param[inout] stats
762 * When non-NULL, it points to the area where the meter stats counters read
763 * from *data* are saved. Only the meter stats counters for the *tc_mask*
764 * traffic classes are read and stored to *stats*.
766 * When non-zero, the meter stats counters are cleared (i.e. set to zero),
767 * otherwise the counters are not modified. When the read operation is enabled
768 * (*stats* is non-NULL), the clear operation is performed after the read
769 * operation is completed.
771 * Zero on success, non-zero error code otherwise.
773 int __rte_experimental
774 rte_table_action_meter_read(struct rte_table_action *action,
777 struct rte_table_action_mtr_counters *stats,
781 * Table action TTL read.
784 * Handle to table action object (needs to be valid).
786 * Data byte array (typically table rule data) with TTL action previously
788 * @param[inout] stats
789 * When non-NULL, it points to the area where the TTL stats counters read from
792 * When non-zero, the TTL stats counters are cleared (i.e. set to zero),
793 * otherwise the counters are not modified. When the read operation is enabled
794 * (*stats* is non-NULL), the clear operation is performed after the read
795 * operation is completed.
797 * Zero on success, non-zero error code otherwise.
799 int __rte_experimental
800 rte_table_action_ttl_read(struct rte_table_action *action,
802 struct rte_table_action_ttl_counters *stats,
806 * Table action stats read.
809 * Handle to table action object (needs to be valid).
811 * Data byte array (typically table rule data) with stats action previously
813 * @param[inout] stats
814 * When non-NULL, it points to the area where the stats counters read from
817 * When non-zero, the stats counters are cleared (i.e. set to zero), otherwise
818 * the counters are not modified. When the read operation is enabled (*stats*
819 * is non-NULL), the clear operation is performed after the read operation is
822 * Zero on success, non-zero error code otherwise.
824 int __rte_experimental
825 rte_table_action_stats_read(struct rte_table_action *action,
827 struct rte_table_action_stats_counters *stats,
831 * Table action timestamp read.
834 * Handle to table action object (needs to be valid).
836 * Data byte array (typically table rule data) with timestamp action
837 * previously applied on it.
838 * @param[inout] timestamp
839 * Pre-allocated memory where the timestamp read from *data* is saved (has to
842 * Zero on success, non-zero error code otherwise.
844 int __rte_experimental
845 rte_table_action_time_read(struct rte_table_action *action,
847 uint64_t *timestamp);
853 #endif /* __INCLUDE_RTE_TABLE_ACTION_H__ */