1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2021 Intel Corporation 3 */ 4 #ifndef __INCLUDE_RTE_SWX_TABLE_SELECTOR_H__ 5 #define __INCLUDE_RTE_SWX_TABLE_SELECTOR_H__ 6 7 /** 8 * @file 9 * RTE SWX Selector Table 10 * 11 * Selector table interface. 12 */ 13 14 #include <stdint.h> 15 16 #include <rte_compat.h> 17 18 #include "rte_swx_table.h" 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 /** Selector table creation parameters. */ 25 struct rte_swx_table_selector_params { 26 /** Group ID offset. */ 27 uint32_t group_id_offset; 28 29 /** Selector size in bytes. Must be non-zero. */ 30 uint32_t selector_size; 31 32 /** Offset of the first byte of the selector within the selector buffer. */ 33 uint32_t selector_offset; 34 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. 42 */ 43 uint8_t *selector_mask; 44 45 /** Member ID offset. */ 46 uint32_t member_id_offset; 47 48 /** Maximum number of groups. Must be non-zero. */ 49 uint32_t n_groups_max; 50 51 /** Maximum number of members per group. Must be non-zero. */ 52 uint32_t n_members_per_group_max; 53 }; 54 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; 59 60 /** Member ID. */ 61 uint32_t member_id; 62 63 /** Member weight. */ 64 uint32_t member_weight; 65 }; 66 67 /** List of group members. */ 68 RTE_TAILQ_HEAD(rte_swx_table_selector_member_list, rte_swx_table_selector_member); 69 70 /** Group parameters. */ 71 struct rte_swx_table_selector_group { 72 /** List of group members. */ 73 struct rte_swx_table_selector_member_list members; 74 }; 75 76 /** 77 * Selector table memory footprint get 78 * 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. 83 * @return 84 * Selector table memory footprint in bytes. 85 */ 86 __rte_experimental 87 uint64_t 88 rte_swx_table_selector_footprint_get(uint32_t n_groups_max, uint32_t n_members_per_group_max); 89 90 /** 91 * Selector table mailbox size get 92 * 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. 96 * 97 * @return 98 * Selector table mailbox footprint in bytes. 99 */ 100 __rte_experimental 101 uint64_t 102 rte_swx_table_selector_mailbox_size_get(void); 103 104 /** 105 * Selector table create 106 * 107 * @param[in] params 108 * Selector table creation parameters. 109 * @param[in] groups 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. 115 * @return 116 * Table handle, on success, or NULL, on error. 117 */ 118 __rte_experimental 119 void * 120 rte_swx_table_selector_create(struct rte_swx_table_selector_params *params, 121 struct rte_swx_table_selector_group **groups, 122 int numa_node); 123 124 /** 125 * Group set 126 * 127 * @param[in] table 128 * Selector table handle. 129 * @param[in] group_id 130 * Group ID. 131 * @param[in] group 132 * Group parameters. 133 * @return 134 * 0 on success or the following error codes otherwise: 135 * -EINVAL: Invalid argument(s); 136 * -ENOSPC: Too many group members. 137 */ 138 __rte_experimental 139 int 140 rte_swx_table_selector_group_set(void *table, 141 uint32_t group_id, 142 struct rte_swx_table_selector_group *group); 143 144 /** 145 * Selector table select 146 * 147 * This operation selects a member from the given group based on a hasing scheme. 148 * 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. 153 * 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. 156 * 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. 164 * 165 * @param[in] table 166 * Selector table handle. 167 * @param[in] mailbox 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*. 176 * @return 177 * 0 when the operation is not yet completed, and 1 when the operation is complete. No other 178 * return values are allowed. 179 */ 180 __rte_experimental 181 int 182 rte_swx_table_selector_select(void *table, 183 void *mailbox, 184 uint8_t **group_id_buffer, 185 uint8_t **selector_buffer, 186 uint8_t **member_id_buffer); 187 188 /** 189 * Selector table free 190 * 191 * @param[in] table 192 * Selector table handle. 193 */ 194 __rte_experimental 195 void 196 rte_swx_table_selector_free(void *table); 197 198 #ifdef __cplusplus 199 } 200 #endif 201 202 #endif 203