1.\" $OpenBSD: stoeplitz_to_key.9,v 1.8 2022/01/16 00:15:48 jsg Exp $ 2.\" 3.\" Copyright (c) 2020 David Gwynne <dlg@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: January 16 2022 $ 18.Dt STOEPLITZ_TO_KEY 9 19.Os 20.Sh NAME 21.Nm stoeplitz_to_key , 22.Nm stoeplitz_eaddr , 23.Nm stoeplitz_ip4 , 24.Nm stoeplitz_ip4port , 25.Nm stoeplitz_ip6 , 26.Nm stoeplitz_ip6port 27.Nd symmetric Toeplitz hash API 28.Sh SYNOPSIS 29.In net/toeplitz.h 30.Ft void 31.Fn stoeplitz_to_key "void *key" "size_t keylen" 32.Ft uint16_t 33.Fo stoeplitz_eaddr 34.Fa "const uint8_t *eaddr" 35.Fc 36.Ft uint16_t 37.Fo stoeplitz_ip4 38.Fa "uint32_t srcaddr" 39.Fa "uint32_t dstaddr" 40.Fc 41.Ft uint16_t 42.Fo stoeplitz_ip4port 43.Fa "uint32_t srcaddr" 44.Fa "uint32_t dstaddr" 45.Fa "uint16_t srcport" 46.Fa "uint16_t dstport" 47.Fc 48.Ft uint16_t 49.Fo stoeplitz_ip6 50.Fa "const struct in6_addr *srcaddr" 51.Fa "const struct in6_addr *dstaddr" 52.Fc 53.Ft uint16_t 54.Fo stoeplitz_ip6port 55.Fa "const struct in6_addr *srcaddr" 56.Fa "const struct in6_addr *dstaddr" 57.Fa "uint16_t srcport" 58.Fa "uint16_t dstport" 59.Fc 60.Sh DESCRIPTION 61The Toeplitz hash algorithm is commonly used by network interface 62controllers to generate a short hash based on the value of fields 63in network packet headers. 64.\" mention RSS? 65The resulting hash value can be used as a flow identifier, which 66in turn can be used to consistently select a context for processing 67packets using those fields. 68Traditionally, the Toeplitz hash produces different results depending 69on the order of inputs, i.e. adding port 80 then 1234 as inputs would 70produce a different result to hashing port 1234 then 80. 71.Pp 72The symmetric Toeplitz API uses a key selected to generate the same 73hash result regardless of the order the inputs were added. 74The API also supports producing Toeplitz hash keys for use by 75network interface controllers that provide the same symmetric 76property. 77.Pp 78The 79.Fn stoeplitz_to_key 80function generates a Toeplitz key for use by a network interface 81controller based on the system's symmetric Toeplitz key. 82A Toeplitz key of 83.Fa keylen 84bytes will be written to the buffer referenced by the 85.Fa key 86argument. 87.Fa keylen 88must be a multiple of 2 bytes. 89.Pp 90.Fn stoeplitz_eaddr 91calculates a hash value for a single Ethernet address. 92.Pp 93.Fn stoeplitz_ip4 94calculates a hash value for a pair of IPv4 addresses. 95.Pp 96.Fn stoeplitz_ip4port 97calculates a hash value for a pair of IPv4 addresses and ports as 98used by protocols like TCP or UDP. 99.Pp 100.Fn stoeplitz_ip6 101calculates a hash value for a pair of IPv6 addresses. 102.Pp 103.Fn stoeplitz_ip6port 104calculates a hash value for a pair of IPv6 addresses and ports as 105used by protocols like TCP or UDP. 106.Sh CONTEXT 107.Fn stoeplitz_to_key , 108.Fn stoeplitz_eaddr , 109.Fn stoeplitz_ip4 , 110.Fn stoeplitz_ip4port , 111.Fn stoeplitz_ip6 , 112and 113.Fn stoeplitz_ip6port 114can be called during autoconf, from process context, or from an 115interrupt context. 116.Sh RETURN VALUES 117.Fn stoeplitz_eaddr , 118.Fn stoeplitz_ip4 , 119.Fn stoeplitz_ip4port , 120.Fn stoeplitz_ip6 , 121and 122.Fn stoeplitz_ip6port 123return a 16-bit hash value in host byte order. 124.\" .Sh SEE ALSO 125.\" .Xr mbuf 9 , 126.\" .Xr spl 9 127.Sh HISTORY 128The symmetric Toeplitz API is based on the ideas and implementation in 129.Dx 130by 131.An Yanmin Qiao Aq Mt sephe@dragonflybsd.org 132and 133.An Simon Schubert Aq Mt corecode@fs.ei.tum.de . 134.Pp 135The API appeared in 136.Ox 6.8 . 137