share/man/man9/netisr.9

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