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. */
75 /** Common action configuration (per table action profile). */
76 struct rte_table_action_common_config {
77 /** Input packet Internet Protocol (IP) version. Non-zero for IPv4, zero
82 /** IP header offset within the input packet buffer. Offset 0 points to
83 * the first byte of the MBUF structure.
89 * RTE_TABLE_ACTION_FWD
91 /** Forward action parameters (per table rule). */
92 struct rte_table_action_fwd_params {
93 /** Forward action. */
94 enum rte_pipeline_action action;
96 /** Pipeline table ID or output port ID. */
101 * RTE_TABLE_ACTION_MTR
103 /** Max number of traffic classes (TCs). */
104 #define RTE_TABLE_ACTION_TC_MAX 4
106 /** Max number of queues per traffic class. */
107 #define RTE_TABLE_ACTION_TC_QUEUE_MAX 4
109 /** Differentiated Services Code Point (DSCP) translation table entry. */
110 struct rte_table_action_dscp_table_entry {
111 /** Traffic class. Used by the meter or the traffic management actions.
112 * Has to be strictly smaller than *RTE_TABLE_ACTION_TC_MAX*. Traffic
113 * class 0 is the highest priority.
117 /** Traffic class queue. Used by the traffic management action. Has to
118 * be strictly smaller than *RTE_TABLE_ACTION_TC_QUEUE_MAX*.
120 uint32_t tc_queue_id;
122 /** Packet color. Used by the meter action as the packet input color
123 * for the color aware mode of the traffic metering algorithm.
125 enum rte_meter_color color;
128 /** DSCP translation table. */
129 struct rte_table_action_dscp_table {
130 /** Array of DSCP table entries */
131 struct rte_table_action_dscp_table_entry entry[64];
134 /** Supported traffic metering algorithms. */
135 enum rte_table_action_meter_algorithm {
136 /** Single Rate Three Color Marker (srTCM) - IETF RFC 2697. */
137 RTE_TABLE_ACTION_METER_SRTCM,
139 /** Two Rate Three Color Marker (trTCM) - IETF RFC 2698. */
140 RTE_TABLE_ACTION_METER_TRTCM,
143 /** Traffic metering profile (configuration template). */
144 struct rte_table_action_meter_profile {
145 /** Traffic metering algorithm. */
146 enum rte_table_action_meter_algorithm alg;
150 /** Only valid when *alg* is set to srTCM - IETF RFC 2697. */
151 struct rte_meter_srtcm_params srtcm;
153 /** Only valid when *alg* is set to trTCM - IETF RFC 2698. */
154 struct rte_meter_trtcm_params trtcm;
158 /** Policer actions. */
159 enum rte_table_action_policer {
160 /** Recolor the packet as green. */
161 RTE_TABLE_ACTION_POLICER_COLOR_GREEN = 0,
163 /** Recolor the packet as yellow. */
164 RTE_TABLE_ACTION_POLICER_COLOR_YELLOW,
166 /** Recolor the packet as red. */
167 RTE_TABLE_ACTION_POLICER_COLOR_RED,
169 /** Drop the packet. */
170 RTE_TABLE_ACTION_POLICER_DROP,
172 /** Number of policer actions. */
173 RTE_TABLE_ACTION_POLICER_MAX
176 /** Meter action configuration per traffic class. */
177 struct rte_table_action_mtr_tc_params {
178 /** Meter profile ID. */
179 uint32_t meter_profile_id;
181 /** Policer actions. */
182 enum rte_table_action_policer policer[e_RTE_METER_COLORS];
185 /** Meter action statistics counters per traffic class. */
186 struct rte_table_action_mtr_counters_tc {
187 /** Number of packets per color at the output of the traffic metering
188 * and before the policer actions are executed. Only valid when
189 * *n_packets_valid* is non-zero.
191 uint64_t n_packets[e_RTE_METER_COLORS];
193 /** Number of packet bytes per color at the output of the traffic
194 * metering and before the policer actions are executed. Only valid when
195 * *n_bytes_valid* is non-zero.
197 uint64_t n_bytes[e_RTE_METER_COLORS];
199 /** When non-zero, the *n_packets* field is valid. */
202 /** When non-zero, the *n_bytes* field is valid. */
206 /** Meter action configuration (per table action profile). */
207 struct rte_table_action_mtr_config {
208 /** Meter algorithm. */
209 enum rte_table_action_meter_algorithm alg;
211 /** Number of traffic classes. Each traffic class has its own traffic
212 * meter and policer instances. Needs to be equal to either 1 or to
213 * *RTE_TABLE_ACTION_TC_MAX*.
217 /** When non-zero, the *n_packets* meter stats counter is enabled,
218 * otherwise it is disabled.
220 * @see struct rte_table_action_mtr_counters_tc
222 int n_packets_enabled;
224 /** When non-zero, the *n_bytes* meter stats counter is enabled,
225 * otherwise it is disabled.
227 * @see struct rte_table_action_mtr_counters_tc
232 /** Meter action parameters (per table rule). */
233 struct rte_table_action_mtr_params {
234 /** Traffic meter and policer parameters for each of the *tc_mask*
237 struct rte_table_action_mtr_tc_params mtr[RTE_TABLE_ACTION_TC_MAX];
239 /** Bit mask defining which traffic class parameters are valid in *mtr*.
240 * If bit N is set in *tc_mask*, then parameters for traffic class N are
246 /** Meter action statistics counters (per table rule). */
247 struct rte_table_action_mtr_counters {
248 /** Stats counters for each of the *tc_mask* traffic classes. */
249 struct rte_table_action_mtr_counters_tc stats[RTE_TABLE_ACTION_TC_MAX];
251 /** Bit mask defining which traffic class parameters are valid in *mtr*.
252 * If bit N is set in *tc_mask*, then parameters for traffic class N are
259 * Table action profile.
261 struct rte_table_action_profile;
264 * Table action profile create.
267 * Common action configuration.
269 * Table action profile handle on success, NULL otherwise.
271 struct rte_table_action_profile * __rte_experimental
272 rte_table_action_profile_create(struct rte_table_action_common_config *common);
275 * Table action profile free.
278 * Table profile action handle (needs to be valid).
280 * Zero on success, non-zero error code otherwise.
282 int __rte_experimental
283 rte_table_action_profile_free(struct rte_table_action_profile *profile);
286 * Table action profile action register.
289 * Table profile action handle (needs to be valid and not in frozen state).
291 * Specific table action to be registered for *profile*.
292 * @param[in] action_config
293 * Configuration for the *type* action.
294 * If struct rte_table_action_*type*_config is defined by the Table Action
295 * API, it needs to point to a valid instance of this structure, otherwise it
296 * needs to be set to NULL.
298 * Zero on success, non-zero error code otherwise.
300 int __rte_experimental
301 rte_table_action_profile_action_register(struct rte_table_action_profile *profile,
302 enum rte_table_action_type type,
303 void *action_config);
306 * Table action profile freeze.
308 * Once this function is called successfully, the given profile enters the
309 * frozen state with the following immediate effects: no more actions can be
310 * registered for this profile, so the profile can be instantiated to create
311 * table action objects.
314 * Table profile action handle (needs to be valid and not in frozen state).
316 * Zero on success, non-zero error code otherwise.
318 * @see rte_table_action_create()
320 int __rte_experimental
321 rte_table_action_profile_freeze(struct rte_table_action_profile *profile);
326 struct rte_table_action;
329 * Table action create.
331 * Instantiates the given table action profile to create a table action object.
334 * Table profile action handle (needs to be valid and in frozen state).
335 * @param[in] socket_id
336 * CPU socket ID where the internal data structures required by the new table
337 * action object should be allocated.
339 * Handle to table action object on success, NULL on error.
341 * @see rte_table_action_create()
343 struct rte_table_action * __rte_experimental
344 rte_table_action_create(struct rte_table_action_profile *profile,
351 * Handle to table action object (needs to be valid).
353 * Zero on success, non-zero error code otherwise.
355 int __rte_experimental
356 rte_table_action_free(struct rte_table_action *action);
359 * Table action table params get.
362 * Handle to table action object (needs to be valid).
363 * @param[inout] params
364 * Pipeline table parameters (needs to be pre-allocated).
366 * Zero on success, non-zero error code otherwise.
368 int __rte_experimental
369 rte_table_action_table_params_get(struct rte_table_action *action,
370 struct rte_pipeline_table_params *params);
373 * Table action apply.
376 * Handle to table action object (needs to be valid).
378 * Data byte array (typically table rule data) to apply action *type* on.
380 * Specific table action previously registered for the table action profile of
381 * the *action* object.
382 * @param[in] action_params
383 * Parameters for the *type* action.
384 * If struct rte_table_action_*type*_params is defined by the Table Action
385 * API, it needs to point to a valid instance of this structure, otherwise it
386 * needs to be set to NULL.
388 * Zero on success, non-zero error code otherwise.
390 int __rte_experimental
391 rte_table_action_apply(struct rte_table_action *action,
393 enum rte_table_action_type type,
394 void *action_params);
397 * Table action DSCP table update.
400 * Handle to table action object (needs to be valid).
401 * @param[in] dscp_mask
402 * 64-bit mask defining the DSCP table entries to be updated. If bit N is set
403 * in this bit mask, then DSCP table entry N is to be updated, otherwise not.
407 * Zero on success, non-zero error code otherwise.
409 int __rte_experimental
410 rte_table_action_dscp_table_update(struct rte_table_action *action,
412 struct rte_table_action_dscp_table *table);
415 * Table action meter profile add.
418 * Handle to table action object (needs to be valid).
419 * @param[in] meter_profile_id
420 * Meter profile ID to be used for the *profile* once it is successfully added
421 * to the *action* object (needs to be unused by the set of meter profiles
422 * currently registered for the *action* object).
424 * Meter profile to be added.
426 * Zero on success, non-zero error code otherwise.
428 int __rte_experimental
429 rte_table_action_meter_profile_add(struct rte_table_action *action,
430 uint32_t meter_profile_id,
431 struct rte_table_action_meter_profile *profile);
434 * Table action meter profile delete.
437 * Handle to table action object (needs to be valid).
438 * @param[in] meter_profile_id
439 * Meter profile ID of the meter profile to be deleted from the *action*
440 * object (needs to be valid for the *action* object).
442 * Zero on success, non-zero error code otherwise.
444 int __rte_experimental
445 rte_table_action_meter_profile_delete(struct rte_table_action *action,
446 uint32_t meter_profile_id);
449 * Table action meter read.
452 * Handle to table action object (needs to be valid).
454 * Data byte array (typically table rule data) with meter action previously
457 * Bit mask defining which traffic classes should have the meter stats
458 * counters read from *data* and stored into *stats*. If bit N is set in this
459 * bit mask, then traffic class N is part of this operation, otherwise it is
460 * not. If bit N is set in this bit mask, then traffic class N must be one of
461 * the traffic classes that are enabled for the meter action in the table
462 * action profile used by the *action* object.
463 * @param[inout] stats
464 * When non-NULL, it points to the area where the meter stats counters read
465 * from *data* are saved. Only the meter stats counters for the *tc_mask*
466 * traffic classes are read and stored to *stats*.
468 * When non-zero, the meter stats counters are cleared (i.e. set to zero),
469 * otherwise the counters are not modified. When the read operation is enabled
470 * (*stats* is non-NULL), the clear operation is performed after the read
471 * operation is completed.
473 * Zero on success, non-zero error code otherwise.
475 int __rte_experimental
476 rte_table_action_meter_read(struct rte_table_action *action,
479 struct rte_table_action_mtr_counters *stats,
486 #endif /* __INCLUDE_RTE_TABLE_ACTION_H__ */