src/vnet/hash/hash.rst

   1 .. _hash_doc:
   2
   3 Hash Infra
   4 ==========
   5
   6 Overview
   7 ________
   8
   9 Modern physical NICs uses packet flow hash for different purposes, i.e. Receive
  10 Side Scaling, flow steering and interface bonding etc. NICs can also provide
  11 packet flow hash prepended to data packet as metadata which can be used by
  12 applications without recomputing the packet flow hash.
  13
  14 As more and more services are deployed in virtualized environment, making use of
  15 virtual interfaces to interconnect those services.
  16
  17 The Hash Infrastructure
  18 _______________________
  19
  20 VPP implements software based hashing functionality which can be used for different
  21 purposes. It also provides users a centralized way to registry custom hash functions
  22 based on traffic profile to be used in different vpp features i.e. Multi-TXQ,
  23 software RSS or bonding driver.
  24
  25 Data structures
  26 ^^^^^^^^^^^^^^^
  27
  28 Hashing infra provides two types of hashing functions:
  29 ``VNET_HASH_FN_TYPE_ETHERNET`` and ``VNET_HASH_FN_TYPE_IP`` for ethernet traffic and
  30 IP traffic respectively.
  31 Hashing infra provides uniform signature to the functions to be implemented:
  32
  33 .. code:: c
  34
  35   void (*vnet_hash_fn_t) (void **p, u32 *h, u32 n_packets);
  36
  37 Here ``**p`` is the array of pointers pointing to the beginning of packet headers
  38 (either ethernet or ip).
  39 ``*h`` is an empty array of size n_packets. On return, it will contain hashes.
  40 ``n_packets`` is the number of packets pass to this function.
  41
  42 Custom hashing functions can be registered through ``VNET_REGISTER_HASH_FUNCTION``.
  43 Users need to provide a name, description, priority and hashing functions for
  44 registration.
  45
  46 Default hashing function is selected based on the highest priority among the registered
  47 hashing functions.
  48
  49 .. code:: c
  50
  51   typedef struct vnet_hash_function_registration
  52   {
  53     const char *name;
  54     const char *description;
  55     int priority;
  56     vnet_hash_fn_t function[VNET_HASH_FN_TYPE_N];
  57
  58     struct vnet_hash_function_registration *next;
  59   } vnet_hash_function_registration_t;
  60
  61 For example, ``crc32c_5tuple`` provides two hashing functions: for IP traffic and for
  62 ethernet traffic. It uses 5 tuples from the flow to compute the crc32 hash on it.
  63
  64 .. code:: c
  65
  66   void vnet_crc32c_5tuple_ip_func (void **p, u32 *hash, u32 n_packets);
  67   void vnet_crc32c_5tuple_ethernet_func (void **p, u32 *hash, u32 n_packets);
  68
  69   VNET_REGISTER_HASH_FUNCTION (crc32c_5tuple, static) = {
  70     .name = "crc32c-5tuple",
  71     .description = "IPv4/IPv6 header and TCP/UDP ports",
  72     .priority = 50,
  73     .function[VNET_HASH_FN_TYPE_ETHERNET] = vnet_crc32c_5tuple_ethernet_func,
  74     .function[VNET_HASH_FN_TYPE_IP] = vnet_crc32c_5tuple_ip_func,
  75   };
  76
  77
  78 Users can see all the registered hash functions along with priority and description.
  79
  80 Hash API
  81 ^^^^^^^^
  82
  83 There is no Hash API at the moment.
  84
  85 Hash CLI
  86 ^^^^^^^^
  87
  88 ::
  89
  90   show hash