1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2021 Intel Corporation
4 #ifndef __INCLUDE_RTE_SWX_TABLE_SELECTOR_H__
5 #define __INCLUDE_RTE_SWX_TABLE_SELECTOR_H__
13 * RTE SWX Selector Table
15 * Selector table interface.
20 #include <rte_compat.h>
22 #include "rte_swx_table.h"
24 /** Selector table creation parameters. */
25 struct rte_swx_table_selector_params {
26 /** Group ID offset. */
27 uint32_t group_id_offset;
29 /** Selector size in bytes. Must be non-zero. */
30 uint32_t selector_size;
32 /** Offset of the first byte of the selector within the selector buffer. */
33 uint32_t selector_offset;
35 /** Mask of *selector_size* bytes logically laid over the bytes at positions
36 * selector_offset* .. (*selector_offset* + *selector_size* - 1) of the selector buffer in
37 * order to specify which bits from the selector buffer are part of the selector and which
38 * ones are not. A bit value of 1 in the *selector_mask* means the respective bit in the
39 * selector buffer is part of the selector, while a bit value of 0 means the opposite. A
40 * NULL value means that all the bits are part of the selector, i.e. the *selector_mask*
41 * is an all-ones mask.
43 uint8_t *selector_mask;
45 /** Member ID offset. */
46 uint32_t member_id_offset;
48 /** Maximum number of groups. Must be non-zero. */
49 uint32_t n_groups_max;
51 /** Maximum number of members per group. Must be non-zero. */
52 uint32_t n_members_per_group_max;
55 /** Group member parameters. */
56 struct rte_swx_table_selector_member {
57 /** Linked list connectivity. */
58 RTE_TAILQ_ENTRY(rte_swx_table_selector_member) node;
64 uint32_t member_weight;
67 /** List of group members. */
68 RTE_TAILQ_HEAD(rte_swx_table_selector_member_list, rte_swx_table_selector_member);
70 /** Group parameters. */
71 struct rte_swx_table_selector_group {
72 /** List of group members. */
73 struct rte_swx_table_selector_member_list members;
77 * Selector table memory footprint get
79 * @param[in] n_groups_max
80 * Maximum number of groups. Must be non-zero.
81 * @param[in] n_members_per_group_max
82 * Maximum number of members per group. Must be non-zero.
84 * Selector table memory footprint in bytes.
88 rte_swx_table_selector_footprint_get(uint32_t n_groups_max, uint32_t n_members_per_group_max);
91 * Selector table mailbox size get
93 * The mailbox is used to store the context of a select operation that is in
94 * progress and it is passed as a parameter to the select operation. This allows
95 * for multiple concurrent select operations into the same table.
98 * Selector table mailbox footprint in bytes.
102 rte_swx_table_selector_mailbox_size_get(void);
105 * Selector table create
108 * Selector table creation parameters.
110 * Groups to be added to the table at creation time. When NULL, it signifies that all groups are
111 * invalid, otherwise it points to a pre-allocated array of size *n_groups_max*, where a NULL
112 * element indicates that the associated group is invalid.
113 * @param[in] numa_node
114 * Non-Uniform Memory Access (NUMA) node.
116 * Table handle, on success, or NULL, on error.
120 rte_swx_table_selector_create(struct rte_swx_table_selector_params *params,
121 struct rte_swx_table_selector_group **groups,
128 * Selector table handle.
129 * @param[in] group_id
134 * 0 on success or the following error codes otherwise:
135 * -EINVAL: Invalid argument(s);
136 * -ENOSPC: Too many group members.
140 rte_swx_table_selector_group_set(void *table,
142 struct rte_swx_table_selector_group *group);
145 * Selector table select
147 * This operation selects a member from the given group based on a hasing scheme.
149 * Multiple invocations of this function may be required in order to complete a single select
150 * operation for a given table and a given group ID. The completion of the operation is flagged by
151 * a return value of 1; in case of a return value of 0, the function must be invoked again with
152 * exactly the same arguments.
154 * The mailbox argument is used to store the context of each on-going operation. The mailbox
155 * mechanism allows for multiple concurrent select operations into the same table.
157 * The typical reason an implementation may choose to split the operation into multiple steps is to
158 * hide the latency of the inherent memory read operations: before a read operation with the
159 * source data likely not in the CPU cache, the source data prefetch is issued and the operation is
160 * postponed in favor of some other unrelated work, which the CPU executes in parallel with the
161 * source data being fetched into the CPU cache; later on, the operation is resumed, this time with
162 * the source data likely to be read from the CPU cache with no CPU pipeline stall, which
163 * significantly improves the operation performance.
166 * Selector table handle.
168 * Mailbox for the current operation.
169 * @param[in] group_id_buffer
170 * Buffer where the input group ID is located at offset *group_id_offset*.
171 * @param[in] selector_buffer
172 * Buffer where the key to select a member within the identified group is located starting from
173 * offset *selector_offset*. Its size must be equal to the table *selector_size*.
174 * @param[in] member_id_buffer
175 * Buffer where the output member ID is to be placed at offset *member_id_offset*.
177 * 0 when the operation is not yet completed, and 1 when the operation is complete. No other
178 * return values are allowed.
182 rte_swx_table_selector_select(void *table,
184 uint8_t **group_id_buffer,
185 uint8_t **selector_buffer,
186 uint8_t **member_id_buffer);
189 * Selector table free
192 * Selector table handle.
196 rte_swx_table_selector_free(void *table);