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