From 2b053d10b20088ff5a65fccecc61679906aa128f Mon Sep 17 00:00:00 2001 From: rwatson Date: Sun, 7 Jun 2009 21:32:01 +0000 Subject: [PATCH] Try again to add beginnings of netisr(8) man page: this time add netisr.9. --- share/man/man9/netisr.9 | 210 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 share/man/man9/netisr.9 diff --git a/share/man/man9/netisr.9 b/share/man/man9/netisr.9 new file mode 100644 index 000000000000..3c65dee94926 --- /dev/null +++ b/share/man/man9/netisr.9 @@ -0,0 +1,210 @@ +.\" +.\" Copyright (c) 2009 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +.\" DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 7, 2009 +.Dt NETISR 9 +.Os +.Sh NAME +.Nm netisr +.Nd Kernel network dispatch service +.Sh SYNOPSIS +.In net/netisr.h +.Ft void +.Fn netisr_register "const struct netisr_handler *nhp" +.Ft void +.Fn netisr_unregister "const struct netisr_handler *nhp" +.Ft int +.Fn netisr_dispatch "u_int proto" "struct mbuf *m" +.Ft int +.Fn netisr_dispatch_src "u_int proto" "uintptr_t source" "struct mbuf *m" +.Ft int +.Fn netisr_queue "u_int proto" "struct mbuf *m" +.Ft int +.Fn netisr_queue_src "u_int proto" "uintptr_t source" "struct mbuf *m" +.Ft void +.Fn netisr_clearqdrops "const struct netisr_handler *nhp" +.Ft void +.Fn netisr_getqdrops "const struct netisr_handler *nhp" "u_int64_t *qdropsp" +.Ft +void +.Fn netisr_getqlimit "const struct netisr_handler *nhp" "u_int *qlimitp" +.Ft int +.Fn netisr_setqlimit "const struct netisr_handler *nhp" "u_int qlimit" +.Ft u_int +.Fn netisr_default_flow2cpu "u_int flowid" +.Ft u_int +.Fn netisr_get_cpucount "void" +.Ft u_int +.Fn netisr_get_cpuid "u_int cpunumber" +.Sh DESCRIPTION +The +.Nm +kernel interface suite allows device drivers (and other packet sources) to +direct packets to protocols for directly dispatched or deferred processing. +.Ss Protocol registration +Protocols register and unregister handlers using +.Fn netisr_register +and +.Fn netisr_unregister , +and may also manage queue limits and statistics using the +.Fn netisr_clearqdrops , +.Fn netisr_getqdrops , +.Fn netisr_getqlimit , +and +.Fn netisr_setqlimit. +.Pp +.Nm +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 do distribute work across one or more worker +threads. +Registering protocols will declare one of three policies: +.Bl -tag -width NETISR_POLICY_SOURCE +.It Dv NETISR_POLICY_SOURCE +.Nm +should maintain source ordering without advice from the protocol. +.Nm +will ignore any flow IDs present on +.Vt mbuf +headers for the purposes of work placement. +.It Dv NETISR_POLICY_FLOW +.Nm +should maintain flow ordering as defined by the +.Vt mbuf +header flow ID field. +If the protocol implements +.Va nh_m2flow , +then +.Nm +will query the protocol in the evet that the +.Vt mbuf +doesn't have a flow ID, falling back on source ordering. +.It NETISR_POLICY_CPU +.Nm +will entirely delegate all work placement decisions to the protocol, +querying +.Va nh_m2cpuid +for each packet. +.El +.Pp +Registration is declared using +.Vt "struct netisr_handler" , +whose fields are defined as follows: +.Bl -tag -width "netisr_handler_t nh_handler" +.It Vt "const char *" Va nh_name +Unique character string name of the protocol, which may be included in +.Xr 2 sysctl +MIB names, so should not contain whitespace. +.It Vt netisr_handler_t Va nh_handler +Protocol handler function that will be invoked on each packet received for +the protocol. +.It Vt netisr_m2flow_t Va nh_m2flow +Optional protocol function to generate a flow ID and set +.Dv M_FLOWID +for packets that do not enter +.Nm +with +.Dv M_FLOWID +defined. +Will be used only with +.Dv NETISR_POLICY_FLOW . +.It Vt netisr_m2cpuid_t Va nh_m2cpuid +Protocol function to determine what CPU a packet should be processed on. +Will be used only with +.Dv NETISR_POLICY_CPU . +.It Vt u_int Va nh_proto +Protocol number used by both protocols to identify themselves to +.Nm , +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. +.It Vt u_int Va 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. +.It Vt u_int Va nh_policy +The ordering and work placement policy for the protocol, as described +earlier. +.El +.Ss Packet source interface +Packet sources, such as network interfaces, may request protocol processing +using the +.Fn netisr_dispatch +and +.Fn netisr_queue +interfaces. +Both accept a protocol number and +.Vt mbuf +argument, but while +.Fn netisr_queue +will always execute the protocol handler asynchonously in a deferred +context, +.Fn netisr_dispatch +will optionally direct dispatch if permitted by global and per-protocol +policy. +.Pp +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 +.Fn netisr_dispatch_src +and +.Fn netisr_queue_src +variants. +.Ss Protocol number constants +The follow protocol numbers are currently defined: +.Bl -tag -width NETISR_ATALK1 +.It Dv NETISR_IP +IPv4 +.It Dv NETISR_IGMP +IGMPv3 loopback +.It Dv NETISR_ROUTE +Routing socket loopback +.It Dv NETISR_AARP +Appletalk AARP +.It Dv NETISR_ATALK1 +Appletalk phase 1 +.It Dv NETISR_ATALK2 +Appletalk phase 2 +.It Dv NETISR_ARP +ARP +.It Dv NETISR_IPX +IPX/SPX +.It Dv NETISR_IPV6 +IPv6 +.It Dv NETISR_NATM +ATM +.El +.Sh AUTHORS +This manual page and the +.Nm +implementation were written by +.An Robert N. M. Watson .