lib/pipeline/rte_swx_ctl.h

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