rte_thash.h(3)

NAME
rte_thash.h

SYNOPSIS

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

  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_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

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)

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

  #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.

Function Documentation

  void rte_convert_rss_key (const uint32_t * orig, uint32_t * targ, int len) [inline], [static]
Prepare special converted key to use with rte_softrss_be()

Parameters
    orig pointer to original RSS key
    targ pointer to target RSS key
    len RSS key length

Definition at line 133 of file rte_thash.h.

  void rte_thash_load_v6_addrs (const struct rte_ipv6_hdr * orig, union rte_thash_tuple * targ) [inline], [static]
Prepare and load IPv6 addresses (src and dst) into 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.

  uint32_t rte_softrss (uint32_t * input_tuple, uint32_t input_len, const uint8_t * rss_key) [inline], [static]
Generic implementation. Can be used with 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.

  uint32_t rte_softrss_be (uint32_t * input_tuple, uint32_t input_len, const uint8_t * rss_key) [inline], [static]
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_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.

  int rte_thash_gfni_supported (void )
Indicates if GFNI implementations of the Toeplitz hash are supported.

Returns
    1 if GFNI is supported 0 otherwise

  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

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.

  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.

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

  struct rte_thash_ctx * rte_thash_find_existing (const char * name)
Find an existing thash context and return 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.

  void rte_thash_free_ctx (struct rte_thash_ctx * ctx)
Free a thash context object

Parameters
    ctx Thash context

  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.

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

  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

Parameters
    ctx Thash context
    name Name of the helper

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

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

  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.

Parameters
    ctx Thash context

Returns
    A pointer to the toeplitz hash key

  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.

Parameters
    ctx Thash context

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

  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.

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_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.

Modify RSS hash key such that 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.