1.\" $NetBSD: pktqueue.9,v 1.3 2022/09/05 16:42:59 wiz Exp $ 2.\" 3.\" Copyright (c) 2022 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jason R. Thorpe. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd September 3, 2022 31.Dt PKTQUEUE 9 32.Os 33.Sh NAME 34.Nm pktqueue , 35.Nm pktq_create , 36.Nm pktq_destroy , 37.Nm pktq_enqueue , 38.Nm pktq_dequeue , 39.Nm pktq_barrier , 40.Nm pktq_ifdetach , 41.Nm pktq_flush , 42.Nm pktq_set_maxlen , 43.Nm pktq_rps_hash , 44.Nm pktq_sysctl_setup , 45.Nm sysctl_pktq_rps_hash_handler 46.Nd Lockless network protocol input queues with integrated ISR scheduling 47.Sh SYNOPSIS 48.In net/pktqueue.h 49.Ft pktqueue_t * 50.Fn pktq_create "size_t maxlen" "void (*intrh)(void *)" "void *arg" 51.Ft void 52.Fn pktq_destroy "pktqueue_t *pq" 53.Ft bool 54.Fn pktq_enqueue "pktqueue_t *pq" "struct mbuf *m" "u_int hash" 55.Ft struct mbuf * 56.Fn pktq_dequeue "pktqueue_t *pq" 57.Ft void 58.Fn pktq_barrier "pktqueue_t *pq" 59.Ft void 60.Fn pktq_ifdetach "void" 61.Ft void 62.Fn pktq_flush "pktqueue_t *pq" 63.Ft int 64.Fn pktq_set_maxlen "pktqueue_t *pq" "size_t maxlen" 65.Ft uint32_t 66.Fn pktq_rps_hash "const pktq_rps_hash_func_t *funcp" "const struct mbuf *m" 67.Ft int 68.Fn pktq_sysctl_setup "pktqueue_t *pq" "struct sysctllog **clog" \ 69 "const struct sysctlnode *parent_node" "int qid" 70.Ft int 71.Fn sysctl_pktq_rps_hash_handler "SYSCTLFN_ARGS" 72.Sh DESCRIPTION 73The 74.Nm 75functions provide a lockless network protocol input queue interface 76with integrated software interrupt scheduling and support for 77receiver-side packet steering 78.Pq RPS . 79The implementation is based around per-CPU producer-consumer queues; 80multiple CPUs may enqueue packets into a CPU's queue, but only the 81owning CPU will dequeue packets from any given queue. 82.Sh FUNCTIONS 83.Bl -tag -width compact 84.It Fn pktq_create "maxlen" "intrh" "arg" 85Create a packet queue that can store at most 86.Fa maxlen 87packets at one time. 88.Fa maxlen 89must not exceed 90.Dv PCQ_MAXLEN . 91The software interrupt handler 92.Fa intrh 93with argument 94.Fa arg 95will be established at 96.Dv SOFTINT_NET . 97.It Fn pktq_destroy "pq" 98Destroy the specified packet queue. 99The caller is responsible for ensuring that no packets remain in the queue 100prior to calling this function. 101.It Fn pktq_enqueue "pq" "m" "hash" 102Enqueue the packet 103.Fa m 104in the specified packet queue. 105The modulus of 106.Fa hash 107and the number of CPUs will be computed and used to select the per-CPU 108queue where the packet will be stored, and thus upon which CPU the packet 109will be processed. 110Once the CPU selection has been made and the packet placed in the queue, 111the software interrupt associated with packet queue will be scheduled. 112.It Fn pktq_dequeue "pq" 113Dequeue a packet from the current CPU's queue. 114If no packets remain, 115.Dv NULL 116is returned. 117This function must be called with kernel preemption disabled, which is always 118the case when running in a software interrupt handler. 119.It Fn pktq_barrier "pq" 120Wait for a grace period when all packets enqueued at the moment of 121calling this function will have been dequeued. 122.It Fn pktq_ifdetach 123This function is called when a network interface is detached from the 124system. 125It performs a 126.Fn pktq_barrier 127operation on all packet queues. 128.It Fn pktq_flush "pq" 129This function removes and frees all packets in the specified queue. 130The caller is responsible for ensuring that no calls to 131.Fn pktq_enqueue 132or 133.Fn pktq_dequeue 134run concurrently with 135.Fn pktq_flush . 136.It Fn pktq_set_maxlen "pq" "maxlen" 137Sets the maximum queue length to the value 138.Fa maxlen . 139If the new value of 140.Fa maxlen 141is smaller than the previous value, then this routine may block until 142all packets that were previously in the packet queue can be re-enqueued. 143.It Fn pktq_rps_hash "funcp" "m" 144Calculates the RPS hash for the packet 145.Fa m 146using the hash function referenced by 147.Fa funcp . 148The available hash functions are 149.Dq zero 150.Pq always returns 0 , 151.Dq curcpu 152.Pq returns the index of the current CPU , 153.Dq toeplitz 154.Pq Toeplitz hash of an IPv4 or IPv6 packet , 155and 156.Dq toeplitz-othercpus 157.Po 158same as 159.Dq toeplitz 160but always hashes to a CPU other than the current CPU 161.Pc . 162A default hash routine is provided by the global variable 163.Dv pktq_rps_hash_default . 164The default routine is guaranteed to be safe to use for any network protocol. 165The behavior of 166.Dq toeplitz 167and 168.Dq toeplitz-othercpus 169is undefined if used with protocols other than IPv4 or IPv6. 170.It Fn pktq_sysctl_setup "pq" "clog" "parent_node" "qid" 171This function registers standard sysctl handlers for 172.Fa pq 173at the parent sysctl node 174.Fa parent_node . 175.Fa qid 176allows the caller to specify the node ID at which to attach to 177.Fa parent_node ; 178use 179.Dv CTL_CREATE 180to dynamically assign a node ID. 181The 182.Fa clog 183argument is passed directly to 184.Fn sysctl_createv . 185.It Fn sysctl_pktq_rps_hash_handler 186This function provides a way for the user to select the preferred 187RPS hash function to be used by a caller of 188.Fn pktq_rps_hash 189via 190.Xr sysctl 8 . 191When calling 192.Fn sysctl_createv 193to create the sysctl node, pass 194.Fn sysctl_pktq_rps_hash_handler 195as the 196.Fa func 197argument and the pointer to the RPS hash function reference variable 198as the 199.Fa newp 200argument 201.Po 202cast to 203.Sq void * 204.Pc . 205.El 206.Sh CODE REFERENCES 207The 208.Nm 209interface is implemented within the file 210.Pa net/pktqueue.c . 211.Pp 212An example of how to use 213.Fn pktq_rps_hash 214can be found in the 215.Fn ether_input 216function. 217An example of how to use 218.Fn sysctl_pktq_rps_hash_handler 219can be found in the 220.Fn ether_sysctl_setup 221function. 222Both reside within the file 223.Pa net/if_ethersubr.c . 224.Pp 225An example of how to use 226.Fn pktq_sysctl_setup 227can be found in the 228.Fn sysctl_net_inet_ip_setup 229function within the file 230.Pa netinet/ip_input.c . 231.Sh NOTES 232The 233.Fa maxlen 234argument provided to 235.Fn pktq_create 236specifies the maximum number of packets that can be stored in each 237per-CPU queue. 238This means that, in theory, the maximum number of packets that can be 239enqueued is 240.Sq maxlen * ncpu . 241However, as a practical matter, the number will be smaller because the 242distribution of packets across the per-CPU queues is not perfectly uniform. 243.Pp 244Calls to 245.Fn pktq_set_maxlen 246may result in re-ordering the delivery of packets currently in 247the queue. 248.\" .Sh EXAMPLES 249.Sh SEE ALSO 250.Xr sysctl 8 , 251.Xr kpreempt 9 , 252.Xr pcq 9 , 253.Xr softintr 9 , 254.Xr sysctl 9 255.Sh HISTORY 256The 257.Nm 258interface first appeared in 259.Nx 7.0 . 260