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 netgraph/ng_source.h 43.Sh DESCRIPTION 44The 45.Nm source 46node acts as a source of packets according to the parameters set up 47using control messages and input packets. 48The 49.Dv output 50hook must also be connected to a node that responds to the 51.Dv NGM_ETHER_COOKIE Ns / Ns 52.Dv NGM_ETHER_GET_IFINDEX 53message (e.g., an 54.Xr ng_ether 4 55node). 56This type is used for testing and debugging. 57.Pp 58The operation of the node is as follows: 59.Bl -bullet 60.It 61Packets received on the 62.Dv input 63hook are queued internally. 64.It 65On reception of a 66.Dv NGM_SOURCE_START 67message the node starts sending 68the queued packets out the 69.Dv output 70hook on every clock tick as fast 71as the connect interface will take them. 72.It 73While active, on every clock tick the node checks the available space 74in the 75.Va ifqueue 76of the interface connected to the output hook and sends 77that many packets out its 78.Dv output 79hook. 80.It 81Once the number of packets indicated in the start message have been 82sent, or on reception of a stop message, the node stops sending data. 83.El 84.Sh HOOKS 85The 86.Nm source 87node has two hooks: 88.Dv input 89and 90.Dv output . 91The 92.Dv output 93hook must remain connected, its disconnection will shutdown the node. 94.Sh CONTROL MESSAGES 95This node type supports the generic control messages as well as the following, 96which must be sent with the 97.Dv NGM_SOURCE_COOKIE 98attached. 99.Bl -tag -width indent 100.It Dv NGM_SOURCE_GET_STATS Pq Ic getstats 101Returns a structure containing the following fields: 102.Bl -tag -width indent 103.It Va outOctets 104The number of octets/bytes sent out the 105.Dv output 106hook. 107.It Va outFrames 108The number of frames/packets sent out the 109.Dv output 110hook. 111.It Va queueOctets 112The number of octets queued from the 113.Dv input 114hook. 115.It Va queueFrames 116The number of frames queued from the 117.Dv input 118hook. 119.It Va startTime 120The time the last start message was received. 121.It Va endTime 122The time the last end message was received or 123the output packet count was reached. 124.It Va elapsedTime 125Either 126.Va endTime Li \- Va startTime 127or current time 128\- 129.Va startTime . 130.El 131.It Dv NGM_SOURCE_CLR_STATS Pq Ic clrstats 132Clears and resets the statistics returned by 133.Ic getstats 134(except 135.Va queueOctets 136and 137.Va queueFrames ) . 138.It Dv NGM_SOURCE_GETCLR_STATS Pq Ic getclrstats 139As 140.Ic getstats 141but clears the statistics at the same time. 142.It Dv NGM_SOURCE_START Pq Ic start 143.Bl -bullet 144.It 145Takes a single 146.Vt u_int64_t 147parameter which is the number of packets to 148send before stopping. 149.It 150Starts sending the queued packets out the output hook. 151.It 152The output hook must be connected or 153.Er EINVAL 154is returned. 155.It 156The node connected to the output hook must respond to 157.Dv NGM_ETHER_GET_IFINDEX 158which is used to get the 159.Va ifqueue 160of the attached interface. 161.It 162.Dv NGM_ETHER_SET_AUTOSRC 163is sent to the node connected to the 164.Dv output 165hook 166to turn off automatic ethernet source address overwriting (any errors 167from this message are ignored). 168.El 169.It Dv NGM_SOURCE_STOP Pq Ic stop 170Stops the node if it is active. 171.It Dv NGM_SOURCE_CLR_DATA Pq Ic clrdata 172Clears the packets queued from the 173.Dv input 174hook. 175.El 176.Sh SHUTDOWN 177This node shuts down upon receipt of a 178.Dv NGM_SHUTDOWN 179control message, or when the 180.Dv output 181hook has been disconnected. 182.Sh EXAMPLES 183Attach the node to an 184.Xr ng_ether 4 185node for an interface. 186If 187.Nm ng_ether 188is 189not already loaded you will need to do so. 190For example, these commands 191load the 192.Nm ng_ether 193module and attach the 194.Dv output 195hook of a new 196.Nm source 197node to 198.Dv orphans 199hook of the 200.Li bge0: 201.Nm ng_ether 202node. 203.Bd -literal -offset indent 204kldload ng_ether 205ngctl mkpeer bge0: source orphans output 206.Ed 207.Pp 208At this point the new node can be referred to as 209.Dq Li bge0:orphans . 210The 211node can be given its own name like this: 212.Pp 213.Dl "ngctl name bge0:orphans src0" 214.Pp 215After which it can be referred to as 216.Dq Li src0: . 217.Pp 218Once created, packets need to be sent to the node, the TCL net package 219can be used to generate these packets: 220.Pp 221[Sandvine specific TCL code example omitted] 222.Pp 223To feed the output of the above TCL script to the 224.Nm source 225node's 226.Dv input 227hook via 228.Xr nghook 8 : 229.Pp 230.Dl "tcl genPacket | nghook bge0:orphans input" 231.Pp 232To check that the node has queued these packets you can get the node 233statistics: 234.Bd -literal -offset indent 235ngctl msg bge0:orphans getstats 236Args: { queueOctets=64 queueFrames=1 } 237.Ed 238.Pp 239Send as many packets as required out the 240.Dv output 241hook: 242.Pp 243.Dl "ngctl msg bge0:orphans start 16" 244.Pp 245Either wait for them to be sent (periodically fetching stats if desired) 246or send the stop message: 247.Pp 248.Dl "ngctl msg bge0:orphans stop" 249.Pp 250Check the statistics (here we use 251.Ic getclrstats 252to also clear the statistics): 253.Bd -literal -offset indent 254ngctl msg bge0:orphans getclrstats 255Args: { outOctets=1024 outFrames=16 queueOctets=64 queueFrames=1 256startTime={ tv_sec=1035305880 tv_usec=758036 } endTime={ tv_sec=1035305880 257tv_usec=759041 } elapsedTime={ tv_usec=1005 } } 258.Ed 259.Pp 260The times are from 261.Vt "struct timeval" Ns s , 262the 263.Va tv_sec 264field is seconds since 265the Epoch and can be converted into a date string via TCL's [clock 266format] or via the 267.Xr date 1 268command: 269.Bd -literal -offset indent 270date -r 1035305880 271Tue Oct 22 12:58:00 EDT 2002 272.Ed 273.Sh IMPLEMENTATION NOTES 274.No ( Fx 4.4 275version) 276.Pp 277The use of 278.Xr splimp 9 279around the 280.Dv NG_SEND_DATA 281loop is important. 282Without it, 283the time taken by a single invocation of 284.Fn ng_source_intr 285becomes too 286large and the packet rate drops. 287Probably due to the NIC starting to 288send the packets right away. 289.Pp 290Copying all the packets in one loop and sending them in another inside 291of 292.Fn ng_source_send 293is done to limit how long we are at 294.Xr splimp 9 295and gave 296minor packet rate increases (~5% at 256 byte packets). 297However note 298that if there are errors in the send loop, the remaining copied packets 299are simply freed and discarded; thus we skip those packets, and ordering 300of the input queue to the output is not maintained. 301.Pp 302Calling 303.Xr timeout 9 304at the end of 305.Fn ng_source_intr 306instead of near the 307beginning is done to help avoid CPU starvation if 308.Fn ng_source_intr 309takes a long time to run. 310.Pp 311The use of 312.Xr splnet 9 313may be sub-optimal. 314It is used for synchronization 315within the node (e.g., data received on the 316.Dv input 317hook while 318.Fn ng_source_send 319is active) but we do not want to hold it too long and risk 320starving the NIC. 321.Pp 322For clarity and simplicity, debugging messages and instrumentation code 323has been removed. 324On i386 one can include 325.Aq Pa machine/cpufunc.h 326to have access to the 327.Fn rdtsc 328function to read the instruction counter at the 329start and end of 330.Fn ng_source_intr . 331Also useful is the packet count returned by 332.Fn ng_source_send . 333Do not try to report such things from within 334.Fn ng_source_intr , 335instead include the values in 336.Va sc->stats . 337.Sh SEE ALSO 338.Xr netgraph 4 , 339.Xr ng_echo 4 , 340.Xr ng_hole 4 , 341.Xr ng_tee 4 , 342.Xr ngctl 8 , 343.Xr nghook 8 344.Sh HISTORY 345The 346.Nm 347node type was implemented in 348.Fx 4.8 . 349.Sh AUTHORS 350.An Dave Chapeskie Aq dchapeskie@SANDVINE.com 351