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