namtrace.tex

柯老师网站上找到的

\chapter{Nam Trace}
\label{chap:namtrace}

Nam is a Tcl/Tk based animation tool that is used to visualize the ns
simulations and real world packet trace data. The first step to use nam is
to produce a nam trace file. The nam trace file should contain topology
information like nodes, links, queues, node connectivity etc as well as
packet trace information. In this chapter we shall describe the nam trace
format and simple ns commands/APIs that can be used to produce topology 
configurations and control animation in nam.

\section{Nam Trace format}
\label{sec:namtraceformat}
The C++ class Trace used for ns tracing is used for nam tracing as
well. Description of this class may be found under section
\ref{sec:tracemoncplus}. The method Trace::format() defines nam 
format used in nam trace files which are used by nam for
visualization of ns simulations. Trace class method Trace::format() is
described in section \ref{sec:traceformat} of chapter \ref{chap:trace}. If
the macro NAM\_TRACE has been defined (by default it is defined in
trace.h), then the following code is executed as part of the
Trace::format() function:

\begin{program}
        if (namChan_ != 0)
                sprintf(nwrk_,
                        "%c -t "TIME_FORMAT" -s %d -d %d -p %s -e %d -c %d
-i %d -a %d -x {%s.%s %s.%s %d %s %s}",
                        tt,
                        Scheduler::instance().clock(),
                        s,
                        d,
                        name,
                        th->size(),
                        iph->flowid(),
                        th->uid(),
                        iph->flowid(),
                        src_nodeaddr,
                        src_portaddr,
                        dst_nodeaddr,
                        dst_portaddr,
                        seqno,flags,sname);
\end{program}

Every line in a nam trace file follows this format:
\begin{verbatim}
<event-type> -t <time> ...
\end{verbatim}
Depending on the event type, there are different flags following the
time flag. 

In the following we describe nam trace event format in 7 classes:
packet, node, node mark, link/queue, agent, feature, and
miscellaneous.

\subsection{Packet Traces}

When a trace line describes a packet, 
the event type may be + (enqueue), - (dequeue), r (receive), d (drop), 
or h (hop). 
\begin{description}
\item['h'] Hop: The packet started to be transmitted on the link from
src\_addr to dst\_addr and is forwarded to the next\_hop towards its
dst\_addr.

\item['r'] Receive: The packet finished transmission and started to be
received at the destination.

