netisr — Kernel network dispatch service

Authors

       This manual page and the netisr implementation were written by Robert N. M. Watson.

Debian                                           April 25, 2017                                        NETISR(9)

Description

The netisr kernel interface suite allows device drivers (and other packet sources) to direct packets to
protocols for directly dispatched or deferred processing. Protocol registration and work stream
statistics may be monitored using netstat(1).

Protocolregistration
Protocols register and unregister handlers using netisr_register() and netisr_unregister(), and may also
manage queue limits and statistics using the netisr_clearqdrops(), netisr_getqdrops(),
netisr_getqlimit(), and netisr_setqlimit().

In case of VIMAGE kernels each virtual network stack (vnet), that is not the default base system network
stack, calls netisr_register_vnet() and netisr_unregister_vnet() to enable or disable packet processing
by the netisr for each protocol. Disabling will also purge any outstanding packet from the protocol
queue.

netisr supports multi-processor execution of handlers, and relies on a combination of source ordering and
protocol-specific ordering and work-placement policies to decide how to distribute work across one or
more worker threads. Registering protocols will declare one of three policies:

NETISR_POLICY_SOURCE netisr should maintain source ordering without advice from the protocol. netisr
will ignore any flow IDs present on mbuf headers for the purposes of work
placement.

NETISR_POLICY_FLOW netisr should maintain flow ordering as defined by the mbuf header flow ID field.
If the protocol implements nh_m2flow, then netisr will query the protocol in the
event that the mbuf doesn't have a flow ID, falling back on source ordering.

NETISR_POLICY_CPU netisr will entirely delegate all work placement decisions to the protocol,
querying nh_m2cpuid for each packet.

Registration is declared using structnetisr_handler, whose fields are defined as follows:

constchar*nh_name Unique character string name of the protocol, which may be included in
sysctl(3) MIB names, so should not contain whitespace.

netisr_handler_tnh_handler Protocol handler function that will be invoked on each packet received for
the protocol.

netisr_m2flow_tnh_m2flow Optional protocol function to generate a flow ID and set a valid hashtype
for packets that enter the netisr with M_HASHTYPE_GET(m) equal to
M_HASHTYPE_NONE. Will be used only with NETISR_POLICY_FLOW.

netisr_m2cpuid_tnh_m2cpuid Protocol function to determine what CPU a packet should be processed on.
Will be used only with NETISR_POLICY_CPU.

netisr_drainedcpu_tnh_drainedcpu
Optional callback function that will be invoked when a per-CPU queue was
drained. It will never fire for directly dispatched packets. Unless fully
understood, this special-purpose function should not be used.

u_intnh_proto Protocol number used by both protocols to identify themselves to netisr, and
by packet sources to select what handler will be used to process packets. A
table of supported protocol numbers appears below. For implementation
reasons, protocol numbers great than 15 are currently unsupported.

u_intnh_qlimit The maximum per-CPU queue depth for the protocol; due to internal
implementation details, the effective queue depth may be as much as twice
this number.

u_intnh_policy The ordering and work placement policy for the protocol, as described
earlier.

Packetsourceinterface
Packet sources, such as network interfaces, may request protocol processing using the netisr_dispatch()
and netisr_queue() interfaces. Both accept a protocol number and mbuf argument, but while netisr_queue()
will always execute the protocol handler asynchronously in a deferred context, netisr_dispatch() will
optionally direct dispatch if permitted by global and per-protocol policy.

In order to provide additional load balancing and flow information, packet sources may also specify an
opaque source identifier, which in practice might be a network interface number or socket pointer, using
the netisr_dispatch_src() and netisr_queue_src() variants.

Protocolnumberconstants
The follow protocol numbers are currently defined:

NETISR_IP IPv4

NETISR_IGMP IGMPv3 loopback

NETISR_ROUTE Routing socket loopback

NETISR_ARP ARP

NETISR_IPV6 IPv6

NETISR_EPAIR netstat(1), epair(4)

Name

       netisr — Kernel network dispatch service

Synopsis

#include<net/netisr.h>voidnetisr_register(conststructnetisr_handler*nhp);

       voidnetisr_unregister(conststructnetisr_handler*nhp);

       intnetisr_dispatch(u_intproto, structmbuf*m);

       intnetisr_dispatch_src(u_intproto, uintptr_tsource, structmbuf*m);

       intnetisr_queue(u_intproto, structmbuf*m);

       intnetisr_queue_src(u_intproto, uintptr_tsource, structmbuf*m);

       voidnetisr_clearqdrops(conststructnetisr_handler*nhp);

       voidnetisr_getqdrops(conststructnetisr_handler*nhp, uint64_t*qdropsp);

       voidnetisr_getqlimit(conststructnetisr_handler*nhp, u_int*qlimitp);

       intnetisr_setqlimit(conststructnetisr_handler*nhp, u_intqlimit);

       u_intnetisr_default_flow2cpu(u_intflowid);

       u_intnetisr_get_cpucount(void);

       u_intnetisr_get_cpuid(u_intcpunumber);

       With optional virtual network stack support enabled via the following kernel compile option:

             optionsVIMAGEvoidnetisr_register_vnet(conststructnetisr_handler*nhp);

       voidnetisr_unregister_vnet(conststructnetisr_handler*nhp);