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 #ifdef __cplusplus 50 extern "C" { 51 #endif 52 53 #include <stdint.h> 54 55 #include <rte_compat.h> 56 #include <rte_table_hash.h> 57 58 #include "rte_pipeline.h" 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 * @return 185 * Zero on success, non-zero error code otherwise. 186 */ 187 __rte_experimental 188 int 189 rte_port_in_action_profile_free(struct rte_port_in_action_profile *profile); 190 191 /** 192 * Input port action profile action register. 193 * 194 * @param[in] profile 195 * Input port action profile handle (needs to be valid and not in frozen 196 * state). 197 * @param[in] type 198 * Specific input port action to be registered for *profile*. 199 * @param[in] action_config 200 * Configuration for the *type* action. 201 * If struct rte_port_in_action_*type*_config is defined, it needs to point to 202 * a valid instance of this structure, otherwise it needs to be set to NULL. 203 * @return 204 * Zero on success, non-zero error code otherwise. 205 */ 206 __rte_experimental 207 int 208 rte_port_in_action_profile_action_register( 209 struct rte_port_in_action_profile *profile, 210 enum rte_port_in_action_type type, 211 void *action_config); 212 213 /** 214 * Input port action profile freeze. 215 * 216 * Once this function is called successfully, the given profile enters the 217 * frozen state with the following immediate effects: no more actions can be 218 * registered for this profile, so the profile can be instantiated to create 219 * input port action objects. 220 * 221 * @param[in] profile 222 * Input port profile action handle (needs to be valid and not in frozen 223 * state). 224 * @return 225 * Zero on success, non-zero error code otherwise. 226 * 227 * @see rte_port_in_action_create() 228 */ 229 __rte_experimental 230 int 231 rte_port_in_action_profile_freeze(struct rte_port_in_action_profile *profile); 232 233 /** 234 * Input port action. 235 */ 236 struct rte_port_in_action; 237 238 /** 239 * Input port action create. 240 * 241 * Instantiates the given input port action profile to create an input port 242 * action object. 243 * 244 * @param[in] profile 245 * Input port profile action handle (needs to be valid and in frozen state). 246 * @param[in] socket_id 247 * CPU socket ID where the internal data structures required by the new input 248 * port action object should be allocated. 249 * @return 250 * Handle to input port action object on success, NULL on error. 251 */ 252 __rte_experimental 253 struct rte_port_in_action * 254 rte_port_in_action_create(struct rte_port_in_action_profile *profile, 255 uint32_t socket_id); 256 257 /** 258 * Input port action free. 259 * 260 * @param[in] action 261 * Handle to input port action object (needs to be valid). 262 * @return 263 * Zero on success, non-zero error code otherwise. 264 */ 265 __rte_experimental 266 int 267 rte_port_in_action_free(struct rte_port_in_action *action); 268 269 /** 270 * Input port params get. 271 * 272 * @param[in] action 273 * Handle to input port action object (needs to be valid). 274 * @param[inout] params 275 * Pipeline input port parameters (needs to be pre-allocated). 276 * @return 277 * Zero on success, non-zero error code otherwise. 278 */ 279 __rte_experimental 280 int 281 rte_port_in_action_params_get(struct rte_port_in_action *action, 282 struct rte_pipeline_port_in_params *params); 283 284 /** 285 * Input port action apply. 286 * 287 * @param[in] action 288 * Handle to input port action object (needs to be valid). 289 * @param[in] type 290 * Specific input port action previously registered for the input port action 291 * profile of the *action* object. 292 * @param[in] action_params 293 * Parameters for the *type* action. 294 * If struct rte_port_in_action_*type*_params is defined, it needs to point to 295 * a valid instance of this structure, otherwise it needs to be set to NULL. 296 * @return 297 * Zero on success, non-zero error code otherwise. 298 */ 299 __rte_experimental 300 int 301 rte_port_in_action_apply(struct rte_port_in_action *action, 302 enum rte_port_in_action_type type, 303 void *action_params); 304 305 #ifdef __cplusplus 306 } 307 #endif 308 309 #endif /* __INCLUDE_RTE_PORT_IN_ACTION_H__ */ 310