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