lib/pipeline/rte_swx_ctl.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2020 Intel Corporation
   3  */
   4 #ifndef __INCLUDE_RTE_SWX_CTL_H__
   5 #define __INCLUDE_RTE_SWX_CTL_H__
   6
   7 #ifdef __cplusplus
   8 extern "C" {
   9 #endif
  10
  11 /**
  12  * @file
  13  * RTE SWX Pipeline Control
  14  */
  15
  16 #include <stdint.h>
  17 #include <stdio.h>
  18
  19 #include <rte_compat.h>
  20 #include <rte_meter.h>
  21
  22 #include "rte_swx_port.h"
  23 #include "rte_swx_table.h"
  24
  25 struct rte_swx_pipeline;
  26
  27 /** Name size. */
  28 #ifndef RTE_SWX_CTL_NAME_SIZE
  29 #define RTE_SWX_CTL_NAME_SIZE 64
  30 #endif
  31
  32 /*
  33  * Pipeline Query API.
  34  */
  35
  36 /** Pipeline info. */
  37 struct rte_swx_ctl_pipeline_info {
  38         /** Number of input ports. */
  39         uint32_t n_ports_in;
  40
  41         /** Number of input ports. */
  42         uint32_t n_ports_out;
  43
  44         /** Number of packet mirroring slots. */
  45         uint32_t n_mirroring_slots;
  46
  47         /** Number of packet mirroring sessions. */
  48         uint32_t n_mirroring_sessions;
  49
  50         /** Number of actions. */
  51         uint32_t n_actions;
  52
  53         /** Number of tables. */
  54         uint32_t n_tables;
  55
  56         /** Number of selector tables. */
  57         uint32_t n_selectors;
  58
  59         /** Number of learner tables. */
  60         uint32_t n_learners;
  61
  62         /** Number of register arrays. */
  63         uint32_t n_regarrays;
  64
  65         /** Number of meter arrays. */
  66         uint32_t n_metarrays;
  67 };
  68
  69 /**
  70  * Pipeline info get
  71  *
  72  * @param[in] p
  73  *   Pipeline handle.
  74  * @param[out] pipeline
  75  *   Pipeline info.
  76  * @return
  77  *   0 on success or the following error codes otherwise:
  78  *   -EINVAL: Invalid argument.
  79  */
  80 __rte_experimental
  81 int
  82 rte_swx_ctl_pipeline_info_get(struct rte_swx_pipeline *p,
  83                               struct rte_swx_ctl_pipeline_info *pipeline);
  84
  85 /**
  86  * Pipeline NUMA node get
  87  *
  88  * @param[in] p
  89  *   Pipeline handle.
  90  * @param[out] numa_node
  91  *   Pipeline NUMA node.
  92  * @return
  93  *   0 on success or the following error codes otherwise:
  94  *   -EINVAL: Invalid argument.
  95  */
  96 __rte_experimental
  97 int
  98 rte_swx_ctl_pipeline_numa_node_get(struct rte_swx_pipeline *p,
  99                                    int *numa_node);
 100
 101 /*
 102  * Ports Query API.
 103  */
 104
 105 /**
 106  * Input port statistics counters read
 107  *
 108  * @param[in] p
 109  *   Pipeline handle.
 110  * @param[in] port_id
 111  *   Port ID (0 .. *n_ports_in* - 1).
 112  * @param[out] stats
 113  *   Input port stats.
 114  * @return
 115  *   0 on success or the following error codes otherwise:
 116  *   -EINVAL: Invalid argument.
 117  */
 118 __rte_experimental
 119 int
 120 rte_swx_ctl_pipeline_port_in_stats_read(struct rte_swx_pipeline *p,
 121                                         uint32_t port_id,
 122                                         struct rte_swx_port_in_stats *stats);
 123
 124 /**
 125  * Output port statistics counters read
 126  *
 127  * @param[in] p
 128  *   Pipeline handle.
 129  * @param[in] port_id
 130  *   Port ID (0 .. *n_ports_out* - 1).
 131  * @param[out] stats
 132  *   Output port stats.
 133  * @return
 134  *   0 on success or the following error codes otherwise:
 135  *   -EINVAL: Invalid argument.
 136  */
 137 __rte_experimental
 138 int
 139 rte_swx_ctl_pipeline_port_out_stats_read(struct rte_swx_pipeline *p,
 140                                          uint32_t port_id,
 141                                          struct rte_swx_port_out_stats *stats);
 142
 143 /*
 144  * Action Query API.
 145  */
 146
 147 /** Action info. */
 148 struct rte_swx_ctl_action_info {
 149         /** Action name. */
 150         char name[RTE_SWX_CTL_NAME_SIZE];
 151
 152         /** Number of action arguments. */
 153         uint32_t n_args;
 154 };
 155
 156 /**
 157  * Action info get
 158  *
 159  * @param[in] p
 160  *   Pipeline handle.
 161  * @param[in] action_id
 162  *   Action ID (0 .. *n_actions* - 1).
 163  * @param[out] action
 164  *   Action info.
 165  * @return
 166  *   0 on success or the following error codes otherwise:
 167  *   -EINVAL: Invalid argument.
 168  */
 169 __rte_experimental
 170 int
 171 rte_swx_ctl_action_info_get(struct rte_swx_pipeline *p,
 172                             uint32_t action_id,
 173                             struct rte_swx_ctl_action_info *action);
 174
 175 /** Action argument info. */
 176 struct rte_swx_ctl_action_arg_info {
 177         /** Action argument name. */
 178         char name[RTE_SWX_CTL_NAME_SIZE];
 179
 180         /** Action argument size (in bits). */
 181         uint32_t n_bits;
 182
 183         /** Non-zero (true) when this action argument must be stored in the
 184          * table in network byte order (NBO), zero when it must be stored in
 185          * host byte order (HBO).
 186          */
 187         int is_network_byte_order;
 188 };
 189
 190 /**
 191  * Action argument info get
 192  *
 193  * @param[in] p
 194  *   Pipeline handle.
 195  * @param[in] action_id
 196  *   Action ID (0 .. *n_actions* - 1).
 197  * @param[in] action_arg_id
 198  *   Action ID (0 .. *n_args* - 1).
 199  * @param[out] action_arg
 200  *   Action argument info.
 201  * @return
 202  *   0 on success or the following error codes otherwise:
 203  *   -EINVAL: Invalid argument.
 204  */
 205 __rte_experimental
 206 int
 207 rte_swx_ctl_action_arg_info_get(struct rte_swx_pipeline *p,
 208                                 uint32_t action_id,
 209                                 uint32_t action_arg_id,
 210                                 struct rte_swx_ctl_action_arg_info *action_arg);
 211
 212 /*
 213  * Table Query API.
 214  */
 215
 216 /** Table info. */
 217 struct rte_swx_ctl_table_info {
 218         /** Table name. */
 219         char name[RTE_SWX_CTL_NAME_SIZE];
 220
 221         /** Table creation arguments. */
 222         char args[RTE_SWX_CTL_NAME_SIZE];
 223
 224         /** Number of match fields. */
 225         uint32_t n_match_fields;
 226
 227         /** Number of actions. */
 228         uint32_t n_actions;
 229
 230         /** Non-zero (true) when the default action is constant, therefore it
 231          * cannot be changed; zero (false) when the default action not constant,
 232          * therefore it can be changed.
 233          */
 234         int default_action_is_const;
 235
 236         /** Table size parameter. */
 237         uint32_t size;
 238 };
 239
 240 /**
 241  * Table info get
 242  *
 243  * @param[in] p
 244  *   Pipeline handle.
 245  * @param[in] table_id
 246  *   Table ID (0 .. *n_tables* - 1).
 247  * @param[out] table
 248  *   Table info.
 249  * @return
 250  *   0 on success or the following error codes otherwise:
 251  *   -EINVAL: Invalid argument.
 252  */
 253 __rte_experimental
 254 int
 255 rte_swx_ctl_table_info_get(struct rte_swx_pipeline *p,
 256                            uint32_t table_id,
 257                            struct rte_swx_ctl_table_info *table);
 258
 259 /** Table match field info.
 260  *
 261  * If (n_bits, offset) are known for all the match fields of the table, then the
 262  * table (key_offset, key_size, key_mask0) can be computed.
 263  */
 264 struct rte_swx_ctl_table_match_field_info {
 265         /** Match type of the current match field. */
 266         enum rte_swx_table_match_type match_type;
 267
 268         /** Non-zero (true) when the current match field is part of a registered
 269          * header, zero (false) when it is part of the registered meta-data.
 270          */
 271         int is_header;
 272
 273         /** Match field size (in bits). */
 274         uint32_t n_bits;
 275
 276         /** Match field offset within its parent struct (one of the headers or
 277          * the meta-data).
 278          */
 279         uint32_t offset;
 280 };
 281
 282 /**
 283  * Table match field info get
 284  *
 285  * @param[in] p
 286  *   Pipeline handle.
 287  * @param[in] table_id
 288  *   Table ID (0 .. *n_tables*).
 289  * @param[in] match_field_id
 290  *   Match field ID (0 .. *n_match_fields* - 1).
 291  * @param[out] match_field
 292  *   Table match field info.
 293  * @return
 294  *   0 on success or the following error codes otherwise:
 295  *   -EINVAL: Invalid argument.
 296  */
 297 __rte_experimental
 298 int
 299 rte_swx_ctl_table_match_field_info_get(struct rte_swx_pipeline *p,
 300         uint32_t table_id,
 301         uint32_t match_field_id,
 302         struct rte_swx_ctl_table_match_field_info *match_field);
 303
 304 /** Table action info. */
 305 struct rte_swx_ctl_table_action_info {
 306         /** Action ID. */
 307         uint32_t action_id;
 308
 309         /**  When non-zero (true), the action can be assigned to regular table entries. */
 310         int action_is_for_table_entries;
 311
 312         /**  When non-zero (true), the action can be assigned to the table default entry. */
 313         int action_is_for_default_entry;
 314 };
 315
 316 /**
 317  * Table action info get
 318  *
 319  * @param[in] p
 320  *   Pipeline handle.
 321  * @param[in] table_id
 322  *   Table ID (0 .. *n_tables*).
 323  * @param[in] table_action_id
 324  *   Action index within the set of table actions (0 .. table n_actions - 1).
 325  *   Not to be confused with the action ID, which works at the pipeline level
 326  *   (0 .. pipeline n_actions - 1), which is precisely what this function
 327  *   returns as part of *table_action*.
 328  * @param[out] table_action
 329  *   Table action info.
 330  * @return
 331  *   0 on success or the following error codes otherwise:
 332  *   -EINVAL: Invalid argument.
 333  */
 334 __rte_experimental
 335 int
 336 rte_swx_ctl_table_action_info_get(struct rte_swx_pipeline *p,
 337         uint32_t table_id,
 338         uint32_t table_action_id,
 339         struct rte_swx_ctl_table_action_info *table_action);
 340
 341 /**
 342  * Table operations get
 343  *
 344  * @param[in] p
 345  *   Pipeline handle.
 346  * @param[in] table_id
 347  *   Table ID (0 .. *n_tables*).
 348  * @param[out] table_ops
 349  *   Table operations. Only valid when function returns success and *is_stub* is
 350  *   zero (false).
 351  * @param[out] is_stub
 352  *   A stub table is a table with no match fields. No "regular" table entries
 353  *   (i.e. entries other than the default entry) can be added to such a table,
 354  *   therefore the lookup operation always results in lookup miss. Non-zero
 355  *   (true) when the current table is a stub table, zero (false) otherwise.
 356  * @return
 357  *   0 on success or the following error codes otherwise:
 358  *   -EINVAL: Invalid argument.
 359  */
 360 __rte_experimental
 361 int
 362 rte_swx_ctl_table_ops_get(struct rte_swx_pipeline *p,
 363                           uint32_t table_id,
 364                           struct rte_swx_table_ops *table_ops,
 365                           int *is_stub);
 366
 367 /** Table statistics. */
 368 struct rte_swx_table_stats {
 369         /** Number of packets with lookup hit. */
 370         uint64_t n_pkts_hit;
 371
 372         /** Number of packets with lookup miss. */
 373         uint64_t n_pkts_miss;
 374
 375         /** Number of packets (with either lookup hit or miss) per pipeline
 376          * action. Array of pipeline *n_actions* elements indexed by the
 377          * pipeline-level *action_id*, therefore this array has the same size
 378          * for all the tables within the same pipeline.
 379          */
 380         uint64_t *n_pkts_action;
 381 };
 382
 383 /**
 384  * Table statistics counters read
 385  *
 386  * @param[in] p
 387  *   Pipeline handle.
 388  * @param[in] table_name
 389  *   Table name.
 390  * @param[out] stats
 391  *   Table stats. Must point to a pre-allocated structure. The *n_pkts_action*
 392  *   field also needs to be pre-allocated as array of pipeline *n_actions*
 393  *   elements. The pipeline actions that are not valid for the current table
 394  *   have their associated *n_pkts_action* element always set to zero.
 395  * @return
 396  *   0 on success or the following error codes otherwise:
 397  *   -EINVAL: Invalid argument.
 398  */
 399 __rte_experimental
 400 int
 401 rte_swx_ctl_pipeline_table_stats_read(struct rte_swx_pipeline *p,
 402                                       const char *table_name,
 403                                       struct rte_swx_table_stats *stats);
 404
 405 /*
 406  * Selector Table Query API.
 407  */
 408
 409 /** Selector info. */
 410 struct rte_swx_ctl_selector_info {
 411         /** Selector table name. */
 412         char name[RTE_SWX_CTL_NAME_SIZE];
 413
 414         /** Number of selector fields. */
 415         uint32_t n_selector_fields;
 416
 417         /** Maximum number of groups. */
 418         uint32_t n_groups_max;
 419
 420         /** Maximum number of members per group. */
 421         uint32_t n_members_per_group_max;
 422 };
 423
 424 /**
 425  * Selector table info get
 426  *
 427  * @param[in] p
 428  *   Pipeline handle.
 429  * @param[in] selector_id
 430  *   Selector table ID (0 .. *n_selectors* - 1).
 431  * @param[out] selector
 432  *   Selector table info.
 433  * @return
 434  *   0 on success or the following error codes otherwise:
 435  *   -EINVAL: Invalid argument.
 436  */
 437 __rte_experimental
 438 int
 439 rte_swx_ctl_selector_info_get(struct rte_swx_pipeline *p,
 440                               uint32_t selector_id,
 441                               struct rte_swx_ctl_selector_info *selector);
 442
 443 /**
 444  * Selector table "group ID" field info get
 445  *
 446  * @param[in] p
 447  *   Pipeline handle.
 448  * @param[in] selector_id
 449  *   Selector table ID (0 .. *n_selectors*).
 450  * @param[out] field
 451  *   Selector table "group ID" field info.
 452  * @return
 453  *   0 on success or the following error codes otherwise:
 454  *   -EINVAL: Invalid argument.
 455  */
 456 __rte_experimental
 457 int
 458 rte_swx_ctl_selector_group_id_field_info_get(struct rte_swx_pipeline *p,
 459                                              uint32_t selector_id,
 460                                              struct rte_swx_ctl_table_match_field_info *field);
 461
 462 /**
 463  * Sselector table selector field info get
 464  *
 465  * @param[in] p
 466  *   Pipeline handle.
 467  * @param[in] selector_id
 468  *   Selector table ID (0 .. *n_selectors*).
 469  * @param[in] selector_field_id
 470  *   Selector table selector field ID (0 .. *n_selector_fields* - 1).
 471  * @param[out] field
 472  *   Selector table selector field info.
 473  * @return
 474  *   0 on success or the following error codes otherwise:
 475  *   -EINVAL: Invalid argument.
 476  */
 477 __rte_experimental
 478 int
 479 rte_swx_ctl_selector_field_info_get(struct rte_swx_pipeline *p,
 480                                     uint32_t selector_id,
 481                                     uint32_t selector_field_id,
 482                                     struct rte_swx_ctl_table_match_field_info *field);
 483
 484 /**
 485  * Selector table "member ID" field info get
 486  *
 487  * @param[in] p
 488  *   Pipeline handle.
 489  * @param[in] selector_id
 490  *   Selector table ID (0 .. *n_selectors*).
 491  * @param[out] field
 492  *   Selector table "member ID" field info.
 493  * @return
 494  *   0 on success or the following error codes otherwise:
 495  *   -EINVAL: Invalid argument.
 496  */
 497 __rte_experimental
 498 int
 499 rte_swx_ctl_selector_member_id_field_info_get(struct rte_swx_pipeline *p,
 500                                               uint32_t selector_id,
 501                                               struct rte_swx_ctl_table_match_field_info *field);
 502
 503 /** Selector table statistics. */
 504 struct rte_swx_pipeline_selector_stats {
 505         /** Number of packets. */
 506         uint64_t n_pkts;
 507 };
 508
 509 /**
 510  * Selector table statistics counters read
 511  *
 512  * @param[in] p
 513  *   Pipeline handle.
 514  * @param[in] selector_name
 515  *   Selector table name.
 516  * @param[out] stats
 517  *   Selector table stats. Must point to a pre-allocated structure.
 518  * @return
 519  *   0 on success or the following error codes otherwise:
 520  *   -EINVAL: Invalid argument.
 521  */
 522 __rte_experimental
 523 int
 524 rte_swx_ctl_pipeline_selector_stats_read(struct rte_swx_pipeline *p,
 525                                          const char *selector_name,
 526                                          struct rte_swx_pipeline_selector_stats *stats);
 527
 528 /*
 529  * Learner Table Query API.
 530  */
 531
 532 /** Learner table info. */
 533 struct rte_swx_ctl_learner_info {
 534         /** Learner table name. */
 535         char name[RTE_SWX_CTL_NAME_SIZE];
 536
 537         /** Number of match fields. */
 538         uint32_t n_match_fields;
 539
 540         /** Number of actions. */
 541         uint32_t n_actions;
 542
 543         /** Non-zero (true) when the default action is constant, therefore it
 544          * cannot be changed; zero (false) when the default action not constant,
 545          * therefore it can be changed.
 546          */
 547         int default_action_is_const;
 548
 549         /** Learner table size parameter. */
 550         uint32_t size;
 551
 552         /** Number of possible key timeout values. */
 553         uint32_t n_key_timeouts;
 554 };
 555
 556 /**
 557  * Learner table info get
 558  *
 559  * @param[in] p
 560  *   Pipeline handle.
 561  * @param[in] learner_id
 562  *   Learner table ID (0 .. *n_learners* - 1).
 563  * @param[out] learner
 564  *   Learner table info.
 565  * @return
 566  *   0 on success or the following error codes otherwise:
 567  *   -EINVAL: Invalid argument.
 568  */
 569 __rte_experimental
 570 int
 571 rte_swx_ctl_learner_info_get(struct rte_swx_pipeline *p,
 572                              uint32_t learner_id,
 573                              struct rte_swx_ctl_learner_info *learner);
 574
 575 /**
 576  * Learner table match field info get
 577  *
 578  * @param[in] p
 579  *   Pipeline handle.
 580  * @param[in] learner_id
 581  *   Learner table ID (0 .. *n_learners* - 1).
 582  * @param[in] match_field_id
 583  *   Match field ID (0 .. *n_match_fields* - 1).
 584  * @param[out] match_field
 585  *   Learner table match field info.
 586  * @return
 587  *   0 on success or the following error codes otherwise:
 588  *   -EINVAL: Invalid argument.
 589  */
 590 __rte_experimental
 591 int
 592 rte_swx_ctl_learner_match_field_info_get(struct rte_swx_pipeline *p,
 593                                          uint32_t learner_id,
 594                                          uint32_t match_field_id,
 595                                          struct rte_swx_ctl_table_match_field_info *match_field);
 596
 597 /**
 598  * Learner table action info get
 599  *
 600  * @param[in] p
 601  *   Pipeline handle.
 602  * @param[in] learner_id
 603  *   Learner table ID (0 .. *n_learners* - 1).
 604  * @param[in] learner_action_id
 605  *   Action index within the set of learner table actions (0 .. learner table n_actions - 1). Not
 606  *   to be confused with the pipeline-leve action ID (0 .. pipeline n_actions - 1), which is
 607  *   precisely what this function returns as part of the *learner_action*.
 608  * @param[out] learner_action
 609  *   Learner action info.
 610  * @return
 611  *   0 on success or the following error codes otherwise:
 612  *   -EINVAL: Invalid argument.
 613  */
 614 __rte_experimental
 615 int
 616 rte_swx_ctl_learner_action_info_get(struct rte_swx_pipeline *p,
 617                                     uint32_t learner_id,
 618                                     uint32_t learner_action_id,
 619                                     struct rte_swx_ctl_table_action_info *learner_action);
 620
 621 /**
 622  * Learner table timeout get
 623  *
 624  * @param[in] p
 625  *   Pipeline handle.
 626  * @param[in] learner_id
 627  *   Learner table ID (0 .. *n_learners* - 1).
 628  * @param[in] timeout_id
 629  *   Timeout ID.
 630  * @param[out] timeout
 631  *   Timeout value measured in seconds. Must be non-NULL.
 632  * @return
 633  *   0 on success or the following error codes otherwise:
 634  *   -EINVAL: Invalid argument.
 635  */
 636 __rte_experimental
 637 int
 638 rte_swx_ctl_pipeline_learner_timeout_get(struct rte_swx_pipeline *p,
 639                                          uint32_t learner_id,
 640                                          uint32_t timeout_id,
 641                                          uint32_t *timeout);
 642
 643 /**
 644  * Learner table timeout set
 645  *
 646  * @param[in] p
 647  *   Pipeline handle.
 648  * @param[in] learner_id
 649  *   Learner table ID (0 .. *n_learners* - 1).
 650  * @param[in] timeout_id
 651  *   Timeout ID.
 652  * @param[in] timeout
 653  *   Timeout value measured in seconds.
 654  * @return
 655  *   0 on success or the following error codes otherwise:
 656  *   -EINVAL: Invalid argument.
 657  */
 658 __rte_experimental
 659 int
 660 rte_swx_ctl_pipeline_learner_timeout_set(struct rte_swx_pipeline *p,
 661                                          uint32_t learner_id,
 662                                          uint32_t timeout_id,
 663                                          uint32_t timeout);
 664
 665 /** Learner table statistics. */
 666 struct rte_swx_learner_stats {
 667         /** Number of packets with lookup hit. */
 668         uint64_t n_pkts_hit;
 669
 670         /** Number of packets with lookup miss. */
 671         uint64_t n_pkts_miss;
 672
 673         /** Number of packets with successful learning. */
 674         uint64_t n_pkts_learn_ok;
 675
 676         /** Number of packets with learning error. */
 677         uint64_t n_pkts_learn_err;
 678
 679         /** Number of packets with rearm event. */
 680         uint64_t n_pkts_rearm;
 681
 682         /** Number of packets with forget event. */
 683         uint64_t n_pkts_forget;
 684
 685         /** Number of packets (with either lookup hit or miss) per pipeline action. Array of
 686          * pipeline *n_actions* elements indexed by the pipeline-level *action_id*, therefore this
 687          * array has the same size for all the tables within the same pipeline.
 688          */
 689         uint64_t *n_pkts_action;
 690 };
 691
 692 /**
 693  * Learner table statistics counters read
 694  *
 695  * @param[in] p
 696  *   Pipeline handle.
 697  * @param[in] learner_name
 698  *   Learner table name.
 699  * @param[out] stats
 700  *   Learner table stats. Must point to a pre-allocated structure. The *n_pkts_action* field also
 701  *   needs to be pre-allocated as array of pipeline *n_actions* elements. The pipeline actions that
 702  *   are not valid for the current learner table have their associated *n_pkts_action* element
 703  *   always set to zero.
 704  * @return
 705  *   0 on success or the following error codes otherwise:
 706  *   -EINVAL: Invalid argument.
 707  */
 708 __rte_experimental
 709 int
 710 rte_swx_ctl_pipeline_learner_stats_read(struct rte_swx_pipeline *p,
 711                                       const char *learner_name,
 712                                       struct rte_swx_learner_stats *stats);
 713
 714 /*
 715  * Packet mirroring API.
 716  */
 717
 718 /** Packet mirroring session parameters. */
 719 struct rte_swx_pipeline_mirroring_session_params {
 720         /** Output port ID. */
 721         uint32_t port_id;
 722
 723         /** Fast clone flag. */
 724         int fast_clone;
 725
 726         /** Truncation packet length (in bytes). Zero means no truncation. */
 727         uint32_t truncation_length;
 728 };
 729
 730 /**
 731  * Packet mirroring session set
 732  *
 733  * @param[in] p
 734  *   Pipeline handle.
 735  * @param[in] session_id
 736  *   Packet mirroring session ID.
 737  * @param[in] params
 738  *   Packet mirroring session parameters.
 739  * @return
 740  *   0 on success or the following error codes otherwise:
 741  *   -EINVAL: Invalid argument;
 742  *   -EEXIST: Pipeline was already built successfully.
 743  */
 744 __rte_experimental
 745 int
 746 rte_swx_ctl_pipeline_mirroring_session_set(struct rte_swx_pipeline *p,
 747         uint32_t session_id,
 748         struct rte_swx_pipeline_mirroring_session_params *params);
 749
 750 /*
 751  * Table Update API.
 752  */
 753
 754 /** Table state. */
 755 struct rte_swx_table_state {
 756         /** Table object. */
 757         void *obj;
 758
 759         /** Action ID of the table default action. */
 760         uint64_t default_action_id;
 761
 762         /** Action data of the table default action. Ignored when the action
 763          * data size is zero; otherwise, action data size bytes are meaningful.
 764          */
 765         uint8_t *default_action_data;
 766 };
 767
 768 /**
 769  * Pipeline table state get
 770  *
 771  * @param[in] p
 772  *   Pipeline handle.
 773  * @param[out] table_state
 774  *   After successful execution, the *table_state* contains the pointer to the
 775  *   current pipeline table state, which is an array of *n_tables* elements,
 776  *   with array element i containing the state of the i-th pipeline table. The
 777  *   pipeline continues to own all the data structures directly or indirectly
 778  *   referenced by the *table_state* until the subsequent successful invocation
 779  *   of function *rte_swx_pipeline_table_state_set*.
 780  * @return
 781  *   0 on success or the following error codes otherwise:
 782  *   -EINVAL: Invalid argument.
 783  */
 784 __rte_experimental
 785 int
 786 rte_swx_pipeline_table_state_get(struct rte_swx_pipeline *p,
 787                                  struct rte_swx_table_state **table_state);
 788
 789 /**
 790  * Pipeline table state set
 791  *
 792  * @param[in] p
 793  *   Pipeline handle.
 794  * @param[out] table_state
 795  *   After successful execution, the pipeline table state is updated to this
 796  *   *table_state*. The ownership of all the data structures directly or
 797  *   indirectly referenced by this *table_state* is passed from the caller to
 798  *   the pipeline.
 799  * @return
 800  *   0 on success or the following error codes otherwise:
 801  *   -EINVAL: Invalid argument.
 802  */
 803 __rte_experimental
 804 int
 805 rte_swx_pipeline_table_state_set(struct rte_swx_pipeline *p,
 806                                  struct rte_swx_table_state *table_state);
 807
 808 /*
 809  * High Level Reference Table Update API.
 810  */
 811
 812 /** Pipeline control opaque data structure. */
 813 struct rte_swx_ctl_pipeline;
 814
 815 /**
 816  * Pipeline control create
 817  *
 818  * @param[in] p
 819  *   Pipeline handle.
 820  * @return
 821  *   Pipeline control handle, on success, or NULL, on error.
 822  */
 823 __rte_experimental
 824 struct rte_swx_ctl_pipeline *
 825 rte_swx_ctl_pipeline_create(struct rte_swx_pipeline *p);
 826
 827 /**
 828  * Pipeline table entry add
 829  *
 830  * Schedule entry for addition to table or update as part of the next commit
 831  * operation.
 832  *
 833  * @param[in] ctl
 834  *   Pipeline control handle.
 835  * @param[in] table_name
 836  *   Table name.
 837  * @param[in] entry
 838  *   Entry to be added to the table.
 839  * @return
 840  *   0 on success or the following error codes otherwise:
 841  *   -EINVAL: Invalid argument.
 842  */
 843 __rte_experimental
 844 int
 845 rte_swx_ctl_pipeline_table_entry_add(struct rte_swx_ctl_pipeline *ctl,
 846                                      const char *table_name,
 847                                      struct rte_swx_table_entry *entry);
 848
 849 /**
 850  * Pipeline table default entry add
 851  *
 852  * Schedule table default entry update as part of the next commit operation.
 853  *
 854  * @param[in] ctl
 855  *   Pipeline control handle.
 856  * @param[in] table_name
 857  *   Table name.
 858  * @param[in] entry
 859  *   The new table default entry. The *key* and *key_mask* entry fields are
 860  *   ignored.
 861  * @return
 862  *   0 on success or the following error codes otherwise:
 863  *   -EINVAL: Invalid argument.
 864  */
 865 __rte_experimental
 866 int
 867 rte_swx_ctl_pipeline_table_default_entry_add(struct rte_swx_ctl_pipeline *ctl,
 868                                              const char *table_name,
 869                                              struct rte_swx_table_entry *entry);
 870
 871 /**
 872  * Pipeline table entry delete
 873  *
 874  * Schedule entry for deletion from table as part of the next commit operation.
 875  * Request is silently discarded if no such entry exists.
 876  *
 877  * @param[in] ctl
 878  *   Pipeline control handle.
 879  * @param[in] table_name
 880  *   Table name.
 881  * @param[in] entry
 882  *   Entry to be deleted from the table. The *action_id* and *action_data* entry
 883  *   fields are ignored.
 884  * @return
 885  *   0 on success or the following error codes otherwise:
 886  *   -EINVAL: Invalid argument.
 887  */
 888 __rte_experimental
 889 int
 890 rte_swx_ctl_pipeline_table_entry_delete(struct rte_swx_ctl_pipeline *ctl,
 891                                         const char *table_name,
 892                                         struct rte_swx_table_entry *entry);
 893
 894 /**
 895  * Pipeline selector table group add
 896  *
 897  * Add a new group to a selector table. This operation is executed before this
 898  * function returns and its result is independent of the result of the next
 899  * commit operation.
 900  *
 901  * @param[in] ctl
 902  *   Pipeline control handle.
 903  * @param[in] selector_name
 904  *   Selector table name.
 905  * @param[out] group_id
 906  *   The ID of the new group. Only valid when the function call is successful.
 907  *   This group is initially empty, i.e. it does not contain any members.
 908  * @return
 909  *   0 on success or the following error codes otherwise:
 910  *   -EINVAL: Invalid argument;
 911  *   -ENOSPC: All groups are currently in use, no group available.
 912  */
 913 __rte_experimental
 914 int
 915 rte_swx_ctl_pipeline_selector_group_add(struct rte_swx_ctl_pipeline *ctl,
 916                                         const char *selector_name,
 917                                         uint32_t *group_id);
 918
 919 /**
 920  * Pipeline selector table group delete
 921  *
 922  * Schedule a group for deletion as part of the next commit operation. The group
 923  * to be deleted can be empty or non-empty.
 924  *
 925  * @param[in] ctl
 926  *   Pipeline control handle.
 927  * @param[in] selector_name
 928  *   Selector table name.
 929  * @param[in] group_id
 930  *   Group to be deleted from the selector table.
 931  * @return
 932  *   0 on success or the following error codes otherwise:
 933  *   -EINVAL: Invalid argument;
 934  *   -ENOMEM: Not enough memory.
 935  */
 936 __rte_experimental
 937 int
 938 rte_swx_ctl_pipeline_selector_group_delete(struct rte_swx_ctl_pipeline *ctl,
 939                                            const char *selector_name,
 940                                            uint32_t group_id);
 941
 942 /**
 943  * Pipeline selector table member add to group
 944  *
 945  * Schedule the operation to add a new member to an existing group as part of
 946  * the next commit operation. If this member is already in this group, the
 947  * member weight is updated to the new value. A weight of zero means this member
 948  * is to be deleted from the group.
 949  *
 950  * @param[in] ctl
 951  *   Pipeline control handle.
 952  * @param[in] selector_name
 953  *   Selector table name.
 954  * @param[in] group_id
 955  *   The group ID.
 956  * @param[in] member_id
 957  *   The member to be added to the group.
 958  * @param[in] member_weight
 959  *   Member weight.
 960  * @return
 961  *   0 on success or the following error codes otherwise:
 962  *   -EINVAL: Invalid argument;
 963  *   -ENOMEM: Not enough memory;
 964  *   -ENOSPC: The group is full.
 965  */
 966 __rte_experimental
 967 int
 968 rte_swx_ctl_pipeline_selector_group_member_add(struct rte_swx_ctl_pipeline *ctl,
 969                                                const char *selector_name,
 970                                                uint32_t group_id,
 971                                                uint32_t member_id,
 972                                                uint32_t member_weight);
 973
 974 /**
 975  * Pipeline selector table member delete from group
 976  *
 977  * Schedule the operation to delete a member from an existing group as part of
 978  * the next commit operation.
 979  *
 980  * @param[in] ctl
 981  *   Pipeline control handle.
 982  * @param[in] selector_name
 983  *   Selector table name.
 984  * @param[in] group_id
 985  *   The group ID. Must be valid.
 986  * @param[in] member_id
 987  *   The member to be added to the group. Must be valid.
 988  * @return
 989  *   0 on success or the following error codes otherwise:
 990  *   -EINVAL: Invalid argument.
 991  */
 992 __rte_experimental
 993 int
 994 rte_swx_ctl_pipeline_selector_group_member_delete(struct rte_swx_ctl_pipeline *ctl,
 995                                                   const char *selector_name,
 996                                                   uint32_t group_id,
 997                                                   uint32_t member_id);
 998
 999 /**
1000  * Pipeline learner table default entry add
1001  *
1002  * Schedule learner table default entry update as part of the next commit operation.
1003  *
1004  * @param[in] ctl
1005  *   Pipeline control handle.
1006  * @param[in] learner_name
1007  *   Learner table name.
1008  * @param[in] entry
1009  *   The new table default entry. The *key* and *key_mask* entry fields are ignored.
1010  * @return
1011  *   0 on success or the following error codes otherwise:
1012  *   -EINVAL: Invalid argument.
1013  */
1014 __rte_experimental
1015 int
1016 rte_swx_ctl_pipeline_learner_default_entry_add(struct rte_swx_ctl_pipeline *ctl,
1017                                                const char *learner_name,
1018                                                struct rte_swx_table_entry *entry);
1019
1020 /**
1021  * Pipeline commit
1022  *
1023  * Perform all the scheduled table work.
1024  *
1025  * @param[in] ctl
1026  *   Pipeline control handle.
1027  * @param[in] abort_on_fail
1028  *   When non-zero (false), all the scheduled work is discarded after a failed
1029  *   commit. Otherwise, the scheduled work is still kept pending for the next
1030  *   commit.
1031  * @return
1032  *   0 on success or the following error codes otherwise:
1033  *   -EINVAL: Invalid argument.
1034  */
1035 __rte_experimental
1036 int
1037 rte_swx_ctl_pipeline_commit(struct rte_swx_ctl_pipeline *ctl,
1038                             int abort_on_fail);
1039
1040 /**
1041  * Pipeline abort
1042  *
1043  * Discard all the scheduled table work.
1044  *
1045  * @param[in] ctl
1046  *   Pipeline control handle.
1047  */
1048 __rte_experimental
1049 void
1050 rte_swx_ctl_pipeline_abort(struct rte_swx_ctl_pipeline *ctl);
1051
1052 /**
1053  * Pipeline table entry read
1054  *
1055  * Read table entry from string.
1056  *
1057  * @param[in] ctl
1058  *   Pipeline control handle.
1059  * @param[in] table_name
1060  *   Table name.
1061  * @param[in] string
1062  *   String containing the table entry.
1063  * @param[out] is_blank_or_comment
1064  *   On error, this argument provides an indication of whether *string* contains
1065  *   an invalid table entry (set to zero) or a blank or comment line that should
1066  *   typically be ignored (set to a non-zero value).
1067  * @return
1068  *   0 on success or the following error codes otherwise:
1069  *   -EINVAL: Invalid argument.
1070  */
1071 __rte_experimental
1072 struct rte_swx_table_entry *
1073 rte_swx_ctl_pipeline_table_entry_read(struct rte_swx_ctl_pipeline *ctl,
1074                                       const char *table_name,
1075                                       const char *string,
1076                                       int *is_blank_or_comment);
1077
1078 /**
1079  * Pipeline learner table default entry read
1080  *
1081  * Read learner table default entry from string.
1082  *
1083  * @param[in] ctl
1084  *   Pipeline control handle.
1085  * @param[in] learner_name
1086  *   Learner table name.
1087  * @param[in] string
1088  *   String containing the learner table default entry.
1089  * @param[out] is_blank_or_comment
1090  *   On error, this argument provides an indication of whether *string* contains
1091  *   an invalid table entry (set to zero) or a blank or comment line that should
1092  *   typically be ignored (set to a non-zero value).
1093  * @return
1094  *   0 on success or the following error codes otherwise:
1095  *   -EINVAL: Invalid argument.
1096  */
1097 __rte_experimental
1098 struct rte_swx_table_entry *
1099 rte_swx_ctl_pipeline_learner_default_entry_read(struct rte_swx_ctl_pipeline *ctl,
1100                                                 const char *learner_name,
1101                                                 const char *string,
1102                                                 int *is_blank_or_comment);
1103
1104 /**
1105  * Pipeline table print to file
1106  *
1107  * Print all the table entries to file.
1108  *
1109  * @param[in] f
1110  *   Output file.
1111  * @param[in] ctl
1112  *   Pipeline control handle.
1113  * @param[in] table_name
1114  *   Table name.
1115  * @return
1116  *   0 on success or the following error codes otherwise:
1117  *   -EINVAL: Invalid argument.
1118  */
1119 __rte_experimental
1120 int
1121 rte_swx_ctl_pipeline_table_fprintf(FILE *f,
1122                                    struct rte_swx_ctl_pipeline *ctl,
1123                                    const char *table_name);
1124
1125 /**
1126  * Pipeline selector print to file
1127  *
1128  * Print all the selector entries to file.
1129  *
1130  * @param[in] f
1131  *   Output file.
1132  * @param[in] ctl
1133  *   Pipeline control handle.
1134  * @param[in] selector_name
1135  *   Selector table name.
1136  * @return
1137  *   0 on success or the following error codes otherwise:
1138  *   -EINVAL: Invalid argument.
1139  */
1140 __rte_experimental
1141 int
1142 rte_swx_ctl_pipeline_selector_fprintf(FILE *f,
1143                                       struct rte_swx_ctl_pipeline *ctl,
1144                                       const char *selector_name);
1145
1146 /*
1147  * Register Array Query API.
1148  */
1149
1150 /** Register array info. */
1151 struct rte_swx_ctl_regarray_info {
1152         /** Register array name. */
1153         char name[RTE_SWX_CTL_NAME_SIZE];
1154
1155         /** Register array size. */
1156         uint32_t size;
1157 };
1158
1159 /**
1160  * Register array info get
1161  *
1162  * @param[in] p
1163  *   Pipeline handle.
1164  * @param[in] regarray_id
1165  *   Register array ID (0 .. *n_regarrays* - 1).
1166  * @param[out] regarray
1167  *   Register array info.
1168  * @return
1169  *   0 on success or the following error codes otherwise:
1170  *   -EINVAL: Invalid argument.
1171  */
1172 __rte_experimental
1173 int
1174 rte_swx_ctl_regarray_info_get(struct rte_swx_pipeline *p,
1175                               uint32_t regarray_id,
1176                               struct rte_swx_ctl_regarray_info *regarray);
1177
1178 /**
1179  * Register read
1180  *
1181  * @param[in] p
1182  *   Pipeline handle.
1183  * @param[in] regarray_name
1184  *   Register array name.
1185  * @param[in] regarray_index
1186  *   Register index within the array (0 .. *size* - 1).
1187  * @param[out] value
1188  *   Current register value.
1189  * @return
1190  *   0 on success or the following error codes otherwise:
1191  *   -EINVAL: Invalid argument.
1192  */
1193 __rte_experimental
1194 int
1195 rte_swx_ctl_pipeline_regarray_read(struct rte_swx_pipeline *p,
1196                                    const char *regarray_name,
1197                                    uint32_t regarray_index,
1198                                    uint64_t *value);
1199
1200 /**
1201  * Register write
1202  *
1203  * @param[in] p
1204  *   Pipeline handle.
1205  * @param[in] regarray_name
1206  *   Register array name.
1207  * @param[in] regarray_index
1208  *   Register index within the array (0 .. *size* - 1).
1209  * @param[in] value
1210  *   Value to be written to the register.
1211  * @return
1212  *   0 on success or the following error codes otherwise:
1213  *   -EINVAL: Invalid argument.
1214  */
1215 __rte_experimental
1216 int
1217 rte_swx_ctl_pipeline_regarray_write(struct rte_swx_pipeline *p,
1218                                    const char *regarray_name,
1219                                    uint32_t regarray_index,
1220                                    uint64_t value);
1221
1222 /*
1223  * Meter Array Query and Configuration API.
1224  */
1225
1226 /** Meter array info. */
1227 struct rte_swx_ctl_metarray_info {
1228         /** Meter array name. */
1229         char name[RTE_SWX_CTL_NAME_SIZE];
1230
1231         /** Meter array size. */
1232         uint32_t size;
1233 };
1234
1235 /**
1236  * Meter array info get
1237  *
1238  * @param[in] p
1239  *   Pipeline handle.
1240  * @param[in] metarray_id
1241  *   Meter array ID (0 .. *n_metarrays* - 1).
1242  * @param[out] metarray
1243  *   Meter array info.
1244  * @return
1245  *   0 on success or the following error codes otherwise:
1246  *   -EINVAL: Invalid argument.
1247  */
1248 __rte_experimental
1249 int
1250 rte_swx_ctl_metarray_info_get(struct rte_swx_pipeline *p,
1251                               uint32_t metarray_id,
1252                               struct rte_swx_ctl_metarray_info *metarray);
1253
1254 /**
1255  * Meter profile add
1256  *
1257  * @param[in] p
1258  *   Pipeline handle.
1259  * @param[in] name
1260  *   Meter profile name.
1261  * @param[in] params
1262  *   Meter profile parameters.
1263  * @return
1264  *   0 on success or the following error codes otherwise:
1265  *   -EINVAL: Invalid argument;
1266  *   -ENOMEM: Not enough space/cannot allocate memory;
1267  *   -EEXIST: Meter profile with this name already exists.
1268  */
1269 __rte_experimental
1270 int
1271 rte_swx_ctl_meter_profile_add(struct rte_swx_pipeline *p,
1272                               const char *name,
1273                               struct rte_meter_trtcm_params *params);
1274
1275 /**
1276  * Meter profile delete
1277  *
1278  * @param[in] p
1279  *   Pipeline handle.
1280  * @param[in] name
1281  *   Meter profile name.
1282  * @return
1283  *   0 on success or the following error codes otherwise:
1284  *   -EINVAL: Invalid argument;
1285  *   -EBUSY: Meter profile is currently in use.
1286  */
1287 __rte_experimental
1288 int
1289 rte_swx_ctl_meter_profile_delete(struct rte_swx_pipeline *p,
1290                                  const char *name);
1291
1292 /**
1293  * Meter reset
1294  *
1295  * Reset a meter within a given meter array to use the default profile that
1296  * causes all the input packets to be colored as green. It is the responsibility
1297  * of the control plane to make sure this meter is not used by the data plane
1298  * pipeline before calling this function.
1299  *
1300  * @param[in] p
1301  *   Pipeline handle.
1302  * @param[in] metarray_name
1303  *   Meter array name.
1304  * @param[in] metarray_index
1305  *   Meter index within the meter array.
1306  * @return
1307  *   0 on success or the following error codes otherwise:
1308  *   -EINVAL: Invalid argument.
1309  */
1310 __rte_experimental
1311 int
1312 rte_swx_ctl_meter_reset(struct rte_swx_pipeline *p,
1313                         const char *metarray_name,
1314                         uint32_t metarray_index);
1315
1316 /**
1317  * Meter set
1318  *
1319  * Set a meter within a given meter array to use a specific profile. It is the
1320  * responsibility of the control plane to make sure this meter is not used by
1321  * the data plane pipeline before calling this function.
1322  *
1323  * @param[in] p
1324  *   Pipeline handle.
1325  * @param[in] metarray_name
1326  *   Meter array name.
1327  * @param[in] metarray_index
1328  *   Meter index within the meter array.
1329  * @param[in] profile_name
1330  *   Existing meter profile name.
1331  * @return
1332  *   0 on success or the following error codes otherwise:
1333  *   -EINVAL: Invalid argument.
1334  */
1335 __rte_experimental
1336 int
1337 rte_swx_ctl_meter_set(struct rte_swx_pipeline *p,
1338                       const char *metarray_name,
1339                       uint32_t metarray_index,
1340                       const char *profile_name);
1341
1342 /** Meter statistics counters. */
1343 struct rte_swx_ctl_meter_stats {
1344         /** Number of packets tagged by the meter for each color. */
1345         uint64_t n_pkts[RTE_COLORS];
1346
1347         /** Number of bytes tagged by the meter for each color. */
1348         uint64_t n_bytes[RTE_COLORS];
1349 };
1350
1351 /**
1352  * Meter statistics counters read
1353  *
1354  * @param[in] p
1355  *   Pipeline handle.
1356  * @param[in] metarray_name
1357  *   Meter array name.
1358  * @param[in] metarray_index
1359  *   Meter index within the meter array.
1360  * @param[out] stats
1361  *   Meter statistics counters.
1362  * @return
1363  *   0 on success or the following error codes otherwise:
1364  *   -EINVAL: Invalid argument.
1365  */
1366 __rte_experimental
1367 int
1368 rte_swx_ctl_meter_stats_read(struct rte_swx_pipeline *p,
1369                              const char *metarray_name,
1370                              uint32_t metarray_index,
1371                              struct rte_swx_ctl_meter_stats *stats);
1372
1373 /**
1374  * Pipeline control free
1375  *
1376  * @param[in] ctl
1377  *   Pipeline control handle.
1378  */
1379 __rte_experimental
1380 void
1381 rte_swx_ctl_pipeline_free(struct rte_swx_ctl_pipeline *ctl);
1382
1383 #ifdef __cplusplus
1384 }
1385 #endif
1386
1387 #endif