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 #include <rte_meter.h>
  63
  64 #include "rte_pipeline.h"
  65
  66 /** Table actions. */
  67 enum rte_table_action_type {
  68         /** Forward to next pipeline table, output port or drop. */
  69         RTE_TABLE_ACTION_FWD = 0,
  70
  71         /**  Traffic Metering and Policing. */
  72         RTE_TABLE_ACTION_MTR,
  73 };
  74
  75 /** Common action configuration (per table action profile). */
  76 struct rte_table_action_common_config {
  77         /** Input packet Internet Protocol (IP) version. Non-zero for IPv4, zero
  78          * for IPv6.
  79          */
  80         int ip_version;
  81
  82         /** IP header offset within the input packet buffer. Offset 0 points to
  83          * the first byte of the MBUF structure.
  84          */
  85         uint32_t ip_offset;
  86 };
  87
  88 /**
  89  * RTE_TABLE_ACTION_FWD
  90  */
  91 /** Forward action parameters (per table rule). */
  92 struct rte_table_action_fwd_params {
  93         /** Forward action. */
  94         enum rte_pipeline_action action;
  95
  96         /** Pipeline table ID or output port ID. */
  97         uint32_t id;
  98 };
  99
 100 /**
 101  * RTE_TABLE_ACTION_MTR
 102  */
 103 /** Max number of traffic classes (TCs). */
 104 #define RTE_TABLE_ACTION_TC_MAX                                  4
 105
 106 /** Max number of queues per traffic class. */
 107 #define RTE_TABLE_ACTION_TC_QUEUE_MAX                            4
 108
 109 /** Differentiated Services Code Point (DSCP) translation table entry. */
 110 struct rte_table_action_dscp_table_entry {
 111         /** Traffic class. Used by the meter or the traffic management actions.
 112          * Has to be strictly smaller than *RTE_TABLE_ACTION_TC_MAX*. Traffic
 113          * class 0 is the highest priority.
 114          */
 115         uint32_t tc_id;
 116
 117         /** Traffic class queue. Used by the traffic management action. Has to
 118          * be strictly smaller than *RTE_TABLE_ACTION_TC_QUEUE_MAX*.
 119          */
 120         uint32_t tc_queue_id;
 121
 122         /** Packet color. Used by the meter action as the packet input color
 123          * for the color aware mode of the traffic metering algorithm.
 124          */
 125         enum rte_meter_color color;
 126 };
 127
 128 /** DSCP translation table. */
 129 struct rte_table_action_dscp_table {
 130         /** Array of DSCP table entries */
 131         struct rte_table_action_dscp_table_entry entry[64];
 132 };
 133
 134 /** Supported traffic metering algorithms. */
 135 enum rte_table_action_meter_algorithm {
 136         /** Single Rate Three Color Marker (srTCM) - IETF RFC 2697. */
 137         RTE_TABLE_ACTION_METER_SRTCM,
 138
 139         /** Two Rate Three Color Marker (trTCM) - IETF RFC 2698. */
 140         RTE_TABLE_ACTION_METER_TRTCM,
 141 };
 142
 143 /** Traffic metering profile (configuration template). */
 144 struct rte_table_action_meter_profile {
 145         /** Traffic metering algorithm. */
 146         enum rte_table_action_meter_algorithm alg;
 147
 148         RTE_STD_C11
 149         union {
 150                 /** Only valid when *alg* is set to srTCM - IETF RFC 2697. */
 151                 struct rte_meter_srtcm_params srtcm;
 152
 153                 /** Only valid when *alg* is set to trTCM - IETF RFC 2698. */
 154                 struct rte_meter_trtcm_params trtcm;
 155         };
 156 };
 157
 158 /** Policer actions. */
 159 enum rte_table_action_policer {
 160         /** Recolor the packet as green. */
 161         RTE_TABLE_ACTION_POLICER_COLOR_GREEN = 0,
 162
 163         /** Recolor the packet as yellow. */
 164         RTE_TABLE_ACTION_POLICER_COLOR_YELLOW,
 165
 166         /** Recolor the packet as red. */
 167         RTE_TABLE_ACTION_POLICER_COLOR_RED,
 168
 169         /** Drop the packet. */
 170         RTE_TABLE_ACTION_POLICER_DROP,
 171
 172         /** Number of policer actions. */
 173         RTE_TABLE_ACTION_POLICER_MAX
 174 };
 175
 176 /** Meter action configuration per traffic class. */
 177 struct rte_table_action_mtr_tc_params {
 178         /** Meter profile ID. */
 179         uint32_t meter_profile_id;
 180
 181         /** Policer actions. */
 182         enum rte_table_action_policer policer[e_RTE_METER_COLORS];
 183 };
 184
 185 /** Meter action statistics counters per traffic class. */
 186 struct rte_table_action_mtr_counters_tc {
 187         /** Number of packets per color at the output of the traffic metering
 188          * and before the policer actions are executed. Only valid when
 189          * *n_packets_valid* is non-zero.
 190          */
 191         uint64_t n_packets[e_RTE_METER_COLORS];
 192
 193         /** Number of packet bytes per color at the output of the traffic
 194          * metering and before the policer actions are executed. Only valid when
 195          * *n_bytes_valid* is non-zero.
 196          */
 197         uint64_t n_bytes[e_RTE_METER_COLORS];
 198
 199         /** When non-zero, the *n_packets* field is valid. */
 200         int n_packets_valid;
 201
 202         /** When non-zero, the *n_bytes* field is valid. */
 203         int n_bytes_valid;
 204 };
 205
 206 /** Meter action configuration (per table action profile). */
 207 struct rte_table_action_mtr_config {
 208         /** Meter algorithm. */
 209         enum rte_table_action_meter_algorithm alg;
 210
 211         /** Number of traffic classes. Each traffic class has its own traffic
 212          * meter and policer instances. Needs to be equal to either 1 or to
 213          * *RTE_TABLE_ACTION_TC_MAX*.
 214          */
 215         uint32_t n_tc;
 216
 217         /** When non-zero, the *n_packets* meter stats counter is enabled,
 218          * otherwise it is disabled.
 219          *
 220          * @see struct rte_table_action_mtr_counters_tc
 221          */
 222         int n_packets_enabled;
 223
 224         /** When non-zero, the *n_bytes* meter stats counter is enabled,
 225          * otherwise it is disabled.
 226          *
 227          * @see struct rte_table_action_mtr_counters_tc
 228          */
 229         int n_bytes_enabled;
 230 };
 231
 232 /** Meter action parameters (per table rule). */
 233 struct rte_table_action_mtr_params {
 234         /** Traffic meter and policer parameters for each of the *tc_mask*
 235          * traffic classes.
 236          */
 237         struct rte_table_action_mtr_tc_params mtr[RTE_TABLE_ACTION_TC_MAX];
 238
 239         /** Bit mask defining which traffic class parameters are valid in *mtr*.
 240          * If bit N is set in *tc_mask*, then parameters for traffic class N are
 241          * valid in *mtr*.
 242          */
 243         uint32_t tc_mask;
 244 };
 245
 246 /** Meter action statistics counters (per table rule). */
 247 struct rte_table_action_mtr_counters {
 248         /** Stats counters for each of the *tc_mask* traffic classes. */
 249         struct rte_table_action_mtr_counters_tc stats[RTE_TABLE_ACTION_TC_MAX];
 250
 251         /** Bit mask defining which traffic class parameters are valid in *mtr*.
 252          * If bit N is set in *tc_mask*, then parameters for traffic class N are
 253          * valid in *mtr*.
 254          */
 255         uint32_t tc_mask;
 256 };
 257
 258 /**
 259  * Table action profile.
 260  */
 261 struct rte_table_action_profile;
 262
 263 /**
 264  * Table action profile create.
 265  *
 266  * @param[in] common
 267  *   Common action configuration.
 268  * @return
 269  *   Table action profile handle on success, NULL otherwise.
 270  */
 271 struct rte_table_action_profile * __rte_experimental
 272 rte_table_action_profile_create(struct rte_table_action_common_config *common);
 273
 274 /**
 275  * Table action profile free.
 276  *
 277  * @param[in] profile
 278  *   Table profile action handle (needs to be valid).
 279  * @return
 280  *   Zero on success, non-zero error code otherwise.
 281  */
 282 int __rte_experimental
 283 rte_table_action_profile_free(struct rte_table_action_profile *profile);
 284
 285 /**
 286  * Table action profile action register.
 287  *
 288  * @param[in] profile
 289  *   Table profile action handle (needs to be valid and not in frozen state).
 290  * @param[in] type
 291  *   Specific table action to be registered for *profile*.
 292  * @param[in] action_config
 293  *   Configuration for the *type* action.
 294  *   If struct rte_table_action_*type*_config is defined by the Table Action
 295  *   API, it needs to point to a valid instance of this structure, otherwise it
 296  *   needs to be set to NULL.
 297  * @return
 298  *   Zero on success, non-zero error code otherwise.
 299  */
 300 int __rte_experimental
 301 rte_table_action_profile_action_register(struct rte_table_action_profile *profile,
 302         enum rte_table_action_type type,
 303         void *action_config);
 304
 305 /**
 306  * Table action profile freeze.
 307  *
 308  * Once this function is called successfully, the given profile enters the
 309  * frozen state with the following immediate effects: no more actions can be
 310  * registered for this profile, so the profile can be instantiated to create
 311  * table action objects.
 312  *
 313  * @param[in] profile
 314  *   Table profile action handle (needs to be valid and not in frozen state).
 315  * @return
 316  *   Zero on success, non-zero error code otherwise.
 317  *
 318  * @see rte_table_action_create()
 319  */
 320 int __rte_experimental
 321 rte_table_action_profile_freeze(struct rte_table_action_profile *profile);
 322
 323 /**
 324  * Table action.
 325  */
 326 struct rte_table_action;
 327
 328 /**
 329  * Table action create.
 330  *
 331  * Instantiates the given table action profile to create a table action object.
 332  *
 333  * @param[in] profile
 334  *   Table profile action handle (needs to be valid and in frozen state).
 335  * @param[in] socket_id
 336  *   CPU socket ID where the internal data structures required by the new table
 337  *   action object should be allocated.
 338  * @return
 339  *   Handle to table action object on success, NULL on error.
 340  *
 341  * @see rte_table_action_create()
 342  */
 343 struct rte_table_action * __rte_experimental
 344 rte_table_action_create(struct rte_table_action_profile *profile,
 345         uint32_t socket_id);
 346
 347 /**
 348  * Table action free.
 349  *
 350  * @param[in] action
 351  *   Handle to table action object (needs to be valid).
 352  * @return
 353  *   Zero on success, non-zero error code otherwise.
 354  */
 355 int __rte_experimental
 356 rte_table_action_free(struct rte_table_action *action);
 357
 358 /**
 359  * Table action table params get.
 360  *
 361  * @param[in] action
 362  *   Handle to table action object (needs to be valid).
 363  * @param[inout] params
 364  *   Pipeline table parameters (needs to be pre-allocated).
 365  * @return
 366  *   Zero on success, non-zero error code otherwise.
 367  */
 368 int __rte_experimental
 369 rte_table_action_table_params_get(struct rte_table_action *action,
 370         struct rte_pipeline_table_params *params);
 371
 372 /**
 373  * Table action apply.
 374  *
 375  * @param[in] action
 376  *   Handle to table action object (needs to be valid).
 377  * @param[in] data
 378  *   Data byte array (typically table rule data) to apply action *type* on.
 379  * @param[in] type
 380  *   Specific table action previously registered for the table action profile of
 381  *   the *action* object.
 382  * @param[in] action_params
 383  *   Parameters for the *type* action.
 384  *   If struct rte_table_action_*type*_params is defined by the Table Action
 385  *   API, it needs to point to a valid instance of this structure, otherwise it
 386  *   needs to be set to NULL.
 387  * @return
 388  *   Zero on success, non-zero error code otherwise.
 389  */
 390 int __rte_experimental
 391 rte_table_action_apply(struct rte_table_action *action,
 392         void *data,
 393         enum rte_table_action_type type,
 394         void *action_params);
 395
 396 /**
 397  * Table action DSCP table update.
 398  *
 399  * @param[in] action
 400  *   Handle to table action object (needs to be valid).
 401  * @param[in] dscp_mask
 402  *   64-bit mask defining the DSCP table entries to be updated. If bit N is set
 403  *   in this bit mask, then DSCP table entry N is to be updated, otherwise not.
 404  * @param[in] table
 405  *   DSCP table.
 406  * @return
 407  *   Zero on success, non-zero error code otherwise.
 408  */
 409 int __rte_experimental
 410 rte_table_action_dscp_table_update(struct rte_table_action *action,
 411         uint64_t dscp_mask,
 412         struct rte_table_action_dscp_table *table);
 413
 414 /**
 415  * Table action meter profile add.
 416  *
 417  * @param[in] action
 418  *   Handle to table action object (needs to be valid).
 419  * @param[in] meter_profile_id
 420  *   Meter profile ID to be used for the *profile* once it is successfully added
 421  *   to the *action* object (needs to be unused by the set of meter profiles
 422  *   currently registered for the *action* object).
 423  * @param[in] profile
 424  *   Meter profile to be added.
 425  * @return
 426  *   Zero on success, non-zero error code otherwise.
 427  */
 428 int __rte_experimental
 429 rte_table_action_meter_profile_add(struct rte_table_action *action,
 430         uint32_t meter_profile_id,
 431         struct rte_table_action_meter_profile *profile);
 432
 433 /**
 434  * Table action meter profile delete.
 435  *
 436  * @param[in] action
 437  *   Handle to table action object (needs to be valid).
 438  * @param[in] meter_profile_id
 439  *   Meter profile ID of the meter profile to be deleted from the *action*
 440  *   object (needs to be valid for the *action* object).
 441  * @return
 442  *   Zero on success, non-zero error code otherwise.
 443  */
 444 int __rte_experimental
 445 rte_table_action_meter_profile_delete(struct rte_table_action *action,
 446         uint32_t meter_profile_id);
 447
 448 /**
 449  * Table action meter read.
 450  *
 451  * @param[in] action
 452  *   Handle to table action object (needs to be valid).
 453  * @param[in] data
 454  *   Data byte array (typically table rule data) with meter action previously
 455  *   applied on it.
 456  * @param[in] tc_mask
 457  *   Bit mask defining which traffic classes should have the meter stats
 458  *   counters read from *data* and stored into *stats*. If bit N is set in this
 459  *   bit mask, then traffic class N is part of this operation, otherwise it is
 460  *   not. If bit N is set in this bit mask, then traffic class N must be one of
 461  *   the traffic classes that are enabled for the meter action in the table
 462  *   action profile used by the *action* object.
 463  * @param[inout] stats
 464  *   When non-NULL, it points to the area where the meter stats counters read
 465  *   from *data* are saved. Only the meter stats counters for the *tc_mask*
 466  *   traffic classes are read and stored to *stats*.
 467  * @param[in] clear
 468  *   When non-zero, the meter stats counters are cleared (i.e. set to zero),
 469  *   otherwise the counters are not modified. When the read operation is enabled
 470  *   (*stats* is non-NULL), the clear operation is performed after the read
 471  *   operation is completed.
 472  * @return
 473  *   Zero on success, non-zero error code otherwise.
 474  */
 475 int __rte_experimental
 476 rte_table_action_meter_read(struct rte_table_action *action,
 477         void *data,
 478         uint32_t tc_mask,
 479         struct rte_table_action_mtr_counters *stats,
 480         int clear);
 481
 482 #ifdef __cplusplus
 483 }
 484 #endif
 485
 486 #endif /* __INCLUDE_RTE_TABLE_ACTION_H__ */