DPDK  23.03.0
Data Structures | Macros | Typedefs | Functions
rte_thash.h File Reference
#include <stdint.h>
#include <rte_compat.h>
#include <rte_byteorder.h>
#include <rte_ip.h>
#include <rte_common.h>
#include <rte_thash_gfni.h>

Go to the source code of this file.

Data Structures

struct  rte_ipv4_tuple
 
struct  rte_ipv6_tuple
 

Macros

#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_IGNORE_PERIOD_OVERFLOW   0x1
 
#define RTE_THASH_MINIMAL_SEQ   0x2
 

Typedefs

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

Functions

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)
 
__rte_experimental int rte_thash_gfni_supported (void)
 
__rte_experimental void rte_thash_complete_matrix (uint64_t *matrixes, const uint8_t *rss_key, int size)
 
__rte_experimental 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)
 
__rte_experimental struct rte_thash_ctx * rte_thash_find_existing (const char *name)
 
__rte_experimental void rte_thash_free_ctx (struct rte_thash_ctx *ctx)
 
__rte_experimental int rte_thash_add_helper (struct rte_thash_ctx *ctx, const char *name, uint32_t len, uint32_t offset)
 
__rte_experimental struct rte_thash_subtuple_helper * rte_thash_get_helper (struct rte_thash_ctx *ctx, const char *name)
 
__rte_experimental uint32_t rte_thash_get_complement (struct rte_thash_subtuple_helper *h, uint32_t hash, uint32_t desired_hash)
 
__rte_experimental const uint8_t * rte_thash_get_key (struct rte_thash_ctx *ctx)
 
__rte_experimental const uint64_t * rte_thash_get_gfni_matrices (struct rte_thash_ctx *ctx)
 
__rte_experimental 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)
 

Detailed Description

Software implementation of the Toeplitz hash function used by RSS. Can be used either for packet distribution on single queue NIC or for simulating of RSS computation on specific NIC (for example after GRE header decapsulating)

Definition in file rte_thash.h.

Macro Definition Documentation

◆ RTE_THASH_V4_L3_LEN

#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 45 of file rte_thash.h.

◆ RTE_THASH_V4_L4_LEN

#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 53 of file rte_thash.h.

◆ RTE_THASH_V6_L3_LEN

#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 59 of file rte_thash.h.

◆ RTE_THASH_V6_L4_LEN

#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 67 of file rte_thash.h.

◆ RTE_THASH_IGNORE_PERIOD_OVERFLOW

#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 266 of file rte_thash.h.

◆ RTE_THASH_MINIMAL_SEQ

#define RTE_THASH_MINIMAL_SEQ   0x2

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

Definition at line 271 of file rte_thash.h.

Typedef Documentation

◆ rte_thash_check_tuple_t

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.

Warning
EXPERIMENTAL: this API may change without prior notice.
Parameters
userdataPointer to the userdata. It could be a pointer to the table with used tuples to search.
tuplePointer to the tuple to check
Returns
1 on success 0 otherwise

Definition at line 457 of file rte_thash.h.

Function Documentation

◆ rte_convert_rss_key()

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

Prepare special converted key to use with rte_softrss_be()

Parameters
origpointer to original RSS key
targpointer to target RSS key
lenRSS key length

Definition at line 123 of file rte_thash.h.

◆ rte_thash_load_v6_addrs()

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

Prepare and load IPv6 addresses (src and dst) into target tuple

Parameters
origPointer to ipv6 header of the original packet
targPointer to rte_ipv6_tuple structure

Definition at line 140 of file rte_thash.h.

◆ rte_softrss()

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

Generic implementation. Can be used with original rss_key

Parameters
input_tuplePointer to input tuple
input_lenLength of input_tuple in 4-bytes chunks
rss_keyPointer to RSS hash key.
Returns
Calculated hash value.

Definition at line 178 of file rte_thash.h.

◆ rte_softrss_be()

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

Optimized implementation. If you want the calculated hash value matches NIC RSS value you have to use special converted key with rte_convert_rss_key() fn.

Parameters
input_tuplePointer to input tuple
input_lenLength of input_tuple in 4-bytes chunks
*rss_keyPointer to RSS hash key.
Returns
Calculated hash value.

Definition at line 208 of file rte_thash.h.

◆ rte_thash_gfni_supported()

__rte_experimental int rte_thash_gfni_supported ( void  )