\item['d] Drop: The packet was dropped from queue or link from src\_addr
to dst\_addr. Drop here doesn't distinguish between dropping from queue or
link. This is decided by the drop time.  

\item['+'] Enter queue: The packet entered the queue from src\_addr to
dst\_addr.

\item['-'] Leave queue: The packet left the queue from src\_addr to
dst\_addr.  
\end{description}

The other flags have the following meaning:
\begin{description}
\item[-t <time>] is the time the event occurred.
\item[-s <src>] is the originating node.
\item[-d <dst>] is the destination node.
\item[-p <pkt-type>] is the descriptive name of the type of packet seen.
See section \ref{sec:traceptype} for the different types of packets 
supported in \ns.
\item[-e <extent>] is the size (in bytes) of the packet.
\item[-c <conv>] is the conversation id or flow-id of that session.
\item[-i <id>] is the packet id in the conversation.
\item[-a <attr>] is the packet attribute, which is currently used as color
id. 
\item[-x <src-na.pa> <dst-sa.na> <seq> <flags> <sname>] is taken from
ns-traces and it gives the source and destination node and port
addresses, sequence number, flags (if any) and the type of message.
For example \code{ -x {0.1 -2147483648.0 -1 ------- SRM_SESS} } denotes an
SRM message being sent from node 0 (port 1).
\end{description}

In addition to the above nam format for packet events there are nam traces
that provide information about nam version, hierarchical
addressing structure, node/link/queue states, node-marks, protocol states,
color and annotations. These nam trace outputs typically have the
following letters (or tags) as their first field and they represent the
following trace types: 
n (node state), m (node marking), l (link state), q (queue), a 
(protocol state), f (protocol state variable),
V (nam version), A (hierarchy information), c (nam color) and v
(annotations).

\subsection{Node state}

The nam trace format defining node state is:\\
\code{n -t <time> -a <src-addr> -s <src-id> -S <state> -v <shape> -c <color> -i <l-color> -o <color>}\\
"n" denotes the node state. Flags "-t" indicates time and "-a" and "-s"
denotes the node address and id. "-S" gives the node state transition.
The possible values: 
\begin{itemize}
\item UP, DOWN indicates node recovery and failure.
\item COLOR indicates node color change. If COLOR is given, a
  following {\tt -c <color>} is expected which gives the new color
  value. Also, flag {\tt -o} is expected so that backtracing can
  restore the old color of a node. 
\item DLABEL indicates addition of label to node. If DLABEL is
  given, a following -l <old-label> -L <new-label> is expected that gives
  the old-label, if any (for backtracing) and current label. Shape gives
  the node shape. The color of a node label can be specified via the
  {\tt -i} flag. 
\end{itemize}
As an example, the line\\
\code{n -t * -a 4 -s 4 -S UP -v circle -c tan -i tan}\\
defines a node with address and id of 4 that has the shape of a
circle, and color of tan and label-color (-i) of tan.

\subsection{Node Marking}

Node marks are colored concentric circles around nodes. 
They are created by:
\begin{verbatim}
m -t <time> -n <mark name> -s <node> -c <color> -h <shape> -o <color>
\end{verbatim}
and can be deleted by:
\begin{verbatim}
m -t <time> -n <mark name> -s <node> -X
\end{verbatim}
Note that once created, a node mark cannot change its shape. The possible
choices for shapes are, circle, square, and hexagon. They are defined as 
lower-case strings exactly as above. A nam trace showing node mark is:
\begin{verbatim}
m -t 4 -s 0 -n m1 -c blue -h circle
\end{verbatim}
indicating node 0 is marked with a blue circle at time 4.0. The name of
the mark is m1.

\subsection{Link/Queue State}

The nam trace for link and queue states are given by (respectively):
\begin{verbatim}
l -t <time> -s <src> -d <dst> -S <state> -c <color> -o orientation -r <bw> -D <delay>
q -t <time> -s <src> -d <dst> -a <attr>
\end{verbatim}
where {\tt <state>} and {\tt <color>} indicate the same attributes
(and the same format) as described above in the node state traces. 
Flag {\tt -o} gives the link orientation (angle between link and
horizontal). 
Flags {\tt -r} and {\tt -D} give the bandwidth (in Mb) and delay (in
ms), respectively.
An example of a link trace is:
\begin{verbatim}
l -t * -s 0 -d 1 -S UP -r 1500000 -D 0.01 -c black -o right
\end{verbatim}
Queues are visualized in nam as a straight line along which packets
(small squares) are packed.
In queue trace events, flag {\tt -a} specifies the orientation of the
line of the queue (angle between the queue line and the horizontal
line, counter-clockwise). 
For example, the following line specifies a queue that grows
vertically upwards with respect to the screen (here {\tt 0.5} means
the angle of the queue line is $\frac{\pi}{2}$):
\begin{verbatim}
q -t * -s 0 -d 1 -a 0.5
\end{verbatim}

\subsection{Agent Tracing}

Agent trace events are used to visualize protocol state.
They are always associated with nodes. 
An agent event has a name, which is a {\it unique} identifier of the
agent. 
An agent is shown as a square with its name inside, and a line link
the square to its associated node 

Agent events are constructed using the following format:
\begin{verbatim}
a -t <time> -n <agent name> -s <src> 
\end{verbatim}
Because in \ns, agents may be detached from nodes, an agent may be 
``destructed'' in nam with:
\begin{verbatim}
a -t <time> -n <agent name> -s <src> -X
\end{verbatim}
For example, the following nam trace line creates an agent named {\tt
  srm(5)} associated with node 5 at time 0:
\begin{verbatim}
a -t 0.00000000000000000 -s 5 -n srm(5)
\end{verbatim}

\subsection{Variable Tracing}

To visualize state variables associated with a protocol agent, we use
the feature trace events.
% three types of features: timers, lists and simple variable
Currently we allow a feature to display a simple variable, i.e., a