1.\" 2.\" Copyright (c) 2009 Robert N. M. Watson 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice(s), this list of conditions and the following disclaimer as 10.\" the first lines of this file unmodified other than the possible 11.\" addition of one or more copyright notices. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice(s), this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 17.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 18.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 19.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY 20.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 21.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 22.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 23.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 26.\" DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd April 12, 2023 31.Dt NETISR 9 32.Os 33.Sh NAME 34.Nm netisr 35.Nd Kernel network dispatch service 36.Sh SYNOPSIS 37.In net/netisr.h 38.Ft void 39.Fn netisr_register "const struct netisr_handler *nhp" 40.Ft void 41.Fn netisr_unregister "const struct netisr_handler *nhp" 42.Ft int 43.Fn netisr_dispatch "u_int proto" "struct mbuf *m" 44.Ft int 45.Fn netisr_dispatch_src "u_int proto" "uintptr_t source" "struct mbuf *m" 46.Ft int 47.Fn netisr_queue "u_int proto" "struct mbuf *m" 48.Ft int 49.Fn netisr_queue_src "u_int proto" "uintptr_t source" "struct mbuf *m" 50.Ft void 51.Fn netisr_clearqdrops "const struct netisr_handler *nhp" 52.Ft void 53.Fn netisr_getqdrops "const struct netisr_handler *nhp" "uint64_t *qdropsp" 54.Ft void 55.Fn netisr_getqlimit "const struct netisr_handler *nhp" "u_int *qlimitp" 56.Ft int 57.Fn netisr_setqlimit "const struct netisr_handler *nhp" "u_int qlimit" 58.Ft u_int 59.Fn netisr_default_flow2cpu "u_int flowid" 60.Ft u_int 61.Fn netisr_get_cpucount "void" 62.Ft u_int 63.Fn netisr_get_cpuid "u_int cpunumber" 64.Pp 65With optional virtual network stack support enabled via the following kernel 66compile option: 67.Bd -ragged -offset indent 68.Cd "options VIMAGE" 69.Ed 70.Ft void 71.Fn netisr_register_vnet "const struct netisr_handler *nhp" 72.Ft void 73.Fn netisr_unregister_vnet "const struct netisr_handler *nhp" 74.Sh DESCRIPTION 75The 76.Nm 77kernel interface suite allows device drivers (and other packet sources) to 78direct packets to protocols for directly dispatched or deferred processing. 79Protocol registration and work stream statistics may be monitored using 80.Xr netstat 1 . 81.Ss Protocol registration 82Protocols register and unregister handlers using 83.Fn netisr_register 84and 85.Fn netisr_unregister , 86and may also manage queue limits and statistics using the 87.Fn netisr_clearqdrops , 88.Fn netisr_getqdrops , 89.Fn netisr_getqlimit , 90and 91.Fn netisr_setqlimit . 92.Pp 93In case of VIMAGE kernels each virtual network stack (vnet), that is not the 94default base system network stack, calls 95.Fn netisr_register_vnet 96and 97.Fn netisr_unregister_vnet 98to enable or disable packet processing by the 99.Nm 100for each protocol. 101Disabling will also purge any outstanding packet from the protocol queue. 102.Pp 103.Nm 104supports multi-processor execution of handlers, and relies on a combination 105of source ordering and protocol-specific ordering and work-placement 106policies to decide how to distribute work across one or more worker 107threads. 108Registering protocols will declare one of three policies: 109.Bl -tag -width NETISR_POLICY_SOURCE 110.It Dv NETISR_POLICY_SOURCE 111.Nm 112should maintain source ordering without advice from the protocol. 113.Nm 114will ignore any flow IDs present on 115.Vt mbuf 116headers for the purposes of work placement. 117.It Dv NETISR_POLICY_FLOW 118.Nm 119should maintain flow ordering as defined by the 120.Vt mbuf 121header flow ID field. 122If the protocol implements 123.Va nh_m2flow , 124then 125.Nm 126will query the protocol in the event that the 127.Vt mbuf 128doesn't have a flow ID, falling back on source ordering. 129.It NETISR_POLICY_CPU 130.Nm 131will entirely delegate all work placement decisions to the protocol, 132querying 133.Va nh_m2cpuid 134for each packet. 135.El 136.Pp 137Registration is declared using 138.Vt "struct netisr_handler" , 139whose fields are defined as follows: 140.Bl -tag -width "netisr_handler_t nh_handler" 141.It Vt "const char *" Va nh_name 142Unique character string name of the protocol, which may be included in 143.Xr sysctl 3 144MIB names, so should not contain whitespace. 145.It Vt netisr_handler_t Va nh_handler 146Protocol handler function that will be invoked on each packet received for 147the protocol. 148.It Vt netisr_m2flow_t Va nh_m2flow 149Optional protocol function to generate a flow ID and set a valid 150hashtype for packets that enter the 151.Nm 152with 153.Dv M_HASHTYPE_GET(m) 154equal to 155.Dv M_HASHTYPE_NONE . 156Will be used only with 157.Dv NETISR_POLICY_FLOW . 158.It Vt netisr_m2cpuid_t Va nh_m2cpuid 159Protocol function to determine what CPU a packet should be processed on. 160Will be used only with 161.Dv NETISR_POLICY_CPU . 162.It Vt netisr_drainedcpu_t Va nh_drainedcpu 163Optional callback function that will be invoked when a per-CPU queue 164was drained. 165It will never fire for directly dispatched packets. 166Unless fully understood, this special-purpose function should not be used. 167.\" In case you intend to use this please send 50 chocolate bars to each 168.\" of rwatson and bz and wait for an answer. 169.It Vt u_int Va nh_proto 170Protocol number used by both protocols to identify themselves to 171.Nm , 172and by packet sources to select what handler will be used to process 173packets. 174A table of supported protocol numbers appears below. 175For implementation reasons, protocol numbers great than 15 are currently 176unsupported. 177.It Vt u_int Va nh_qlimit 178The maximum per-CPU queue depth for the protocol; due to internal 179implementation details, the effective queue depth may be as much as twice 180this number. 181.It Vt u_int Va nh_policy 182The ordering and work placement policy for the protocol, as described 183earlier. 184.El 185.Ss Packet source interface 186Packet sources, such as network interfaces, may request protocol processing 187using the 188.Fn netisr_dispatch 189and 190.Fn netisr_queue 191interfaces. 192Both accept a protocol number and 193.Vt mbuf 194argument, but while 195.Fn netisr_queue 196will always execute the protocol handler asynchronously in a deferred 197context, 198.Fn netisr_dispatch 199will optionally direct dispatch if permitted by global and per-protocol 200policy. 201.Pp 202In order to provide additional load balancing and flow information, 203packet sources may also specify an opaque source identifier, which in 204practice might be a network interface number or socket pointer, using 205the 206.Fn netisr_dispatch_src 207and 208.Fn netisr_queue_src 209variants. 210.Ss Protocol number constants 211The follow protocol numbers are currently defined: 212.Bl -tag -width NETISR_ROUTE 213.It Dv NETISR_IP 214IPv4 215.It Dv NETISR_IGMP 216IGMPv3 loopback 217.It Dv NETISR_ROUTE 218Routing socket loopback 219.It Dv NETISR_ARP 220ARP 221.It Dv NETISR_IPV6 222IPv6 223.El 224.Sh AUTHORS 225This manual page and the 226.Nm 227implementation were written by 228.An Robert N. M. Watson . 229