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