rte_thash.h(3)

📦
version 25.11.3 · 11 versions
, in ubuntu resolute, ubuntu stonking

💖 rte_thash.h — NAME 💖

okay so. rte_thash.h(3), from the Library Functions Manual, bestie. This is the header, and it's a whole vibe — it's the Toeplitz hash header that the DPDK girlies use for RSS. No cap. 💅

🌸 SYNOPSIS 🌸

Like, here's how you even get in the door:

#include <stdint.h>
#include <rte_byteorder.h>
#include <rte_ip.h>
#include <rte_common.h>
#include <rte_thash_gfni.h>

🧸 Data Structures

the little struct babies we're working with:

  • struct rte_ipv4_tuple
  • struct rte_ipv6_tuple

🎀 Macros

the defines, and yes, we're keeping every single number exactly as-is:

  • #define RTE_THASH_V4_L3_LEN
  • #define RTE_THASH_V4_L4_LEN ((sizeof(struct rte_ipv4_tuple)) / 4)
  • #define RTE_THASH_V6_L3_LEN
  • #define RTE_THASH_V6_L4_LEN ((sizeof(struct rte_ipv6_tuple)) / 4)
  • #define RTE_THASH_KEY_LEN_MAX 52
  • #define RTE_THASH_IGNORE_PERIOD_OVERFLOW 0x1
  • #define RTE_THASH_MINIMAL_SEQ 0x2

🦋 Typedefs

  • typedef int(* rte_thash_check_tuple_t) (void *userdata, uint8_t *tuple)

⭐ Functions

not me listing literally every single one, but like — here they all are, verbatim, because we do not skip. we do not summarise. periodt:

static void rte_convert_rss_key (const uint32_t *orig, uint32_t *targ,
    int len)
static void rte_thash_load_v6_addrs (const struct rte_ipv6_hdr *orig,
    union rte_thash_tuple *targ)
static uint32_t rte_softrss (uint32_t *input_tuple, uint32_t input_len,
    const uint8_t *rss_key)
static uint32_t rte_softrss_be (uint32_t *input_tuple, uint32_t
    input_len, const uint8_t *rss_key)
int rte_thash_gfni_supported (void)
void rte_thash_complete_matrix (uint64_t *matrixes, const uint8_t
    *rss_key, int size)
struct rte_thash_ctx * rte_thash_init_ctx (const char *name, uint32_t
    key_len, uint32_t reta_sz, uint8_t *key, uint32_t flags)
struct rte_thash_ctx * rte_thash_find_existing (const char *name)
void rte_thash_free_ctx (struct rte_thash_ctx *ctx)
int rte_thash_add_helper (struct rte_thash_ctx *ctx, const char *name,
    uint32_t len, uint32_t offset)
struct rte_thash_subtuple_helper * rte_thash_get_helper (struct
    rte_thash_ctx *ctx, const char *name)
uint32_t rte_thash_get_complement (struct rte_thash_subtuple_helper *h,
    uint32_t hash, uint32_t desired_hash)
const uint8_t * rte_thash_get_key (struct rte_thash_ctx *ctx)
const uint64_t * rte_thash_get_gfni_matrices (struct rte_thash_ctx *ctx)
int rte_thash_adjust_tuple (struct rte_thash_ctx *ctx, struct
    rte_thash_subtuple_helper *h, uint8_t *tuple, unsigned int
    tuple_len, uint32_t desired_value, unsigned int attempts,
    rte_thash_check_tuple_t fn, void *userdata)
__rte_experimental int rte_thash_gen_key (uint8_t *key, size_t key_len,
    size_t reta_sz_log, uint32_t entropy_start, size_t entropy_sz)

✨ DESCRIPTION (Detailed Description) ✨

So what is this whole situation? 💭

It's a software implementation of the Toeplitz hash function used by RSS. yes girl, the real thing.

