system/freebsd-src
system/freebsd-src
1
0
Fork 0
mirror of https://github.com/freebsd/freebsd-src synced 2024-10-18 22:33:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

mdoc(7) police: overhaul.

Browse source 
Approved by:	re
This commit is contained in:
Ruslan Ermilov 2002-12-12 15:25:56 +00:00
parent a7348c92db
commit 76648c1f93
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=107782
1 changed files with 216 additions and 132 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

348
share/man/man4/ng_source.4
View file

@ -1,4 +1,3 @@
.\" ng_source.4
.\" Copyright 2002 Sandvine Inc.
.\" All rights reserved.
.\"
@ -42,220 +41,305 @@
.Sh SYNOPSIS
.In netgraph/ng_source.h
.Sh DESCRIPTION
The
The
.Nm source
node acts as a source of packets according to the parameters set up
using control messages and input packets.
The 'output' hook must also be connected to a node that responds to the
.Em NGM_ETHER_COOKIE
/
.Em NGM_ETHER_GET_IFINDEX
message (e.g. an
ng_ether
The
.Dv output
hook must also be connected to a node that responds to the
.Dv NGM_ETHER_COOKIE Ns / Ns
.Dv NGM_ETHER_GET_IFINDEX
message (e.g., an
.Xr ng_ether 4
node).
node type silently discards all data and control messages it receives.
This type is used for testing and debugging.
.Pp
The operation of the node is as follows:
.Pp
.Bl -bullet -compact -offset 2n
.Bl -bullet
.It
Packets received on the 'input' hook are queued internally.
Packets received on the
.Dv input
hook are queued internally.
.It
On recpetion of a NGM_SOURCE_START message the node starts sending
the queued packets out the 'output' hook on every clock tick as fast
On reception of a
.Dv NGM_SOURCE_START
message the node starts sending
the queued packets out the
.Dv output
hook on every clock tick as fast
as the connect interface will take them.
.It
While active, on every clock tick the node checks the available space
in the ifqueue of the interface connected to the output hook and sends
that many packets out it's output hook.
in the
.Va ifqueue
of the interface connected to the output hook and sends
that many packets out its
.Dv output
hook.
.It
Once the number of packets indicated in the start message have been
sent, or on reception of a stop message, the node stops sending data.
.El
.Sh HOOKS
The
The
.Nm source
node has two hooks: 'input' and 'output'. The 'output'
node has two hooks:
.Dv input
and
.Dv output .
The
.Dv output
hook must remain connected, its disconnection will shutdown the node.
.Sh CONTROL MESSAGES
This node type supports the generic control messages as well as the following,
which must be sent with the
.Em NGM_SOURCE_COOKIE
.Dv NGM_SOURCE_COOKIE
attached.
.Bl -tag -width ######
.It NGM_SOURCE_GET_STATS
.Bl -tag -width #########
.It "getstats":
.Bl -tag -width indent
.It Dv NGM_SOURCE_GET_STATS Pq Ic getstats
Returns a structure containing the following fields:
.\".Bl -bullet -compact -offset 2n
.Bl -tag -width #####
.It outOctets:
The number of octets/bytes sent out the 'output' hook.
.It outFrames:
The number of frames/packets sent out the 'output' hook.
.It queueOctets:
The number of octets queued from the 'input' hook.
.It queueFrames:
The number of frames queued from the 'input' hook.
.It startTime:
The time the last start message was recieved.
.It endTime:
The time the last end message was recieved or
.Bl -tag -width indent
.It Va outOctets
The number of octets/bytes sent out the
.Dv output
hook.
.It Va outFrames
The number of frames/packets sent out the
.Dv output
hook.
.It Va queueOctets
The number of octets queued from the
.Dv input
hook.
.It Va queueFrames
The number of frames queued from the
.Dv input
hook.
.It Va startTime
The time the last start message was received.
.It Va endTime
The time the last end message was received or
the output packet count was reached.
.It elapsedTime:
Either endTime-startTime or current time - startTime.
.It Va elapsedTime
Either
.Va endTime Li \- Va startTime
or current time
\-
.Va startTime .
.El
.El
.It NGM_SOURCE_CLR_STATS
"clrstats":
Clears and resets the statistics returned by getstats (except
queueOctects and queueFrames).
.It NGM_SOURCE_GETCLR_STATS
"getclrstats":
As getstats but clears the statistics at the same time.
.It NGM_SOURCE_START
"start":
.Bl -bullet -compact -offset 2n
.It Dv NGM_SOURCE_CLR_STATS Pq Ic clrstats
Clears and resets the statistics returned by
.Ic getstats
(except
.Va queueOctets
and
.Va queueFrames ) .
.It Dv NGM_SOURCE_GETCLR_STATS Pq Ic getclrstats
As
.Ic getstats
but clears the statistics at the same time.
.It Dv NGM_SOURCE_START Pq Ic start
.Bl -bullet
.It
Takes a single u_int64_t parameter which is the number of packets to
Takes a single
.Vt u_int64_t
parameter which is the number of packets to
send before stopping.
.It
Starts sending the queued packets out the output hook.
.It
The output hook must be connected or EINVAL is returned.
The output hook must be connected or
.Er EINVAL
is returned.
.It
The node connected to the output hook must respond to
.Em NGM_ETHER_GET_IFINDEX
which is used to get the ifqueue of the attached
interface.
.Dv NGM_ETHER_GET_IFINDEX
which is used to get the
.Va ifqueue
of the attached interface.
.It
.Em NGM_ETHER_SET_AUTOSRC
is sent to the node connected to the output hook
.Dv NGM_ETHER_SET_AUTOSRC
is sent to the node connected to the
.Dv output
hook
to turn off automatic ethernet source address overwriting (any errors
from this message are ignored).
.El
.It NGM_SOURCE_STOP
"stop":
.It Dv NGM_SOURCE_STOP Pq Ic stop
Stops the node if it is active.
.It NGM_SOURCE_CLR_DATA
"clrdata":
Clears the packets queued from the 'input' hook.
.It Dv NGM_SOURCE_CLR_DATA Pq Ic clrdata
Clears the packets queued from the
.Dv input
hook.
.El
.Sh SHUTDOWN
This node shuts down upon receipt of a
.Dv NGM_SHUTDOWN
control message, or when the
.Em output
control message, or when the
.Dv output
hook has been disconnected.
.Sh EXAMPLE
Build and install the node to /modules (or load it anually).
.Bd -literal -offset 0n
$ make obj
$ make depend
$ make
$ make install
.Sh EXAMPLES
Attach the node to an
.Xr ng_ether 4
node for an interface.
If
.Nm ng_ether
is
not already loaded you will need to do so.
For example, these commands
load the
.Nm ng_ether
module and attach the
.Dv output
hook of a new
.Nm source
node to
.Dv orphans
hook of the
.Li bge0:
.Nm ng_ether
node.
.Bd -literal -offset indent
kldload ng_ether
ngctl mkpeer bge0: source orphans output
.Ed
.Pp
Attach the node to an ng_ether node for an interface. If ng_ether is
not already loaded you'll need to do so. For example these commands
load the ng_ether module and attach the output hook of a new source node
to orphans hook of the bge0: ng_ether node.
.Bd -literal -offset 0n
$ kldload ng_ether
$ ngctl mkpeer bge0: source orphans output
.Ed
At this point the new node can be referred to as
.Dq Li bge0:orphans .
The
node can be given its own name like this:
.Pp
At this point the new node can be refered to as "bge0:orphans". The
node can be given it's own name like this:
.Bd -literal -offset 0n
$ ngctl name bge0:orphans src0
.Ed
.Dl "ngctl name bge0:orphans src0"
.Pp
After which it can be refered to as "src0:".
After which it can be referred to as
.Dq Li src0: .
.Pp
Once created packets need to be sent to the node, the TCL net package
Once created, packets need to be sent to the node, the TCL net package
can be used to generate these packets:
.Pp
[Sandvine specific TCL code example omitted]
.Pp
To feed the output of the above TCL script to the ng_source node's input
hook via nghook:
.Bd -literal -offset 0n
$ tcl genPacket | nghook bge0:orphans input
.Ed
To feed the output of the above TCL script to the
.Nm source
node's
.Dv input
hook via
.Xr nghook 8 :
.Pp
.Dl "tcl genPacket | nghook bge0:orphans input"
.Pp
To check that the node has queued these packets you can get the node
statistics:
.Bd -literal -offset 0n
$ ngctl msg bge0:orphans getstats
.Bd -literal -offset indent
ngctl msg bge0:orphans getstats
Args: { queueOctets=64 queueFrames=1 }
.Ed
.Pp
Send as many packets as required out the output hook:
.Bd -literal -offset 0n
$ ngctl msg bge0:orphans start 16
.Ed
Send as many packets as required out the
.Dv output
hook:
.Pp
Either wait for them to be sent (periodicly fetching stats if desired)
.Dl "ngctl msg bge0:orphans start 16"
.Pp
Either wait for them to be sent (periodically fetching stats if desired)
or send the stop message:
.Bd -literal -offset 0n
$ ngctl msg bge0:orphans stop
.Ed
.Pp
Check the statistics (here we use getclrstats to also clear the
statistics):
.Bd -literal -offset 0n
$ ngctl msg bge0:orphans getclrstats
.Dl "ngctl msg bge0:orphans stop"
.Pp
Check the statistics (here we use
.Ic getclrstats
to also clear the statistics):
.Bd -literal -offset indent
ngctl msg bge0:orphans getclrstats
Args: { outOctets=1024 outFrames=16 queueOctets=64 queueFrames=1
startTime={ tv_sec=1035305880 tv_usec=758036 } endTime={ tv_sec=1035305880
tv_usec=759041 } elapsedTime={ tv_usec=1005 } }
.Ed
.Pp
The times are from "struct timeval"s, the tv_sec field is seconds since
the epoch and can be converted into a date string via TCL's [clock
format] or via the UNIX date command:
.Bd -literal -offset 0n
$ date -r 1035305880
The times are from
.Vt "struct timeval" Ns s ,
the
.Va tv_sec
field is seconds since
the Epoch and can be converted into a date string via TCL's [clock
format] or via the
.Xr date 1
command:
.Bd -literal -offset indent
date -r 1035305880
Tue Oct 22 12:58:00 EDT 2002
.Ed
.Pp
.Sh IMPLEMENTATION NOTES
(FreeBSD 4.4 version)
.No ( Fx 4.4
version)
.Pp
The use of splimp around the NG_SEND_DATA loop is important. Without
it the time taken by a single invocation of ng_source_intr becomes too
large and the packet rate drops. Probably due to the NIC starting to
The use of
.Xr splimp 9
around the
.Dv NG_SEND_DATA
loop is important.
Without it,
the time taken by a single invocation of
.Fn ng_source_intr
becomes too
large and the packet rate drops.
Probably due to the NIC starting to
send the packets right away.
.Pp
Copying all the packets in one loop and sending them in another inside
of ng_source_send is done to limit how long we're at splimp and gave
minor packet rate increases (~5% at 256 byte packets). However note
that if there are errors in the send loop the remaining copied packets
are simply freed and discarded thus we skip those packets and ordering
of
.Fn ng_source_send
is done to limit how long we are at
.Xr splimp 9
and gave
minor packet rate increases (~5% at 256 byte packets).
However note
that if there are errors in the send loop, the remaining copied packets
are simply freed and discarded; thus we skip those packets, and ordering
of the input queue to the output is not maintained.
.Pp
Calling timeout(9) at the end of ng_source_intr instead of near the
begining is done to help avoid CPU starvaion if ng_source_intr takes a
long time to run.
Calling
.Xr timeout 9
at the end of
.Fn ng_source_intr
instead of near the
beginning is done to help avoid CPU starvation if
.Fn ng_source_intr
takes a long time to run.
.Pp
The use of splnet may be sub-optimal. It's used for syncronization
within the node (e.g. data recieved on the input hook while
ng_source_send is active) but we don't want to hold it too long and risk
The use of
.Xr splnet 9
may be sub-optimal.
It is used for synchronization
within the node (e.g., data received on the
.Dv input
hook while
.Fn ng_source_send
is active) but we do not want to hold it too long and risk
starving the NIC.
.Pp
For clarity and simplicity debugging messages and instrumentation code
has been removed. On i386 one can include machine/cpufunc.h to have
access to the rdtsc() function to read the instruction counter at the
start and end of ng_source_intr. Also useful is the packet count
returned by ng_source_send. Do not try to report such things from
within ng_source_intr, instead include the values in sc->stats.
For clarity and simplicity, debugging messages and instrumentation code
has been removed.
On i386 one can include
.Aq Pa machine/cpufunc.h
to have access to the
.Fn rdtsc
function to read the instruction counter at the
start and end of
.Fn ng_source_intr .
Also useful is the packet count returned by
.Fn ng_source_send .
Do not try to report such things from within
.Fn ng_source_intr ,
instead include the values in
.Va sc->stats .
.Sh SEE ALSO
.Xr netgraph 4 ,
.Xr ng_echo 4 ,
.Xr ng_hole 4 ,
.Xr ng_tee 4 ,
.Xr ngctl 8
.Xr ngctl 8 ,
.Xr nghook 8
.Sh HISTORY
The