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