NETISR(9)

🌸 NETISR(9) 🌸

okay bestie, gather round, because we're about to talk about netisr — the kernel network dispatch service, from the Kernel Developer's Manual. yes it's a (9) page, yes it's kernel-land, yes it's iconic. sit down, hydrate, let's go 💅

---

✨ NAME ✨

netisr — Kernel network dispatch service 🫶

---

🎀 SYNOPSIS 🎀

#include <net/netisr.h>

void
netisr_register(const struct netisr_handler *nhp);

void
netisr_unregister(const struct netisr_handler *nhp);

int
netisr_dispatch(u_int proto, struct mbuf *m);

int
netisr_dispatch_src(u_int proto, uintptr_t source, struct mbuf *m);

int
netisr_queue(u_int proto, struct mbuf *m);

int
netisr_queue_src(u_int proto, uintptr_t source, struct mbuf *m);

void
netisr_clearqdrops(const struct netisr_handler *nhp);

void
netisr_getqdrops(const struct netisr_handler *nhp, uint64_t *qdropsp);

void
netisr_getqlimit(const struct netisr_handler *nhp, u_int *qlimitp);

int
netisr_setqlimit(const struct netisr_handler *nhp, u_int qlimit);

u_int
netisr_default_flow2cpu(u_int flowid);

u_int
netisr_get_cpucount(void);

u_int
netisr_get_cpuid(u_int cpunumber);

and if you've got the optional virtual network stack support turned on via this kernel compile option:

options VIMAGE

then you ALSO get these two:

void
netisr_register_vnet(const struct netisr_handler *nhp);

void
netisr_unregister_vnet(const struct netisr_handler *nhp);

---

💖 DESCRIPTION 💖

so the netisr kernel interface suite is literally the whole group chat between device drivers (and other packet sources) and protocols — it lets them hand packets off for either directly dispatched or deferred processing. and the way that you can keep an eye on protocol registration and work stream statistics? that's netstat(1). no cap 🔥

🌈 Protocol registration

protocols register and unregister their handlers with netisr_register() and netisr_unregister(), and they can also manage queue limits and stats using netisr_clearqdrops(), netisr_getqdrops(), netisr_getqlimit(), and netisr_setqlimit().

in case of VIMAGE kernels, every 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. and heads up — disabling will also purge any outstanding packet from the protocol queue. bye bye packet 🙈

netisr supports multi-processor execution of handlers, and it 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 struct netisr_handler, whose fields are defined as follows:

• const char * nh_name — unique character string name of the protocol, which may be included in sysctl(3) MIB names, so it should not contain whitespace.
• netisr_handler_t nh_handler — protocol handler function that will be invoked on each packet received for the protocol.
• netisr_m2flow_t nh_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_t nh_m2cpuid — protocol function to determine what CPU a packet should be processed on. will be used only with NETISR_POLICY_CPU.
• netisr_drainedcpu_t nh_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_int nh_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_int nh_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_int nh_policy — the ordering and work placement policy for the protocol, as described earlier.

🦋 Packet source interface

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 here's the tea ☕ — 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. slay ✨

⭐ Protocol number constants

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)

---

👑 AUTHORS 👑

this manual page and the netisr implementation were written by Robert N. M. Watson. legend behaviour, honestly 💜

---

and that's the whole page, bestie!! this one came from the Debian crew and it's dated April 25, 2017, living in section NETISR(9) of the Kernel Developer's Manual. go forth and dispatch responsibly 🧚💖