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