1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2018 Intel Corporation 3 */ 4 5 #ifndef __INCLUDE_RTE_PORT_IN_ACTION_H__ 6 #define __INCLUDE_RTE_PORT_IN_ACTION_H__ 7 8 /** 9 * @file 10 * RTE Pipeline Input Port Actions 11 * 12 * This API provides a common set of actions for pipeline input ports to speed 13 * up application development. 14 * 15 * Each pipeline input port can be assigned an action handler to be executed 16 * on every input packet during the pipeline execution. The pipeline library 17 * allows the user to define his own input port actions by providing customized 18 * input port action handler. While the user can still follow this process, this 19 * API is intended to provide a quicker development alternative for a set of 20 * predefined actions. 21 * 22 * The typical steps to use this API are: 23 * - Define an input port action profile. This is a configuration template that 24 * can potentially be shared by multiple input ports from the same or 25 * different pipelines, with different input ports from the same pipeline 26 * able to use different action profiles. For every input port using a given 27 * action profile, the profile defines the set of actions and the action 28 * configuration to be executed by the input port. API functions: 29 * rte_port_in_action_profile_create(), 30 * rte_port_in_action_profile_action_register(), 31 * rte_port_in_action_profile_freeze(). 32 * 33 * - Instantiate the input port action profile to create input port action 34 * objects. Each pipeline input port has its own action object. 35 * API functions: rte_port_in_action_create(). 36 * 37 * - Use the input port action object to generate the input port action handler 38 * invoked by the pipeline. API functions: 39 * rte_port_in_action_params_get(). 40 * 41 * - Use the input port action object to generate the internal data structures 42 * used by the input port action handler based on given action parameters. 43 * API functions: rte_port_in_action_apply(). 44 * 45 * @warning 46 * @b EXPERIMENTAL: this API may change without prior notice 47 */ 48 49 #include <stdint.h> 50 51 #include <rte_compat.h> 52 #include <rte_table_hash.h> 53 54 #include "rte_pipeline.h" 55 56 #ifdef __cplusplus 57 extern "C" { 58 #endif 59 60 /** Input port actions. */ 61 enum rte_port_in_action_type { 62 /** Filter selected input packets. */ 63 RTE_PORT_IN_ACTION_FLTR = 0, 64 65 /** Load balance. */ 66 RTE_PORT_IN_ACTION_LB, 67 }; 68 69 /** 70 * RTE_PORT_IN_ACTION_FLTR 71 */ 72 /** Filter key size (number of bytes) */ 73 #define RTE_PORT_IN_ACTION_FLTR_KEY_SIZE 16 74 75 /** Filter action configuration (per action profile). */ 76 struct rte_port_in_action_fltr_config { 77 /** Key offset within the input packet buffer. Offset 0 points to the 78 * first byte of the MBUF structure. 79 */ 80 uint32_t key_offset; 81 82 /** Key mask. */ 83 uint8_t key_mask[RTE_PORT_IN_ACTION_FLTR_KEY_SIZE]; 84 85 /** Key value. */ 86 uint8_t key[RTE_PORT_IN_ACTION_FLTR_KEY_SIZE]; 87 88 /** When non-zero, all the input packets that match the *key* (with the 89 * *key_mask* applied) are sent to the pipeline output port *port_id*. 90 * When zero, all the input packets that do NOT match the *key* (with 91 * *key_mask* applied) are sent to the pipeline output port *port_id*. 92 */ 93 int filter_on_match; 94 95 /** Pipeline output port ID to send the filtered input packets to. 96 * Can be updated later. 97 * 98 * @see struct rte_port_in_action_fltr_params 99 */ 100 uint32_t port_id; 101 }; 102 103 /** Filter action parameters (per action). */ 104 struct rte_port_in_action_fltr_params { 105 /** Pipeline output port ID to send the filtered input packets to. */ 106 uint32_t port_id; 107 }; 108 109 /** 110 * RTE_PORT_IN_ACTION_LB 111 */ 112 /** Load balance key size min (number of bytes). */ 113 #define RTE_PORT_IN_ACTION_LB_KEY_SIZE_MIN 8 114 115 /** Load balance key size max (number of bytes). */ 116 #define RTE_PORT_IN_ACTION_LB_KEY_SIZE_MAX 64 117 118 /** Load balance table size. */ 119 #define RTE_PORT_IN_ACTION_LB_TABLE_SIZE 16 120 121 /** Load balance action configuration (per action profile). */ 122 struct rte_port_in_action_lb_config { 123 /** Key size (number of bytes). */ 124 uint32_t key_size; 125 126 /** Key offset within the input packet buffer. Offset 0 points to the 127 * first byte of the MBUF structure. 128 */ 129 uint32_t key_offset; 130 131 /** Key mask(*key_size* bytes are valid). */ 132 uint8_t key_mask[RTE_PORT_IN_ACTION_LB_KEY_SIZE_MAX]; 133 134 /** Hash function. */ 135 rte_table_hash_op_hash f_hash; 136 137 /** Seed value for *f_hash*. */ 138 uint64_t seed; 139 140 /** Table defining the weight of each pipeline output port. The weights 141 * are set in 1/RTE_PORT_IN_ACTION_LB_TABLE_SIZE increments. To assign a 142 * weight of N/RTE_PORT_IN_ACTION_LB_TABLE_SIZE to a given output port 143 * (0 <= N <= RTE_PORT_IN_ACTION_LB_TABLE_SIZE), the output port needs 144 * to show up exactly N times in this table. Can be updated later. 145 * 146 * @see struct rte_port_in_action_lb_params 147 */ 148 uint32_t port_id[RTE_PORT_IN_ACTION_LB_TABLE_SIZE]; 149 }; 150 151 /** Load balance action parameters (per action). */ 152 struct rte_port_in_action_lb_params { 153 /** Table defining the weight of each pipeline output port. The weights 154 * are set in 1/RTE_PORT_IN_ACTION_LB_TABLE_SIZE increments. To assign a 155 * weight of N/RTE_PORT_IN_ACTION_LB_TABLE_SIZE to a given output port 156 * (0 <= N <= RTE_PORT_IN_ACTION_LB_TABLE_SIZE), the output port needs 157 * to show up exactly N times in this table. 158 */ 159 uint32_t port_id[RTE_PORT_IN_ACTION_LB_TABLE_SIZE]; 160 }; 161 162 /** 163 * Input port action profile. 164 */ 165 struct rte_port_in_action_profile; 166 167 /** 168 * Input port action profile create. 169 * 170 * @param[in] socket_id 171 * CPU socket ID for the internal data structures memory allocation. 172 * @return 173 * Input port action profile handle on success, NULL otherwise. 174 */ 175 __rte_experimental 176 struct rte_port_in_action_profile * 177 rte_port_in_action_profile_create(uint32_t socket_id); 178 179 /** 180 * Input port action profile free. 181 * 182 * @param[in] profile 183 * Input port action profile handle (needs to be valid). 184 * If profile is NULL, no operation is performed. 185 * @return 186 * Always zero. 187 */ 188 __rte_experimental 189 int 190 rte_port_in_action_profile_free(struct rte_port_in_action_profile *profile); 191 192 /** 193 * Input port action profile action register. 194 * 195 * @param[in] profile 196 * Input port action profile handle (needs to be valid and not in frozen 197 * state). 198 * @param[in] type 199 * Specific input port action to be registered for *profile*. 200 * @param[in] action_config 201 * Configuration for the *type* action. 202 * If struct rte_port_in_action_*type*_config is defined, it needs to point to 203 * a valid instance of this structure, otherwise it needs to be set to NULL. 204 * @return 205 * Zero on success, non-zero error code otherwise. 206 */ 207 __rte_experimental 208 int 209 rte_port_in_action_profile_action_register( 210 struct rte_port_in_action_profile *profile, 211 enum rte_port_in_action_type type, 212 void *action_config); 213 214 /** 215 * Input port action profile freeze. 216 * 217 * Once this function is called successfully, the given profile enters the 218 * frozen state with the following immediate effects: no more actions can be 219 * registered for this profile, so the profile can be instantiated to create 220 * input port action objects. 221 * 222 * @param[in] profile 223 * Input port profile action handle (needs to be valid and not in frozen 224 * state). 225 * @return 226 * Zero on success, non-zero error code otherwise. 227 * 228 * @see rte_port_in_action_create() 229 */ 230 __rte_experimental 231 int 232 rte_port_in_action_profile_freeze(struct rte_port_in_action_profile *profile); 233 234 /** 235 * Input port action. 236 */ 237 struct rte_port_in_action; 238 239 /** 240 * Input port action create. 241 * 242 * Instantiates the given input port action profile to create an input port 243 * action object. 244 * 245 * @param[in] profile 246 * Input port profile action handle (needs to be valid and in frozen state). 247 * @param[in] socket_id 248 * CPU socket ID where the internal data structures required by the new input 249 * port action object should be allocated. 250 * @return 251 * Handle to input port action object on success, NULL on error. 252 */ 253 __rte_experimental 254 struct rte_port_in_action * 255 rte_port_in_action_create(struct rte_port_in_action_profile *profile, 256 uint32_t socket_id); 257 258 /** 259 * Input port action free. 260 * 261 * @param[in] action 262 * Handle to input port action object (needs to be valid). 263 * If action is NULL, no operation is performed. 264 * @return 265 * Always zero. 266 */ 267 __rte_experimental 268 int 269 rte_port_in_action_free(struct rte_port_in_action *action); 270 271 /** 272 * Input port params get. 273 * 274 * @param[in] action 275 * Handle to input port action object (needs to be valid). 276 * @param[inout] params 277 * Pipeline input port parameters (needs to be pre-allocated). 278 * @return 279 * Zero on success, non-zero error code otherwise. 280 */ 281 __rte_experimental 282 int 283 rte_port_in_action_params_get(struct rte_port_in_action *action, 284 struct rte_pipeline_port_in_params *params); 285 286 /** 287 * Input port action apply. 288 * 289 * @param[in] action 290 * Handle to input port action object (needs to be valid). 291 * @param[in] type 292 * Specific input port action previously registered for the input port action 293 * profile of the *action* object. 294 * @param[in] action_params 295 * Parameters for the *type* action. 296 * If struct rte_port_in_action_*type*_params is defined, it needs to point to 297 * a valid instance of this structure, otherwise it needs to be set to NULL. 298 * @return 299 * Zero on success, non-zero error code otherwise. 300 */ 301 __rte_experimental 302 int 303 rte_port_in_action_apply(struct rte_port_in_action *action, 304 enum rte_port_in_action_type type, 305 void *action_params); 306 307 #ifdef __cplusplus 308 } 309 #endif 310 311 #endif /* __INCLUDE_RTE_PORT_IN_ACTION_H__ */ 312