1.1 --- a/Makefile	Mon Apr 06 21:16:26 2009 +0200
     1.2 +++ b/Makefile	Mon Apr 06 22:43:46 2009 +0200
     1.3 @@ -19,12 +19,14 @@
     1.4  device-channel.dia \
     1.5  WifiArchitecture.dia \
     1.6  internet-stack.dia \
     1.7 -attribute-namespace.dia
     1.8 +attribute-namespace.dia \
     1.9 +trace-source-sink.dia
    1.10  PDF_SOURCES=test-random-variable.pdf
    1.11  PNG_SOURCES=\
    1.12  ns-3-doxygen.png \
    1.13  gtk-config-store.png \
    1.14 -attribute-doxygen.png
    1.15 +attribute-doxygen.png \
    1.16 +trace-source-doxygen.png
    1.17  
    1.18  DIA_PDFS=$(addsuffix .pdf,$(basename $(DIA_SOURCES)))
    1.19  PNG_PDFS=$(addsuffix .pdf,$(basename $(PNG_SOURCES)))

     2.1 Binary file trace-source-doxygen.png has changed

     3.1 Binary file trace-source-sink.dia has changed

     4.1 --- a/tutorial.tex	Mon Apr 06 21:16:26 2009 +0200
     4.2 +++ b/tutorial.tex	Mon Apr 06 22:43:46 2009 +0200
     4.3 @@ -909,5 +909,186 @@
     4.4  
     4.5  \end{frame}
     4.6  
     4.7 +\begin{frame}[fragile]{Tracing}
     4.8 +
     4.9 +Setup simple ascii and pcap tracing:
    4.10 +{\footnotesize
    4.11 +\begin{block}{}
    4.12 +\begin{verbatim}
    4.13 +std::ofstream ascii;
    4.14 +ascii.open ("wns3-helper.tr");
    4.15 +CsmaHelper::EnableAsciiAll (ascii);
    4.16 +CsmaHelper::EnablePcapAll ("wns3-helper");
    4.17 +YansWifiPhyHelper::EnablePcapAll ("wsn3-helper");
    4.18 +\end{verbatim}
    4.19 +\end{block}
    4.20 +}
    4.21 +
    4.22 +\end{frame}
    4.23 +
    4.24 +\begin{frame}[fragile]{Tracing requirements}
    4.25 +
    4.26 +\begin{itemize}
    4.27 +\item Tracing is a structured form of simulation output
    4.28 +\item Example (from ns-2):
    4.29 +\begin{verbatim}
    4.30 ++ 1.84375 0 2 cbr 210 ------- 0 0.0 3.1 225 610
    4.31 +- 1.84375 0 2 cbr 210 ------- 0 0.0 3.1 225 610
    4.32 +r 1.84471 2 1 cbr 210 ------- 1 3.0 1.0 195 600
    4.33 +r 1.84566 2 0 ack 40 ------- 2 3.2 0.1 82 602
    4.34 ++ 1.84566 0 2 tcp 1000 ------- 2 0.1 3.2 102 611
    4.35 +\end{verbatim}
    4.36 +\item Problem: tracing needs vary widely
    4.37 +\begin{itemize}
    4.38 +\item Would like to change tracing output without
    4.39 +editing the core
    4.40 +\item Would like to support multiple outputs
    4.41 +\end{itemize}
    4.42 +\end{itemize}
    4.43 +
    4.44 +\end{frame}
    4.45 +
    4.46 +\begin{frame}{Tracing overview}
    4.47 +
    4.48 +\begin{itemize}
    4.49 +\item Simulator provides a set of pre-configured
    4.50 +  trace sources
    4.51 +\begin{itemize}
    4.52 +\item Users may edit the core to add their own
    4.53 +\end{itemize}
    4.54 +\item Users provide trace sinks and attach to the
    4.55 +  trace source
    4.56 +\begin{itemize}
    4.57 +\item Simulator core provides a few examples for
    4.58 +     common cases
    4.59 +\end{itemize}
    4.60 +\item Multiple trace sources can connect to a
    4.61 +  trace sink
    4.62 +\end{itemize}
    4.63 +
    4.64 +\end{frame}
    4.65 +
    4.66 +\begin{frame}{The ns-3 tracing model}
    4.67 +
    4.68 +Decouple trace sources from trace sinks:
    4.69 +\\
    4.70 +\vspace{1cm}
    4.71 +\includegraphics[width=9cm]{trace-source-sink}
    4.72 +\\
    4.73 +\vspace{1cm}
    4.74 +Benefit: Customizable trace sinks
    4.75 +
    4.76 +\end{frame}
    4.77 +
    4.78 +\begin{frame}{Ns-3 trace sources}
    4.79 +
    4.80 +\begin{itemize}
    4.81 +\item Various trace sources (e.g., packet receptions, state
    4.82 +  machine transitions) are plumbed through the system
    4.83 +\item Organized with the rest of the attribute system
    4.84 +\end{itemize}
    4.85 +
    4.86 +\includegraphics[width=9cm]{trace-source-doxygen}
    4.87 +
    4.88 +\end{frame}
    4.89 +
    4.90 +\begin{frame}{Multiple levels of tracing}
    4.91 +
    4.92 +\begin{itemize}
    4.93 +\item High-level: use a helper to hook
    4.94 +a predefined trace sink to a trace source and
    4.95 +generate simple tracing output (ascii, pcap)
    4.96 +\item Mid-level: hook a special trace sink
    4.97 +to an existing trace source to generate
    4.98 +adhoc tracing
    4.99 +\item Low-level: add a new trace source
   4.100 +and connect it to a special trace sink
   4.101 +\end{itemize}
   4.102 +
   4.103 +\end{frame}
   4.104 +
   4.105 +\begin{frame}[fragile]{High-level tracing}
   4.106 +
   4.107 +\begin{itemize}
   4.108 +\item Use predefined trace sinks in helpers
   4.109 +\item All helpers provide ascii and pcap trace sinks
   4.110 +\end{itemize}
   4.111 +{\footnotesize
   4.112 +\begin{block}{}
   4.113 +\begin{verbatim}
   4.114 +CsmaHelper::EnablePcap ("filename", nodeid, deviceid);
   4.115 +std::ofstream os;
   4.116 +os.open ("filename.tr");
   4.117 +CsmaHelper::EnableAscii (os, nodeid, deviceid);
   4.118 +\end{verbatim}
   4.119 +\end{block}
   4.120 +}
   4.121 +
   4.122 +\end{frame}
   4.123 +
   4.124 +\begin{frame}[fragile]{Mid-level tracing}
   4.125 +
   4.126 +\begin{itemize}
   4.127 +\item Provide a new trace sink
   4.128 +\item Use attribute/trace namespace to connect trace sink and source
   4.129 +\end{itemize}
   4.130 +
   4.131 +{\footnotesize
   4.132 +\begin{block}{}
   4.133 +\begin{verbatim}
   4.134 +void
   4.135 +DevTxTrace (std::string context, 
   4.136 +            Ptr<const Packet> p, Mac48Address address)
   4.137 +{
   4.138 +  std::cout << " TX to=" << address << " p: " << *p << std::endl;
   4.139 +}
   4.140 +Config::Connect ("/NodeList/*/DeviceList/*/Mac/MacTx", 
   4.141 +                 MakeCallback (&DevTxTrace));
   4.142 +\end{verbatim}
   4.143 +\end{block}
   4.144 +}
   4.145 +
   4.146 +\end{frame}
   4.147 +
   4.148 +\begin{frame}[fragile]{Using mid-level tracing for pcap output}
   4.149 +
   4.150 +The trace sink:
   4.151 +{\footnotesize
   4.152 +\begin{block}{}
   4.153 +\begin{verbatim}
   4.154 +static void PcapSnifferEvent (Ptr<PcapWriter> writer, 
   4.155 +                              Ptr<const Packet> packet)
   4.156 +{
   4.157 +  writer->WritePacket (packet);
   4.158 +}
   4.159 +\end{verbatim}
   4.160 +\end{block}
   4.161 +}
   4.162 +
   4.163 +Prepare the pcap output:
   4.164 +{\footnotesize
   4.165 +\begin{block}{}
   4.166 +\begin{verbatim}
   4.167 +oss << filename << "-" << nodeid << "-" << deviceid << ".pcap";
   4.168 +Ptr<PcapWriter> pcap = ::ns3::Create<PcapWriter> ();
   4.169 +pcap->Open (oss.str ());
   4.170 +pcap->WriteWifiHeader ();
   4.171 +\end{verbatim}
   4.172 +\end{block}
   4.173 +}
   4.174 +
   4.175 +Finally, connect the trace sink to the trace source:
   4.176 +{\footnotesize
   4.177 +\begin{block}{}
   4.178 +\begin{verbatim}
   4.179 +oss << "/NodeList/" << nodeid << "/DeviceList/" << deviceid;
   4.180 +oss << "/$ns3::WifiNetDevice/Phy/PromiscSniffer";
   4.181 +Config::ConnectWithoutContext (oss.str (), 
   4.182 +                MakeBoundCallback (&PcapSnifferEvent, pcap));
   4.183 +\end{verbatim}
   4.184 +\end{block}
   4.185 +}
   4.186 +
   4.187 +\end{frame}
   4.188  
   4.189  \end{document}