From 478588ca1b52b3a312fed28f8b3175631d592dbd Mon Sep 17 00:00:00 2001 From: glebius Date: Tue, 5 Apr 2005 17:27:36 +0000 Subject: - Update and expand description of node operation. - Cut section IMPLELEMENTATION NOTES. It doesn't apply to modern FreeBSD. Sponsored by: Rambler --- share/man/man4/ng_source.4 | 190 ++++++++++++++------------------------------- 1 file changed, 60 insertions(+), 130 deletions(-) (limited to 'share') diff --git a/share/man/man4/ng_source.4 b/share/man/man4/ng_source.4 index 28ef641..4e50c24 100644 --- a/share/man/man4/ng_source.4 +++ b/share/man/man4/ng_source.4 @@ -32,12 +32,12 @@ .\" Author: Dave Chapeskie .\" $FreeBSD$ .\" -.Dd November 1, 2002 +.Dd April 5, 2005 .Dt NG_SOURCE 4 .Os .Sh NAME .Nm ng_source -.Nd netgraph discard node type +.Nd netgraph node for traffic generation .Sh SYNOPSIS .In sys/types.h .In netgraph/ng_source.h @@ -47,51 +47,61 @@ The node acts as a source of packets according to the parameters set up using control messages and input packets. The -.Dv output -hook must also be connected to a node that responds to the -.Dv NGM_ETHER_COOKIE Ns / Ns -.Dv NGM_ETHER_GET_IFINDEX -message (e.g., an -.Xr ng_ether 4 -node). -This type is used for testing and debugging. -.Pp -The operation of the node is as follows: -.Bl -bullet -.It -Packets received on the -.Dv input -hook are queued internally. -.It -On reception of a -.Dv NGM_SOURCE_START -message the node starts sending -the queued packets out the -.Dv output -hook on every clock tick as fast -as the connect interface will take them. -.It -While active, on every clock tick the node checks the available space -in the -.Va ifqueue -of the interface connected to the output hook and sends -that many packets out its -.Dv output -hook. -.It -Once the number of packets indicated in the start message have been -sent, or on reception of a stop message, the node stops sending data. -.El +.Nm +node type is used primarily for testing and benchmarking. .Sh HOOKS The .Nm source node has two hooks: -.Dv input +.Va input and -.Dv output . +.Va output . The -.Dv output +.Va output hook must remain connected, its disconnection will shutdown the node. +.Sh OPERATION +The operation of the node is as follows. +Packets received on the +.Va input +hook are queued internally. +When +.Va output +hook is connected, +.Nm +node assumes that its neighbour node is of +.Xr ng_ether +node type. +The neighbor is queried for its interface name. +.Nm +node then uses queue of the interface for its evil purposes. +.Nm +node also disables +.Va autosrc +option on neighbour +.Xr ng_ether +node. +If interface name can't be obtained automatically, it should +be configured explicitly with help of +.Dv NGM_SOURCE_SETIFACE +control message, and +.Va autosrc +should be turned off on +.Xr ng_ether +node manually. +.Pp +Once interface is configured, upon receival of +.Dv NGM_SOURCE_START +control message the node starts sending +the previously queued packets out the +.Va output +hook on every clock tick as fast +as the connected interface will take them. +While active, on every clock tick the node checks the available space +in the interface queue and sends that many packets out its +.Va output +hook. +Once the number of packets indicated in the start message have been +sent, or upon reception of a stop message, the node stops sending data. .Sh CONTROL MESSAGES This node type supports the generic control messages as well as the following, which must be sent with the @@ -141,109 +151,29 @@ As .Ic getstats but clears the statistics at the same time. .It Dv NGM_SOURCE_START Pq Ic start -.Bl -bullet -.It -Takes a single -.Vt u_int64_t +This message requires a single +.Vt uint64_t parameter which is the number of packets to send before stopping. -.It -Starts sending the queued packets out the output hook. -.It -The output hook must be connected or -.Er EINVAL -is returned. -.It -The node connected to the output hook must respond to -.Dv NGM_ETHER_GET_IFINDEX -which is used to get the -.Va ifqueue -of the attached interface. -.It -.Dv NGM_ETHER_SET_AUTOSRC -is sent to the node connected to the -.Dv output -hook -to turn off automatic Ethernet source address overwriting (any errors -from this message are ignored). -.El +Node starts sending the queued packets out the output hook. +The output hook must be connected and node must have +interface configured. .It Dv NGM_SOURCE_STOP Pq Ic stop Stops the node if it is active. .It Dv NGM_SOURCE_CLR_DATA Pq Ic clrdata Clears the packets queued from the .Dv input hook. +.It Dv NGM_SOURCE_SETIFACE Pq Ic setiface +This message requires a string argument - name of the interface +to be configured. .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN -control message, or when the -.Dv output +control message, when all hooks has been disconnected, or when the +.Va output hook has been disconnected. -.Sh IMPLEMENTATION NOTES -.No ( Fx 4.4 -version) -.Pp -The use of -.Xr splimp 9 -around the -.Dv NG_SEND_DATA -loop is important. -Without it, -the time taken by a single invocation of -.Fn ng_source_intr -becomes too -large and the packet rate drops. -Probably due to the NIC starting to -send the packets right away. -.Pp -Copying all the packets in one loop and sending them in another inside -of -.Fn ng_source_send -is done to limit how long we are at -.Xr splimp 9 -and gave -minor packet rate increases (~5% at 256 byte packets). -However note -that if there are errors in the send loop, the remaining copied packets -are simply freed and discarded; thus we skip those packets, and ordering -of the input queue to the output is not maintained. -.Pp -Calling -.Xr timeout 9 -at the end of -.Fn ng_source_intr -instead of near the -beginning is done to help avoid CPU starvation if -.Fn ng_source_intr -takes a long time to run. -.Pp -The use of -.Xr splnet 9 -may be sub-optimal. -It is used for synchronization -within the node (e.g., data received on the -.Dv input -hook while -.Fn ng_source_send -is active) but we do not want to hold it too long and risk -starving the NIC. -.Pp -For clarity and simplicity, debugging messages and instrumentation code -has been removed. -On i386 one can include -.In machine/cpufunc.h -to have access to the -.Fn rdtsc -function to read the instruction counter at the -start and end of -.Fn ng_source_intr . -Also useful is the packet count returned by -.Fn ng_source_send . -Do not try to report such things from within -.Fn ng_source_intr , -instead include the values in -.Va sc->stats . .Sh EXAMPLES Attach the node to an .Xr ng_ether 4 -- cgit v1.1