| ng_source.4 (141350) | ng_source.4 (144675) |
|---|---|
| 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 --- 16 unchanged lines hidden (view full) --- 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> | 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 --- 16 unchanged lines hidden (view full) --- 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: head/share/man/man4/ng_source.4 141350 2005-02-05 11:31:31Z ru $ | 33.\" $FreeBSD: head/share/man/man4/ng_source.4 144675 2005-04-05 17:27:36Z glebius $ |
| 34.\" | 34.\" |
| 35.Dd November 1, 2002 | 35.Dd April 5, 2005 |
| 36.Dt NG_SOURCE 4 37.Os 38.Sh NAME 39.Nm ng_source | 36.Dt NG_SOURCE 4 37.Os 38.Sh NAME 39.Nm ng_source |
| 40.Nd netgraph discard node type | 40.Nd netgraph node for traffic generation |
| 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 | 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 | 50.Nm 51node type is used primarily for testing and benchmarking. |
| 85.Sh HOOKS 86The 87.Nm source 88node has two hooks: | 52.Sh HOOKS 53The 54.Nm source 55node has two hooks: |
| 89.Dv input | 56.Va input |
| 90and | 57and |
| 91.Dv output . | 58.Va output . |
| 92The | 59The |
| 93.Dv output | 60.Va output |
| 94hook must remain connected, its disconnection will shutdown the node. | 61hook must remain connected, its disconnection will shutdown the node. |
| 62.Sh OPERATION 63The operation of the node is as follows. 64Packets received on the 65.Va input 66hook are queued internally. 67When 68.Va output 69hook is connected, 70.Nm 71node assumes that its neighbour node is of 72.Xr ng_ether 73node type. 74The neighbor is queried for its interface name. 75.Nm 76node then uses queue of the interface for its evil purposes. 77.Nm 78node also disables 79.Va autosrc 80option on neighbour 81.Xr ng_ether 82node. 83If interface name can't be obtained automatically, it should 84be configured explicitly with help of 85.Dv NGM_SOURCE_SETIFACE 86control message, and 87.Va autosrc 88should be turned off on 89.Xr ng_ether 90node manually. 91.Pp 92Once interface is configured, upon receival of 93.Dv NGM_SOURCE_START 94control message the node starts sending 95the previously queued packets out the 96.Va output 97hook on every clock tick as fast 98as the connected interface will take them. 99While active, on every clock tick the node checks the available space 100in the interface queue and sends that many packets out its 101.Va output 102hook. 103Once the number of packets indicated in the start message have been 104sent, or upon reception of a stop message, the node stops sending data. |
|
| 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: --- 33 unchanged lines hidden (view full) --- 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 | 105.Sh CONTROL MESSAGES 106This node type supports the generic control messages as well as the following, 107which must be sent with the 108.Dv NGM_SOURCE_COOKIE 109attached. 110.Bl -tag -width indent 111.It Dv NGM_SOURCE_GET_STATS Pq Ic getstats 112Returns a structure containing the following fields: --- 33 unchanged lines hidden (view full) --- 146.Va queueOctets 147and 148.Va queueFrames ) . 149.It Dv NGM_SOURCE_GETCLR_STATS Pq Ic getclrstats 150As 151.Ic getstats 152but clears the statistics at the same time. 153.It Dv NGM_SOURCE_START Pq Ic start |
| 144.Bl -bullet 145.It 146Takes a single 147.Vt u_int64_t | 154This message requires a single 155.Vt uint64_t |
| 148parameter which is the number of packets to 149send before stopping. | 156parameter which is the number of packets to 157send 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 | 158Node starts sending the queued packets out the output hook. 159The output hook must be connected and node must have 160interface configured. |
| 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. | 161.It Dv NGM_SOURCE_STOP Pq Ic stop 162Stops the node if it is active. 163.It Dv NGM_SOURCE_CLR_DATA Pq Ic clrdata 164Clears the packets queued from the 165.Dv input 166hook. |
| 167.It Dv NGM_SOURCE_SETIFACE Pq Ic setiface 168This message requires a string argument - name of the interface 169to be configured. |
|
| 176.El 177.Sh SHUTDOWN 178This node shuts down upon receipt of a 179.Dv NGM_SHUTDOWN | 170.El 171.Sh SHUTDOWN 172This node shuts down upon receipt of a 173.Dv NGM_SHUTDOWN |
| 180control message, or when the 181.Dv output | 174control message, when all hooks has been disconnected, or when the 175.Va output |
| 182hook has been disconnected. | 176hook 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. --- 97 unchanged lines hidden --- | 177.Sh EXAMPLES 178Attach the node to an 179.Xr ng_ether 4 180node for an interface. 181If 182.Nm ng_ether 183is 184not already loaded you will need to do so. --- 97 unchanged lines hidden --- |