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