lib/table/rte_swx_table_selector.h

   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