2 .\" Copyright (c) 2009 Robert N. M. Watson
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
35 .Nd Kernel network dispatch service
39 .Fn netisr_register "const struct netisr_handler *nhp"
41 .Fn netisr_unregister "const struct netisr_handler *nhp"
43 .Fn netisr_dispatch "u_int proto" "struct mbuf *m"
45 .Fn netisr_dispatch_src "u_int proto" "uintptr_t source" "struct mbuf *m"
47 .Fn netisr_queue "u_int proto" "struct mbuf *m"
49 .Fn netisr_queue_src "u_int proto" "uintptr_t source" "struct mbuf *m"
51 .Fn netisr_clearqdrops "const struct netisr_handler *nhp"
53 .Fn netisr_getqdrops "const struct netisr_handler *nhp" "uint64_t *qdropsp"
55 .Fn netisr_getqlimit "const struct netisr_handler *nhp" "u_int *qlimitp"
57 .Fn netisr_setqlimit "const struct netisr_handler *nhp" "u_int qlimit"
59 .Fn netisr_default_flow2cpu "u_int flowid"
61 .Fn netisr_get_cpucount "void"
63 .Fn netisr_get_cpuid "u_int cpunumber"
65 With optional virtual network stack support enabled via the following kernel
67 .Bd -ragged -offset indent
71 .Fn netisr_register_vnet "const struct netisr_handler *nhp"
73 .Fn netisr_unregister_vnet "const struct netisr_handler *nhp"
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
81 .Ss Protocol registration
82 Protocols register and unregister handlers using
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 ,
91 .Fn netisr_setqlimit .
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
97 .Fn netisr_unregister_vnet
98 to enable or disable packet processing by the
101 Disabling will also purge any outstanding packet from the protocol queue.
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
108 Registering protocols will declare one of three policies:
109 .Bl -tag -width NETISR_POLICY_SOURCE
110 .It Dv NETISR_POLICY_SOURCE
112 should maintain source ordering without advice from the protocol.
114 will ignore any flow IDs present on
116 headers for the purposes of work placement.
117 .It Dv NETISR_POLICY_FLOW
119 should maintain flow ordering as defined by the
121 header flow ID field.
122 If the protocol implements
126 will query the protocol in the event that the
128 doesn't have a flow ID, falling back on source ordering.
129 .It NETISR_POLICY_CPU
131 will entirely delegate all work placement decisions to the protocol,
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
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
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
153 .Dv M_HASHTYPE_GET(m)
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
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
172 and by packet sources to select what handler will be used to process
174 A table of supported protocol numbers appears below.
175 For implementation reasons, protocol numbers great than 15 are currently
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
181 .It Vt u_int Va nh_policy
182 The ordering and work placement policy for the protocol, as described
185 .Ss Packet source interface
186 Packet sources, such as network interfaces, may request protocol processing
192 Both accept a protocol number and
196 will always execute the protocol handler asynchronously in a deferred
199 will optionally direct dispatch if permitted by global and per-protocol
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
206 .Fn netisr_dispatch_src
210 .Ss Protocol number constants
211 The follow protocol numbers are currently defined:
212 .Bl -tag -width NETISR_ROUTE
218 Routing socket loopback
228 This manual page and the
230 implementation were written by
231 .An Robert N. M. Watson .