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