Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src/share/man/man9 Document the pktqueue interface.
details: https://anonhg.NetBSD.org/src/rev/04aa49e5e64f
branches: trunk
changeset: 369864:04aa49e5e64f
user: thorpej <thorpej%NetBSD.org@localhost>
date: Sun Sep 04 21:37:50 2022 +0000
description:
Document the pktqueue interface.
diffstat:
distrib/sets/lists/comp/mi | 38 ++++++-
share/man/man9/Makefile | 15 ++-
share/man/man9/pktqueue.9 | 259 +++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 309 insertions(+), 3 deletions(-)
diffs (truncated from 386 to 300 lines):
diff -r 6a730e95b2dd -r 04aa49e5e64f distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi Sun Sep 04 20:06:26 2022 +0000
+++ b/distrib/sets/lists/comp/mi Sun Sep 04 21:37:50 2022 +0000
@@ -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
diff -r 6a730e95b2dd -r 04aa49e5e64f share/man/man9/Makefile
--- a/share/man/man9/Makefile Sun Sep 04 20:06:26 2022 +0000
+++ b/share/man/man9/Makefile Sun Sep 04 21:37:50 2022 +0000
@@ -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 @@
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 @@
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 \
diff -r 6a730e95b2dd -r 04aa49e5e64f share/man/man9/pktqueue.9
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/pktqueue.9 Sun Sep 04 21:37:50 2022 +0000
@@ -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
Home |
Main Index |
Thread Index |
Old Index