Module Name: src
Committed By: thorpej
Date: Sun Sep 4 21:37:50 UTC 2022
Modified Files:
src/distrib/sets/lists/comp: mi
src/share/man/man9: Makefile
Added Files:
src/share/man/man9: pktqueue.9
Log Message:
Document the pktqueue interface.
To generate a diff of this commit:
cvs rdiff -u -r1.2420 -r1.2421 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.464 -r1.465 src/share/man/man9/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man9/pktqueue.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.2420 src/distrib/sets/lists/comp/mi:1.2421
--- src/distrib/sets/lists/comp/mi:1.2420 Sun Sep 4 20:06:26 2022
+++ src/distrib/sets/lists/comp/mi Sun Sep 4 21:37:50 2022
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.2420 2022/09/04 20:06:26 thorpej Exp $
+# $NetBSD: mi,v 1.2421 2022/09/04 21:37:50 thorpej Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -12246,6 +12246,17 @@
./usr/share/man/cat9/pgrp_find.0 comp-sys-catman .cat
./usr/share/man/cat9/pgsignal.0 comp-sys-catman .cat
./usr/share/man/cat9/physio.0 comp-sys-catman .cat
+./usr/share/man/cat9/pktq_barrier.0 comp-sys-catman .cat
+./usr/share/man/cat9/pktq_create.0 comp-sys-catman .cat
+./usr/share/man/cat9/pktq_dequeue.0 comp-sys-catman .cat
+./usr/share/man/cat9/pktq_destroy.0 comp-sys-catman .cat
+./usr/share/man/cat9/pktq_enqueue.0 comp-sys-catman .cat
+./usr/share/man/cat9/pktq_flush.0 comp-sys-catman .cat
+./usr/share/man/cat9/pktq_ifdetach.0 comp-sys-catman .cat
+./usr/share/man/cat9/pktq_rps_hash.0 comp-sys-catman .cat
+./usr/share/man/cat9/pktq_set_maxlen.0 comp-sys-catman .cat
+./usr/share/man/cat9/pktq_sysctl_setup.0 comp-sys-catman .cat
+./usr/share/man/cat9/pktqueue.0 comp-sys-catman .cat
./usr/share/man/cat9/pmap.0 comp-sys-catman .cat
./usr/share/man/cat9/pmap_activate.0 comp-sys-catman .cat
./usr/share/man/cat9/pmap_clear_modify.0 comp-sys-catman .cat
@@ -12577,6 +12588,7 @@
./usr/share/man/cat9/sysctl_needfunc.0 comp-sys-catman .cat
./usr/share/man/cat9/sysctl_notavail.0 comp-sys-catman .cat
./usr/share/man/cat9/sysctl_null.0 comp-sys-catman .cat
+./usr/share/man/cat9/sysctl_pktq_rps_hash_handler.0 comp-sys-catman .cat
./usr/share/man/cat9/sysctl_query.0 comp-sys-catman .cat
./usr/share/man/cat9/sysctl_teardown.0 comp-sys-catman .cat
./usr/share/man/cat9/sysctl_unlock.0 comp-sys-catman .cat
@@ -20465,6 +20477,17 @@
./usr/share/man/html9/pgrp_find.html comp-sys-htmlman html
./usr/share/man/html9/pgsignal.html comp-sys-htmlman html
./usr/share/man/html9/physio.html comp-sys-htmlman html
+./usr/share/man/html9/pktq_barrier.html comp-sys-htmlman html
+./usr/share/man/html9/pktq_create.html comp-sys-htmlman html
+./usr/share/man/html9/pktq_dequeue.html comp-sys-htmlman html
+./usr/share/man/html9/pktq_destroy.html comp-sys-htmlman html
+./usr/share/man/html9/pktq_enqueue.html comp-sys-htmlman html
+./usr/share/man/html9/pktq_flush.html comp-sys-htmlman html
+./usr/share/man/html9/pktq_ifdetach.html comp-sys-htmlman html
+./usr/share/man/html9/pktq_rps_hash.html comp-sys-htmlman html
+./usr/share/man/html9/pktq_set_maxlen.html comp-sys-htmlman html
+./usr/share/man/html9/pktq_sysctl_setup.html comp-sys-htmlman html
+./usr/share/man/html9/pktqueue.html comp-sys-htmlman html
./usr/share/man/html9/pmap.html comp-sys-htmlman html
./usr/share/man/html9/pmap_activate.html comp-sys-htmlman html
./usr/share/man/html9/pmap_clear_modify.html comp-sys-htmlman html
@@ -20777,6 +20800,7 @@
./usr/share/man/html9/sysctl_needfunc.html comp-sys-htmlman html
./usr/share/man/html9/sysctl_notavail.html comp-sys-htmlman html
./usr/share/man/html9/sysctl_null.html comp-sys-htmlman html
+./usr/share/man/html9/sysctl_pktq_rps_hash_handler.html comp-sys-htmlman html
./usr/share/man/html9/sysctl_query.html comp-sys-htmlman html
./usr/share/man/html9/sysctl_teardown.html comp-sys-htmlman html
./usr/share/man/html9/sysctl_unlock.html comp-sys-htmlman html
@@ -28845,6 +28869,17 @@
./usr/share/man/man9/pgrp_find.9 comp-sys-man .man
./usr/share/man/man9/pgsignal.9 comp-sys-man .man
./usr/share/man/man9/physio.9 comp-sys-man .man
+./usr/share/man/man9/pktq_barrier.9 comp-sys-man .man
+./usr/share/man/man9/pktq_create.9 comp-sys-man .man
+./usr/share/man/man9/pktq_dequeue.9 comp-sys-man .man
+./usr/share/man/man9/pktq_destroy.9 comp-sys-man .man
+./usr/share/man/man9/pktq_enqueue.9 comp-sys-man .man
+./usr/share/man/man9/pktq_flush.9 comp-sys-man .man
+./usr/share/man/man9/pktq_ifdetach.9 comp-sys-man .man
+./usr/share/man/man9/pktq_rps_hash.9 comp-sys-man .man
+./usr/share/man/man9/pktq_set_maxlen.9 comp-sys-man .man
+./usr/share/man/man9/pktq_sysctl_setup.9 comp-sys-man .man
+./usr/share/man/man9/pktqueue.9 comp-sys-man .man
./usr/share/man/man9/pmap.9 comp-sys-man .man
./usr/share/man/man9/pmap_activate.9 comp-sys-man .man
./usr/share/man/man9/pmap_clear_modify.9 comp-sys-man .man
@@ -29176,6 +29211,7 @@
./usr/share/man/man9/sysctl_needfunc.9 comp-sys-man .man
./usr/share/man/man9/sysctl_notavail.9 comp-sys-man .man
./usr/share/man/man9/sysctl_null.9 comp-sys-man .man
+./usr/share/man/man9/sysctl_pktq_rps_hash_handler.9 comp-sys-man .man
./usr/share/man/man9/sysctl_query.9 comp-sys-man .man
./usr/share/man/man9/sysctl_teardown.9 comp-sys-man .man
./usr/share/man/man9/sysctl_unlock.9 comp-sys-man .man
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.464 src/share/man/man9/Makefile:1.465
--- src/share/man/man9/Makefile:1.464 Tue Feb 15 22:46:29 2022
+++ src/share/man/man9/Makefile Sun Sep 4 21:37:50 2022
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.464 2022/02/15 22:46:29 riastradh Exp $
+# $NetBSD: Makefile,v 1.465 2022/09/04 21:37:50 thorpej Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -43,7 +43,7 @@ MAN= accept_filter.9 accf_data.9 accf_ht
namei.9 nullop.9 opencrypto.9 optstr.9 \
panic.9 pathbuf.9 pci.9 pci_configure_bus.9 pci_intr.9 \
pci_msi.9 pckbport.9 pcmcia.9 pcq.9 pcu.9 \
- percpu.9 pfil.9 physio.9 pmap.9 pmatch.9 pmf.9 pool.9 \
+ percpu.9 pfil.9 physio.9 pktqueue.9 pmap.9 pmatch.9 pmf.9 pool.9 \
pool_cache.9 powerhook_establish.9 ppsratecheck.9 preempt.9 \
proc_find.9 pserialize.9 pslist.9 psref.9 putter.9 \
radio.9 ras.9 rasops.9 ratecheck.9 resettodr.9 rnd.9 \
@@ -703,6 +703,17 @@ MLINKS+=pfil.9 pfil_hook_get.9 \
pfil.9 pfil_run_hooks.9 \
pfil.9 pfil_run_addrhooks.9 \
pfil.9 pfil_run_ifhooks.9
+MLINKS+=pktqueue.9 pktq_create.9 \
+ pktqueue.9 pktq_destroy.9 \
+ pktqueue.9 pktq_enqueue.9 \
+ pktqueue.9 pktq_dequeue.9 \
+ pktqueue.9 pktq_barrier.9 \
+ pktqueue.9 pktq_ifdetach.9 \
+ pktqueue.9 pktq_flush.9 \
+ pktqueue.9 pktq_set_maxlen.9 \
+ pktqueue.9 pktq_rps_hash.9 \
+ pktqueue.9 pktq_sysctl_setup.9 \
+ pktqueue.9 sysctl_pktq_rps_hash_handler.9
MLINKS+=pmap.9 pmap_init.9 \
pmap.9 pmap_virtual_space.9 \
pmap.9 pmap_steal_memory.9 \
Added files:
Index: src/share/man/man9/pktqueue.9
diff -u /dev/null src/share/man/man9/pktqueue.9:1.1
--- /dev/null Sun Sep 4 21:37:50 2022
+++ src/share/man/man9/pktqueue.9 Sun Sep 4 21:37:50 2022
@@ -0,0 +1,259 @@
+.\" $NetBSD: pktqueue.9,v 1.1 2022/09/04 21:37:50 thorpej 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 reponsible 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 reponsible 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 greater 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 kpreempt 9 ,
+.Xr pcq 9 ,
+.Xr softintr 9 ,
+.Xr sysctl 8 ,
+.Xr sysctl 9
+.Sh HISTORY
+The
+.Nm
+interface first appeared in
+.Nx 7.0 .
