summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMohsin Kazmi <sykazmi@cisco.com>2023-05-05 11:09:31 +0000
committerDave Wallace <dwallacelf@gmail.com>2023-05-24 14:47:42 +0000
commit5e42eae58be468ca82a372b4f751e98f327b389e (patch)
tree25a06c777d19fefc6713ae30fea7a2ec8a7de6ed
parenta7dd04d73bf5abed944fb77a5e957bbad24e2750 (diff)
hash: add hash documentation
Type: docs Signed-off-by: Mohsin Kazmi <sykazmi@cisco.com> Change-Id: I36764aa3c0e9657d228413aeafa0a54bbd755e49
l---------docs/developer/corefeatures/hash.rst1
-rw-r--r--docs/developer/corefeatures/index.rst1
-rw-r--r--src/vnet/hash/hash.rst90
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