1 files changed, 259 insertions, 0 deletions
diff --git a/static/netbsd/man9/pktqueue.9 b/static/netbsd/man9/pktqueue.9
new file mode 100644
index 00000000..d880a666
--- /dev/null
+++ b/static/netbsd/man9/pktqueue.9
@@ -0,0 +1,259 @@
+.\"	$NetBSD: pktqueue.9,v 1.3 2022/09/05 16:42:59 wiz Exp $
+.\"
+.\" Copyright (c) 2022 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Jason R. Thorpe.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd September 3, 2022
+.Dt PKTQUEUE 9
+.Os
+.Sh NAME
+.Nm pktqueue ,
+.Nm pktq_create ,
+.Nm pktq_destroy ,
+.Nm pktq_enqueue ,
+.Nm pktq_dequeue ,
+.Nm pktq_barrier ,
+.Nm pktq_ifdetach ,
+.Nm pktq_flush ,
+.Nm pktq_set_maxlen ,
+.Nm pktq_rps_hash ,
+.Nm pktq_sysctl_setup ,
+.Nm sysctl_pktq_rps_hash_handler
+.Nd Lockless network protocol input queues with integrated ISR scheduling
+.Sh SYNOPSIS
+.In net/pktqueue.h
+.Ft pktqueue_t *
+.Fn pktq_create "size_t maxlen" "void (*intrh)(void *)" "void *arg"
+.Ft void
+.Fn pktq_destroy "pktqueue_t *pq"
+.Ft bool
+.Fn pktq_enqueue "pktqueue_t *pq" "struct mbuf *m" "u_int hash"
+.Ft struct mbuf *
+.Fn pktq_dequeue "pktqueue_t *pq"
+.Ft void
+.Fn pktq_barrier "pktqueue_t *pq"
+.Ft void
+.Fn pktq_ifdetach "void"
+.Ft void
+.Fn pktq_flush "pktqueue_t *pq"
+.Ft int
+.Fn pktq_set_maxlen "pktqueue_t *pq" "size_t maxlen"
+.Ft uint32_t
+.Fn pktq_rps_hash "const pktq_rps_hash_func_t *funcp" "const struct mbuf *m"
+.Ft int
+.Fn pktq_sysctl_setup "pktqueue_t *pq" "struct sysctllog **clog" \
+    "const struct sysctlnode *parent_node" "int qid"
+.Ft int
+.Fn sysctl_pktq_rps_hash_handler "SYSCTLFN_ARGS"
+.Sh DESCRIPTION
+The
+.Nm
+functions provide a lockless network protocol input queue interface
+with integrated software interrupt scheduling and support for
+receiver-side packet steering
+.Pq RPS .
+The implementation is based around per-CPU producer-consumer queues;
+multiple CPUs may enqueue packets into a CPU's queue, but only the
+owning CPU will dequeue packets from any given queue.
+.Sh FUNCTIONS
+.Bl -tag -width compact
+.It Fn pktq_create "maxlen" "intrh" "arg"
+Create a packet queue that can store at most
+.Fa maxlen
+packets at one time.
+.Fa maxlen
+must not exceed
+.Dv PCQ_MAXLEN .
+The software interrupt handler
+.Fa intrh
+with argument
+.Fa arg
+will be established at
+.Dv SOFTINT_NET .
+.It Fn pktq_destroy "pq"
+Destroy the specified packet queue.
+The caller is responsible for ensuring that no packets remain in the queue
+prior to calling this function.
+.It Fn pktq_enqueue "pq" "m" "hash"
+Enqueue the packet
+.Fa m
+in the specified packet queue.
+The modulus of
+.Fa hash
+and the number of CPUs will be computed and used to select the per-CPU
+queue where the packet will be stored, and thus upon which CPU the packet
+will be processed.
+Once the CPU selection has been made and the packet placed in the queue,
+the software interrupt associated with packet queue will be scheduled.
+.It Fn pktq_dequeue "pq"
+Dequeue a packet from the current CPU's queue.
+If no packets remain,
+.Dv NULL
+is returned.
+This function must be called with kernel preemption disabled, which is always
+the case when running in a software interrupt handler.
+.It Fn pktq_barrier "pq"
+Wait for a grace period when all packets enqueued at the moment of
+calling this function will have been dequeued.
+.It Fn pktq_ifdetach
+This function is called when a network interface is detached from the
+system.
+It performs a
+.Fn pktq_barrier
+operation on all packet queues.
+.It Fn pktq_flush "pq"
+This function removes and frees all packets in the specified queue.
+The caller is responsible for ensuring that no calls to
+.Fn pktq_enqueue
+or
+.Fn pktq_dequeue
+run concurrently with
+.Fn pktq_flush .
+.It Fn pktq_set_maxlen "pq" "maxlen"
+Sets the maximum queue length to the value
+.Fa maxlen .
+If the new value of
+.Fa maxlen
+is smaller than the previous value, then this routine may block until
+all packets that were previously in the packet queue can be re-enqueued.
+.It Fn pktq_rps_hash "funcp" "m"
+Calculates the RPS hash for the packet
+.Fa m
+using the hash function referenced by
+.Fa funcp .
+The available hash functions are
+.Dq zero
+.Pq always returns 0 ,
+.Dq curcpu
+.Pq returns the index of the current CPU ,
+.Dq toeplitz
+.Pq Toeplitz hash of an IPv4 or IPv6 packet ,
+and
+.Dq toeplitz-othercpus
+.Po
+same as
+.Dq toeplitz
+but always hashes to a CPU other than the current CPU
+.Pc .
+A default hash routine is provided by the global variable
+.Dv pktq_rps_hash_default .
+The default routine is guaranteed to be safe to use for any network protocol.
+The behavior of
+.Dq toeplitz
+and
+.Dq toeplitz-othercpus
+is undefined if used with protocols other than IPv4 or IPv6.
+.It Fn pktq_sysctl_setup "pq" "clog" "parent_node" "qid"
+This function registers standard sysctl handlers for
+.Fa pq
+at the parent sysctl node
+.Fa parent_node .
+.Fa qid
+allows the caller to specify the node ID at which to attach to
+.Fa parent_node ;
+use
+.Dv CTL_CREATE
+to dynamically assign a node ID.
+The
+.Fa clog
+argument is passed directly to
+.Fn sysctl_createv .
+.It Fn sysctl_pktq_rps_hash_handler
+This function provides a way for the user to select the preferred
+RPS hash function to be used by a caller of
+.Fn pktq_rps_hash
+via
+.Xr sysctl 8 .
+When calling
+.Fn sysctl_createv
+to create the sysctl node, pass
+.Fn sysctl_pktq_rps_hash_handler
+as the
+.Fa func
+argument and the pointer to the RPS hash function reference variable
+as the
+.Fa newp
+argument
+.Po
+cast to
+.Sq void *
+.Pc .
+.El
+.Sh CODE REFERENCES
+The
+.Nm
+interface is implemented within the file
+.Pa net/pktqueue.c .
+.Pp
+An example of how to use
+.Fn pktq_rps_hash
+can be found in the
+.Fn ether_input
+function.
+An example of how to use
+.Fn sysctl_pktq_rps_hash_handler
+can be found in the
+.Fn ether_sysctl_setup
+function.
+Both reside within the file
+.Pa net/if_ethersubr.c .
+.Pp
+An example of how to use
+.Fn pktq_sysctl_setup
+can be found in the
+.Fn sysctl_net_inet_ip_setup
+function within the file
+.Pa netinet/ip_input.c .
+.Sh NOTES
+The
+.Fa maxlen
+argument provided to
+.Fn pktq_create
+specifies the maximum number of packets that can be stored in each
+per-CPU queue.
+This means that, in theory, the maximum number of packets that can be
+enqueued is
+.Sq maxlen * ncpu .
+However, as a practical matter, the number will be smaller because the
+distribution of packets across the per-CPU queues is not perfectly uniform.
+.Pp
+Calls to
+.Fn pktq_set_maxlen
+may result in re-ordering the delivery of packets currently in
+the queue.
+.\" .Sh EXAMPLES
+.Sh SEE ALSO
+.Xr sysctl 8 ,
+.Xr kpreempt 9 ,
+.Xr pcq 9 ,
+.Xr softintr 9 ,
+.Xr sysctl 9
+.Sh HISTORY
+The
+.Nm
+interface first appeared in
+.Nx 7.0 .