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