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