lib/librte_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
  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 register arrays. */
  51         uint32_t n_regarrays;
  52 };
  53
  54 /**
  55  * Pipeline info get
  56  *
  57  * @param[in] p
  58  *   Pipeline handle.
  59  * @param[out] pipeline
  60  *   Pipeline info.
  61  * @return
  62  *   0 on success or the following error codes otherwise:
  63  *   -EINVAL: Invalid argument.
  64  */
  65 __rte_experimental
  66 int
  67 rte_swx_ctl_pipeline_info_get(struct rte_swx_pipeline *p,
  68                               struct rte_swx_ctl_pipeline_info *pipeline);
  69
  70 /**
  71  * Pipeline NUMA node get
  72  *
  73  * @param[in] p
  74  *   Pipeline handle.
  75  * @param[out] numa_node
  76  *   Pipeline NUMA node.
  77  * @return
  78  *   0 on success or the following error codes otherwise:
  79  *   -EINVAL: Invalid argument.
  80  */
  81 __rte_experimental
  82 int
  83 rte_swx_ctl_pipeline_numa_node_get(struct rte_swx_pipeline *p,
  84                                    int *numa_node);
  85
  86 /*
  87  * Ports Query API.
  88  */
  89
  90 /**
  91  * Input port statistics counters read
  92  *
  93  * @param[in] p
  94  *   Pipeline handle.
  95  * @param[in] port_id
  96  *   Port ID (0 .. *n_ports_in* - 1).
  97  * @param[out] stats
  98  *   Input port stats.
  99  * @return
 100  *   0 on success or the following error codes otherwise:
 101  *   -EINVAL: Invalid argument.
 102  */
 103 __rte_experimental
 104 int
 105 rte_swx_ctl_pipeline_port_in_stats_read(struct rte_swx_pipeline *p,
 106                                         uint32_t port_id,
 107                                         struct rte_swx_port_in_stats *stats);
 108
 109 /**
 110  * Output port statistics counters read
 111  *
 112  * @param[in] p
 113  *   Pipeline handle.
 114  * @param[in] port_id
 115  *   Port ID (0 .. *n_ports_out* - 1).
 116  * @param[out] stats
 117  *   Output port stats.
 118  * @return
 119  *   0 on success or the following error codes otherwise:
 120  *   -EINVAL: Invalid argument.
 121  */
 122 __rte_experimental
 123 int
 124 rte_swx_ctl_pipeline_port_out_stats_read(struct rte_swx_pipeline *p,
 125                                          uint32_t port_id,
 126                                          struct rte_swx_port_out_stats *stats);
 127
 128 /*
 129  * Action Query API.
 130  */
 131
 132 /** Action info. */
 133 struct rte_swx_ctl_action_info {
 134         /** Action name. */
 135         char name[RTE_SWX_CTL_NAME_SIZE];
 136
 137         /** Number of action arguments. */
 138         uint32_t n_args;
 139 };
 140
 141 /**
 142  * Action info get
 143  *
 144  * @param[in] p
 145  *   Pipeline handle.
 146  * @param[in] action_id
 147  *   Action ID (0 .. *n_actions* - 1).
 148  * @param[out] action
 149  *   Action info.
 150  * @return
 151  *   0 on success or the following error codes otherwise:
 152  *   -EINVAL: Invalid argument.
 153  */
 154 __rte_experimental
 155 int
 156 rte_swx_ctl_action_info_get(struct rte_swx_pipeline *p,
 157                             uint32_t action_id,
 158                             struct rte_swx_ctl_action_info *action);
 159
 160 /** Action argument info. */
 161 struct rte_swx_ctl_action_arg_info {
 162         /** Action argument name. */
 163         char name[RTE_SWX_CTL_NAME_SIZE];
 164
 165         /** Action argument size (in bits). */
 166         uint32_t n_bits;
 167 };
 168
 169 /**
 170  * Action argument info get
 171  *
 172  * @param[in] p
 173  *   Pipeline handle.
 174  * @param[in] action_id
 175  *   Action ID (0 .. *n_actions* - 1).
 176  * @param[in] action_arg_id
 177  *   Action ID (0 .. *n_args* - 1).
 178  * @param[out] action_arg
 179  *   Action argument info.
 180  * @return
 181  *   0 on success or the following error codes otherwise:
 182  *   -EINVAL: Invalid argument.
 183  */
 184 __rte_experimental
 185 int
 186 rte_swx_ctl_action_arg_info_get(struct rte_swx_pipeline *p,
 187                                 uint32_t action_id,
 188                                 uint32_t action_arg_id,
 189                                 struct rte_swx_ctl_action_arg_info *action_arg);
 190
 191 /*
 192  * Table Query API.
 193  */
 194
 195 /** Table info. */
 196 struct rte_swx_ctl_table_info {
 197         /** Table name. */
 198         char name[RTE_SWX_CTL_NAME_SIZE];
 199
 200         /** Table creation arguments. */
 201         char args[RTE_SWX_CTL_NAME_SIZE];
 202
 203         /** Number of match fields. */
 204         uint32_t n_match_fields;
 205
 206         /** Number of actions. */
 207         uint32_t n_actions;
 208
 209         /** Non-zero (true) when the default action is constant, therefore it
 210          * cannot be changed; zero (false) when the default action not constant,
 211          * therefore it can be changed.
 212          */
 213         int default_action_is_const;
 214
 215         /** Table size parameter. */
 216         uint32_t size;
 217 };
 218
 219 /**
 220  * Table info get
 221  *
 222  * @param[in] p
 223  *   Pipeline handle.
 224  * @param[in] table_id
 225  *   Table ID (0 .. *n_tables* - 1).
 226  * @param[out] table
 227  *   Table info.
 228  * @return
 229  *   0 on success or the following error codes otherwise:
 230  *   -EINVAL: Invalid argument.
 231  */
 232 __rte_experimental
 233 int
 234 rte_swx_ctl_table_info_get(struct rte_swx_pipeline *p,
 235                            uint32_t table_id,
 236                            struct rte_swx_ctl_table_info *table);
 237
 238 /** Table match field info.
 239  *
 240  * If (n_bits, offset) are known for all the match fields of the table, then the
 241  * table (key_offset, key_size, key_mask0) can be computed.
 242  */
 243 struct rte_swx_ctl_table_match_field_info {
 244         /** Match type of the current match field. */
 245         enum rte_swx_table_match_type match_type;
 246
 247         /** Non-zero (true) when the current match field is part of a registered
 248          * header, zero (false) when it is part of the registered meta-data.
 249          */
 250         int is_header;
 251
 252         /** Match field size (in bits). */
 253         uint32_t n_bits;
 254
 255         /** Match field offset within its parent struct (one of the headers or
 256          * the meta-data).
 257          */
 258         uint32_t offset;
 259 };
 260
 261 /**
 262  * Table match field info get
 263  *
 264  * @param[in] p
 265  *   Pipeline handle.
 266  * @param[in] table_id
 267  *   Table ID (0 .. *n_tables*).
 268  * @param[in] match_field_id
 269  *   Match field ID (0 .. *n_match_fields* - 1).
 270  * @param[out] match_field
 271  *   Table match field info.
 272  * @return
 273  *   0 on success or the following error codes otherwise:
 274  *   -EINVAL: Invalid argument.
 275  */
 276 __rte_experimental
 277 int
 278 rte_swx_ctl_table_match_field_info_get(struct rte_swx_pipeline *p,
 279         uint32_t table_id,
 280         uint32_t match_field_id,
 281         struct rte_swx_ctl_table_match_field_info *match_field);
 282
 283 /** Table action info. */
 284 struct rte_swx_ctl_table_action_info {
 285         /** Action ID. */
 286         uint32_t action_id;
 287 };
 288
 289 /**
 290  * Table action info get
 291  *
 292  * @param[in] p
 293  *   Pipeline handle.
 294  * @param[in] table_id
 295  *   Table ID (0 .. *n_tables*).
 296  * @param[in] table_action_id
 297  *   Action index within the set of table actions (0 .. table n_actions - 1).
 298  *   Not to be confused with the action ID, which works at the pipeline level
 299  *   (0 .. pipeline n_actions - 1), which is precisely what this function
 300  *   returns as part of *table_action*.
 301  * @param[out] table_action
 302  *   Table action info.
 303  * @return
 304  *   0 on success or the following error codes otherwise:
 305  *   -EINVAL: Invalid argument.
 306  */
 307 __rte_experimental
 308 int
 309 rte_swx_ctl_table_action_info_get(struct rte_swx_pipeline *p,
 310         uint32_t table_id,
 311         uint32_t table_action_id,
 312         struct rte_swx_ctl_table_action_info *table_action);
 313
 314 /**
 315  * Table operations get
 316  *
 317  * @param[in] p
 318  *   Pipeline handle.
 319  * @param[in] table_id
 320  *   Table ID (0 .. *n_tables*).
 321  * @param[out] table_ops
 322  *   Table operations. Only valid when function returns success and *is_stub* is
 323  *   zero (false).
 324  * @param[out] is_stub
 325  *   A stub table is a table with no match fields. No "regular" table entries
 326  *   (i.e. entries other than the default entry) can be added to such a table,
 327  *   therefore the lookup operation always results in lookup miss. Non-zero
 328  *   (true) when the current table is a stub table, zero (false) otherwise.
 329  * @return
 330  *   0 on success or the following error codes otherwise:
 331  *   -EINVAL: Invalid argument.
 332  */
 333 __rte_experimental
 334 int
 335 rte_swx_ctl_table_ops_get(struct rte_swx_pipeline *p,
 336                           uint32_t table_id,
 337                           struct rte_swx_table_ops *table_ops,
 338                           int *is_stub);
 339
 340 /*
 341  * Table Update API.
 342  */
 343
 344 /** Table state. */
 345 struct rte_swx_table_state {
 346         /** Table object. */
 347         void *obj;
 348
 349         /** Action ID of the table default action. */
 350         uint64_t default_action_id;
 351
 352         /** Action data of the table default action. Ignored when the action
 353          * data size is zero; otherwise, action data size bytes are meaningful.
 354          */
 355         uint8_t *default_action_data;
 356 };
 357
 358 /**
 359  * Pipeline table state get
 360  *
 361  * @param[in] p
 362  *   Pipeline handle.
 363  * @param[out] table_state
 364  *   After successful execution, the *table_state* contains the pointer to the
 365  *   current pipeline table state, which is an array of *n_tables* elements,
 366  *   with array element i containing the state of the i-th pipeline table. The
 367  *   pipeline continues to own all the data structures directly or indirectly
 368  *   referenced by the *table_state* until the subsequent successful invocation
 369  *   of function *rte_swx_pipeline_table_state_set*.
 370  * @return
 371  *   0 on success or the following error codes otherwise:
 372  *   -EINVAL: Invalid argument.
 373  */
 374 __rte_experimental
 375 int
 376 rte_swx_pipeline_table_state_get(struct rte_swx_pipeline *p,
 377                                  struct rte_swx_table_state **table_state);
 378
 379 /**
 380  * Pipeline table state set
 381  *
 382  * @param[in] p
 383  *   Pipeline handle.
 384  * @param[out] table_state
 385  *   After successful execution, the pipeline table state is updated to this
 386  *   *table_state*. The ownership of all the data structures directly or
 387  *   indirectly referenced by this *table_state* is passed from the caller to
 388  *   the pipeline.
 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_pipeline_table_state_set(struct rte_swx_pipeline *p,
 396                                  struct rte_swx_table_state *table_state);
 397
 398 /*
 399  * High Level Reference Table Update API.
 400  */
 401
 402 /** Pipeline control opaque data structure. */
 403 struct rte_swx_ctl_pipeline;
 404
 405 /**
 406  * Pipeline control create
 407  *
 408  * @param[in] p
 409  *   Pipeline handle.
 410  * @return
 411  *   Pipeline control handle, on success, or NULL, on error.
 412  */
 413 __rte_experimental
 414 struct rte_swx_ctl_pipeline *
 415 rte_swx_ctl_pipeline_create(struct rte_swx_pipeline *p);
 416
 417 /**
 418  * Pipeline table entry add
 419  *
 420  * Schedule entry for addition to table or update as part of the next commit
 421  * operation.
 422  *
 423  * @param[in] ctl
 424  *   Pipeline control handle.
 425  * @param[in] table_name
 426  *   Table name.
 427  * @param[in] entry
 428  *   Entry to be added to the table.
 429  * @return
 430  *   0 on success or the following error codes otherwise:
 431  *   -EINVAL: Invalid argument.
 432  */
 433 __rte_experimental
 434 int
 435 rte_swx_ctl_pipeline_table_entry_add(struct rte_swx_ctl_pipeline *ctl,
 436                                      const char *table_name,
 437                                      struct rte_swx_table_entry *entry);
 438
 439 /**
 440  * Pipeline table default entry add
 441  *
 442  * Schedule table default entry update as part of the next commit operation.
 443  *
 444  * @param[in] ctl
 445  *   Pipeline control handle.
 446  * @param[in] table_name
 447  *   Table name.
 448  * @param[in] entry
 449  *   The new table default entry. The *key* and *key_mask* entry fields are
 450  *   ignored.
 451  * @return
 452  *   0 on success or the following error codes otherwise:
 453  *   -EINVAL: Invalid argument.
 454  */
 455 __rte_experimental
 456 int
 457 rte_swx_ctl_pipeline_table_default_entry_add(struct rte_swx_ctl_pipeline *ctl,
 458                                              const char *table_name,
 459                                              struct rte_swx_table_entry *entry);
 460
 461 /**
 462  * Pipeline table entry delete
 463  *
 464  * Schedule entry for deletion from table as part of the next commit operation.
 465  * Request is silently discarded if no such entry exists.
 466  *
 467  * @param[in] ctl
 468  *   Pipeline control handle.
 469  * @param[in] table_name
 470  *   Table name.
 471  * @param[in] entry
 472  *   Entry to be deleted from the table. The *action_id* and *action_data* entry
 473  *   fields are ignored.
 474  * @return
 475  *   0 on success or the following error codes otherwise:
 476  *   -EINVAL: Invalid argument.
 477  */
 478 __rte_experimental
 479 int
 480 rte_swx_ctl_pipeline_table_entry_delete(struct rte_swx_ctl_pipeline *ctl,
 481                                         const char *table_name,
 482                                         struct rte_swx_table_entry *entry);
 483
 484 /**
 485  * Pipeline commit
 486  *
 487  * Perform all the scheduled table work.
 488  *
 489  * @param[in] ctl
 490  *   Pipeline control handle.
 491  * @param[in] abort_on_fail
 492  *   When non-zero (false), all the scheduled work is discarded after a failed
 493  *   commit. Otherwise, the scheduled work is still kept pending for the next
 494  *   commit.
 495  * @return
 496  *   0 on success or the following error codes otherwise:
 497  *   -EINVAL: Invalid argument.
 498  */
 499 __rte_experimental
 500 int
 501 rte_swx_ctl_pipeline_commit(struct rte_swx_ctl_pipeline *ctl,
 502                             int abort_on_fail);
 503
 504 /**
 505  * Pipeline abort
 506  *
 507  * Discard all the scheduled table work.
 508  *
 509  * @param[in] ctl
 510  *   Pipeline control handle.
 511  */
 512 __rte_experimental
 513 void
 514 rte_swx_ctl_pipeline_abort(struct rte_swx_ctl_pipeline *ctl);
 515
 516 /**
 517  * Pipeline table entry read
 518  *
 519  * Read table entry from string.
 520  *
 521  * @param[in] ctl
 522  *   Pipeline control handle.
 523  * @param[in] table_name
 524  *   Table name.
 525  * @param[in] string
 526  *   String containing the table entry.
 527  * @param[out] is_blank_or_comment
 528  *   On error, this argument provides an indication of whether *string* contains
 529  *   an invalid table entry (set to zero) or a blank or comment line that should
 530  *   typically be ignored (set to a non-zero value).
 531  * @return
 532  *   0 on success or the following error codes otherwise:
 533  *   -EINVAL: Invalid argument.
 534  */
 535 __rte_experimental
 536 struct rte_swx_table_entry *
 537 rte_swx_ctl_pipeline_table_entry_read(struct rte_swx_ctl_pipeline *ctl,
 538                                       const char *table_name,
 539                                       const char *string,
 540                                       int *is_blank_or_comment);
 541
 542 /**
 543  * Pipeline table print to file
 544  *
 545  * Print all the table entries to file.
 546  *
 547  * @param[in] f
 548  *   Output file.
 549  * @param[in] ctl
 550  *   Pipeline control handle.
 551  * @param[in] table_name
 552  *   Table name.
 553  * @return
 554  *   0 on success or the following error codes otherwise:
 555  *   -EINVAL: Invalid argument.
 556  */
 557 __rte_experimental
 558 int
 559 rte_swx_ctl_pipeline_table_fprintf(FILE *f,
 560                                    struct rte_swx_ctl_pipeline *ctl,
 561                                    const char *table_name);
 562
 563 /*
 564  * Register Array Query API.
 565  */
 566
 567 /** Register array info. */
 568 struct rte_swx_ctl_regarray_info {
 569         /** Register array name. */
 570         char name[RTE_SWX_CTL_NAME_SIZE];
 571
 572         /** Register array size. */
 573         uint32_t size;
 574 };
 575
 576 /**
 577  * Register array info get
 578  *
 579  * @param[in] p
 580  *   Pipeline handle.
 581  * @param[in] regarray_id
 582  *   Register array ID (0 .. *n_regarrays* - 1).
 583  * @param[out] regarray
 584  *   Register array info.
 585  * @return
 586  *   0 on success or the following error codes otherwise:
 587  *   -EINVAL: Invalid argument.
 588  */
 589 __rte_experimental
 590 int
 591 rte_swx_ctl_regarray_info_get(struct rte_swx_pipeline *p,
 592                               uint32_t regarray_id,
 593                               struct rte_swx_ctl_regarray_info *regarray);
 594
 595 /**
 596  * Register read
 597  *
 598  * @param[in] p
 599  *   Pipeline handle.
 600  * @param[in] regarray_name
 601  *   Register array name.
 602  * @param[in] regarray_index
 603  *   Register index within the array (0 .. *size* - 1).
 604  * @param[out] value
 605  *   Current register value.
 606  * @return
 607  *   0 on success or the following error codes otherwise:
 608  *   -EINVAL: Invalid argument.
 609  */
 610 __rte_experimental
 611 int
 612 rte_swx_ctl_pipeline_regarray_read(struct rte_swx_pipeline *p,
 613                                    const char *regarray_name,
 614                                    uint32_t regarray_index,
 615                                    uint64_t *value);
 616
 617 /**
 618  * Register write
 619  *
 620  * @param[in] p
 621  *   Pipeline handle.
 622  * @param[in] regarray_name
 623  *   Register array name.
 624  * @param[in] regarray_index
 625  *   Register index within the array (0 .. *size* - 1).
 626  * @param[in] value
 627  *   Value to be written to the register.
 628  * @return
 629  *   0 on success or the following error codes otherwise:
 630  *   -EINVAL: Invalid argument.
 631  */
 632 __rte_experimental
 633 int
 634 rte_swx_ctl_pipeline_regarray_write(struct rte_swx_pipeline *p,
 635                                    const char *regarray_name,
 636                                    uint32_t regarray_index,
 637                                    uint64_t value);
 638
 639 /**
 640  * Pipeline control free
 641  *
 642  * @param[in] ctl
 643  *   Pipeline control handle.
 644  */
 645 __rte_experimental
 646 void
 647 rte_swx_ctl_pipeline_free(struct rte_swx_ctl_pipeline *ctl);
 648
 649 #ifdef __cplusplus
 650 }
 651 #endif
 652
 653 #endif