585ff168dc
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
265 lines
8.9 KiB
Groff
265 lines
8.9 KiB
Groff
.\" 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
|