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