1.\" $OpenBSD: stoeplitz_to_key.9,v 1.4 2020/06/19 08:50:59 dlg 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: June 19 2020 $ 18.Dt STOEPLITZ_TO_KEY 9 19.Os 20.Sh NAME 21.Nm stoeplitz_to_key , 22.Nm stoeplitz_hash_ip4 , 23.Nm stoeplitz_hash_ip4port , 24.Nm stoeplitz_hash_ip6 , 25.Nm stoeplitz_hash_ip6port 26.Nd symmetric Toeplitz hash API 27.Sh SYNOPSIS 28.In net/toeplitz.h 29.Ft void 30.Fn stoeplitz_to_key "void *key" "size_t keylen" 31.Ft uint16_t 32.Fo stoeplitz_hash_ip4 33.Fa "uint32_t srcaddr" 34.Fa "uint32_t dstaddr" 35.Fc 36.Ft uint16_t 37.Fo stoeplitz_hash_ip4port 38.Fa "uint32_t srcaddr" 39.Fa "uint32_t dstaddr" 40.Fa "uint16_t srcport" 41.Fa "uint16_t dstport" 42.Fc 43.Ft uint16_t 44.Fo stoeplitz_hash_ip6 45.Fa "const struct in6_addr *srcaddr" 46.Fa "const struct in6_addr *dstaddr" 47.Fc 48.Ft uint16_t 49.Fo stoeplitz_hash_ip6port 50.Fa "const struct in6_addr *srcaddr" 51.Fa "const struct in6_addr *dstaddr" 52.Fa "uint16_t srcport" 53.Fa "uint16_t dstport" 54.Fc 55.Sh DESCRIPTION 56The Toeplitz hash algorithm is commonly used by network interface 57controllers to generate a short hash based on the value of fields 58in network packet headers. 59.\" mention RSS? 60The resulting hash value can be used as a flow identifier, which 61in turn can be used to consistently select a context for processing 62packets using those fields. 63Traditionally, the Toeplitz hash produces different results depending 64on the order of inputs, i.e. adding port 80 then 1234 as inputs would 65produce a different result to hashing port 1234 then 80. 66.Pp 67The symmetric Toeplitz API uses a key selected to generate the same 68hash result regardless of the order the inputs were added. 69The API also supports producing Toeplitz hash keys for use by 70network interface controllers that provide the same symmetric 71property. 72.Pp 73The 74.Fn stoeplitz_to_key 75function generates a Toeplitz key for use by a network interface 76controller based on the system's symmetric Toeplitz key. 77A Toeplitz key of 78.Fa keylen 79bytes will be written to the buffer referenced by the 80.Fa key 81argument. 82.Fa keylen 83must be a multiple of 2 bytes. 84.Pp 85.Fn stoeplitz_hash_ip4 86calculates a hash value for a pair of IPv4 addresses. 87.Pp 88.Fn stoeplitz_hash_ip4port 89calculates a hash value for a pair of IPv4 addresses and ports as 90used by protocols like TCP or UDP. 91.Pp 92.Fn stoeplitz_hash_ip6 93calculates a hash value for a pair of IPv6 addresses. 94.Pp 95.Fn stoeplitz_hash_ip6port 96calculates a hash value for a pair of IPv6 addresses and ports as 97used by protocols like TCP or UDP. 98.Sh CONTEXT 99.Fn stoeplitz_to_key , 100.Fn stoeplitz_hash_ip4 , 101.Fn stoeplitz_hash_ip4port , 102.Fn stoeplitz_hash_ip6 , 103and 104.Fn stoeplitz_hash_ip6port 105can be called during autoconf, from process context, or from an 106interrupt context. 107.Sh RETURN VALUES 108.Fn stoeplitz_hash_ip4 , 109.Fn stoeplitz_hash_ip4port , 110.Fn stoeplitz_hash_ip6 , 111and 112.Fn stoeplitz_hash_ip6port 113return a 16-bit hash value in host byte order. 114.\" .Sh SEE ALSO 115.\" .Xr mbuf 9 , 116.\" .Xr spl 9 117.Sh HISTORY 118The symmetric Toeplitz API is based on the ideas and implementation in 119.Dx 120by 121.An Yanmin Qiao Aq Mt sephe@dragonflybsd.org 122and 123.An Simon Schubert Aq Mt corecode@fs.ei.tum.de . 124.Pp 125The API appeared in 126.Ox 6.8 . 127