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 #ifdef __cplusplus 8 extern "C" { 9 #endif 10 11 /** 12 * @file 13 * RTE SWX Selector Table 14 * 15 * Selector table interface. 16 */ 17 18 #include <stdint.h> 19 #include <sys/queue.h> 20 21 #include <rte_compat.h> 22 23 #include "rte_swx_table.h" 24 25 /** Selector table creation parameters. */ 26 struct rte_swx_table_selector_params { 27 /** Group ID offset. */ 28 uint32_t group_id_offset; 29 30 /** Selector size in bytes. Must be non-zero. */ 31 uint32_t selector_size; 32 33 /** Offset of the first byte of the selector within the selector buffer. */ 34 uint32_t selector_offset; 35 36 /** Mask of *selector_size* bytes logically laid over the bytes at positions 37 * selector_offset* .. (*selector_offset* + *selector_size* - 1) of the selector buffer in 38 * order to specify which bits from the selector buffer are part of the selector and which 39 * ones are not. A bit value of 1 in the *selector_mask* means the respective bit in the 40 * selector buffer is part of the selector, while a bit value of 0 means the opposite. A 41 * NULL value means that all the bits are part of the selector, i.e. the *selector_mask* 42 * is an all-ones mask. 43 */ 44 uint8_t *selector_mask; 45 46 /** Member ID offset. */ 47 uint32_t member_id_offset; 48 49 /** Maximum number of groups. Must be non-zero. */ 50 uint32_t n_groups_max; 51 52 /** Maximum number of members per group. Must be non-zero. */ 53 uint32_t n_members_per_group_max; 54 }; 55 56 /** Group member parameters. */ 57 struct rte_swx_table_selector_member { 58 /** Linked list connectivity. */ 59 TAILQ_ENTRY(rte_swx_table_selector_member) node; 60 61 /** Member ID. */ 62 uint32_t member_id; 63 64 /** Member weight. */ 65 uint32_t member_weight; 66 }; 67 68 /** List of group members. */ 69 TAILQ_HEAD(rte_swx_table_selector_member_list, rte_swx_table_selector_member); 70 71 /** Group parameters. */ 72 struct rte_swx_table_selector_group { 73 /** List of group members. */ 74 struct rte_swx_table_selector_member_list members; 75 }; 76 77 /** 78 * Selector table memory footprint get 79 * 80 * @param[in] n_groups_max 81 * Maximum number of groups. Must be non-zero. 82 * @param[in] n_members_per_group_max 83 * Maximum number of members per group. Must be non-zero. 84 * @return 85 * Selector table memory footprint in bytes. 86 */ 87 __rte_experimental 88 uint64_t 89 rte_swx_table_selector_footprint_get(uint32_t n_groups_max, uint32_t n_members_per_group_max); 90 91 /** 92 * Selector table mailbox size get 93 * 94 * The mailbox is used to store the context of a select operation that is in 95 * progress and it is passed as a parameter to the select operation. This allows 96 * for multiple concurrent select operations into the same table. 97 * 98 * @return 99 * Selector table mailbox footprint in bytes. 100 */ 101 __rte_experimental 102 uint64_t 103 rte_swx_table_selector_mailbox_size_get(void); 104 105 /** 106 * Selector table create 107 * 108 * @param[in] params 109 * Selector table creation parameters. 110 * @param[in] groups 111 * Groups to be added to the table at creation time. When NULL, it signifies that all groups are 112 * invalid, otherwise it points to a pre-allocated array of size *n_groups_max*, where a NULL 113 * element indicates that the associated group is invalid. 114 * @param[in] numa_node 115 * Non-Uniform Memory Access (NUMA) node. 116 * @return 117 * Table handle, on success, or NULL, on error. 118 */ 119 __rte_experimental 120 void * 121 rte_swx_table_selector_create(struct rte_swx_table_selector_params *params, 122 struct rte_swx_table_selector_group **groups, 123 int numa_node); 124 125 /** 126 * Group set 127 * 128 * @param[in] table 129 * Selector table handle. 130 * @param[in] group_id 131 * Group ID. 132 * @param[in] group 133 * Group parameters. 134 * @return 135 * 0 on success or the following error codes otherwise: 136 * -EINVAL: Invalid argument(s); 137 * -ENOSPC: Too many group members. 138 */ 139 __rte_experimental 140 int 141 rte_swx_table_selector_group_set(void *table, 142 uint32_t group_id, 143 struct rte_swx_table_selector_group *group); 144 145 /** 146 * Selector table select 147 * 148 * This operation selects a member from the given group based on a hasing scheme. 149 * 150 * Multiple invocations of this function may be required in order to complete a single select 151 * operation for a given table and a given group ID. The completion of the operation is flagged by 152 * a return value of 1; in case of a return value of 0, the function must be invoked again with 153 * exactly the same arguments. 154 * 155 * The mailbox argument is used to store the context of each on-going operation. The mailbox 156 * mechanism allows for multiple concurrent select operations into the same table. 157 * 158 * The typical reason an implementation may choose to split the operation into multiple steps is to 159 * hide the latency of the inherrent memory read operations: before a read operation with the 160 * source data likely not in the CPU cache, the source data prefetch is issued and the operation is 161 * postponed in favor of some other unrelated work, which the CPU executes in parallel with the 162 * source data being fetched into the CPU cache; later on, the operation is resumed, this time with 163 * the source data likely to be read from the CPU cache with no CPU pipeline stall, which 164 * significantly improves the operation performance. 165 * 166 * @param[in] table 167 * Selector table handle. 168 * @param[in] mailbox 169 * Mailbox for the current operation. 170 * @param[in] group_id_buffer 171 * Buffer where the input group ID is located at offset *group_id_offset*. 172 * @param[in] selector_buffer 173 * Buffer where the key to select a member within the identified group is located starting from 174 * offset *selector_offset*. Its size must be equal to the table *selector_size*. 175 * @param[in] member_id_buffer 176 * Buffer where the output member ID is to be placed at offset *member_id_offset*. 177 * @return 178 * 0 when the operation is not yet completed, and 1 when the operation is complete. No other 179 * return values are allowed. 180 */ 181 __rte_experimental 182 int 183 rte_swx_table_selector_select(void *table, 184 void *mailbox, 185 uint8_t **group_id_buffer, 186 uint8_t **selector_buffer, 187 uint8_t **member_id_buffer); 188 189 /** 190 * Selector table free 191 * 192 * @param[in] table 193 * Selector table handle. 194 */ 195 __rte_experimental 196 void 197 rte_swx_table_selector_free(void *table); 198 199 #ifdef __cplusplus 200 } 201 #endif 202 203 #endif 204