share/man/man4/ng_source.4

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