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: head/share/man/man4/ng_source.4 107782 2002-12-12 15:25:56Z ru $
.Dd November 1, 2002 .Dt NG_SOURCE 4 .Os .Sh NAME .Nm ng_source .Nd netgraph discard node type .Sh SYNOPSIS n 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 .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.
p The operation of the node is as follows: l -bullet t Packets received on the .Dv input hook are queued internally. t 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. t 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. t 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: .Dv input and .Dv output . The .Dv 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 .Dv NGM_SOURCE_COOKIE attached. l -tag -width indent t Dv NGM_SOURCE_GET_STATS Pq Ic getstats Returns a structure containing the following fields: l -tag -width indent t Va outOctets The number of octets/bytes sent out the .Dv output hook. t Va outFrames The number of frames/packets sent out the .Dv output hook. t Va queueOctets The number of octets queued from the .Dv input hook. t Va queueFrames The number of frames queued from the .Dv input hook. t Va startTime The time the last start message was received. t Va endTime The time the last end message was received or the output packet count was reached. t Va elapsedTime Either .Va endTime Li - Va startTime or current time - .Va startTime . .El t Dv NGM_SOURCE_CLR_STATS Pq Ic clrstats Clears and resets the statistics returned by c getstats (except .Va queueOctets and .Va queueFrames ) . t Dv NGM_SOURCE_GETCLR_STATS Pq Ic getclrstats As c getstats but clears the statistics at the same time. t Dv NGM_SOURCE_START Pq Ic start l -bullet t Takes a single .Vt u_int64_t parameter which is the number of packets to send before stopping. t Starts sending the queued packets out the output hook. t The output hook must be connected or .Er EINVAL is returned. t 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. t .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 t Dv NGM_SOURCE_STOP Pq Ic stop Stops the node if it is active. t Dv NGM_SOURCE_CLR_DATA Pq Ic clrdata Clears the packets queued from the .Dv input hook. .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when the .Dv output hook has been disconnected. .Sh EXAMPLES Attach the node to an .Xr ng_ether 4 node for an interface. If .Nm ng_ether is not already loaded you will need to do so. For example, these commands load the .Nm ng_ether module and attach the .Dv output hook of a new .Nm source node to .Dv orphans hook of the .Li bge0: .Nm ng_ether node. d -literal -offset indent kldload ng_ether ngctl mkpeer bge0: source orphans output .Ed
p At this point the new node can be referred to as .Dq Li bge0:orphans . The node can be given its own name like this:
p .Dl "ngctl name bge0:orphans src0"
p After which it can be referred to as .Dq Li src0: .
p Once created, packets need to be sent to the node, the TCL net package can be used to generate these packets:
p [Sandvine specific TCL code example omitted]
p To feed the output of the above TCL script to the .Nm source node's .Dv input hook via .Xr nghook 8 :
p .Dl "tcl genPacket | nghook bge0:orphans input"
p To check that the node has queued these packets you can get the node statistics: d -literal -offset indent ngctl msg bge0:orphans getstats Args: { queueOctets=64 queueFrames=1 } .Ed
p Send as many packets as required out the .Dv output hook:
p .Dl "ngctl msg bge0:orphans start 16"
p Either wait for them to be sent (periodically fetching stats if desired) or send the stop message:
p .Dl "ngctl msg bge0:orphans stop"
p Check the statistics (here we use c getclrstats to also clear the statistics): d -literal -offset indent 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
p The times are from .Vt "struct timeval" Ns s , the .Va tv_sec field is seconds since the Epoch and can be converted into a date string via TCL's [clock format] or via the .Xr date 1 command: d -literal -offset indent date -r 1035305880 Tue Oct 22 12:58:00 EDT 2002 .Ed .Sh IMPLEMENTATION NOTES .No ( Fx 4.4 version)
p 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.
p 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.
p 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.
p 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.
p For clarity and simplicity, debugging messages and instrumentation code has been removed. On i386 one can include .Aq Pa 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 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