1.\" ng_source.4 2.\" Copyright 2002 Sandvine Inc. 3.\" All rights reserved. 4.\" 5.\" Subject to the following obligations and disclaimer of warranty, use and 6.\" redistribution of this software, in source or object code forms, with or 7.\" without modifications are expressly permitted by Sandvine Inc.; provided, 8.\" however, that: 9.\" 1. Any and all reproductions of the source or object code must include the 10.\" copyright notice above and the following disclaimer of warranties; and 11.\" 2. No rights are granted, in any manner or form, to use Sandvine Inc. 12.\" trademarks, including the mark "SANDVINE" on advertising, endorsements, 13.\" or otherwise except as such appears in the above copyright notice or in 14.\" the software. 15.\" 16.\" THIS SOFTWARE IS BEING PROVIDED BY SANDVINE "AS IS", AND TO THE MAXIMUM 17.\" EXTENT PERMITTED BY LAW, SANDVINE MAKES NO REPRESENTATIONS OR WARRANTIES, 18.\" EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, 19.\" ANY AND ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 20.\" PURPOSE, OR NON-INFRINGEMENT. SANDVINE DOES NOT WARRANT, GUARANTEE, OR 21.\" MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE 22.\" USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY 23.\" OR OTHERWISE. IN NO EVENT SHALL SANDVINE BE LIABLE FOR ANY DAMAGES 24.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING 25.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 26.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR 27.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY 28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 30.\" THIS SOFTWARE, EVEN IF SANDVINE IS ADVISED OF THE POSSIBILITY OF SUCH 31.\" DAMAGE. 32.\" 33.\" Author: Dave Chapeskie <dchapeskie@sandvine.com> 34.\" $FreeBSD$ 35.\" 36.Dd November 1, 2002 37.Dt NG_SOURCE 4 38.Os 39.Sh NAME 40.Nm ng_source 41.Nd netgraph discard node type 42.Sh SYNOPSIS 43.In netgraph/ng_source.h 44.Sh DESCRIPTION 45The 46.Nm source 47node acts as a source of packets according to the parameters set up 48using control messages and input packets. 49The 'output' hook must also be connected to a node that responds to the 50.Em NGM_ETHER_COOKIE 51/ 52.Em NGM_ETHER_GET_IFINDEX 53message (e.g. an 54ng_ether 55node). 56node type silently discards all data and control messages it receives. 57This type is used for testing and debugging. 58.Pp 59The operation of the node is as follows: 60.Pp 61.Bl -bullet -compact -offset 2n 62.It 63Packets received on the 'input' hook are queued internally. 64.It 65On recpetion of a NGM_SOURCE_START message the node starts sending 66the queued packets out the 'output' hook on every clock tick as fast 67as the connect interface will take them. 68.It 69While active, on every clock tick the node checks the available space 70in the ifqueue of the interface connected to the output hook and sends 71that many packets out it's output hook. 72.It 73Once the number of packets indicated in the start message have been 74sent, or on reception of a stop message, the node stops sending data. 75.El 76.Sh HOOKS 77The 78.Nm source 79node has two hooks: 'input' and 'output'. The 'output' 80hook must remain connected, its disconnection will shutdown the node. 81.Sh CONTROL MESSAGES 82This node type supports the generic control messages as well as the following, 83which must be sent with the 84.Em NGM_SOURCE_COOKIE 85attached. 86.Bl -tag -width NGM_SOURCE_GETCLR_STATS 87.It NGM_SOURCE_GET_STATS 88"getstats": 89Returns a structure containing the following fields: 90.\".Bl -bullet -compact -offset 2n 91.Bl -tag -width queueFrames: 92.It outOctets: 93The number of octets/bytes sent out the 'output' hook. 94.It outFrames: 95The number of frames/packets sent out the 'output' hook. 96.It queueOctets: 97The number of octets queued from the 'input' hook. 98.It queueFrames: 99The number of frames queued from the 'input' hook. 100.It startTime: 101The time the last start message was recieved. 102.It endTime: 103The time the last end message was recieved or 104the output packet count was reached. 105.It elapsedTime: 106Either endTime-startTime or current time - startTime. 107.El 108.It NGM_SOURCE_CLR_STATS 109"clrstats": 110Clears and resets the statistics returned by getstats (except 111queueOctects and queueFrames). 112.It NGM_SOURCE_GETCLR_STATS 113"getclrstats": 114As getstats but clears the statistics at the same time. 115.It NGM_SOURCE_START 116"start": 117.Bl -bullet -compact -offset 2n 118.It 119Takes a single u_int64_t parameter which is the number of packets to 120send before stopping. 121.It 122Starts sending the queued packets out the output hook. 123.It 124The output hook must be connected or EINVAL is returned. 125.It 126The node connected to the output hook must respond to 127.Em NGM_ETHER_GET_IFINDEX 128which is used to get the ifqueue of the attached 129interface. 130.It 131.Em NGM_ETHER_SET_AUTOSRC 132is sent to the node connected to the output hook 133to turn off automatic ethernet source address overwriting (any errors 134from this message are ignored). 135.El 136.It NGM_SOURCE_STOP 137"stop": 138Stops the node if it is active. 139.It NGM_SOURCE_CLR_DATA 140"clrdata": 141Clears the packets queued from the 'input' hook. 142.El 143.Sh SHUTDOWN 144This node shuts down upon receipt of a 145.Dv NGM_SHUTDOWN 146control message, or when the 147.Em output 148hook has been disconnected. 149.Sh EXAMPLE 150Build and install the node to /modules (or load it anually). 151.Bd -literal -offset 0n 152$ make obj 153$ make depend 154$ make 155$ make install 156.Ed 157.Pp 158Attach the node to an ng_ether node for an interface. If ng_ether is 159not already loaded you'll need to do so. For example these commands 160load the ng_ether module and attach the output hook of a new source node 161to orphans hook of the bge0: ng_ether node. 162.Bd -literal -offset 0n 163$ kldload ng_ether 164$ ngctl mkpeer bge0: source orphans output 165.Ed 166.Pp 167At this point the new node can be refered to as "bge0:orphans". The 168node can be given it's own name like this: 169.Bd -literal -offset 0n 170$ ngctl name bge0:orphans src0 171.Ed 172.Pp 173After which it can be refered to as "src0:". 174.Pp 175Once created packets need to be sent to the node, the TCL net package 176can be used to generate these packets: 177.Pp 178[Sandvine specific TCL code example omitted] 179.Pp 180To feed the output of the above TCL script to the ng_source node's input 181hook via nghook: 182.Bd -literal -offset 0n 183$ tcl genPacket | nghook bge0:orphans input 184.Ed 185.Pp 186To check that the node has queued these packets you can get the node 187statistics: 188.Bd -literal -offset 0n 189$ ngctl msg bge0:orphans getstats 190Args: { queueOctets=64 queueFrames=1 } 191.Ed 192.Pp 193Send as many packets as required out the output hook: 194.Bd -literal -offset 0n 195$ ngctl msg bge0:orphans start 16 196.Ed 197.Pp 198Either wait for them to be sent (periodicly fetching stats if desired) 199or send the stop message: 200.Bd -literal -offset 0n 201$ ngctl msg bge0:orphans stop 202.Ed 203.Pp 204Check the statistics (here we use getclrstats to also clear the 205statistics): 206.Bd -literal -offset 0n 207$ ngctl msg bge0:orphans getclrstats 208Args: { outOctets=1024 outFrames=16 queueOctets=64 queueFrames=1 209startTime={ tv_sec=1035305880 tv_usec=758036 } endTime={ tv_sec=1035305880 210tv_usec=759041 } elapsedTime={ tv_usec=1005 } } 211.Ed 212.Pp 213The times are from "struct timeval"s, the tv_sec field is seconds since 214the epoch and can be converted into a date string via TCL's [clock 215format] or via the UNIX date command: 216.Bd -literal -offset 0n 217$ date -r 1035305880 218Tue Oct 22 12:58:00 EDT 2002 219.Ed 220.Pp 221.Sh IMPLEMENTATION NOTES 222(FreeBSD 4.4 version) 223.Pp 224The use of splimp around the NG_SEND_DATA loop is important. Without 225it the time taken by a single invocation of ng_source_intr becomes too 226large and the packet rate drops. Probably due to the NIC starting to 227send the packets right away. 228.Pp 229Copying all the packets in one loop and sending them in another inside 230of ng_source_send is done to limit how long we're at splimp and gave 231minor packet rate increases (~5% at 256 byte packets). However note 232that if there are errors in the send loop the remaining copied packets 233are simply freed and discarded thus we skip those packets and ordering 234of the input queue to the output is not maintained. 235.Pp 236Calling timeout(9) at the end of ng_source_intr instead of near the 237begining is done to help avoid CPU starvaion if ng_source_intr takes a 238long time to run. 239.Pp 240The use of splnet may be sub-optimal. It's used for syncronization 241within the node (e.g. data recieved on the input hook while 242ng_source_send is active) but we don't want to hold it too long and risk 243starving the NIC. 244.Pp 245For clarity and simplicity debugging messages and instrumentation code 246has been removed. On i386 one can include machine/cpufunc.h to have 247access to the rdtsc() function to read the instruction counter at the 248start and end of ng_source_intr. Also useful is the packet count 249returned by ng_source_send. Do not try to report such things from 250within ng_source_intr, instead include the values in sc->stats. 251.Sh SEE ALSO 252.Xr netgraph 4 , 253.Xr ng_echo 4 , 254.Xr ng_hole 4 , 255.Xr ng_tee 4 , 256.Xr ngctl 8 257.Xr nghook 8 258.Sh HISTORY 259The 260.Nm 261node type was implemented in 262.Fx 4.8 . 263.Sh AUTHORS 264.An Dave Chapeskie Aq dchapeskie@SANDVINE.com 265