how do you use the stoeplitz stuff?

2 files changed, 129 insertions, 3 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 7e61f865205..0906dd1130e 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.300 2020/06/05 02:24:12 dlg Exp $
+#	$OpenBSD: Makefile,v 1.301 2020/06/16 05:17:09 dlg Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -35,8 +35,8 @@ MAN=	aml_evalnode.9 atomic_add_int.9 atomic_cas_uint.9 \
 	rtlabel_id2name.9 rtrequest.9 rwlock.9 SRPL_EMPTY_LOCKED.9 SipHash24.9 \
 	sensor_attach.9 sigio_init.9 \
 	SMR_LIST_INIT.9 SMR_PTR_GET.9 smr_call.9 \
-	spl.9 srp_enter.9 srpl_rc_init.9 startuphook_establish.9 \
-	socreate.9 sosplice.9 strcmp.9 style.9 syscall.9 sysctl_int.9 \
+	spl.9 srp_enter.9 srpl_rc_init.9 startuphook_establish.9 socreate.9 \
+	sosplice.9 stoeplitz_to_key.9 strcmp.9 style.9 syscall.9 sysctl_int.9 \
 	task_add.9 tc_init.9 tfind.9 thread_fork.9 \
 	time_second.9 timeout.9 tsleep.9 tvtohz.9 \
 	uiomove.9 \
diff --git a/share/man/man9/stoeplitz_to_key.9 b/share/man/man9/stoeplitz_to_key.9
new file mode 100644
index 00000000000..5b9c0c2e885
--- /dev/null
+++ b/share/man/man9/stoeplitz_to_key.9
@@ -0,0 +1,126 @@
+.\" $OpenBSD: stoeplitz_to_key.9,v 1.1 2020/06/16 05:17:09 dlg Exp $
+.\"
+.\" Copyright (c) 2020 David Gwynne <dlg@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: June 16 2020 $
+.Dt STOEPLITZ_TO_KEY 9
+.Os
+.Sh NAME
+.Nm stoeplitz_to_key ,
+.Nm stoeplitz_hash_ip4 ,
+.Nm stoeplitz_hash_ip4port ,
+.Nm stoeplitz_hash_ip6 ,
+.Nm stoeplitz_hash_ip4port
+.Nd Symmetric Toeplitz Hash API
+.Sh SYNOPSIS
+.In net/toeplitz.h
+.Ft void
+.Fn stoeplitz_to_key "uint8_t *key" "size_t keylen"
+.Ft uint16_t
+.Fo stoeplitz_hash_ip4
+.Fa "uint32_t srcaddr"
+.Fa "uint32_t dstaddr"
+.Fc
+.Ft uint16_t
+.Fo stoeplitz_hash_ip4port
+.Fa "uint32_t srcaddr"
+.Fa "uint32_t dstaddr"
+.Fa "uint16_t srcport"
+.Fa "uint16_t dstport"
+.Fc
+.Ft uint16_t
+.Fo stoeplitz_hash_ip6
+.Fa "const struct in6_addr *srcaddr"
+.Fa "const struct in6_addr *dstaddr"
+.Fc
+.Ft uint16_t
+.Fo stoeplitz_hash_ip6port
+.Fa "const struct in6_addr *srcaddr"
+.Fa "const struct in6_addr *dstaddr"
+.Fa "uint16_t srcport"
+.Fa "uint16_t dstport"
+.Fc
+.Sh DESCRIPTION
+The Toeplitz hash algorithm is commonly used by network interface
+controllers to to generate a short hash based on the value of fields
+in network packet headers.
+.\" mention RSS?
+The resulting hash value can be used as a flow identifier, which
+in turn can be used to consistently select a context for processing
+packets using those fields.
+Traditionally, the Toeplitz hash produces different results depending
+on the order of inputs, ie, adding port 80 then 1234 as inputs would
+produce a different result to hashing port 1234 then 80.
+.Pp
+The symmetric Toeplitz API uses a key selected to generate the same
+hash result regardless of the order the inputs were added.
+The API also supports producing Toeplitz hash keys for use by
+network interface controllers that provide the same symmetric
+property.
+.Pp
+The
+.Fn stoeplitz_to_key
+function generates a Toeplitz key for use by a network interface
+controller based on the systems symmetric Toeplitz key.
+A Toeplitz key of
+.Fa keylen
+bytes will be written to the buffer referenced by the
+.Fa key
+argument.
+.Fa keylen
+must be a multiple of 2 bytes.
+.Pp
+.Fn stoeplitz_hash_ip4
+calculates a hash value for a pair of IPv4 addresses.
+.Pp
+.Fn stoeplitz_hash_ip4port
+calculates a hash value for a pair of IPv4 addresses and ports as
+used by protocols like TCP or UDP.
+.Pp
+.Fn stoeplitz_hash_ip6
+calculates a hash value for a pair of IPv6 addresses.
+.Pp
+.Fn stoeplitz_hash_ip6port
+calculates a hash value for a pair of IPv6 addresses and ports as
+used by protocols like TCP or UDP.
+.Sh CONTEXT
+.Fn stoeplitz_to_key ,
+.Fn stoeplitz_hash_ip4 ,
+.Fn stoeplitz_hash_ip4port ,
+.Fn stoeplitz_hash_ip6 ,
+and
+.Fn stoeplitz_hash_ip6port
+can be called during autoconf, from process context, or from an
+interrupt context.
+.Sh RETURN VALUES
+.Fn stoeplitz_hash_ip4 ,
+.Fn stoeplitz_hash_ip4port ,
+.Fn stoeplitz_hash_ip6 ,
+and
+.Fn stoeplitz_hash_ip6port
+return a 16 bit hash value in host byte order.
+.\" .Sh SEE ALSO
+.\" .Xr mbuf 9 ,
+.\" .Xr spl 9
+.Sh HISTORY
+The symmetric Toeplitz API is based on the ideas and implementation in
+.Dx
+by
+.An Yanmin Qiao Aq Mt sephe@dragonflybsd.org
+and
+.An Simon Schubert Aq Mt corecode@fs.ei.tum.de .
+.Pp
+The API appeared in
+.Ox 6.8 .