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). */
172 /** Non-zero (true) when this action argument must be stored in the
173 * table in network byte order (NBO), zero when it must be stored in
174 * host byte order (HBO).
176 int is_network_byte_order;
180 * Action argument info get
184 * @param[in] action_id
185 * Action ID (0 .. *n_actions* - 1).
186 * @param[in] action_arg_id
187 * Action ID (0 .. *n_args* - 1).
188 * @param[out] action_arg
189 * Action argument info.
191 * 0 on success or the following error codes otherwise:
192 * -EINVAL: Invalid argument.
196 rte_swx_ctl_action_arg_info_get(struct rte_swx_pipeline *p,
198 uint32_t action_arg_id,
199 struct rte_swx_ctl_action_arg_info *action_arg);
206 struct rte_swx_ctl_table_info {
208 char name[RTE_SWX_CTL_NAME_SIZE];
210 /** Table creation arguments. */
211 char args[RTE_SWX_CTL_NAME_SIZE];
213 /** Number of match fields. */
214 uint32_t n_match_fields;
216 /** Number of actions. */
219 /** Non-zero (true) when the default action is constant, therefore it
220 * cannot be changed; zero (false) when the default action not constant,
221 * therefore it can be changed.
223 int default_action_is_const;
225 /** Table size parameter. */
234 * @param[in] table_id
235 * Table ID (0 .. *n_tables* - 1).
239 * 0 on success or the following error codes otherwise:
240 * -EINVAL: Invalid argument.
244 rte_swx_ctl_table_info_get(struct rte_swx_pipeline *p,
246 struct rte_swx_ctl_table_info *table);
248 /** Table match field info.
250 * If (n_bits, offset) are known for all the match fields of the table, then the
251 * table (key_offset, key_size, key_mask0) can be computed.
253 struct rte_swx_ctl_table_match_field_info {
254 /** Match type of the current match field. */
255 enum rte_swx_table_match_type match_type;
257 /** Non-zero (true) when the current match field is part of a registered
258 * header, zero (false) when it is part of the registered meta-data.
262 /** Match field size (in bits). */
265 /** Match field offset within its parent struct (one of the headers or
272 * Table match field info get
276 * @param[in] table_id
277 * Table ID (0 .. *n_tables*).
278 * @param[in] match_field_id
279 * Match field ID (0 .. *n_match_fields* - 1).
280 * @param[out] match_field
281 * Table match field info.
283 * 0 on success or the following error codes otherwise:
284 * -EINVAL: Invalid argument.
288 rte_swx_ctl_table_match_field_info_get(struct rte_swx_pipeline *p,
290 uint32_t match_field_id,
291 struct rte_swx_ctl_table_match_field_info *match_field);
293 /** Table action info. */
294 struct rte_swx_ctl_table_action_info {
300 * Table action info get
304 * @param[in] table_id
305 * Table ID (0 .. *n_tables*).
306 * @param[in] table_action_id
307 * Action index within the set of table actions (0 .. table n_actions - 1).
308 * Not to be confused with the action ID, which works at the pipeline level
309 * (0 .. pipeline n_actions - 1), which is precisely what this function
310 * returns as part of *table_action*.
311 * @param[out] table_action
314 * 0 on success or the following error codes otherwise:
315 * -EINVAL: Invalid argument.
319 rte_swx_ctl_table_action_info_get(struct rte_swx_pipeline *p,
321 uint32_t table_action_id,
322 struct rte_swx_ctl_table_action_info *table_action);
325 * Table operations get
329 * @param[in] table_id
330 * Table ID (0 .. *n_tables*).
331 * @param[out] table_ops
332 * Table operations. Only valid when function returns success and *is_stub* is
334 * @param[out] is_stub
335 * A stub table is a table with no match fields. No "regular" table entries
336 * (i.e. entries other than the default entry) can be added to such a table,
337 * therefore the lookup operation always results in lookup miss. Non-zero
338 * (true) when the current table is a stub table, zero (false) otherwise.
340 * 0 on success or the following error codes otherwise:
341 * -EINVAL: Invalid argument.
345 rte_swx_ctl_table_ops_get(struct rte_swx_pipeline *p,
347 struct rte_swx_table_ops *table_ops,
350 /** Table statistics. */
351 struct rte_swx_table_stats {
352 /** Number of packets with lookup hit. */
355 /** Number of packets with lookup miss. */
356 uint64_t n_pkts_miss;
358 /** Number of packets (with either lookup hit or miss) per pipeline
359 * action. Array of pipeline *n_actions* elements indedex by the
360 * pipeline-level *action_id*, therefore this array has the same size
361 * for all the tables within the same pipeline.
363 uint64_t *n_pkts_action;
367 * Table statistics counters read
371 * @param[in] table_name
374 * Table stats. Must point to a pre-allocated structure. The *n_pkts_action*
375 * field also needs to be pre-allocated as array of pipeline *n_actions*
376 * elements. The pipeline actions that are not valid for the current table
377 * have their associated *n_pkts_action* element always set to zero.
379 * 0 on success or the following error codes otherwise:
380 * -EINVAL: Invalid argument.
384 rte_swx_ctl_pipeline_table_stats_read(struct rte_swx_pipeline *p,
385 const char *table_name,
386 struct rte_swx_table_stats *stats);
393 struct rte_swx_table_state {
397 /** Action ID of the table default action. */
398 uint64_t default_action_id;
400 /** Action data of the table default action. Ignored when the action
401 * data size is zero; otherwise, action data size bytes are meaningful.
403 uint8_t *default_action_data;
407 * Pipeline table state get
411 * @param[out] table_state
412 * After successful execution, the *table_state* contains the pointer to the
413 * current pipeline table state, which is an array of *n_tables* elements,
414 * with array element i containing the state of the i-th pipeline table. The
415 * pipeline continues to own all the data structures directly or indirectly
416 * referenced by the *table_state* until the subsequent successful invocation
417 * of function *rte_swx_pipeline_table_state_set*.
419 * 0 on success or the following error codes otherwise:
420 * -EINVAL: Invalid argument.
424 rte_swx_pipeline_table_state_get(struct rte_swx_pipeline *p,
425 struct rte_swx_table_state **table_state);
428 * Pipeline table state set
432 * @param[out] table_state
433 * After successful execution, the pipeline table state is updated to this
434 * *table_state*. The ownership of all the data structures directly or
435 * indirectly referenced by this *table_state* is passed from the caller to
438 * 0 on success or the following error codes otherwise:
439 * -EINVAL: Invalid argument.
443 rte_swx_pipeline_table_state_set(struct rte_swx_pipeline *p,
444 struct rte_swx_table_state *table_state);
447 * High Level Reference Table Update API.
450 /** Pipeline control opaque data structure. */
451 struct rte_swx_ctl_pipeline;
454 * Pipeline control create
459 * Pipeline control handle, on success, or NULL, on error.
462 struct rte_swx_ctl_pipeline *
463 rte_swx_ctl_pipeline_create(struct rte_swx_pipeline *p);
466 * Pipeline table entry add
468 * Schedule entry for addition to table or update as part of the next commit
472 * Pipeline control handle.
473 * @param[in] table_name
476 * Entry to be added to the table.
478 * 0 on success or the following error codes otherwise:
479 * -EINVAL: Invalid argument.
483 rte_swx_ctl_pipeline_table_entry_add(struct rte_swx_ctl_pipeline *ctl,
484 const char *table_name,
485 struct rte_swx_table_entry *entry);
488 * Pipeline table default entry add
490 * Schedule table default entry update as part of the next commit operation.
493 * Pipeline control handle.
494 * @param[in] table_name
497 * The new table default entry. The *key* and *key_mask* entry fields are
500 * 0 on success or the following error codes otherwise:
501 * -EINVAL: Invalid argument.
505 rte_swx_ctl_pipeline_table_default_entry_add(struct rte_swx_ctl_pipeline *ctl,
506 const char *table_name,
507 struct rte_swx_table_entry *entry);
510 * Pipeline table entry delete
512 * Schedule entry for deletion from table as part of the next commit operation.
513 * Request is silently discarded if no such entry exists.
516 * Pipeline control handle.
517 * @param[in] table_name
520 * Entry to be deleted from the table. The *action_id* and *action_data* entry
521 * fields are ignored.
523 * 0 on success or the following error codes otherwise:
524 * -EINVAL: Invalid argument.
528 rte_swx_ctl_pipeline_table_entry_delete(struct rte_swx_ctl_pipeline *ctl,
529 const char *table_name,
530 struct rte_swx_table_entry *entry);
535 * Perform all the scheduled table work.
538 * Pipeline control handle.
539 * @param[in] abort_on_fail
540 * When non-zero (false), all the scheduled work is discarded after a failed
541 * commit. Otherwise, the scheduled work is still kept pending for the next
544 * 0 on success or the following error codes otherwise:
545 * -EINVAL: Invalid argument.
549 rte_swx_ctl_pipeline_commit(struct rte_swx_ctl_pipeline *ctl,
555 * Discard all the scheduled table work.
558 * Pipeline control handle.
562 rte_swx_ctl_pipeline_abort(struct rte_swx_ctl_pipeline *ctl);
565 * Pipeline table entry read
567 * Read table entry from string.
570 * Pipeline control handle.
571 * @param[in] table_name
574 * String containing the table entry.
575 * @param[out] is_blank_or_comment
576 * On error, this argument provides an indication of whether *string* contains
577 * an invalid table entry (set to zero) or a blank or comment line that should
578 * typically be ignored (set to a non-zero value).
580 * 0 on success or the following error codes otherwise:
581 * -EINVAL: Invalid argument.
584 struct rte_swx_table_entry *
585 rte_swx_ctl_pipeline_table_entry_read(struct rte_swx_ctl_pipeline *ctl,
586 const char *table_name,
588 int *is_blank_or_comment);
591 * Pipeline table print to file
593 * Print all the table entries to file.
598 * Pipeline control handle.
599 * @param[in] table_name
602 * 0 on success or the following error codes otherwise:
603 * -EINVAL: Invalid argument.
607 rte_swx_ctl_pipeline_table_fprintf(FILE *f,
608 struct rte_swx_ctl_pipeline *ctl,
609 const char *table_name);
612 * Register Array Query API.
615 /** Register array info. */
616 struct rte_swx_ctl_regarray_info {
617 /** Register array name. */
618 char name[RTE_SWX_CTL_NAME_SIZE];
620 /** Register array size. */
625 * Register array info get
629 * @param[in] regarray_id
630 * Register array ID (0 .. *n_regarrays* - 1).
631 * @param[out] regarray
632 * Register array info.
634 * 0 on success or the following error codes otherwise:
635 * -EINVAL: Invalid argument.
639 rte_swx_ctl_regarray_info_get(struct rte_swx_pipeline *p,
640 uint32_t regarray_id,
641 struct rte_swx_ctl_regarray_info *regarray);
648 * @param[in] regarray_name
649 * Register array name.
650 * @param[in] regarray_index
651 * Register index within the array (0 .. *size* - 1).
653 * Current register value.
655 * 0 on success or the following error codes otherwise:
656 * -EINVAL: Invalid argument.
660 rte_swx_ctl_pipeline_regarray_read(struct rte_swx_pipeline *p,
661 const char *regarray_name,
662 uint32_t regarray_index,
670 * @param[in] regarray_name
671 * Register array name.
672 * @param[in] regarray_index
673 * Register index within the array (0 .. *size* - 1).
675 * Value to be written to the register.
677 * 0 on success or the following error codes otherwise:
678 * -EINVAL: Invalid argument.
682 rte_swx_ctl_pipeline_regarray_write(struct rte_swx_pipeline *p,
683 const char *regarray_name,
684 uint32_t regarray_index,
688 * Meter Array Query and Configuration API.
691 /** Meter array info. */
692 struct rte_swx_ctl_metarray_info {
693 /** Meter array name. */
694 char name[RTE_SWX_CTL_NAME_SIZE];
696 /** Meter array size. */
701 * Meter array info get
705 * @param[in] metarray_id
706 * Meter array ID (0 .. *n_metarrays* - 1).
707 * @param[out] metarray
710 * 0 on success or the following error codes otherwise:
711 * -EINVAL: Invalid argument.
715 rte_swx_ctl_metarray_info_get(struct rte_swx_pipeline *p,
716 uint32_t metarray_id,
717 struct rte_swx_ctl_metarray_info *metarray);
725 * Meter profile name.
727 * Meter profile parameters.
729 * 0 on success or the following error codes otherwise:
730 * -EINVAL: Invalid argument;
731 * -ENOMEM: Not enough space/cannot allocate memory;
732 * -EEXIST: Meter profile with this name already exists.
736 rte_swx_ctl_meter_profile_add(struct rte_swx_pipeline *p,
738 struct rte_meter_trtcm_params *params);
741 * Meter profile delete
746 * Meter profile name.
748 * 0 on success or the following error codes otherwise:
749 * -EINVAL: Invalid argument;
750 * -EBUSY: Meter profile is currently in use.
754 rte_swx_ctl_meter_profile_delete(struct rte_swx_pipeline *p,
760 * Reset a meter within a given meter array to use the default profile that
761 * causes all the input packets to be colored as green. It is the responsibility
762 * of the control plane to make sure this meter is not used by the data plane
763 * pipeline before calling this function.
767 * @param[in] metarray_name
769 * @param[in] metarray_index
770 * Meter index within the meter array.
772 * 0 on success or the following error codes otherwise:
773 * -EINVAL: Invalid argument.
777 rte_swx_ctl_meter_reset(struct rte_swx_pipeline *p,
778 const char *metarray_name,
779 uint32_t metarray_index);
784 * Set a meter within a given meter array to use a specific profile. It is the
785 * responsibility of the control plane to make sure this meter is not used by
786 * the data plane pipeline before calling this function.
790 * @param[in] metarray_name
792 * @param[in] metarray_index
793 * Meter index within the meter array.
794 * @param[in] profile_name
795 * Existing meter profile name.
797 * 0 on success or the following error codes otherwise:
798 * -EINVAL: Invalid argument.
802 rte_swx_ctl_meter_set(struct rte_swx_pipeline *p,
803 const char *metarray_name,
804 uint32_t metarray_index,
805 const char *profile_name);
807 /** Meter statistics counters. */
808 struct rte_swx_ctl_meter_stats {
809 /** Number of packets tagged by the meter for each color. */
810 uint64_t n_pkts[RTE_COLORS];
812 /** Number of bytes tagged by the meter for each color. */
813 uint64_t n_bytes[RTE_COLORS];
817 * Meter statistics counters read
821 * @param[in] metarray_name
823 * @param[in] metarray_index
824 * Meter index within the meter array.
826 * Meter statistics counters.
828 * 0 on success or the following error codes otherwise:
829 * -EINVAL: Invalid argument.
833 rte_swx_ctl_meter_stats_read(struct rte_swx_pipeline *p,
834 const char *metarray_name,
835 uint32_t metarray_index,
836 struct rte_swx_ctl_meter_stats *stats);
839 * Pipeline control free
842 * Pipeline control handle.
846 rte_swx_ctl_pipeline_free(struct rte_swx_ctl_pipeline *ctl);