- Update and expand description of node operation.

- Cut section IMPLELEMENTATION NOTES. It doesn't apply to
  modern FreeBSD.

Sponsored by:	Rambler

1 files changed, 60 insertions, 130 deletions

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 <dchapeskie@sandvine.com>
 .\" $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