And the way it can be used is, like, two whole moods:

  • for packet distribution on a single queue NIC, or
  • for simulating RSS computation on a specific NIC (for example after GRE header decapsulating).
no extra lore, that's literally it — I'm not adding fake facts, we stay honest in this group chat 🫶

Definition in file rte_thash.h.

🧚 MACRO DEFINITION DOCUMENTATION 🧚

🌈 #define RTE_THASH_V4_L3_LEN

Value:

((sizeof(struct rte_ipv4_tuple) -   \
sizeof(((struct rte_ipv4_tuple *)0)->sctp_tag)) / 4)

length in dwords of input tuple to calculate hash of ipv4 header only.

Definition at line 37 of file rte_thash.h.

🌈 #define RTE_THASH_V4_L4_LEN ((sizeof(struct rte_ipv4_tuple)) / 4)

length in dwords of input tuple to calculate hash of ipv4 header + transport header.

Definition at line 45 of file rte_thash.h.

🌈 #define RTE_THASH_V6_L3_LEN

Value:

((sizeof(struct rte_ipv6_tuple) -       \
sizeof(((struct rte_ipv6_tuple *)0)->sctp_tag)) / 4)

length in dwords of input tuple to calculate hash of ipv6 header only.

Definition at line 51 of file rte_thash.h.

🌈 #define RTE_THASH_V6_L4_LEN ((sizeof(struct rte_ipv6_tuple)) / 4)

length in dwords of input tuple to calculate hash of ipv6 header + transport header.

Definition at line 59 of file rte_thash.h.

🌈 #define RTE_THASH_KEY_LEN_MAX 52

Longest RSS hash key currently supported.

Definition at line 119 of file rte_thash.h.

🌈 #define RTE_THASH_IGNORE_PERIOD_OVERFLOW 0x1

LFSR will ignore if generated m-sequence has more than 2^n -1 bits, where n is the logarithm of the RSS ReTa size.

Definition at line 273 of file rte_thash.h.

🌈 #define RTE_THASH_MINIMAL_SEQ 0x2

Generate minimal required bit (equal to ReTa LSB) sequence into the hash_key.

Definition at line 278 of file rte_thash.h.

💜 TYPEDEF DOCUMENTATION 💜

🫶 typedef int(* rte_thash_check_tuple_t) (void *userdata, uint8_t *tuple)

Function prototype for the rte_thash_adjust_tuple to check if adjusted tuple could be used. Generally it is some kind of lookup function to check if adjusted tuple is already in use.

Parameters

  • userdata — Pointer to the userdata. It could be a pointer to the table with used tuples to search.
  • tuple — Pointer to the tuple to check

Returns

1 on success 0 otherwise.

Definition at line 432 of file rte_thash.h.

okay bestie we are SO not done, hold onto your scrunchie — part 2 is right there 👑

✨ Function Documentation ✨

rte_convert_rss_key

void rte_convert_rss_key (const uint32_t * orig, uint32_t * targ, int len)

[inline], [static]

okay bestie, this one is the little setup step you need first 💅 — it preps a special converted key so you can feed it to rte_softrss_be().

Parameters

  • orig — pointer to the original RSS key
  • targ — pointer to the target RSS key
  • len — RSS key length

Definition at line 133 of file rte_thash.h.

rte_thash_load_v6_addrs

void rte_thash_load_v6_addrs (const struct rte_ipv6_hdr * orig,
                              union rte_thash_tuple * targ)

[inline], [static]

she's here to prepare and load IPv6 addresses (both src and dst 🫶) straight into the target tuple.

Parameters

  • orig — Pointer to ipv6 header of the original packet
  • targ — Pointer to rte_ipv6_tuple structure

Definition at line 150 of file rte_thash.h.

rte_softrss

uint32_t rte_softrss (uint32_t * input_tuple, uint32_t input_len,
                      const uint8_t * rss_key)

[inline], [static]

the generic implementation bestie ✨ and yes, you can totally use it with the original rss_key.

