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
 306 /**
 307  * Table action info get
 308  *
 309  * @param[in] p
 310  *   Pipeline handle.
 311  * @param[in] table_id
 312  *   Table ID (0 .. *n_tables*).
 313  * @param[in] table_action_id
 314  *   Action index within the set of table actions (0 .. table n_actions - 1).
 315  *   Not to be confused with the action ID, which works at the pipeline level
 316  *   (0 .. pipeline n_actions - 1), which is precisely what this function
 317  *   returns as part of *table_action*.
 318  * @param[out] table_action
 319  *   Table action info.
 320  * @return
 321  *   0 on success or the following error codes otherwise:
 322  *   -EINVAL: Invalid argument.
 323  */
 324 __rte_experimental
 325 int
 326 rte_swx_ctl_table_action_info_get(struct rte_swx_pipeline *p,
 327         uint32_t table_id,
 328         uint32_t table_action_id,
 329         struct rte_swx_ctl_table_action_info *table_action);
 330
 331 /**
 332  * Table operations get
 333  *
 334  * @param[in] p
 335  *   Pipeline handle.
 336  * @param[in] table_id
 337  *   Table ID (0 .. *n_tables*).
 338  * @param[out] table_ops
 339  *   Table operations. Only valid when function returns success and *is_stub* is
 340  *   zero (false).
 341  * @param[out] is_stub
 342  *   A stub table is a table with no match fields. No "regular" table entries
 343  *   (i.e. entries other than the default entry) can be added to such a table,
 344  *   therefore the lookup operation always results in lookup miss. Non-zero
 345  *   (true) when the current table is a stub table, zero (false) otherwise.
 346  * @return
 347  *   0 on success or the following error codes otherwise:
 348  *   -EINVAL: Invalid argument.
 349  */
 350 __rte_experimental
 351 int
 352 rte_swx_ctl_table_ops_get(struct rte_swx_pipeline *p,
 353                           uint32_t table_id,
 354                           struct rte_swx_table_ops *table_ops,
 355                           int *is_stub);
 356
 357 /** Table statistics. */
 358 struct rte_swx_table_stats {
 359         /** Number of packets with lookup hit. */
 360         uint64_t n_pkts_hit;
 361
 362         /** Number of packets with lookup miss. */
 363         uint64_t n_pkts_miss;
 364
 365         /** Number of packets (with either lookup hit or miss) per pipeline
 366          * action. Array of pipeline *n_actions* elements indedex by the
 367          * pipeline-level *action_id*, therefore this array has the same size
 368          * for all the tables within the same pipeline.
 369          */
 370         uint64_t *n_pkts_action;
 371 };
 372
 373 /**
 374  * Table statistics counters read
 375  *
 376  * @param[in] p
 377  *   Pipeline handle.
 378  * @param[in] table_name
 379  *   Table name.
 380  * @param[out] stats
 381  *   Table stats. Must point to a pre-allocated structure. The *n_pkts_action*
 382  *   field also needs to be pre-allocated as array of pipeline *n_actions*
 383  *   elements. The pipeline actions that are not valid for the current table
 384  *   have their associated *n_pkts_action* element always set to zero.
 385  * @return
 386  *   0 on success or the following error codes otherwise:
 387  *   -EINVAL: Invalid argument.
 388  */
 389 __rte_experimental
 390 int
 391 rte_swx_ctl_pipeline_table_stats_read(struct rte_swx_pipeline *p,
 392                                       const char *table_name,
 393                                       struct rte_swx_table_stats *stats);
 394
 395 /*
 396  * Selector Table Query API.
 397  */
 398
 399 /** Selector info. */
 400 struct rte_swx_ctl_selector_info {
 401         /** Selector table name. */
 402         char name[RTE_SWX_CTL_NAME_SIZE];
 403
 404         /** Number of selector fields. */
 405         uint32_t n_selector_fields;
 406
 407         /** Maximum number of groups. */
 408         uint32_t n_groups_max;
 409
 410         /** Maximum number of members per group. */
 411         uint32_t n_members_per_group_max;
 412 };
 413
 414 /**
 415  * Selector table info get
 416  *
 417  * @param[in] p
 418  *   Pipeline handle.
 419  * @param[in] selector_id
 420  *   Selector table ID (0 .. *n_selectors* - 1).
 421  * @param[out] selector
 422  *   Selector table info.
 423  * @return
 424  *   0 on success or the following error codes otherwise:
 425  *   -EINVAL: Invalid argument.
 426  */
 427 __rte_experimental
 428 int
 429 rte_swx_ctl_selector_info_get(struct rte_swx_pipeline *p,
 430                               uint32_t selector_id,
 431                               struct rte_swx_ctl_selector_info *selector);
 432
 433 /**
 434  * Selector table "group ID" field info get
 435  *
 436  * @param[in] p
 437  *   Pipeline handle.
 438  * @param[in] selector_id
 439  *   Selector table ID (0 .. *n_selectors*).
 440  * @param[out] field
 441  *   Selector table "group ID" field info.
 442  * @return
 443  *   0 on success or the following error codes otherwise:
 444  *   -EINVAL: Invalid argument.
 445  */
 446 __rte_experimental
 447 int
 448 rte_swx_ctl_selector_group_id_field_info_get(struct rte_swx_pipeline *p,
 449                                              uint32_t selector_id,
 450                                              struct rte_swx_ctl_table_match_field_info *field);
 451
 452 /**
 453  * Sselector table selector field info get
 454  *
 455  * @param[in] p
 456  *   Pipeline handle.
 457  * @param[in] selector_id
 458  *   Selector table ID (0 .. *n_selectors*).
 459  * @param[in] selector_field_id
 460  *   Selector table selector field ID (0 .. *n_selector_fields* - 1).
 461  * @param[out] field
 462  *   Selector table selector field info.
 463  * @return
 464  *   0 on success or the following error codes otherwise:
 465  *   -EINVAL: Invalid argument.
 466  */
 467 __rte_experimental
 468 int
 469 rte_swx_ctl_selector_field_info_get(struct rte_swx_pipeline *p,
 470                                     uint32_t selector_id,
 471                                     uint32_t selector_field_id,
 472                                     struct rte_swx_ctl_table_match_field_info *field);
 473
 474 /**
 475  * Selector table "member ID" field info get
 476  *
 477  * @param[in] p
 478  *   Pipeline handle.
 479  * @param[in] selector_id
 480  *   Selector table ID (0 .. *n_selectors*).
 481  * @param[out] field
 482  *   Selector table "member ID" field info.
 483  * @return
 484  *   0 on success or the following error codes otherwise:
 485  *   -EINVAL: Invalid argument.
 486  */
 487 __rte_experimental
 488 int
 489 rte_swx_ctl_selector_member_id_field_info_get(struct rte_swx_pipeline *p,
 490                                               uint32_t selector_id,
 491                                               struct rte_swx_ctl_table_match_field_info *field);
 492
 493 /** Selector table statistics. */
 494 struct rte_swx_pipeline_selector_stats {
 495         /** Number of packets. */
 496         uint64_t n_pkts;
 497 };
 498
 499 /**
 500  * Selector table statistics counters read
 501  *
 502  * @param[in] p
 503  *   Pipeline handle.
 504  * @param[in] selector_name
 505  *   Selector table name.
 506  * @param[out] stats
 507  *   Selector table stats. Must point to a pre-allocated structure.
 508  * @return
 509  *   0 on success or the following error codes otherwise:
 510  *   -EINVAL: Invalid argument.
 511  */
 512 __rte_experimental
 513 int
 514 rte_swx_ctl_pipeline_selector_stats_read(struct rte_swx_pipeline *p,
 515                                          const char *selector_name,
 516                                          struct rte_swx_pipeline_selector_stats *stats);
 517
 518 /*
 519  * Learner Table Query API.
 520  */
 521
 522 /** Learner table info. */
 523 struct rte_swx_ctl_learner_info {
 524         /** Learner table name. */
 525         char name[RTE_SWX_CTL_NAME_SIZE];
 526
 527         /** Number of match fields. */
 528         uint32_t n_match_fields;
 529
 530         /** Number of actions. */
 531         uint32_t n_actions;
 532
 533         /** Non-zero (true) when the default action is constant, therefore it
 534          * cannot be changed; zero (false) when the default action not constant,
 535          * therefore it can be changed.
 536          */
 537         int default_action_is_const;
 538
 539         /** Learner table size parameter. */
 540         uint32_t size;
 541 };
 542
 543 /**
 544  * Learner table info get
 545  *
 546  * @param[in] p
 547  *   Pipeline handle.
 548  * @param[in] learner_id
 549  *   Learner table ID (0 .. *n_learners* - 1).
 550  * @param[out] learner
 551  *   Learner table info.
 552  * @return
 553  *   0 on success or the following error codes otherwise:
 554  *   -EINVAL: Invalid argument.
 555  */
 556 __rte_experimental
 557 int
 558 rte_swx_ctl_learner_info_get(struct rte_swx_pipeline *p,
 559                              uint32_t learner_id,
 560                              struct rte_swx_ctl_learner_info *learner);
 561
 562 /**
 563  * Learner table match field info get
 564  *
 565  * @param[in] p
 566  *   Pipeline handle.
 567  * @param[in] learner_id
 568  *   Learner table ID (0 .. *n_learners* - 1).
 569  * @param[in] match_field_id
 570  *   Match field ID (0 .. *n_match_fields* - 1).
 571  * @param[out] match_field
 572  *   Learner table match field info.
 573  * @return
 574  *   0 on success or the following error codes otherwise:
 575  *   -EINVAL: Invalid argument.
 576  */
 577 __rte_experimental
 578 int
 579 rte_swx_ctl_learner_match_field_info_get(struct rte_swx_pipeline *p,
 580                                          uint32_t learner_id,
 581                                          uint32_t match_field_id,
 582                                          struct rte_swx_ctl_table_match_field_info *match_field);
 583
 584 /**
 585  * Learner table action info get
 586  *
 587  * @param[in] p
 588  *   Pipeline handle.
 589  * @param[in] learner_id
 590  *   Learner table ID (0 .. *n_learners* - 1).
 591  * @param[in] learner_action_id
 592  *   Action index within the set of learner table actions (0 .. learner table n_actions - 1). Not
 593  *   to be confused with the pipeline-leve action ID (0 .. pipeline n_actions - 1), which is
 594  *   precisely what this function returns as part of the *learner_action*.
 595  * @param[out] learner_action
 596  *   Learner action info.
 597  * @return
 598  *   0 on success or the following error codes otherwise:
 599  *   -EINVAL: Invalid argument.
 600  */
 601 __rte_experimental
 602 int
 603 rte_swx_ctl_learner_action_info_get(struct rte_swx_pipeline *p,
 604                                     uint32_t learner_id,
 605                                     uint32_t learner_action_id,
 606                                     struct rte_swx_ctl_table_action_info *learner_action);
 607
 608 /** Learner table statistics. */
 609 struct rte_swx_learner_stats {
 610         /** Number of packets with lookup hit. */
 611         uint64_t n_pkts_hit;
 612
 613         /** Number of packets with lookup miss. */
 614         uint64_t n_pkts_miss;
 615
 616         /** Number of packets with successful learning. */
 617         uint64_t n_pkts_learn_ok;
 618
 619         /** Number of packets with learning error. */
 620         uint64_t n_pkts_learn_err;
 621
 622         /** Number of packets with forget event. */
 623         uint64_t n_pkts_forget;
 624
 625         /** Number of packets (with either lookup hit or miss) per pipeline action. Array of
 626          * pipeline *n_actions* elements indedex by the pipeline-level *action_id*, therefore this
 627          * array has the same size for all the tables within the same pipeline.
 628          */
 629         uint64_t *n_pkts_action;
 630 };
 631
 632 /**
 633  * Learner table statistics counters read
 634  *
 635  * @param[in] p
 636  *   Pipeline handle.
 637  * @param[in] learner_name
 638  *   Learner table name.
 639  * @param[out] stats
 640  *   Learner table stats. Must point to a pre-allocated structure. The *n_pkts_action* field also
 641  *   needs to be pre-allocated as array of pipeline *n_actions* elements. The pipeline actions that
 642  *   are not valid for the current learner table have their associated *n_pkts_action* element
 643  *   always set to zero.
 644  * @return
 645  *   0 on success or the following error codes otherwise:
 646  *   -EINVAL: Invalid argument.
 647  */
 648 __rte_experimental
 649 int
 650 rte_swx_ctl_pipeline_learner_stats_read(struct rte_swx_pipeline *p,
 651                                       const char *learner_name,
 652                                       struct rte_swx_learner_stats *stats);
 653
 654 /*
 655  * Table Update API.
 656  */
 657
 658 /** Table state. */
 659 struct rte_swx_table_state {
 660         /** Table object. */
 661         void *obj;
 662
 663         /** Action ID of the table default action. */
 664         uint64_t default_action_id;
 665
 666         /** Action data of the table default action. Ignored when the action
 667          * data size is zero; otherwise, action data size bytes are meaningful.
 668          */
 669         uint8_t *default_action_data;
 670 };
 671
 672 /**
 673  * Pipeline table state get
 674  *
 675  * @param[in] p
 676  *   Pipeline handle.
 677  * @param[out] table_state
 678  *   After successful execution, the *table_state* contains the pointer to the
 679  *   current pipeline table state, which is an array of *n_tables* elements,
 680  *   with array element i containing the state of the i-th pipeline table. The
 681  *   pipeline continues to own all the data structures directly or indirectly
 682  *   referenced by the *table_state* until the subsequent successful invocation
 683  *   of function *rte_swx_pipeline_table_state_set*.
 684  * @return
 685  *   0 on success or the following error codes otherwise:
 686  *   -EINVAL: Invalid argument.
 687  */
 688 __rte_experimental
 689 int
 690 rte_swx_pipeline_table_state_get(struct rte_swx_pipeline *p,
 691                                  struct rte_swx_table_state **table_state);
 692
 693 /**
 694  * Pipeline table state set
 695  *
 696  * @param[in] p
 697  *   Pipeline handle.
 698  * @param[out] table_state
 699  *   After successful execution, the pipeline table state is updated to this
 700  *   *table_state*. The ownership of all the data structures directly or
 701  *   indirectly referenced by this *table_state* is passed from the caller to
 702  *   the pipeline.
 703  * @return
 704  *   0 on success or the following error codes otherwise:
 705  *   -EINVAL: Invalid argument.
 706  */
 707 __rte_experimental
 708 int
 709 rte_swx_pipeline_table_state_set(struct rte_swx_pipeline *p,
 710                                  struct rte_swx_table_state *table_state);
 711
 712 /*
 713  * High Level Reference Table Update API.
 714  */
 715
 716 /** Pipeline control opaque data structure. */
 717 struct rte_swx_ctl_pipeline;
 718
 719 /**
 720  * Pipeline control create
 721  *
 722  * @param[in] p
 723  *   Pipeline handle.
 724  * @return
 725  *   Pipeline control handle, on success, or NULL, on error.
 726  */
 727 __rte_experimental
 728 struct rte_swx_ctl_pipeline *
 729 rte_swx_ctl_pipeline_create(struct rte_swx_pipeline *p);
 730
 731 /**
 732  * Pipeline table entry add
 733  *
 734  * Schedule entry for addition to table or update as part of the next commit
 735  * operation.
 736  *
 737  * @param[in] ctl
 738  *   Pipeline control handle.
 739  * @param[in] table_name
 740  *   Table name.
 741  * @param[in] entry
 742  *   Entry to be added to the table.
 743  * @return
 744  *   0 on success or the following error codes otherwise:
 745  *   -EINVAL: Invalid argument.
 746  */
 747 __rte_experimental
 748 int
 749 rte_swx_ctl_pipeline_table_entry_add(struct rte_swx_ctl_pipeline *ctl,
 750                                      const char *table_name,
 751                                      struct rte_swx_table_entry *entry);
 752
 753 /**
 754  * Pipeline table default entry add
 755  *
 756  * Schedule table default entry update as part of the next commit operation.
 757  *
 758  * @param[in] ctl
 759  *   Pipeline control handle.
 760  * @param[in] table_name
 761  *   Table name.
 762  * @param[in] entry
 763  *   The new table default entry. The *key* and *key_mask* entry fields are
 764  *   ignored.
 765  * @return
 766  *   0 on success or the following error codes otherwise:
 767  *   -EINVAL: Invalid argument.
 768  */
 769 __rte_experimental
 770 int
 771 rte_swx_ctl_pipeline_table_default_entry_add(struct rte_swx_ctl_pipeline *ctl,
 772                                              const char *table_name,
 773                                              struct rte_swx_table_entry *entry);
 774
 775 /**
 776  * Pipeline table entry delete
 777  *
 778  * Schedule entry for deletion from table as part of the next commit operation.
 779  * Request is silently discarded if no such entry exists.
 780  *
 781  * @param[in] ctl
 782  *   Pipeline control handle.
 783  * @param[in] table_name
 784  *   Table name.
 785  * @param[in] entry
 786  *   Entry to be deleted from the table. The *action_id* and *action_data* entry
 787  *   fields are ignored.
 788  * @return
 789  *   0 on success or the following error codes otherwise:
 790  *   -EINVAL: Invalid argument.
 791  */
 792 __rte_experimental
 793 int
 794 rte_swx_ctl_pipeline_table_entry_delete(struct rte_swx_ctl_pipeline *ctl,
 795                                         const char *table_name,
 796                                         struct rte_swx_table_entry *entry);
 797
 798 /**
 799  * Pipeline selector table group add
 800  *
 801  * Add a new group to a selector table. This operation is executed before this
 802  * function returns and its result is independent of the result of the next
 803  * commit operation.
 804  *
 805  * @param[in] ctl
 806  *   Pipeline control handle.
 807  * @param[in] selector_name
 808  *   Selector table name.
 809  * @param[out] group_id
 810  *   The ID of the new group. Only valid when the function call is successful.
 811  *   This group is initially empty, i.e. it does not contain any members.
 812  * @return
 813  *   0 on success or the following error codes otherwise:
 814  *   -EINVAL: Invalid argument;
 815  *   -ENOSPC: All groups are currently in use, no group available.
 816  */
 817 __rte_experimental
 818 int
 819 rte_swx_ctl_pipeline_selector_group_add(struct rte_swx_ctl_pipeline *ctl,
 820                                         const char *selector_name,
 821                                         uint32_t *group_id);
 822
 823 /**
 824  * Pipeline selector table group delete
 825  *
 826  * Schedule a group for deletion as part of the next commit operation. The group
 827  * to be deleted can be empty or non-empty.
 828  *
 829  * @param[in] ctl
 830  *   Pipeline control handle.
 831  * @param[in] selector_name
 832  *   Selector table name.
 833  * @param[in] group_id
 834  *   Group to be deleted from the selector table.
 835  * @return
 836  *   0 on success or the following error codes otherwise:
 837  *   -EINVAL: Invalid argument;
 838  *   -ENOMEM: Not enough memory.
 839  */
 840 __rte_experimental
 841 int
 842 rte_swx_ctl_pipeline_selector_group_delete(struct rte_swx_ctl_pipeline *ctl,
 843                                            const char *selector_name,
 844                                            uint32_t group_id);
 845
 846 /**
 847  * Pipeline selector table member add to group
 848  *
 849  * Schedule the operation to add a new member to an existing group as part of
 850  * the next commit operation. If this member is already in this group, the
 851  * member weight is updated to the new value. A weight of zero means this member
 852  * is to be deleted from the group.
 853  *
 854  * @param[in] ctl
 855  *   Pipeline control handle.
 856  * @param[in] selector_name
 857  *   Selector table name.
 858  * @param[in] group_id
 859  *   The group ID.
 860  * @param[in] member_id
 861  *   The member to be added to the group.
 862  * @param[in] member_weight
 863  *   Member weight.
 864  * @return
 865  *   0 on success or the following error codes otherwise:
 866  *   -EINVAL: Invalid argument;
 867  *   -ENOMEM: Not enough memory;
 868  *   -ENOSPC: The group is full.
 869  */
 870 __rte_experimental
 871 int
 872 rte_swx_ctl_pipeline_selector_group_member_add(struct rte_swx_ctl_pipeline *ctl,
 873                                                const char *selector_name,
 874                                                uint32_t group_id,
 875                                                uint32_t member_id,
 876                                                uint32_t member_weight);
 877
 878 /**
 879  * Pipeline selector table member delete from group
 880  *
 881  * Schedule the operation to delete a member from an existing group as part of
 882  * the next commit operation.
 883  *
 884  * @param[in] ctl
 885  *   Pipeline control handle.
 886  * @param[in] selector_name
 887  *   Selector table name.
 888  * @param[in] group_id
 889  *   The group ID. Must be valid.
 890  * @param[in] member_id
 891  *   The member to be added to the group. Must be valid.
 892  * @return
 893  *   0 on success or the following error codes otherwise:
 894  *   -EINVAL: Invalid argument.
 895  */
 896 __rte_experimental
 897 int
 898 rte_swx_ctl_pipeline_selector_group_member_delete(struct rte_swx_ctl_pipeline *ctl,
 899                                                   const char *selector_name,
 900                                                   uint32_t group_id,
 901                                                   uint32_t member_id);
 902
 903 /**
 904  * Pipeline learner table default entry add
 905  *
 906  * Schedule learner table default entry update as part of the next commit operation.
 907  *
 908  * @param[in] ctl
 909  *   Pipeline control handle.
 910  * @param[in] learner_name
 911  *   Learner table name.
 912  * @param[in] entry
 913  *   The new table default entry. The *key* and *key_mask* entry fields are ignored.
 914  * @return
 915  *   0 on success or the following error codes otherwise:
 916  *   -EINVAL: Invalid argument.
 917  */
 918 __rte_experimental
 919 int
 920 rte_swx_ctl_pipeline_learner_default_entry_add(struct rte_swx_ctl_pipeline *ctl,
 921                                                const char *learner_name,
 922                                                struct rte_swx_table_entry *entry);
 923
 924 /**
 925  * Pipeline commit
 926  *
 927  * Perform all the scheduled table work.
 928  *
 929  * @param[in] ctl
 930  *   Pipeline control handle.
 931  * @param[in] abort_on_fail
 932  *   When non-zero (false), all the scheduled work is discarded after a failed
 933  *   commit. Otherwise, the scheduled work is still kept pending for the next
 934  *   commit.
 935  * @return
 936  *   0 on success or the following error codes otherwise:
 937  *   -EINVAL: Invalid argument.
 938  */
 939 __rte_experimental
 940 int
 941 rte_swx_ctl_pipeline_commit(struct rte_swx_ctl_pipeline *ctl,
 942                             int abort_on_fail);
 943
 944 /**
 945  * Pipeline abort
 946  *
 947  * Discard all the scheduled table work.
 948  *
 949  * @param[in] ctl
 950  *   Pipeline control handle.
 951  */
 952 __rte_experimental
 953 void
 954 rte_swx_ctl_pipeline_abort(struct rte_swx_ctl_pipeline *ctl);
 955
 956 /**
 957  * Pipeline table entry read
 958  *
 959  * Read table entry from string.
 960  *
 961  * @param[in] ctl
 962  *   Pipeline control handle.
 963  * @param[in] table_name
 964  *   Table name.
 965  * @param[in] string
 966  *   String containing the table entry.
 967  * @param[out] is_blank_or_comment
 968  *   On error, this argument provides an indication of whether *string* contains
 969  *   an invalid table entry (set to zero) or a blank or comment line that should
 970  *   typically be ignored (set to a non-zero value).
 971  * @return
 972  *   0 on success or the following error codes otherwise:
 973  *   -EINVAL: Invalid argument.
 974  */
 975 __rte_experimental
 976 struct rte_swx_table_entry *
 977 rte_swx_ctl_pipeline_table_entry_read(struct rte_swx_ctl_pipeline *ctl,
 978                                       const char *table_name,
 979                                       const char *string,
 980                                       int *is_blank_or_comment);
 981
 982 /**
 983  * Pipeline learner table default entry read
 984  *
 985  * Read learner table default entry from string.
 986  *
 987  * @param[in] ctl
 988  *   Pipeline control handle.
 989  * @param[in] learner_name
 990  *   Learner table name.
 991  * @param[in] string
 992  *   String containing the learner table default entry.
 993  * @param[out] is_blank_or_comment
 994  *   On error, this argument provides an indication of whether *string* contains
 995  *   an invalid table entry (set to zero) or a blank or comment line that should
 996  *   typically be ignored (set to a non-zero value).
 997  * @return
 998  *   0 on success or the following error codes otherwise:
 999  *   -EINVAL: Invalid argument.
1000  */
1001 __rte_experimental
1002 struct rte_swx_table_entry *
1003 rte_swx_ctl_pipeline_learner_default_entry_read(struct rte_swx_ctl_pipeline *ctl,
1004                                                 const char *learner_name,
1005                                                 const char *string,
1006                                                 int *is_blank_or_comment);
1007
1008 /**
1009  * Pipeline table print to file
1010  *
1011  * Print all the table entries to file.
1012  *
1013  * @param[in] f
1014  *   Output file.
1015  * @param[in] ctl
1016  *   Pipeline control handle.
1017  * @param[in] table_name
1018  *   Table name.
1019  * @return
1020  *   0 on success or the following error codes otherwise:
1021  *   -EINVAL: Invalid argument.
1022  */
1023 __rte_experimental
1024 int
1025 rte_swx_ctl_pipeline_table_fprintf(FILE *f,
1026                                    struct rte_swx_ctl_pipeline *ctl,
1027                                    const char *table_name);
1028
1029 /**
1030  * Pipeline selector print to file
1031  *
1032  * Print all the selector entries to file.
1033  *
1034  * @param[in] f
1035  *   Output file.
1036  * @param[in] ctl
1037  *   Pipeline control handle.
1038  * @param[in] selector_name
1039  *   Selector table name.
1040  * @return
1041  *   0 on success or the following error codes otherwise:
1042  *   -EINVAL: Invalid argument.
1043  */
1044 __rte_experimental
1045 int
1046 rte_swx_ctl_pipeline_selector_fprintf(FILE *f,
1047                                       struct rte_swx_ctl_pipeline *ctl,
1048                                       const char *selector_name);
1049
1050 /*
1051  * Register Array Query API.
1052  */
1053
1054 /** Register array info. */
1055 struct rte_swx_ctl_regarray_info {
1056         /** Register array name. */
1057         char name[RTE_SWX_CTL_NAME_SIZE];
1058
1059         /** Register array size. */
1060         uint32_t size;
1061 };
1062
1063 /**
1064  * Register array info get
1065  *
1066  * @param[in] p
1067  *   Pipeline handle.
1068  * @param[in] regarray_id
1069  *   Register array ID (0 .. *n_regarrays* - 1).
1070  * @param[out] regarray
1071  *   Register array info.
1072  * @return
1073  *   0 on success or the following error codes otherwise:
1074  *   -EINVAL: Invalid argument.
1075  */
1076 __rte_experimental
1077 int
1078 rte_swx_ctl_regarray_info_get(struct rte_swx_pipeline *p,
1079                               uint32_t regarray_id,
1080                               struct rte_swx_ctl_regarray_info *regarray);
1081
1082 /**
1083  * Register read
1084  *
1085  * @param[in] p
1086  *   Pipeline handle.
1087  * @param[in] regarray_name
1088  *   Register array name.
1089  * @param[in] regarray_index
1090  *   Register index within the array (0 .. *size* - 1).
1091  * @param[out] value
1092  *   Current register value.
1093  * @return
1094  *   0 on success or the following error codes otherwise:
1095  *   -EINVAL: Invalid argument.
1096  */
1097 __rte_experimental
1098 int
1099 rte_swx_ctl_pipeline_regarray_read(struct rte_swx_pipeline *p,
1100                                    const char *regarray_name,
1101                                    uint32_t regarray_index,
1102                                    uint64_t *value);
1103
1104 /**
1105  * Register write
1106  *
1107  * @param[in] p
1108  *   Pipeline handle.
1109  * @param[in] regarray_name
1110  *   Register array name.
1111  * @param[in] regarray_index
1112  *   Register index within the array (0 .. *size* - 1).
1113  * @param[in] value
1114  *   Value to be written to the register.
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_regarray_write(struct rte_swx_pipeline *p,
1122                                    const char *regarray_name,
1123                                    uint32_t regarray_index,
1124                                    uint64_t value);
1125
1126 /*
1127  * Meter Array Query and Configuration API.
1128  */
1129
1130 /** Meter array info. */
1131 struct rte_swx_ctl_metarray_info {
1132         /** Meter array name. */
1133         char name[RTE_SWX_CTL_NAME_SIZE];
1134
1135         /** Meter array size. */
1136         uint32_t size;
1137 };
1138
1139 /**
1140  * Meter array info get
1141  *
1142  * @param[in] p
1143  *   Pipeline handle.
1144  * @param[in] metarray_id
1145  *   Meter array ID (0 .. *n_metarrays* - 1).
1146  * @param[out] metarray
1147  *   Meter array info.
1148  * @return
1149  *   0 on success or the following error codes otherwise:
1150  *   -EINVAL: Invalid argument.
1151  */
1152 __rte_experimental
1153 int
1154 rte_swx_ctl_metarray_info_get(struct rte_swx_pipeline *p,
1155                               uint32_t metarray_id,
1156                               struct rte_swx_ctl_metarray_info *metarray);
1157
1158 /**
1159  * Meter profile add
1160  *
1161  * @param[in] p
1162  *   Pipeline handle.
1163  * @param[in] name
1164  *   Meter profile name.
1165  * @param[in] params
1166  *   Meter profile parameters.
1167  * @return
1168  *   0 on success or the following error codes otherwise:
1169  *   -EINVAL: Invalid argument;
1170  *   -ENOMEM: Not enough space/cannot allocate memory;
1171  *   -EEXIST: Meter profile with this name already exists.
1172  */
1173 __rte_experimental
1174 int
1175 rte_swx_ctl_meter_profile_add(struct rte_swx_pipeline *p,
1176                               const char *name,
1177                               struct rte_meter_trtcm_params *params);
1178
1179 /**
1180  * Meter profile delete
1181  *
1182  * @param[in] p
1183  *   Pipeline handle.
1184  * @param[in] name
1185  *   Meter profile name.
1186  * @return
1187  *   0 on success or the following error codes otherwise:
1188  *   -EINVAL: Invalid argument;
1189  *   -EBUSY: Meter profile is currently in use.
1190  */
1191 __rte_experimental
1192 int
1193 rte_swx_ctl_meter_profile_delete(struct rte_swx_pipeline *p,
1194                                  const char *name);
1195
1196 /**
1197  * Meter reset
1198  *
1199  * Reset a meter within a given meter array to use the default profile that
1200  * causes all the input packets to be colored as green. It is the responsibility
1201  * of the control plane to make sure this meter is not used by the data plane
1202  * pipeline before calling this function.
1203  *
1204  * @param[in] p
1205  *   Pipeline handle.
1206  * @param[in] metarray_name
1207  *   Meter array name.
1208  * @param[in] metarray_index
1209  *   Meter index within the meter array.
1210  * @return
1211  *   0 on success or the following error codes otherwise:
1212  *   -EINVAL: Invalid argument.
1213  */
1214 __rte_experimental
1215 int
1216 rte_swx_ctl_meter_reset(struct rte_swx_pipeline *p,
1217                         const char *metarray_name,
1218                         uint32_t metarray_index);
1219
1220 /**
1221  * Meter set
1222  *
1223  * Set a meter within a given meter array to use a specific profile. It is the
1224  * responsibility of the control plane to make sure this meter is not used by
1225  * the data plane pipeline before calling this function.
1226  *
1227  * @param[in] p
1228  *   Pipeline handle.
1229  * @param[in] metarray_name
1230  *   Meter array name.
1231  * @param[in] metarray_index
1232  *   Meter index within the meter array.
1233  * @param[in] profile_name
1234  *   Existing meter profile name.
1235  * @return
1236  *   0 on success or the following error codes otherwise:
1237  *   -EINVAL: Invalid argument.
1238  */
1239 __rte_experimental
1240 int
1241 rte_swx_ctl_meter_set(struct rte_swx_pipeline *p,
1242                       const char *metarray_name,
1243                       uint32_t metarray_index,
1244                       const char *profile_name);
1245
1246 /** Meter statistics counters. */
1247 struct rte_swx_ctl_meter_stats {
1248         /** Number of packets tagged by the meter for each color. */
1249         uint64_t n_pkts[RTE_COLORS];
1250
1251         /** Number of bytes tagged by the meter for each color. */
1252         uint64_t n_bytes[RTE_COLORS];
1253 };
1254
1255 /**
1256  * Meter statistics counters read
1257  *
1258  * @param[in] p
1259  *   Pipeline handle.
1260  * @param[in] metarray_name
1261  *   Meter array name.
1262  * @param[in] metarray_index
1263  *   Meter index within the meter array.
1264  * @param[out] stats
1265  *   Meter statistics counters.
1266  * @return
1267  *   0 on success or the following error codes otherwise:
1268  *   -EINVAL: Invalid argument.
1269  */
1270 __rte_experimental
1271 int
1272 rte_swx_ctl_meter_stats_read(struct rte_swx_pipeline *p,
1273                              const char *metarray_name,
1274                              uint32_t metarray_index,
1275                              struct rte_swx_ctl_meter_stats *stats);
1276
1277 /**
1278  * Pipeline control free
1279  *
1280  * @param[in] ctl
1281  *   Pipeline control handle.
1282  */
1283 __rte_experimental
1284 void
1285 rte_swx_ctl_pipeline_free(struct rte_swx_ctl_pipeline *ctl);
1286
1287 #ifdef __cplusplus
1288 }
1289 #endif
1290
1291 #endif