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>
63 #include "rte_pipeline.h"
66 enum rte_table_action_type {
67 /** Forward to next pipeline table, output port or drop. */
68 RTE_TABLE_ACTION_FWD = 0,
71 /** Common action configuration (per table action profile). */
72 struct rte_table_action_common_config {
73 /** Input packet Internet Protocol (IP) version. Non-zero for IPv4, zero
78 /** IP header offset within the input packet buffer. Offset 0 points to
79 * the first byte of the MBUF structure.
85 * RTE_TABLE_ACTION_FWD
87 /** Forward action parameters (per table rule). */
88 struct rte_table_action_fwd_params {
89 /** Forward action. */
90 enum rte_pipeline_action action;
92 /** Pipeline table ID or output port ID. */
97 * Table action profile.
99 struct rte_table_action_profile;
102 * Table action profile create.
105 * Common action configuration.
107 * Table action profile handle on success, NULL otherwise.
109 struct rte_table_action_profile * __rte_experimental
110 rte_table_action_profile_create(struct rte_table_action_common_config *common);
113 * Table action profile free.
116 * Table profile action handle (needs to be valid).
118 * Zero on success, non-zero error code otherwise.
120 int __rte_experimental
121 rte_table_action_profile_free(struct rte_table_action_profile *profile);
124 * Table action profile action register.
127 * Table profile action handle (needs to be valid and not in frozen state).
129 * Specific table action to be registered for *profile*.
130 * @param[in] action_config
131 * Configuration for the *type* action.
132 * If struct rte_table_action_*type*_config is defined by the Table Action
133 * API, it needs to point to a valid instance of this structure, otherwise it
134 * needs to be set to NULL.
136 * Zero on success, non-zero error code otherwise.
138 int __rte_experimental
139 rte_table_action_profile_action_register(struct rte_table_action_profile *profile,
140 enum rte_table_action_type type,
141 void *action_config);
144 * Table action profile freeze.
146 * Once this function is called successfully, the given profile enters the
147 * frozen state with the following immediate effects: no more actions can be
148 * registered for this profile, so the profile can be instantiated to create
149 * table action objects.
152 * Table profile action handle (needs to be valid and not in frozen state).
154 * Zero on success, non-zero error code otherwise.
156 * @see rte_table_action_create()
158 int __rte_experimental
159 rte_table_action_profile_freeze(struct rte_table_action_profile *profile);
164 struct rte_table_action;
167 * Table action create.
169 * Instantiates the given table action profile to create a table action object.
172 * Table profile action handle (needs to be valid and in frozen state).
173 * @param[in] socket_id
174 * CPU socket ID where the internal data structures required by the new table
175 * action object should be allocated.
177 * Handle to table action object on success, NULL on error.
179 * @see rte_table_action_create()
181 struct rte_table_action * __rte_experimental
182 rte_table_action_create(struct rte_table_action_profile *profile,
189 * Handle to table action object (needs to be valid).
191 * Zero on success, non-zero error code otherwise.
193 int __rte_experimental
194 rte_table_action_free(struct rte_table_action *action);
197 * Table action apply.
200 * Handle to table action object (needs to be valid).
202 * Data byte array (typically table rule data) to apply action *type* on.
204 * Specific table action previously registered for the table action profile of
205 * the *action* object.
206 * @param[in] action_params
207 * Parameters for the *type* action.
208 * If struct rte_table_action_*type*_params is defined by the Table Action
209 * API, it needs to point to a valid instance of this structure, otherwise it
210 * needs to be set to NULL.
212 * Zero on success, non-zero error code otherwise.
214 int __rte_experimental
215 rte_table_action_apply(struct rte_table_action *action,
217 enum rte_table_action_type type,
218 void *action_params);
224 #endif /* __INCLUDE_RTE_TABLE_ACTION_H__ */