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