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_meter.h>
64 #include "rte_pipeline.h"
67 enum rte_table_action_type {
68 /** Forward to next pipeline table, output port or drop. */
69 RTE_TABLE_ACTION_FWD = 0,
71 /** Traffic Metering and Policing. */
74 /** Traffic Management. */
78 /** Common action configuration (per table action profile). */
79 struct rte_table_action_common_config {
80 /** Input packet Internet Protocol (IP) version. Non-zero for IPv4, zero
85 /** IP header offset within the input packet buffer. Offset 0 points to
86 * the first byte of the MBUF structure.
92 * RTE_TABLE_ACTION_FWD
94 /** Forward action parameters (per table rule). */
95 struct rte_table_action_fwd_params {
96 /** Forward action. */
97 enum rte_pipeline_action action;
99 /** Pipeline table ID or output port ID. */
104 * RTE_TABLE_ACTION_MTR
106 /** Max number of traffic classes (TCs). */
107 #define RTE_TABLE_ACTION_TC_MAX 4
109 /** Max number of queues per traffic class. */
110 #define RTE_TABLE_ACTION_TC_QUEUE_MAX 4
112 /** Differentiated Services Code Point (DSCP) translation table entry. */
113 struct rte_table_action_dscp_table_entry {
114 /** Traffic class. Used by the meter or the traffic management actions.
115 * Has to be strictly smaller than *RTE_TABLE_ACTION_TC_MAX*. Traffic
116 * class 0 is the highest priority.
120 /** Traffic class queue. Used by the traffic management action. Has to
121 * be strictly smaller than *RTE_TABLE_ACTION_TC_QUEUE_MAX*.
123 uint32_t tc_queue_id;
125 /** Packet color. Used by the meter action as the packet input color
126 * for the color aware mode of the traffic metering algorithm.
128 enum rte_meter_color color;
131 /** DSCP translation table. */
132 struct rte_table_action_dscp_table {
133 /** Array of DSCP table entries */
134 struct rte_table_action_dscp_table_entry entry[64];
137 /** Supported traffic metering algorithms. */
138 enum rte_table_action_meter_algorithm {
139 /** Single Rate Three Color Marker (srTCM) - IETF RFC 2697. */
140 RTE_TABLE_ACTION_METER_SRTCM,
142 /** Two Rate Three Color Marker (trTCM) - IETF RFC 2698. */
143 RTE_TABLE_ACTION_METER_TRTCM,
146 /** Traffic metering profile (configuration template). */
147 struct rte_table_action_meter_profile {
148 /** Traffic metering algorithm. */
149 enum rte_table_action_meter_algorithm alg;
153 /** Only valid when *alg* is set to srTCM - IETF RFC 2697. */
154 struct rte_meter_srtcm_params srtcm;
156 /** Only valid when *alg* is set to trTCM - IETF RFC 2698. */
157 struct rte_meter_trtcm_params trtcm;
161 /** Policer actions. */
162 enum rte_table_action_policer {
163 /** Recolor the packet as green. */
164 RTE_TABLE_ACTION_POLICER_COLOR_GREEN = 0,
166 /** Recolor the packet as yellow. */
167 RTE_TABLE_ACTION_POLICER_COLOR_YELLOW,
169 /** Recolor the packet as red. */
170 RTE_TABLE_ACTION_POLICER_COLOR_RED,
172 /** Drop the packet. */
173 RTE_TABLE_ACTION_POLICER_DROP,
175 /** Number of policer actions. */
176 RTE_TABLE_ACTION_POLICER_MAX
179 /** Meter action configuration per traffic class. */
180 struct rte_table_action_mtr_tc_params {
181 /** Meter profile ID. */
182 uint32_t meter_profile_id;
184 /** Policer actions. */
185 enum rte_table_action_policer policer[e_RTE_METER_COLORS];
188 /** Meter action statistics counters per traffic class. */
189 struct rte_table_action_mtr_counters_tc {
190 /** Number of packets per color at the output of the traffic metering
191 * and before the policer actions are executed. Only valid when
192 * *n_packets_valid* is non-zero.
194 uint64_t n_packets[e_RTE_METER_COLORS];
196 /** Number of packet bytes per color at the output of the traffic
197 * metering and before the policer actions are executed. Only valid when
198 * *n_bytes_valid* is non-zero.
200 uint64_t n_bytes[e_RTE_METER_COLORS];
202 /** When non-zero, the *n_packets* field is valid. */
205 /** When non-zero, the *n_bytes* field is valid. */
209 /** Meter action configuration (per table action profile). */
210 struct rte_table_action_mtr_config {
211 /** Meter algorithm. */
212 enum rte_table_action_meter_algorithm alg;
214 /** Number of traffic classes. Each traffic class has its own traffic
215 * meter and policer instances. Needs to be equal to either 1 or to
216 * *RTE_TABLE_ACTION_TC_MAX*.
220 /** When non-zero, the *n_packets* meter stats counter is enabled,
221 * otherwise it is disabled.
223 * @see struct rte_table_action_mtr_counters_tc
225 int n_packets_enabled;
227 /** When non-zero, the *n_bytes* meter stats counter is enabled,
228 * otherwise it is disabled.
230 * @see struct rte_table_action_mtr_counters_tc
235 /** Meter action parameters (per table rule). */
236 struct rte_table_action_mtr_params {
237 /** Traffic meter and policer parameters for each of the *tc_mask*
240 struct rte_table_action_mtr_tc_params mtr[RTE_TABLE_ACTION_TC_MAX];
242 /** Bit mask defining which traffic class parameters are valid in *mtr*.
243 * If bit N is set in *tc_mask*, then parameters for traffic class N are
249 /** Meter action statistics counters (per table rule). */
250 struct rte_table_action_mtr_counters {
251 /** Stats counters for each of the *tc_mask* traffic classes. */
252 struct rte_table_action_mtr_counters_tc stats[RTE_TABLE_ACTION_TC_MAX];
254 /** Bit mask defining which traffic class parameters are valid in *mtr*.
255 * If bit N is set in *tc_mask*, then parameters for traffic class N are
262 * RTE_TABLE_ACTION_TM
264 /** Traffic management action configuration (per table action profile). */
265 struct rte_table_action_tm_config {
266 /** Number of subports per port. */
267 uint32_t n_subports_per_port;
269 /** Number of pipes per subport. */
270 uint32_t n_pipes_per_subport;
273 /** Traffic management action parameters (per table rule). */
274 struct rte_table_action_tm_params {
283 * Table action profile.
285 struct rte_table_action_profile;
288 * Table action profile create.
291 * Common action configuration.
293 * Table action profile handle on success, NULL otherwise.
295 struct rte_table_action_profile * __rte_experimental
296 rte_table_action_profile_create(struct rte_table_action_common_config *common);
299 * Table action profile free.
302 * Table profile action handle (needs to be valid).
304 * Zero on success, non-zero error code otherwise.
306 int __rte_experimental
307 rte_table_action_profile_free(struct rte_table_action_profile *profile);
310 * Table action profile action register.
313 * Table profile action handle (needs to be valid and not in frozen state).
315 * Specific table action to be registered for *profile*.
316 * @param[in] action_config
317 * Configuration for the *type* action.
318 * If struct rte_table_action_*type*_config is defined by the Table Action
319 * API, it needs to point to a valid instance of this structure, otherwise it
320 * needs to be set to NULL.
322 * Zero on success, non-zero error code otherwise.
324 int __rte_experimental
325 rte_table_action_profile_action_register(struct rte_table_action_profile *profile,
326 enum rte_table_action_type type,
327 void *action_config);
330 * Table action profile freeze.
332 * Once this function is called successfully, the given profile enters the
333 * frozen state with the following immediate effects: no more actions can be
334 * registered for this profile, so the profile can be instantiated to create
335 * table action objects.
338 * Table profile action handle (needs to be valid and not in frozen state).
340 * Zero on success, non-zero error code otherwise.
342 * @see rte_table_action_create()
344 int __rte_experimental
345 rte_table_action_profile_freeze(struct rte_table_action_profile *profile);
350 struct rte_table_action;
353 * Table action create.
355 * Instantiates the given table action profile to create a table action object.
358 * Table profile action handle (needs to be valid and in frozen state).
359 * @param[in] socket_id
360 * CPU socket ID where the internal data structures required by the new table
361 * action object should be allocated.
363 * Handle to table action object on success, NULL on error.
365 * @see rte_table_action_create()
367 struct rte_table_action * __rte_experimental
368 rte_table_action_create(struct rte_table_action_profile *profile,
375 * Handle to table action object (needs to be valid).
377 * Zero on success, non-zero error code otherwise.
379 int __rte_experimental
380 rte_table_action_free(struct rte_table_action *action);
383 * Table action table params get.
386 * Handle to table action object (needs to be valid).
387 * @param[inout] params
388 * Pipeline table parameters (needs to be pre-allocated).
390 * Zero on success, non-zero error code otherwise.
392 int __rte_experimental
393 rte_table_action_table_params_get(struct rte_table_action *action,
394 struct rte_pipeline_table_params *params);
397 * Table action apply.
400 * Handle to table action object (needs to be valid).
402 * Data byte array (typically table rule data) to apply action *type* on.
404 * Specific table action previously registered for the table action profile of
405 * the *action* object.
406 * @param[in] action_params
407 * Parameters for the *type* action.
408 * If struct rte_table_action_*type*_params is defined by the Table Action
409 * API, it needs to point to a valid instance of this structure, otherwise it
410 * needs to be set to NULL.
412 * Zero on success, non-zero error code otherwise.
414 int __rte_experimental
415 rte_table_action_apply(struct rte_table_action *action,
417 enum rte_table_action_type type,
418 void *action_params);
421 * Table action DSCP table update.
424 * Handle to table action object (needs to be valid).
425 * @param[in] dscp_mask
426 * 64-bit mask defining the DSCP table entries to be updated. If bit N is set
427 * in this bit mask, then DSCP table entry N is to be updated, otherwise not.
431 * Zero on success, non-zero error code otherwise.
433 int __rte_experimental
434 rte_table_action_dscp_table_update(struct rte_table_action *action,
436 struct rte_table_action_dscp_table *table);
439 * Table action meter profile add.
442 * Handle to table action object (needs to be valid).
443 * @param[in] meter_profile_id
444 * Meter profile ID to be used for the *profile* once it is successfully added
445 * to the *action* object (needs to be unused by the set of meter profiles
446 * currently registered for the *action* object).
448 * Meter profile to be added.
450 * Zero on success, non-zero error code otherwise.
452 int __rte_experimental
453 rte_table_action_meter_profile_add(struct rte_table_action *action,
454 uint32_t meter_profile_id,
455 struct rte_table_action_meter_profile *profile);
458 * Table action meter profile delete.
461 * Handle to table action object (needs to be valid).
462 * @param[in] meter_profile_id
463 * Meter profile ID of the meter profile to be deleted from the *action*
464 * object (needs to be valid for the *action* object).
466 * Zero on success, non-zero error code otherwise.
468 int __rte_experimental
469 rte_table_action_meter_profile_delete(struct rte_table_action *action,
470 uint32_t meter_profile_id);
473 * Table action meter read.
476 * Handle to table action object (needs to be valid).
478 * Data byte array (typically table rule data) with meter action previously
481 * Bit mask defining which traffic classes should have the meter stats
482 * counters read from *data* and stored into *stats*. If bit N is set in this
483 * bit mask, then traffic class N is part of this operation, otherwise it is
484 * not. If bit N is set in this bit mask, then traffic class N must be one of
485 * the traffic classes that are enabled for the meter action in the table
486 * action profile used by the *action* object.
487 * @param[inout] stats
488 * When non-NULL, it points to the area where the meter stats counters read
489 * from *data* are saved. Only the meter stats counters for the *tc_mask*
490 * traffic classes are read and stored to *stats*.
492 * When non-zero, the meter stats counters are cleared (i.e. set to zero),
493 * otherwise the counters are not modified. When the read operation is enabled
494 * (*stats* is non-NULL), the clear operation is performed after the read
495 * operation is completed.
497 * Zero on success, non-zero error code otherwise.
499 int __rte_experimental
500 rte_table_action_meter_read(struct rte_table_action *action,
503 struct rte_table_action_mtr_counters *stats,
510 #endif /* __INCLUDE_RTE_TABLE_ACTION_H__ */