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