diff options
| l--------- | docs/developer/corefeatures/hash.rst | 1 | ||||
| -rw-r--r-- | docs/developer/corefeatures/index.rst | 1 | ||||
| -rw-r--r-- | src/vnet/hash/hash.rst | 90 |
3 files changed, 92 insertions, 0 deletions
diff --git a/docs/developer/corefeatures/hash.rst b/docs/developer/corefeatures/hash.rst new file mode 120000 index 00000000000..6f967691e76 --- /dev/null +++ b/docs/developer/corefeatures/hash.rst @@ -0,0 +1 @@ +../../../src/vnet/hash/hash.rst
\ No newline at end of file diff --git a/docs/developer/corefeatures/index.rst b/docs/developer/corefeatures/index.rst index 780fc837eb6..f1b40b3a2f1 100644 --- a/docs/developer/corefeatures/index.rst +++ b/docs/developer/corefeatures/index.rst @@ -23,3 +23,4 @@ Core Features stats selinux_doc policer + hash diff --git a/src/vnet/hash/hash.rst b/src/vnet/hash/hash.rst new file mode 100644 index 00000000000..3db74e2f093 --- /dev/null +++ b/src/vnet/hash/hash.rst @@ -0,0 +1,90 @@ +.. _hash_doc: + +Hash Infra +========== + +Overview +________ + +Modern physical NICs uses packet flow hash for different purposes, i.e. Receive +Side Scaling, flow steering and interface bonding etc. NICs can also provide +packet flow hash prepended to data packet as metadata which can be used by +applications without recomputing the packet flow hash. + +As more and more services are deployed in virtualized environment, making use of +virtual interfaces to interconnect those services. + +The Hash Infrastructure +_______________________ + +VPP implements software based hashing functionality which can be used for different +purposes. It also provides users a centralized way to registry custom hash functions +based on traffic profile to be used in different vpp features i.e. Multi-TXQ, +software RSS or bonding driver. + +Data structures +^^^^^^^^^^^^^^^ + +Hashing infra provides two types of hashing functions: +``VNET_HASH_FN_TYPE_ETHERNET`` and ``VNET_HASH_FN_TYPE_IP`` for ethernet traffic and +IP traffic respectively. +Hashing infra provides uniform signature to the functions to be implemented: + +.. code:: c + + void (*vnet_hash_fn_t) (void **p, u32 *h, u32 n_packets); + +Here ``**p`` is the array of pointers pointing to the beginning of packet headers +(either ethernet or ip). +``*h`` is an empty array of size n_packets. On return, it will contain hashes. +``n_packets`` is the number of packets pass to this function. + +Custom hashing functions can be registered through ``VNET_REGISTER_HASH_FUNCTION``. +Users need to provide a name, description, priority and hashing functions for +registration. + +Default hashing function is selected based on the highest priority among the registered +hashing functions. + +.. code:: c + + typedef struct vnet_hash_function_registration + { + const char *name; + const char *description; + int priority; + vnet_hash_fn_t function[VNET_HASH_FN_TYPE_N]; + + struct vnet_hash_function_registration *next; + } vnet_hash_function_registration_t; + +For example, ``crc32c_5tuple`` provides two hashing functions: for IP traffic and for +ethernet traffic. It uses 5 tuples from the flow to compute the crc32 hash on it. + +.. code:: c + + void vnet_crc32c_5tuple_ip_func (void **p, u32 *hash, u32 n_packets); + void vnet_crc32c_5tuple_ethernet_func (void **p, u32 *hash, u32 n_packets); + + VNET_REGISTER_HASH_FUNCTION (crc32c_5tuple, static) = { + .name = "crc32c-5tuple", + .description = "IPv4/IPv6 header and TCP/UDP ports", + .priority = 50, + .function[VNET_HASH_FN_TYPE_ETHERNET] = vnet_crc32c_5tuple_ethernet_func, + .function[VNET_HASH_FN_TYPE_IP] = vnet_crc32c_5tuple_ip_func, + }; + + +Users can see all the registered hash functions along with priority and description. + +Hash API +^^^^^^^^ + +There is no Hash API at the moment. + +Hash CLI +^^^^^^^^ + +:: + + show hash |