1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2020 Intel Corporation
4 #ifndef __INCLUDE_RTE_SWX_CTL_H__
5 #define __INCLUDE_RTE_SWX_CTL_H__
13 * RTE SWX Pipeline Control
20 #include <rte_compat.h>
21 #include <rte_meter.h>
23 #include "rte_swx_port.h"
24 #include "rte_swx_table.h"
26 struct rte_swx_pipeline;
29 #ifndef RTE_SWX_CTL_NAME_SIZE
30 #define RTE_SWX_CTL_NAME_SIZE 64
38 struct rte_swx_ctl_pipeline_info {
39 /** Number of input ports. */
42 /** Number of input ports. */
45 /** Number of actions. */
48 /** Number of tables. */
51 /** Number of register arrays. */
54 /** Number of meter arrays. */
63 * @param[out] pipeline
66 * 0 on success or the following error codes otherwise:
67 * -EINVAL: Invalid argument.
71 rte_swx_ctl_pipeline_info_get(struct rte_swx_pipeline *p,
72 struct rte_swx_ctl_pipeline_info *pipeline);
75 * Pipeline NUMA node get
79 * @param[out] numa_node
82 * 0 on success or the following error codes otherwise:
83 * -EINVAL: Invalid argument.
87 rte_swx_ctl_pipeline_numa_node_get(struct rte_swx_pipeline *p,
95 * Input port statistics counters read
100 * Port ID (0 .. *n_ports_in* - 1).
104 * 0 on success or the following error codes otherwise:
105 * -EINVAL: Invalid argument.
109 rte_swx_ctl_pipeline_port_in_stats_read(struct rte_swx_pipeline *p,
111 struct rte_swx_port_in_stats *stats);
114 * Output port statistics counters read
119 * Port ID (0 .. *n_ports_out* - 1).
123 * 0 on success or the following error codes otherwise:
124 * -EINVAL: Invalid argument.
128 rte_swx_ctl_pipeline_port_out_stats_read(struct rte_swx_pipeline *p,
130 struct rte_swx_port_out_stats *stats);
137 struct rte_swx_ctl_action_info {
139 char name[RTE_SWX_CTL_NAME_SIZE];
141 /** Number of action arguments. */
150 * @param[in] action_id
151 * Action ID (0 .. *n_actions* - 1).
155 * 0 on success or the following error codes otherwise:
156 * -EINVAL: Invalid argument.
160 rte_swx_ctl_action_info_get(struct rte_swx_pipeline *p,
162 struct rte_swx_ctl_action_info *action);
164 /** Action argument info. */
165 struct rte_swx_ctl_action_arg_info {
166 /** Action argument name. */
167 char name[RTE_SWX_CTL_NAME_SIZE];
169 /** Action argument size (in bits). */
174 * Action argument info get
178 * @param[in] action_id
179 * Action ID (0 .. *n_actions* - 1).
180 * @param[in] action_arg_id
181 * Action ID (0 .. *n_args* - 1).
182 * @param[out] action_arg
183 * Action argument info.
185 * 0 on success or the following error codes otherwise:
186 * -EINVAL: Invalid argument.
190 rte_swx_ctl_action_arg_info_get(struct rte_swx_pipeline *p,
192 uint32_t action_arg_id,
193 struct rte_swx_ctl_action_arg_info *action_arg);
200 struct rte_swx_ctl_table_info {
202 char name[RTE_SWX_CTL_NAME_SIZE];
204 /** Table creation arguments. */
205 char args[RTE_SWX_CTL_NAME_SIZE];
207 /** Number of match fields. */
208 uint32_t n_match_fields;
210 /** Number of actions. */
213 /** Non-zero (true) when the default action is constant, therefore it
214 * cannot be changed; zero (false) when the default action not constant,
215 * therefore it can be changed.
217 int default_action_is_const;
219 /** Table size parameter. */
228 * @param[in] table_id
229 * Table ID (0 .. *n_tables* - 1).
233 * 0 on success or the following error codes otherwise:
234 * -EINVAL: Invalid argument.
238 rte_swx_ctl_table_info_get(struct rte_swx_pipeline *p,
240 struct rte_swx_ctl_table_info *table);
242 /** Table match field info.
244 * If (n_bits, offset) are known for all the match fields of the table, then the
245 * table (key_offset, key_size, key_mask0) can be computed.
247 struct rte_swx_ctl_table_match_field_info {
248 /** Match type of the current match field. */
249 enum rte_swx_table_match_type match_type;
251 /** Non-zero (true) when the current match field is part of a registered
252 * header, zero (false) when it is part of the registered meta-data.
256 /** Match field size (in bits). */
259 /** Match field offset within its parent struct (one of the headers or
266 * Table match field info get
270 * @param[in] table_id
271 * Table ID (0 .. *n_tables*).
272 * @param[in] match_field_id
273 * Match field ID (0 .. *n_match_fields* - 1).
274 * @param[out] match_field
275 * Table match field info.
277 * 0 on success or the following error codes otherwise:
278 * -EINVAL: Invalid argument.
282 rte_swx_ctl_table_match_field_info_get(struct rte_swx_pipeline *p,
284 uint32_t match_field_id,
285 struct rte_swx_ctl_table_match_field_info *match_field);
287 /** Table action info. */
288 struct rte_swx_ctl_table_action_info {
294 * Table action info get
298 * @param[in] table_id
299 * Table ID (0 .. *n_tables*).
300 * @param[in] table_action_id
301 * Action index within the set of table actions (0 .. table n_actions - 1).
302 * Not to be confused with the action ID, which works at the pipeline level
303 * (0 .. pipeline n_actions - 1), which is precisely what this function
304 * returns as part of *table_action*.
305 * @param[out] table_action
308 * 0 on success or the following error codes otherwise:
309 * -EINVAL: Invalid argument.
313 rte_swx_ctl_table_action_info_get(struct rte_swx_pipeline *p,
315 uint32_t table_action_id,
316 struct rte_swx_ctl_table_action_info *table_action);
319 * Table operations get
323 * @param[in] table_id
324 * Table ID (0 .. *n_tables*).
325 * @param[out] table_ops
326 * Table operations. Only valid when function returns success and *is_stub* is
328 * @param[out] is_stub
329 * A stub table is a table with no match fields. No "regular" table entries
330 * (i.e. entries other than the default entry) can be added to such a table,
331 * therefore the lookup operation always results in lookup miss. Non-zero
332 * (true) when the current table is a stub table, zero (false) otherwise.
334 * 0 on success or the following error codes otherwise:
335 * -EINVAL: Invalid argument.
339 rte_swx_ctl_table_ops_get(struct rte_swx_pipeline *p,
341 struct rte_swx_table_ops *table_ops,
349 struct rte_swx_table_state {
353 /** Action ID of the table default action. */
354 uint64_t default_action_id;
356 /** Action data of the table default action. Ignored when the action
357 * data size is zero; otherwise, action data size bytes are meaningful.
359 uint8_t *default_action_data;
363 * Pipeline table state get
367 * @param[out] table_state
368 * After successful execution, the *table_state* contains the pointer to the
369 * current pipeline table state, which is an array of *n_tables* elements,
370 * with array element i containing the state of the i-th pipeline table. The
371 * pipeline continues to own all the data structures directly or indirectly
372 * referenced by the *table_state* until the subsequent successful invocation
373 * of function *rte_swx_pipeline_table_state_set*.
375 * 0 on success or the following error codes otherwise:
376 * -EINVAL: Invalid argument.
380 rte_swx_pipeline_table_state_get(struct rte_swx_pipeline *p,
381 struct rte_swx_table_state **table_state);
384 * Pipeline table state set
388 * @param[out] table_state
389 * After successful execution, the pipeline table state is updated to this
390 * *table_state*. The ownership of all the data structures directly or
391 * indirectly referenced by this *table_state* is passed from the caller to
394 * 0 on success or the following error codes otherwise:
395 * -EINVAL: Invalid argument.
399 rte_swx_pipeline_table_state_set(struct rte_swx_pipeline *p,
400 struct rte_swx_table_state *table_state);
403 * High Level Reference Table Update API.
406 /** Pipeline control opaque data structure. */
407 struct rte_swx_ctl_pipeline;
410 * Pipeline control create
415 * Pipeline control handle, on success, or NULL, on error.
418 struct rte_swx_ctl_pipeline *
419 rte_swx_ctl_pipeline_create(struct rte_swx_pipeline *p);
422 * Pipeline table entry add
424 * Schedule entry for addition to table or update as part of the next commit
428 * Pipeline control handle.
429 * @param[in] table_name
432 * Entry to be added to the table.
434 * 0 on success or the following error codes otherwise:
435 * -EINVAL: Invalid argument.
439 rte_swx_ctl_pipeline_table_entry_add(struct rte_swx_ctl_pipeline *ctl,
440 const char *table_name,
441 struct rte_swx_table_entry *entry);
444 * Pipeline table default entry add
446 * Schedule table default entry update as part of the next commit operation.
449 * Pipeline control handle.
450 * @param[in] table_name
453 * The new table default entry. The *key* and *key_mask* entry fields are
456 * 0 on success or the following error codes otherwise:
457 * -EINVAL: Invalid argument.
461 rte_swx_ctl_pipeline_table_default_entry_add(struct rte_swx_ctl_pipeline *ctl,
462 const char *table_name,
463 struct rte_swx_table_entry *entry);
466 * Pipeline table entry delete
468 * Schedule entry for deletion from table as part of the next commit operation.
469 * Request is silently discarded if no such entry exists.
472 * Pipeline control handle.
473 * @param[in] table_name
476 * Entry to be deleted from the table. The *action_id* and *action_data* entry
477 * fields are ignored.
479 * 0 on success or the following error codes otherwise:
480 * -EINVAL: Invalid argument.
484 rte_swx_ctl_pipeline_table_entry_delete(struct rte_swx_ctl_pipeline *ctl,
485 const char *table_name,
486 struct rte_swx_table_entry *entry);
491 * Perform all the scheduled table work.
494 * Pipeline control handle.
495 * @param[in] abort_on_fail
496 * When non-zero (false), all the scheduled work is discarded after a failed
497 * commit. Otherwise, the scheduled work is still kept pending for the next
500 * 0 on success or the following error codes otherwise:
501 * -EINVAL: Invalid argument.
505 rte_swx_ctl_pipeline_commit(struct rte_swx_ctl_pipeline *ctl,
511 * Discard all the scheduled table work.
514 * Pipeline control handle.
518 rte_swx_ctl_pipeline_abort(struct rte_swx_ctl_pipeline *ctl);
521 * Pipeline table entry read
523 * Read table entry from string.
526 * Pipeline control handle.
527 * @param[in] table_name
530 * String containing the table entry.
531 * @param[out] is_blank_or_comment
532 * On error, this argument provides an indication of whether *string* contains
533 * an invalid table entry (set to zero) or a blank or comment line that should
534 * typically be ignored (set to a non-zero value).
536 * 0 on success or the following error codes otherwise:
537 * -EINVAL: Invalid argument.
540 struct rte_swx_table_entry *
541 rte_swx_ctl_pipeline_table_entry_read(struct rte_swx_ctl_pipeline *ctl,
542 const char *table_name,
544 int *is_blank_or_comment);
547 * Pipeline table print to file
549 * Print all the table entries to file.
554 * Pipeline control handle.
555 * @param[in] table_name
558 * 0 on success or the following error codes otherwise:
559 * -EINVAL: Invalid argument.
563 rte_swx_ctl_pipeline_table_fprintf(FILE *f,
564 struct rte_swx_ctl_pipeline *ctl,
565 const char *table_name);
568 * Register Array Query API.
571 /** Register array info. */
572 struct rte_swx_ctl_regarray_info {
573 /** Register array name. */
574 char name[RTE_SWX_CTL_NAME_SIZE];
576 /** Register array size. */
581 * Register array info get
585 * @param[in] regarray_id
586 * Register array ID (0 .. *n_regarrays* - 1).
587 * @param[out] regarray
588 * Register array info.
590 * 0 on success or the following error codes otherwise:
591 * -EINVAL: Invalid argument.
595 rte_swx_ctl_regarray_info_get(struct rte_swx_pipeline *p,
596 uint32_t regarray_id,
597 struct rte_swx_ctl_regarray_info *regarray);
604 * @param[in] regarray_name
605 * Register array name.
606 * @param[in] regarray_index
607 * Register index within the array (0 .. *size* - 1).
609 * Current register value.
611 * 0 on success or the following error codes otherwise:
612 * -EINVAL: Invalid argument.
616 rte_swx_ctl_pipeline_regarray_read(struct rte_swx_pipeline *p,
617 const char *regarray_name,
618 uint32_t regarray_index,
626 * @param[in] regarray_name
627 * Register array name.
628 * @param[in] regarray_index
629 * Register index within the array (0 .. *size* - 1).
631 * Value to be written to the register.
633 * 0 on success or the following error codes otherwise:
634 * -EINVAL: Invalid argument.
638 rte_swx_ctl_pipeline_regarray_write(struct rte_swx_pipeline *p,
639 const char *regarray_name,
640 uint32_t regarray_index,
644 * Meter Array Query and Configuration API.
647 /** Meter array info. */
648 struct rte_swx_ctl_metarray_info {
649 /** Meter array name. */
650 char name[RTE_SWX_CTL_NAME_SIZE];
652 /** Meter array size. */
657 * Meter array info get
661 * @param[in] metarray_id
662 * Meter array ID (0 .. *n_metarrays* - 1).
663 * @param[out] metarray
666 * 0 on success or the following error codes otherwise:
667 * -EINVAL: Invalid argument.
671 rte_swx_ctl_metarray_info_get(struct rte_swx_pipeline *p,
672 uint32_t metarray_id,
673 struct rte_swx_ctl_metarray_info *metarray);
681 * Meter profile name.
683 * Meter profile parameters.
685 * 0 on success or the following error codes otherwise:
686 * -EINVAL: Invalid argument;
687 * -ENOMEM: Not enough space/cannot allocate memory;
688 * -EEXIST: Meter profile with this name already exists.
692 rte_swx_ctl_meter_profile_add(struct rte_swx_pipeline *p,
694 struct rte_meter_trtcm_params *params);
697 * Meter profile delete
702 * Meter profile name.
704 * 0 on success or the following error codes otherwise:
705 * -EINVAL: Invalid argument;
706 * -EBUSY: Meter profile is currently in use.
710 rte_swx_ctl_meter_profile_delete(struct rte_swx_pipeline *p,
716 * Reset a meter within a given meter array to use the default profile that
717 * causes all the input packets to be colored as green. It is the responsibility
718 * of the control plane to make sure this meter is not used by the data plane
719 * pipeline before calling this function.
723 * @param[in] metarray_name
725 * @param[in] metarray_index
726 * Meter index within the meter array.
728 * 0 on success or the following error codes otherwise:
729 * -EINVAL: Invalid argument.
733 rte_swx_ctl_meter_reset(struct rte_swx_pipeline *p,
734 const char *metarray_name,
735 uint32_t metarray_index);
740 * Set a meter within a given meter array to use a specific profile. It is the
741 * responsibility of the control plane to make sure this meter is not used by
742 * the data plane pipeline before calling this function.
746 * @param[in] metarray_name
748 * @param[in] metarray_index
749 * Meter index within the meter array.
750 * @param[in] profile_name
751 * Existing meter profile name.
753 * 0 on success or the following error codes otherwise:
754 * -EINVAL: Invalid argument.
758 rte_swx_ctl_meter_set(struct rte_swx_pipeline *p,
759 const char *metarray_name,
760 uint32_t metarray_index,
761 const char *profile_name);
763 /** Meter statistics counters. */
764 struct rte_swx_ctl_meter_stats {
765 /** Number of packets tagged by the meter for each color. */
766 uint64_t n_pkts[RTE_COLORS];
768 /** Number of bytes tagged by the meter for each color. */
769 uint64_t n_bytes[RTE_COLORS];
773 * Meter statistics counters read
777 * @param[in] metarray_name
779 * @param[in] metarray_index
780 * Meter index within the meter array.
782 * Meter statistics counters.
784 * 0 on success or the following error codes otherwise:
785 * -EINVAL: Invalid argument.
789 rte_swx_ctl_meter_stats_read(struct rte_swx_pipeline *p,
790 const char *metarray_name,
791 uint32_t metarray_index,
792 struct rte_swx_ctl_meter_stats *stats);
795 * Pipeline control free
798 * Pipeline control handle.
802 rte_swx_ctl_pipeline_free(struct rte_swx_ctl_pipeline *ctl);