Add the netgraph 'source' module.

This is NOT YET CONVERTED TO -current.
This node is a source for preprogrammed packets at a known rate for testing.

I will convert it to -current "in place" but will MFC teh original
pre-conversion variant as that is  what is originally submitted.
Man page my me, info from Dave's README.

Submitted by:	Dave Chapeskie <dchapeskie@SANDVINE.com>
Obtained from:	Sandvine inc.
MFC after:	1 week

1 files changed, 264 insertions, 0 deletions

diff --git a/share/man/man4/ng_source.4 b/share/man/man4/ng_source.4
new file mode 100644
index 0000000..0af9181
--- /dev/null
+++ b/share/man/man4/ng_source.4
@@ -0,0 +1,264 @@
+.\" ng_source.4
+.\" Copyright 2002 Sandvine Inc.
+.\" All rights reserved.
+.\"
+.\" Subject to the following obligations and disclaimer of warranty, use and
+.\" redistribution of this software, in source or object code forms, with or
+.\" without modifications are expressly permitted by Sandvine Inc.; provided,
+.\" however, that:
+.\" 1. Any and all reproductions of the source or object code must include the
+.\"    copyright notice above and the following disclaimer of warranties; and
+.\" 2. No rights are granted, in any manner or form, to use Sandvine Inc.
+.\"    trademarks, including the mark "SANDVINE" on advertising, endorsements,
+.\"    or otherwise except as such appears in the above copyright notice or in
+.\"    the software.
+.\"
+.\" THIS SOFTWARE IS BEING PROVIDED BY SANDVINE "AS IS", AND TO THE MAXIMUM
+.\" EXTENT PERMITTED BY LAW, SANDVINE MAKES NO REPRESENTATIONS OR WARRANTIES,
+.\" EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, INCLUDING WITHOUT LIMITATION,
+.\" ANY AND ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+.\" PURPOSE, OR NON-INFRINGEMENT.  SANDVINE DOES NOT WARRANT, GUARANTEE, OR
+.\" MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE
+.\" USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY
+.\" OR OTHERWISE.  IN NO EVENT SHALL SANDVINE BE LIABLE FOR ANY DAMAGES
+.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
+.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 SANDVINE IS ADVISED OF THE POSSIBILITY OF SUCH
+.\" DAMAGE.
+.\"
+.\" Author: Dave Chapeskie <dchapeskie@sandvine.com>
+.\" $FreeBSD$
+.\"
+.Dd November 1, 2002
+.Dt NG_SOURCE 4
+.Os
+.Sh NAME
+.Nm ng_source
+.Nd netgraph discard node type
+.Sh SYNOPSIS
+.In netgraph/ng_source.h
+.Sh DESCRIPTION
+The 
+.Nm source
+node acts as a source of packets according to the parameters set up
+using control messages and input packets.
+The 'output' hook must also be connected to a node that responds to the
+.Em NGM_ETHER_COOKIE
+/
+.Em NGM_ETHER_GET_IFINDEX
+message (e.g. an
+ng_ether
+node).
+node type silently discards all data and control messages it receives.
+This type is used for testing and debugging.
+.Pp
+The operation of the node is as follows:
+.Pp
+.Bl -bullet -compact -offset 2n
+.It
+Packets received on the 'input' hook are queued internally.
+.It
+On recpetion of a NGM_SOURCE_START message the node starts sending
+the queued packets out the '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 ifqueue of the interface connected to the output hook and sends
+that many packets out it's 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
+.Sh HOOKS
+The 
+.Nm source
+node has two hooks: 'input' and 'output'.  The 'output'
+hook must remain connected, its disconnection will shutdown the node.
+.Sh CONTROL MESSAGES
+This node type supports the generic control messages as well as the following,
+which must be sent with the
+.Em NGM_SOURCE_COOKIE
+attached.
+.Bl -tag -width NGM_SOURCE_GETCLR_STATS
+.It NGM_SOURCE_GET_STATS
+"getstats":
+Returns a structure containing the following fields:
+.\".Bl -bullet -compact -offset 2n
+.Bl -tag -width queueFrames:
+.It outOctets:
+The number of octets/bytes sent out the 'output' hook.
+.It outFrames:
+The number of frames/packets sent out the 'output' hook.
+.It queueOctets:
+The number of octets queued from the 'input' hook.
+.It queueFrames:
+The number of frames queued from the 'input' hook.
+.It startTime:
+The time the last start message was recieved.
+.It endTime:
+The time the last end message was recieved or
+the output packet count was reached.
+.It elapsedTime:
+Either endTime-startTime or current time - startTime.
+.El
+.It NGM_SOURCE_CLR_STATS
+"clrstats":
+Clears and resets the statistics returned by getstats (except
+queueOctects and queueFrames).
+.It NGM_SOURCE_GETCLR_STATS
+"getclrstats":
+As getstats but clears the statistics at the same time.
+.It NGM_SOURCE_START
+"start":
+.Bl -bullet -compact -offset 2n
+.It
+Takes a single u_int64_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 EINVAL is returned.
+.It
+The node connected to the output hook must respond to
+.Em NGM_ETHER_GET_IFINDEX
+which is used to get the ifqueue of the attached
+interface.
+.It
+.Em NGM_ETHER_SET_AUTOSRC
+is sent to the node connected to the output hook
+to turn off automatic ethernet source address overwriting (any errors
+from this message are ignored).
+.El
+.It NGM_SOURCE_STOP
+"stop":
+Stops the node if it is active.
+.It NGM_SOURCE_CLR_DATA
+"clrdata":
+Clears the packets queued from the 'input' hook.
+.El
+.Sh SHUTDOWN
+This node shuts down upon receipt of a
+.Dv NGM_SHUTDOWN
+control message, or when the 
+.Em output
+hook has been disconnected.
+.Sh EXAMPLE
+Build and install the node to /modules (or load it anually).
+.Bd -literal -offset 0n
+$ make obj
+$ make depend
+$ make
+$ make install
+.Ed
+.Pp
+Attach the node to an ng_ether node for an interface.  If ng_ether is
+not already loaded you'll need to do so.  For example these commands
+load the ng_ether module and attach the output hook of a new source node
+to orphans hook of the bge0: ng_ether node.
+.Bd -literal -offset 0n
+$ kldload ng_ether
+$ ngctl mkpeer bge0: source orphans output 
+.Ed
+.Pp
+At this point the new node can be refered to as "bge0:orphans".  The
+node can be given it's own name like this:
+.Bd -literal -offset 0n
+$ ngctl name bge0:orphans src0
+.Ed
+.Pp
+After which it can be refered to as "src0:".
+.Pp
+Once created packets need to be sent to the node, the TCL net package
+can be used to generate these packets:
+.Pp
+[Sandvine specific TCL code example omitted]
+.Pp
+To feed the output of the above TCL script to the ng_source node's input
+hook via nghook:
+.Bd -literal -offset 0n
+$ tcl genPacket | nghook bge0:orphans input
+.Ed
+.Pp
+To check that the node has queued these packets you can get the node
+statistics:
+.Bd -literal -offset 0n
+$ ngctl msg bge0:orphans getstats
+Args:   { queueOctets=64 queueFrames=1 }
+.Ed
+.Pp
+Send as many packets as required out the output hook:
+.Bd -literal -offset 0n
+$ ngctl msg bge0:orphans start 16
+.Ed
+.Pp
+Either wait for them to be sent (periodicly fetching stats if desired)
+or send the stop message:
+.Bd -literal -offset 0n
+$ ngctl msg bge0:orphans stop
+.Ed
+.Pp
+Check the statistics (here we use getclrstats to also clear the
+statistics):
+.Bd -literal -offset 0n
+$ ngctl msg bge0:orphans getclrstats
+Args:   { outOctets=1024 outFrames=16 queueOctets=64 queueFrames=1
+startTime={ tv_sec=1035305880 tv_usec=758036 } endTime={ tv_sec=1035305880
+tv_usec=759041 } elapsedTime={ tv_usec=1005 } }
+.Ed
+.Pp
+The times are from "struct timeval"s, the tv_sec field is seconds since
+the epoch and can be converted into a date string via TCL's [clock
+format] or via the UNIX date command:
+.Bd -literal -offset 0n
+$ date -r 1035305880
+Tue Oct 22 12:58:00 EDT 2002
+.Ed
+.Pp
+.Sh IMPLEMENTATION NOTES
+(FreeBSD 4.4 version)
+.Pp
+The use of splimp around the NG_SEND_DATA loop is important.  Without
+it the time taken by a single invocation of 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 ng_source_send is done to limit how long we're at splimp 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 timeout(9) at the end of ng_source_intr instead of near the
+begining is done to help avoid CPU starvaion if ng_source_intr takes a
+long time to run.
+.Pp
+The use of splnet may be sub-optimal.  It's used for syncronization
+within the node (e.g. data recieved on the input hook while
+ng_source_send is active) but we don't 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 machine/cpufunc.h to have
+access to the rdtsc() function to read the instruction counter at the
+start and end of ng_source_intr.  Also useful is the packet count
+returned by ng_source_send.  Do not try to report such things from
+within ng_source_intr, instead include the values in sc->stats.
+.Sh SEE ALSO
+.Xr netgraph 4 ,
+.Xr ng_echo 4 ,
+.Xr ng_hole 4 ,
+.Xr ng_tee 4 ,
+.Xr ngctl 8
+.Xr nghook 8
+.Sh HISTORY
+The
+.Nm
+node type was implemented in
+.Fx 4.8 .
+.Sh AUTHORS
+.An Dave Chapeskie Aq dchapeskie@SANDVINE.com