Parameters

  • input_tuple — Pointer to input tuple
  • input_len — Length of input_tuple in 4-bytes chunks
  • rss_key — Pointer to RSS hash key.

Returns

Calculated hash value. 💖

Definition at line 193 of file rte_thash.h.

rte_softrss_be

uint32_t rte_softrss_be (uint32_t * input_tuple, uint32_t input_len,
                         const uint8_t * rss_key)

[inline], [static]

the optimized implementation 🔥 and listen, this part matters: if you want your calculated hash value to match the NIC RSS value, you have to use a special converted key made with the rte_convert_rss_key() fn. no shortcuts, iykyk.

Parameters

  • input_tuple — Pointer to input tuple
  • input_len — Length of input_tuple in 4-bytes chunks
  • *rss_key — Pointer to RSS hash key.

Returns

Calculated hash value. 💖

Definition at line 223 of file rte_thash.h.

rte_thash_gfni_supported

int rte_thash_gfni_supported (void )

vibe check 💀 — this tells you if the GFNI implementations of the Toeplitz hash are supported at all.

Returns

1 if GFNI is supported, 0 otherwise.

rte_thash_complete_matrix

void rte_thash_complete_matrix (uint64_t * matrixes, const uint8_t * rss_key,
                                int size)

she converts a Toeplitz hash key (that's your RSS key bestie) into the matrixes you need for the GFNI implementation 🌈.

Parameters

  • matrixes — pointer to the memory where matrices will be written. Note: the size of this memory must be equal to size * 8
  • rss_key — pointer to the Toeplitz hash key
  • size — Size of the rss_key in bytes.

rte_thash_init_ctx

struct rte_thash_ctx * rte_thash_init_ctx (const char * name,
                                           uint32_t key_len,
                                           uint32_t reta_sz,
                                           uint8_t * key,
                                           uint32_t flags)

main character energy 👑 — this creates a brand new thash context.

Parameters

  • name — Context name
  • key_len — Length of the toeplitz hash key
  • reta_sz — Logarithm of the NIC's Redirection Table (ReTa) size, i.e. number of the LSBs if the hash used to determine the reta entry.
  • key — Pointer to the key used to init an internal key state. Could be NULL, in this case internal key will be inited with random.
  • flags — Supported flags are: RTE_THASH_IGNORE_PERIOD_OVERFLOW, RTE_THASH_MINIMAL_SEQ

Returns

A pointer to the created context on success, NULL otherwise.

rte_thash_find_existing

struct rte_thash_ctx * rte_thash_find_existing (const char * name)

finds an existing thash context and hands you a pointer to it 🫶.

Parameters

  • name — Name of the thash context

Returns

Pointer to the thash context, or NULL if it was not found, with rte_errno set appropriately. Possible rte_errno values include:

  • ENOENT - required entry not available to return.

rte_thash_free_ctx

void rte_thash_free_ctx (struct rte_thash_ctx * ctx)

bye bye 👋 — frees a thash context object.

Parameters

  • ctx — Thash context

rte_thash_add_helper

int rte_thash_add_helper (struct rte_thash_ctx * ctx, const char * name,
                          uint32_t len, uint32_t offset)

adds special properties to the toeplitz hash key inside a thash context ✨. She creates an internal helper struct that carries a complementary table for calculating toeplitz hash collisions.

⚠️ heads up bestie: this function is not multi-thread safe. no cap.

Parameters

  • ctx — Thash context
  • name — Name of the helper
  • len — Length in bits of the target subtuple. Must be no shorter than reta_sz passed on rte_thash_init_ctx().
  • offset — Offset in bits of the subtuple

Returns

0 on success, negative on error.

rte_thash_get_helper

struct rte_thash_subtuple_helper * rte_thash_get_helper
                                        (struct rte_thash_ctx * ctx,
                                         const char * name)

digs up a helper in the context by the given name 🔍.

Parameters

  • ctx — Thash context
  • name — Name of the helper

Returns

Pointer to the thash helper, or NULL if it was not found.

rte_thash_get_complement

uint32_t rte_thash_get_complement (struct rte_thash_subtuple_helper * h,
                                   uint32_t hash, uint32_t desired_hash)

gets a complementary value for the subtuple so you can produce a partial toeplitz hash collision 🎀. You have to XOR it with the subtuple to get the hash value with the desired hash LSB's. And good news — this function is multi-thread safe 💅.

Parameters

  • h — Pointer to the helper struct
  • hash — Toeplitz hash value calculated for the given tuple
  • desired_hash — Desired hash value to find a collision for

Returns

A complementary value which must be xored with the corresponding subtuple.

rte_thash_get_key

const uint8_t * rte_thash_get_key (struct rte_thash_ctx * ctx)

hands you a pointer to the toeplitz hash contained in the context 🦋. Fair warning: it changes after each addition of a helper. It should be installed to the NIC.

Parameters

  • ctx — Thash context

Returns

A pointer to the toeplitz hash key.

rte_thash_get_gfni_matrices

const uint64_t * rte_thash_get_gfni_matrices (struct rte_thash_ctx * ctx)

pointer to the toeplitz hash matrices living inside the context 🌈. These matrices could be used with the fast toeplitz hash implementation if the CPU supports GFNI. And yeah — the matrices change after each addition of a helper, so don't get too attached bestie.

Parameters

  • ctx — Thash context

Returns

A pointer to the toeplitz hash key matrices on success, NULL if GFNI is not supported.

rte_thash_adjust_tuple

int rte_thash_adjust_tuple (struct rte_thash_ctx * ctx,
                            struct rte_thash_subtuple_helper * h,
                            uint8_t * tuple, unsigned int tuple_len,
                            uint32_t desired_value, unsigned int attempts,
                            rte_thash_check_tuple_t fn, void * userdata)

she adjusts the tuple so that the Toeplitz hash has the desired least significant bits ✨. Also multi-thread safe, slay.

Parameters

  • ctx — Thash context
  • h — Pointer to the helper struct
  • tuple — Pointer to the tuple to be adjusted
  • tuple_len — Length of the tuple. Must be multiple of 4.
  • desired_value — Desired value of least significant bits of the hash
  • attempts — Number of attempts to adjust tuple with fn() calling
  • fn — Callback function to check adjusted tuple. Could be NULL
  • userdata — Pointer to the userdata to be passed to fn(). Could be NULL

Returns

0 on success, negative otherwise.

rte_thash_gen_key

__rte_experimental int rte_thash_gen_key (uint8_t * key, size_t key_len,
                                          size_t reta_sz_log,
                                          uint32_t entropy_start,
                                          size_t entropy_sz)
🚨 Warning: EXPERIMENTAL: this API may change without prior notice. fr fr, don't build your whole personality on it.

modifies the RSS hash key such that the subtuple bits corresponding to entropy_sz bits starting from entropy_start will have the most even distribution with this key, with a given ReTa size 🌸.

Parameters

  • key — Pointer to the RSS hash key.
  • key_len — Length of the key.
  • reta_sz_log — Log2 of the size of RSS redirection table, i.e. number of bits of the RSS hash value used to identify RSS ReTa entry.
  • entropy_start — Bit offset from the beginning of the tuple where user expects best distribution of the subtuple values.
  • entropy_sz — Size in bits of the part of subtuple.

Returns

0 on success, negative otherwise.

🌸 Author 🌸

Generated automatically by Doxygen for DPDK from the source code. Not a human bestie, just a very dedicated robot 💜

and that's a wrap on rte_thash.h(3) 🎀 this page came to you from DPDK Version 25.11.3, and it's page rte_thash.h(3) in the manual — go forth and hash responsibly, ily, bye 💅✨

📦 where this page comes from