From 534fe5f33999fd92f27cbcf731accc91b8dc8b78 Mon Sep 17 00:00:00 2001 From: Vladimir Medvedkin Date: Mon, 19 Apr 2021 16:59:54 +0100 Subject: [PATCH] doc: add Toeplitz hash guide Add documentation for the Toeplitz hash library. Signed-off-by: Vladimir Medvedkin Reviewed-by: Konstantin Ananyev Reviewed-by: John McNamara --- MAINTAINERS | 1 + .../prog_guide/img/rss_queue_assign.svg | 1454 +++++++++++++++++ doc/guides/prog_guide/index.rst | 1 + doc/guides/prog_guide/toeplitz_hash_lib.rst | 38 + 4 files changed, 1494 insertions(+) create mode 100644 doc/guides/prog_guide/img/rss_queue_assign.svg create mode 100644 doc/guides/prog_guide/toeplitz_hash_lib.rst diff --git a/MAINTAINERS b/MAINTAINERS index 2550d950de..aa4dbbc764 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1432,6 +1432,7 @@ M: Sameh Gobriel M: Bruce Richardson F: lib/librte_hash/ F: doc/guides/prog_guide/hash_lib.rst +F: doc/guides/prog_guide/toeplitz_hash_lib.rst F: app/test/test_*hash* F: app/test/test_func_reentrancy.c diff --git a/doc/guides/prog_guide/img/rss_queue_assign.svg b/doc/guides/prog_guide/img/rss_queue_assign.svg new file mode 100644 index 0000000000..d0eef8ccbd --- /dev/null +++ b/doc/guides/prog_guide/img/rss_queue_assign.svg @@ -0,0 +1,1454 @@ + + + +image/svg+xml + + + + + + + + + + + + + + + + + + Page-6 + + + + + + + Array.1000 + + Sheet.1001 + + + + Sheet.1002 + + + + Sheet.1003 + + + + Sheet.1004 + + + + Sheet.1005 + + + + Sheet.1006 + Src/Dst ports + + + + Src/Dst ports + + + Sheet.1007 + Dst_ip + + + + Dst_ip + + + Sheet.1008 + Src_ip + + + + Src_ip + + + + + + + Data block.1009 + Received Packet Data + + Sheet.1010 + + + + Sheet.1011 + + + + Sheet.1012 + + + + + + Received Packet Data + + + + Simple Arrow.1013 + + + + + + + + Sheet.1014 + Parser extracts required fields + + + + Parser extracts required fields + + + Sheet.1015 + tuple + + + + tuple + + + Simple Arrow.1016 + + + + + + + + Rectangle.1017 + Toeplitz hash function + + + + + + + Toeplitz hash function + + + Simple Arrow.1018 + + + + + + + + Byte or variable.1019 + + + + + + + Byte or variable.1020 + LSB + + + + + + + LSB + + + Sheet.1021 + 32-bit hash value + + + + 32-bit hash value + + + Simple Arrow.1022 + + + + + + + + + + + Stack or heap.1023 + + Sheet.1024 + + + + Sheet.1025 + + + + Sheet.1026 + + + + Sheet.1027 + + + + Sheet.1028 + + + + Sheet.1029 + + + + Sheet.1030 + + + + Sheet.1031 + + + + Sheet.1032 + + + + Sheet.1033 + Q_idx_0 + + + + Q_idx_0 + + + Sheet.1034 + Q_idx_1 + + + + Q_idx_1 + + + Sheet.1035 + Q_idx_2 + + + + Q_idx_2 + + + Sheet.1036 + Q_idx_3 + + + + Q_idx_3 + + + Sheet.1037 + ... + + + + ... + + + Sheet.1038 + ... + + + + ... + + + Sheet.1039 + Q_idx_n + + + + Q_idx_n + + + + Sheet.1040 + RSS Redirection Table + + + + RSS Redirection Table + + + Sheet.1041 + Hash LSB’s are used as an index in table + + + + Hash LSB’s are used as an index in table + + + Rectangle.1043 + CPU 0 + + + + + + + CPU 0 + + + Rectangle.1044 + CPU 1 + + + + + + + CPU 1 + + + Rectangle.1045 + CPU 2 + + + + + + + CPU 2 + + + Rectangle.1046 + CPU 3 + + + + + + + CPU 3 + + + Dynamic connector.1047 + + + + + + + Rectangle.1048 + CPU 4 + + + + + + + CPU 4 + + + Rectangle.1049 + CPU 5 + + + + + + + CPU 5 + + + Simple Arrow.1050 + + + + + + + + \ No newline at end of file diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index 45c7dec88d..2dce507f46 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -32,6 +32,7 @@ Programmer's Guide link_bonding_poll_mode_drv_lib timer_lib hash_lib + toeplitz_hash_lib efd_lib member_lib lpm_lib diff --git a/doc/guides/prog_guide/toeplitz_hash_lib.rst b/doc/guides/prog_guide/toeplitz_hash_lib.rst new file mode 100644 index 0000000000..2480c551d0 --- /dev/null +++ b/doc/guides/prog_guide/toeplitz_hash_lib.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2021 Intel Corporation. + +Toeplitz Hash Library +===================== + +DPDK provides a Toeplitz Hash Library +to calculate the Toeplitz hash function and to use its properties. +The Toeplitz hash function is commonly used in a wide range of NICs +to calculate the RSS hash sum to spread the traffic among the queues. + +.. _figure_rss_queue_assign: + +.. figure:: img/rss_queue_assign.* + + RSS queue assignment example + + +Toeplitz hash function API +-------------------------- + +There are two functions that provide calculation of the Toeplitz hash sum: + +* ``rte_softrss()`` +* ``rte_softrss_be()`` + +Both of these functions take the parameters: + +* A pointer to the tuple, containing fields extracted from the packet. +* A length of this tuple counted in double words. +* A pointer to the RSS hash key corresponding to the one installed on the NIC. + +Both functions expect the tuple to be in "host" byte order +and a multiple of 4 bytes in length. +The ``rte_softrss()`` function expects the ``rss_key`` +to be exactly the same as the one installed on the NIC. +The ``rte_softrss_be`` function is a faster implementation, +but it expects ``rss_key`` to be converted to the host byte order. -- 2.20.1