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_ether.h>
  63 #include <rte_meter.h>
  64
  65 #include "rte_pipeline.h"
  66
  67 /** Table actions. */
  68 enum rte_table_action_type {
  69         /** Forward to next pipeline table, output port or drop. */
  70         RTE_TABLE_ACTION_FWD = 0,
  71
  72         /**  Traffic Metering and Policing. */
  73         RTE_TABLE_ACTION_MTR,
  74
  75         /**  Traffic Management. */
  76         RTE_TABLE_ACTION_TM,
  77
  78         /** Packet encapsulations. */
  79         RTE_TABLE_ACTION_ENCAP,
  80 };
  81
  82 /** Common action configuration (per table action profile). */
  83 struct rte_table_action_common_config {
  84         /** Input packet Internet Protocol (IP) version. Non-zero for IPv4, zero
  85          * for IPv6.
  86          */
  87         int ip_version;
  88
  89         /** IP header offset within the input packet buffer. Offset 0 points to
  90          * the first byte of the MBUF structure.
  91          */
  92         uint32_t ip_offset;
  93 };
  94
  95 /**
  96  * RTE_TABLE_ACTION_FWD
  97  */
  98 /** Forward action parameters (per table rule). */
  99 struct rte_table_action_fwd_params {
 100         /** Forward action. */
 101         enum rte_pipeline_action action;
 102
 103         /** Pipeline table ID or output port ID. */
 104         uint32_t id;
 105 };
 106
 107 /**
 108  * RTE_TABLE_ACTION_MTR
 109  */
 110 /** Max number of traffic classes (TCs). */
 111 #define RTE_TABLE_ACTION_TC_MAX                                  4
 112
 113 /** Max number of queues per traffic class. */
 114 #define RTE_TABLE_ACTION_TC_QUEUE_MAX                            4
 115
 116 /** Differentiated Services Code Point (DSCP) translation table entry. */
 117 struct rte_table_action_dscp_table_entry {
 118         /** Traffic class. Used by the meter or the traffic management actions.
 119          * Has to be strictly smaller than *RTE_TABLE_ACTION_TC_MAX*. Traffic
 120          * class 0 is the highest priority.
 121          */
 122         uint32_t tc_id;
 123
 124         /** Traffic class queue. Used by the traffic management action. Has to
 125          * be strictly smaller than *RTE_TABLE_ACTION_TC_QUEUE_MAX*.
 126          */
 127         uint32_t tc_queue_id;
 128
 129         /** Packet color. Used by the meter action as the packet input color
 130          * for the color aware mode of the traffic metering algorithm.
 131          */
 132         enum rte_meter_color color;
 133 };
 134
 135 /** DSCP translation table. */
 136 struct rte_table_action_dscp_table {
 137         /** Array of DSCP table entries */
 138         struct rte_table_action_dscp_table_entry entry[64];
 139 };
 140
 141 /** Supported traffic metering algorithms. */
 142 enum rte_table_action_meter_algorithm {
 143         /** Single Rate Three Color Marker (srTCM) - IETF RFC 2697. */
 144         RTE_TABLE_ACTION_METER_SRTCM,
 145
 146         /** Two Rate Three Color Marker (trTCM) - IETF RFC 2698. */
 147         RTE_TABLE_ACTION_METER_TRTCM,
 148 };
 149
 150 /** Traffic metering profile (configuration template). */
 151 struct rte_table_action_meter_profile {
 152         /** Traffic metering algorithm. */
 153         enum rte_table_action_meter_algorithm alg;
 154
 155         RTE_STD_C11
 156         union {
 157                 /** Only valid when *alg* is set to srTCM - IETF RFC 2697. */
 158                 struct rte_meter_srtcm_params srtcm;
 159
 160                 /** Only valid when *alg* is set to trTCM - IETF RFC 2698. */
 161                 struct rte_meter_trtcm_params trtcm;
 162         };
 163 };
 164
 165 /** Policer actions. */
 166 enum rte_table_action_policer {
 167         /** Recolor the packet as green. */
 168         RTE_TABLE_ACTION_POLICER_COLOR_GREEN = 0,
 169
 170         /** Recolor the packet as yellow. */
 171         RTE_TABLE_ACTION_POLICER_COLOR_YELLOW,
 172
 173         /** Recolor the packet as red. */
 174         RTE_TABLE_ACTION_POLICER_COLOR_RED,
 175
 176         /** Drop the packet. */
 177         RTE_TABLE_ACTION_POLICER_DROP,
 178
 179         /** Number of policer actions. */
 180         RTE_TABLE_ACTION_POLICER_MAX
 181 };
 182
 183 /** Meter action configuration per traffic class. */
 184 struct rte_table_action_mtr_tc_params {
 185         /** Meter profile ID. */
 186         uint32_t meter_profile_id;
 187
 188         /** Policer actions. */
 189         enum rte_table_action_policer policer[e_RTE_METER_COLORS];
 190 };
 191
 192 /** Meter action statistics counters per traffic class. */
 193 struct rte_table_action_mtr_counters_tc {
 194         /** Number of packets per color at the output of the traffic metering
 195          * and before the policer actions are executed. Only valid when
 196          * *n_packets_valid* is non-zero.
 197          */
 198         uint64_t n_packets[e_RTE_METER_COLORS];
 199
 200         /** Number of packet bytes per color at the output of the traffic
 201          * metering and before the policer actions are executed. Only valid when
 202          * *n_bytes_valid* is non-zero.
 203          */
 204         uint64_t n_bytes[e_RTE_METER_COLORS];
 205
 206         /** When non-zero, the *n_packets* field is valid. */
 207         int n_packets_valid;
 208
 209         /** When non-zero, the *n_bytes* field is valid. */
 210         int n_bytes_valid;
 211 };
 212
 213 /** Meter action configuration (per table action profile). */
 214 struct rte_table_action_mtr_config {
 215         /** Meter algorithm. */
 216         enum rte_table_action_meter_algorithm alg;
 217
 218         /** Number of traffic classes. Each traffic class has its own traffic
 219          * meter and policer instances. Needs to be equal to either 1 or to
 220          * *RTE_TABLE_ACTION_TC_MAX*.
 221          */
 222         uint32_t n_tc;
 223
 224         /** When non-zero, the *n_packets* meter stats counter is enabled,
 225          * otherwise it is disabled.
 226          *
 227          * @see struct rte_table_action_mtr_counters_tc
 228          */
 229         int n_packets_enabled;
 230
 231         /** When non-zero, the *n_bytes* meter stats counter is enabled,
 232          * otherwise it is disabled.
 233          *
 234          * @see struct rte_table_action_mtr_counters_tc
 235          */
 236         int n_bytes_enabled;
 237 };
 238
 239 /** Meter action parameters (per table rule). */
 240 struct rte_table_action_mtr_params {
 241         /** Traffic meter and policer parameters for each of the *tc_mask*
 242          * traffic classes.
 243          */
 244         struct rte_table_action_mtr_tc_params mtr[RTE_TABLE_ACTION_TC_MAX];
 245
 246         /** Bit mask defining which traffic class parameters are valid in *mtr*.
 247          * If bit N is set in *tc_mask*, then parameters for traffic class N are
 248          * valid in *mtr*.
 249          */
 250         uint32_t tc_mask;
 251 };
 252
 253 /** Meter action statistics counters (per table rule). */
 254 struct rte_table_action_mtr_counters {
 255         /** Stats counters for each of the *tc_mask* traffic classes. */
 256         struct rte_table_action_mtr_counters_tc stats[RTE_TABLE_ACTION_TC_MAX];
 257
 258         /** Bit mask defining which traffic class parameters are valid in *mtr*.
 259          * If bit N is set in *tc_mask*, then parameters for traffic class N are
 260          * valid in *mtr*.
 261          */
 262         uint32_t tc_mask;
 263 };
 264
 265 /**
 266  * RTE_TABLE_ACTION_TM
 267  */
 268 /** Traffic management action configuration (per table action profile). */
 269 struct rte_table_action_tm_config {
 270         /** Number of subports per port. */
 271         uint32_t n_subports_per_port;
 272
 273         /** Number of pipes per subport. */
 274         uint32_t n_pipes_per_subport;
 275 };
 276
 277 /** Traffic management action parameters (per table rule). */
 278 struct rte_table_action_tm_params {
 279         /** Subport ID. */
 280         uint32_t subport_id;
 281
 282         /** Pipe ID. */
 283         uint32_t pipe_id;
 284 };
 285
 286 /**
 287  * RTE_TABLE_ACTION_ENCAP
 288  */
 289 /** Supported packet encapsulation types. */
 290 enum rte_table_action_encap_type {
 291         /** IP -> { Ether | IP } */
 292         RTE_TABLE_ACTION_ENCAP_ETHER = 0,
 293
 294         /** IP -> { Ether | VLAN | IP } */
 295         RTE_TABLE_ACTION_ENCAP_VLAN,
 296
 297         /** IP -> { Ether | S-VLAN | C-VLAN | IP } */
 298         RTE_TABLE_ACTION_ENCAP_QINQ,
 299
 300         /** IP -> { Ether | MPLS | IP } */
 301         RTE_TABLE_ACTION_ENCAP_MPLS,
 302
 303         /** IP -> { Ether | PPPoE | PPP | IP } */
 304         RTE_TABLE_ACTION_ENCAP_PPPOE,
 305 };
 306
 307 /** Pre-computed Ethernet header fields for encapsulation action. */
 308 struct rte_table_action_ether_hdr {
 309         struct ether_addr da; /**< Destination address. */
 310         struct ether_addr sa; /**< Source address. */
 311 };
 312
 313 /** Pre-computed VLAN header fields for encapsulation action. */
 314 struct rte_table_action_vlan_hdr {
 315         uint8_t pcp; /**< Priority Code Point (PCP). */
 316         uint8_t dei; /**< Drop Eligibility Indicator (DEI). */
 317         uint16_t vid; /**< VLAN Identifier (VID). */
 318 };
 319
 320 /** Pre-computed MPLS header fields for encapsulation action. */
 321 struct rte_table_action_mpls_hdr {
 322         uint32_t label; /**< Label. */
 323         uint8_t tc; /**< Traffic Class (TC). */
 324         uint8_t ttl; /**< Time to Live (TTL). */
 325 };
 326
 327 /** Pre-computed PPPoE header fields for encapsulation action. */
 328 struct rte_table_action_pppoe_hdr {
 329         uint16_t session_id; /**< Session ID. */
 330 };
 331
 332 /** Ether encap parameters. */
 333 struct rte_table_action_encap_ether_params {
 334         struct rte_table_action_ether_hdr ether; /**< Ethernet header. */
 335 };
 336
 337 /** VLAN encap parameters. */
 338 struct rte_table_action_encap_vlan_params {
 339         struct rte_table_action_ether_hdr ether; /**< Ethernet header. */
 340         struct rte_table_action_vlan_hdr vlan; /**< VLAN header. */
 341 };
 342
 343 /** QinQ encap parameters. */
 344 struct rte_table_action_encap_qinq_params {
 345         struct rte_table_action_ether_hdr ether; /**< Ethernet header. */
 346         struct rte_table_action_vlan_hdr svlan; /**< Service VLAN header. */
 347         struct rte_table_action_vlan_hdr cvlan; /**< Customer VLAN header. */
 348 };
 349
 350 /** Max number of MPLS labels per output packet for MPLS encapsulation. */
 351 #ifndef RTE_TABLE_ACTION_MPLS_LABELS_MAX
 352 #define RTE_TABLE_ACTION_MPLS_LABELS_MAX                   4
 353 #endif
 354
 355 /** MPLS encap parameters. */
 356 struct rte_table_action_encap_mpls_params {
 357         /** Ethernet header. */
 358         struct rte_table_action_ether_hdr ether;
 359
 360         /** MPLS header. */
 361         struct rte_table_action_mpls_hdr mpls[RTE_TABLE_ACTION_MPLS_LABELS_MAX];
 362
 363         /** Number of MPLS labels in MPLS header. */
 364         uint32_t mpls_count;
 365
 366         /** Non-zero for MPLS unicast, zero for MPLS multicast. */
 367         int unicast;
 368 };
 369
 370 /** PPPoE encap parameters. */
 371 struct rte_table_action_encap_pppoe_params {
 372         struct rte_table_action_ether_hdr ether; /**< Ethernet header. */
 373         struct rte_table_action_pppoe_hdr pppoe; /**< PPPoE/PPP headers. */
 374 };
 375
 376 /** Encap action configuration (per table action profile). */
 377 struct rte_table_action_encap_config {
 378         /** Bit mask defining the set of packet encapsulations enabled for the
 379          * current table action profile. If bit (1 << N) is set in *encap_mask*,
 380          * then packet encapsulation N is enabled, otherwise it is disabled.
 381          *
 382          * @see enum rte_table_action_encap_type
 383          */
 384         uint64_t encap_mask;
 385 };
 386
 387 /** Encap action parameters (per table rule). */
 388 struct rte_table_action_encap_params {
 389         /** Encapsulation type. */
 390         enum rte_table_action_encap_type type;
 391
 392         RTE_STD_C11
 393         union {
 394                 /** Only valid when *type* is set to Ether. */
 395                 struct rte_table_action_encap_ether_params ether;
 396
 397                 /** Only valid when *type* is set to VLAN. */
 398                 struct rte_table_action_encap_vlan_params vlan;
 399
 400                 /** Only valid when *type* is set to QinQ. */
 401                 struct rte_table_action_encap_qinq_params qinq;
 402
 403                 /** Only valid when *type* is set to MPLS. */
 404                 struct rte_table_action_encap_mpls_params mpls;
 405
 406                 /** Only valid when *type* is set to PPPoE. */
 407                 struct rte_table_action_encap_pppoe_params pppoe;
 408         };
 409 };
 410
 411 /**
 412  * Table action profile.
 413  */
 414 struct rte_table_action_profile;
 415
 416 /**
 417  * Table action profile create.
 418  *
 419  * @param[in] common
 420  *   Common action configuration.
 421  * @return
 422  *   Table action profile handle on success, NULL otherwise.
 423  */
 424 struct rte_table_action_profile * __rte_experimental
 425 rte_table_action_profile_create(struct rte_table_action_common_config *common);
 426
 427 /**
 428  * Table action profile free.
 429  *
 430  * @param[in] profile
 431  *   Table profile action handle (needs to be valid).
 432  * @return
 433  *   Zero on success, non-zero error code otherwise.
 434  */
 435 int __rte_experimental
 436 rte_table_action_profile_free(struct rte_table_action_profile *profile);
 437
 438 /**
 439  * Table action profile action register.
 440  *
 441  * @param[in] profile
 442  *   Table profile action handle (needs to be valid and not in frozen state).
 443  * @param[in] type
 444  *   Specific table action to be registered for *profile*.
 445  * @param[in] action_config
 446  *   Configuration for the *type* action.
 447  *   If struct rte_table_action_*type*_config is defined by the Table Action
 448  *   API, it needs to point to a valid instance of this structure, otherwise it
 449  *   needs to be set to NULL.
 450  * @return
 451  *   Zero on success, non-zero error code otherwise.
 452  */
 453 int __rte_experimental
 454 rte_table_action_profile_action_register(struct rte_table_action_profile *profile,
 455         enum rte_table_action_type type,
 456         void *action_config);
 457
 458 /**
 459  * Table action profile freeze.
 460  *
 461  * Once this function is called successfully, the given profile enters the
 462  * frozen state with the following immediate effects: no more actions can be
 463  * registered for this profile, so the profile can be instantiated to create
 464  * table action objects.
 465  *
 466  * @param[in] profile
 467  *   Table profile action handle (needs to be valid and not in frozen state).
 468  * @return
 469  *   Zero on success, non-zero error code otherwise.
 470  *
 471  * @see rte_table_action_create()
 472  */
 473 int __rte_experimental
 474 rte_table_action_profile_freeze(struct rte_table_action_profile *profile);
 475
 476 /**
 477  * Table action.
 478  */
 479 struct rte_table_action;
 480
 481 /**
 482  * Table action create.
 483  *
 484  * Instantiates the given table action profile to create a table action object.
 485  *
 486  * @param[in] profile
 487  *   Table profile action handle (needs to be valid and in frozen state).
 488  * @param[in] socket_id
 489  *   CPU socket ID where the internal data structures required by the new table
 490  *   action object should be allocated.
 491  * @return
 492  *   Handle to table action object on success, NULL on error.
 493  *
 494  * @see rte_table_action_create()
 495  */
 496 struct rte_table_action * __rte_experimental
 497 rte_table_action_create(struct rte_table_action_profile *profile,
 498         uint32_t socket_id);
 499
 500 /**
 501  * Table action free.
 502  *
 503  * @param[in] action
 504  *   Handle to table action object (needs to be valid).
 505  * @return
 506  *   Zero on success, non-zero error code otherwise.
 507  */
 508 int __rte_experimental
 509 rte_table_action_free(struct rte_table_action *action);
 510
 511 /**
 512  * Table action table params get.
 513  *
 514  * @param[in] action
 515  *   Handle to table action object (needs to be valid).
 516  * @param[inout] params
 517  *   Pipeline table parameters (needs to be pre-allocated).
 518  * @return
 519  *   Zero on success, non-zero error code otherwise.
 520  */
 521 int __rte_experimental
 522 rte_table_action_table_params_get(struct rte_table_action *action,
 523         struct rte_pipeline_table_params *params);
 524
 525 /**
 526  * Table action apply.
 527  *
 528  * @param[in] action
 529  *   Handle to table action object (needs to be valid).
 530  * @param[in] data
 531  *   Data byte array (typically table rule data) to apply action *type* on.
 532  * @param[in] type
 533  *   Specific table action previously registered for the table action profile of
 534  *   the *action* object.
 535  * @param[in] action_params
 536  *   Parameters for the *type* action.
 537  *   If struct rte_table_action_*type*_params is defined by the Table Action
 538  *   API, it needs to point to a valid instance of this structure, otherwise it
 539  *   needs to be set to NULL.
 540  * @return
 541  *   Zero on success, non-zero error code otherwise.
 542  */
 543 int __rte_experimental
 544 rte_table_action_apply(struct rte_table_action *action,
 545         void *data,
 546         enum rte_table_action_type type,
 547         void *action_params);
 548
 549 /**
 550  * Table action DSCP table update.
 551  *
 552  * @param[in] action
 553  *   Handle to table action object (needs to be valid).
 554  * @param[in] dscp_mask
 555  *   64-bit mask defining the DSCP table entries to be updated. If bit N is set
 556  *   in this bit mask, then DSCP table entry N is to be updated, otherwise not.
 557  * @param[in] table
 558  *   DSCP table.
 559  * @return
 560  *   Zero on success, non-zero error code otherwise.
 561  */
 562 int __rte_experimental
 563 rte_table_action_dscp_table_update(struct rte_table_action *action,
 564         uint64_t dscp_mask,
 565         struct rte_table_action_dscp_table *table);
 566
 567 /**
 568  * Table action meter profile add.
 569  *
 570  * @param[in] action
 571  *   Handle to table action object (needs to be valid).
 572  * @param[in] meter_profile_id
 573  *   Meter profile ID to be used for the *profile* once it is successfully added
 574  *   to the *action* object (needs to be unused by the set of meter profiles
 575  *   currently registered for the *action* object).
 576  * @param[in] profile
 577  *   Meter profile to be added.
 578  * @return
 579  *   Zero on success, non-zero error code otherwise.
 580  */
 581 int __rte_experimental
 582 rte_table_action_meter_profile_add(struct rte_table_action *action,
 583         uint32_t meter_profile_id,
 584         struct rte_table_action_meter_profile *profile);
 585
 586 /**
 587  * Table action meter profile delete.
 588  *
 589  * @param[in] action
 590  *   Handle to table action object (needs to be valid).
 591  * @param[in] meter_profile_id
 592  *   Meter profile ID of the meter profile to be deleted from the *action*
 593  *   object (needs to be valid for the *action* object).
 594  * @return
 595  *   Zero on success, non-zero error code otherwise.
 596  */
 597 int __rte_experimental
 598 rte_table_action_meter_profile_delete(struct rte_table_action *action,
 599         uint32_t meter_profile_id);
 600
 601 /**
 602  * Table action meter read.
 603  *
 604  * @param[in] action
 605  *   Handle to table action object (needs to be valid).
 606  * @param[in] data
 607  *   Data byte array (typically table rule data) with meter action previously
 608  *   applied on it.
 609  * @param[in] tc_mask
 610  *   Bit mask defining which traffic classes should have the meter stats
 611  *   counters read from *data* and stored into *stats*. If bit N is set in this
 612  *   bit mask, then traffic class N is part of this operation, otherwise it is
 613  *   not. If bit N is set in this bit mask, then traffic class N must be one of
 614  *   the traffic classes that are enabled for the meter action in the table
 615  *   action profile used by the *action* object.
 616  * @param[inout] stats
 617  *   When non-NULL, it points to the area where the meter stats counters read
 618  *   from *data* are saved. Only the meter stats counters for the *tc_mask*
 619  *   traffic classes are read and stored to *stats*.
 620  * @param[in] clear
 621  *   When non-zero, the meter stats counters are cleared (i.e. set to zero),
 622  *   otherwise the counters are not modified. When the read operation is enabled
 623  *   (*stats* is non-NULL), the clear operation is performed after the read
 624  *   operation is completed.
 625  * @return
 626  *   Zero on success, non-zero error code otherwise.
 627  */
 628 int __rte_experimental
 629 rte_table_action_meter_read(struct rte_table_action *action,
 630         void *data,
 631         uint32_t tc_mask,
 632         struct rte_table_action_mtr_counters *stats,
 633         int clear);
 634
 635 #ifdef __cplusplus
 636 }
 637 #endif
 638
 639 #endif /* __INCLUDE_RTE_TABLE_ACTION_H__ */