lib/pipeline/rte_port_in_action.h

   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__ */