--- name: "RTE_THASH_V6_L3_LEN" section: "3" platform: "linux" package: "dpdk-doc" version: "24.11.4-0+deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/rte_thash.h" --- # RTE\_THASH\_V6\_L3\_LEN(3) Part of [rte\_thash.h(3)](/rte_thash.h/3.md). ## NAME rte\_thash.h ## SYNOPSIS `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ ### 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)\ 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:**.PP ``` ((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**. ### #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**. ### #define RTE\_THASH\_V6\_L3\_LEN **Value:**.PP ``` ((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**. ### #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**. ### #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 **269** 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 **274** 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 **428** of file **rte\_thash.h**. ## Function Documentation ### static 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 **134** of file **rte\_thash.h**. ### static 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 **151** of file **rte\_thash.h**. ### static 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 **189** of file **rte\_thash.h**. ### static 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 **219** 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.