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