lib/librte_pipeline/rte_table_action.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2018 Intel Corporation
   3  */
   4
   5 #ifndef __INCLUDE_RTE_TABLE_ACTION_H__
   6 #define __INCLUDE_RTE_TABLE_ACTION_H__
   7
   8 /**
   9  * @file
  10  * RTE Pipeline Table Actions
  11  *
  12  * This API provides a common set of actions for pipeline tables to speed up
  13  * application development.
  14  *
  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
  23  * actions.
  24  *
  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().
  35  *
  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().
  39  *
  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().
  43  *
  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().
  47  *
  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().
  50  *
  51  * @warning
  52  * @b EXPERIMENTAL: this API may change without prior notice
  53  */
  54
  55 #ifdef __cplusplus
  56 extern "C" {
  57 #endif
  58
  59 #include <stdint.h>
  60
  61 #include <rte_compat.h>
  62
  63 #include "rte_pipeline.h"
  64
  65 /** Table actions. */
  66 enum rte_table_action_type {
  67         /** Forward to next pipeline table, output port or drop. */
  68         RTE_TABLE_ACTION_FWD = 0,
  69 };
  70
  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
  74          * for IPv6.
  75          */
  76         int ip_version;
  77
  78         /** IP header offset within the input packet buffer. Offset 0 points to
  79          * the first byte of the MBUF structure.
  80          */
  81         uint32_t ip_offset;
  82 };
  83
  84 /**
  85  * RTE_TABLE_ACTION_FWD
  86  */
  87 /** Forward action parameters (per table rule). */
  88 struct rte_table_action_fwd_params {
  89         /** Forward action. */
  90         enum rte_pipeline_action action;
  91
  92         /** Pipeline table ID or output port ID. */
  93         uint32_t id;
  94 };
  95
  96 /**
  97  * Table action profile.
  98  */
  99 struct rte_table_action_profile;
 100
 101 /**
 102  * Table action profile create.
 103  *
 104  * @param[in] common
 105  *   Common action configuration.
 106  * @return
 107  *   Table action profile handle on success, NULL otherwise.
 108  */
 109 struct rte_table_action_profile * __rte_experimental
 110 rte_table_action_profile_create(struct rte_table_action_common_config *common);
 111
 112 /**
 113  * Table action profile free.
 114  *
 115  * @param[in] profile
 116  *   Table profile action handle (needs to be valid).
 117  * @return
 118  *   Zero on success, non-zero error code otherwise.
 119  */
 120 int __rte_experimental
 121 rte_table_action_profile_free(struct rte_table_action_profile *profile);
 122
 123 /**
 124  * Table action profile action register.
 125  *
 126  * @param[in] profile
 127  *   Table profile action handle (needs to be valid and not in frozen state).
 128  * @param[in] type
 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.
 135  * @return
 136  *   Zero on success, non-zero error code otherwise.
 137  */
 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);
 142
 143 /**
 144  * Table action profile freeze.
 145  *
 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.
 150  *
 151  * @param[in] profile
 152  *   Table profile action handle (needs to be valid and not in frozen state).
 153  * @return
 154  *   Zero on success, non-zero error code otherwise.
 155  *
 156  * @see rte_table_action_create()
 157  */
 158 int __rte_experimental
 159 rte_table_action_profile_freeze(struct rte_table_action_profile *profile);
 160
 161 /**
 162  * Table action.
 163  */
 164 struct rte_table_action;
 165
 166 /**
 167  * Table action create.
 168  *
 169  * Instantiates the given table action profile to create a table action object.
 170  *
 171  * @param[in] profile
 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.
 176  * @return
 177  *   Handle to table action object on success, NULL on error.
 178  *
 179  * @see rte_table_action_create()
 180  */
 181 struct rte_table_action * __rte_experimental
 182 rte_table_action_create(struct rte_table_action_profile *profile,
 183         uint32_t socket_id);
 184
 185 /**
 186  * Table action free.
 187  *
 188  * @param[in] action
 189  *   Handle to table action object (needs to be valid).
 190  * @return
 191  *   Zero on success, non-zero error code otherwise.
 192  */
 193 int __rte_experimental
 194 rte_table_action_free(struct rte_table_action *action);
 195
 196 /**
 197  * Table action apply.
 198  *
 199  * @param[in] action
 200  *   Handle to table action object (needs to be valid).
 201  * @param[in] data
 202  *   Data byte array (typically table rule data) to apply action *type* on.
 203  * @param[in] type
 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.
 211  * @return
 212  *   Zero on success, non-zero error code otherwise.
 213  */
 214 int __rte_experimental
 215 rte_table_action_apply(struct rte_table_action *action,
 216         void *data,
 217         enum rte_table_action_type type,
 218         void *action_params);
 219
 220 #ifdef __cplusplus
 221 }
 222 #endif
 223
 224 #endif /* __INCLUDE_RTE_TABLE_ACTION_H__ */