Indicates if GFNI implementations of the Toeplitz hash are supported.

Warning
EXPERIMENTAL: this API may change without prior notice.
Returns
1 if GFNI is supported 0 otherwise

◆ rte_thash_complete_matrix()

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

Converts Toeplitz hash key (RSS key) into matrixes required for GFNI implementation

Warning
EXPERIMENTAL: this API may change without prior notice.
Parameters
matrixespointer to the memory where matrices will be written. Note: the size of this memory must be equal to size * 8
rss_keypointer to the Toeplitz hash key
sizeSize of the rss_key in bytes.

◆ rte_thash_init_ctx()

__rte_experimental 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 
)

Create a new thash context.

Warning
EXPERIMENTAL: this API may change without prior notice.
Parameters
nameContext name
key_lenLength of the toeplitz hash key
reta_szLogarithm of the NIC's Redirection Table (ReTa) size, i.e. number of the LSBs if the hash used to determine the reta entry.
keyPointer to the key used to init an internal key state. Could be NULL, in this case internal key will be inited with random.
flagsSupported 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()

__rte_experimental struct rte_thash_ctx* rte_thash_find_existing ( const char *  name)

Find an existing thash context and return a pointer to it.

Warning
EXPERIMENTAL: this API may change without prior notice.
Parameters
nameName 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()

__rte_experimental void rte_thash_free_ctx ( struct rte_thash_ctx *  ctx)

Free a thash context object

Warning
EXPERIMENTAL: this API may change without prior notice.
Parameters
ctxThash context

◆ rte_thash_add_helper()

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

Add a special properties to the toeplitz hash key inside a thash context. Creates an internal helper struct which has a complementary table to calculate toeplitz hash collisions. This function is not multi-thread safe.

Warning
EXPERIMENTAL: this API may change without prior notice.
Parameters
ctxThash context
nameName of the helper
lenLength in bits of the target subtuple Must be no shorter than reta_sz passed on rte_thash_init_ctx().
offsetOffset in bits of the subtuple
Returns
0 on success negative on error

◆ rte_thash_get_helper()

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

Find a helper in the context by the given name

Warning
EXPERIMENTAL: this API may change without prior notice.
Parameters
ctxThash context
nameName of the helper
Returns
Pointer to the thash helper or NULL if it was not found.

◆ rte_thash_get_complement()

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

Get a complementary value for the subtuple to produce a partial toeplitz hash collision. It must be XOR'ed with the subtuple to produce the hash value with the desired hash LSB's This function is multi-thread safe.

Parameters
hPointer to the helper struct
hashToeplitz hash value calculated for the given tuple
desired_hashDesired hash value to find a collision for
Returns
A complementary value which must be xored with the corresponding subtuple

◆ rte_thash_get_key()

__rte_experimental const uint8_t* rte_thash_get_key ( struct rte_thash_ctx *  ctx)

Get a pointer to the toeplitz hash contained in the context. It changes after each addition of a helper. It should be installed to the NIC.

Warning
EXPERIMENTAL: this API may change without prior notice.
Parameters
ctxThash context
Returns
A pointer to the toeplitz hash key

◆ rte_thash_get_gfni_matrices()

__rte_experimental const uint64_t* rte_thash_get_gfni_matrices ( struct rte_thash_ctx *  ctx)

Get a pointer to the toeplitz hash matrices contained in the context. These matrices could be used with fast toeplitz hash implementation if CPU supports GFNI. Matrices changes after each addition of a helper.

Warning
EXPERIMENTAL: this API may change without prior notice.
Parameters
ctxThash context
Returns
A pointer to the toeplitz hash key matrices on success NULL if GFNI is not supported.

◆ rte_thash_adjust_tuple()

__rte_experimental 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 
)

Adjusts tuple in the way to make Toeplitz hash has desired least significant bits. This function is multi-thread safe.

Warning
EXPERIMENTAL: this API may change without prior notice.
Parameters
ctxThash context
hPointer to the helper struct
tuplePointer to the tuple to be adjusted
tuple_lenLength of the tuple. Must be multiple of 4.
desired_valueDesired value of least significant bits of the hash
attemptsNumber of attempts to adjust tuple with fn() calling
fnCallback function to check adjusted tuple. Could be NULL
userdataPointer to the userdata to be passed to fn(). Could be NULL
Returns
0 on success negative otherwise