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);

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

             options VIMAGE

       void
       netisr_register_vnet(const struct netisr_handler *nhp);

       void
       netisr_unregister_vnet(const struct netisr_handler *nhp);

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).

   Protocol registration
       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 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 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 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.

   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.

Debian                                           April 25, 2017                                        NETISR(9)