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