doc/tutorial/tweaking.texi
author Tom Henderson <tomh@tomh.org>
Wed, 22 Oct 2008 22:13:22 -0700
changeset 3771 21f40ccb03b3
parent 3382 d5f8e5fae1c6
child 4032 2b675a0b3b94
permissions -rw-r--r--
tutorial typos fixed (bug 379)
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
     1
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
     2
@c ========================================================================
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
     3
@c Begin document body here
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
     4
@c ========================================================================
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
     5
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
     6
@c ========================================================================
3340
0b45016b6097 Table of content fixes
Tom Henderson <tomh@tomh.org>
parents: 3332
diff changeset
     7
@c PART:  Tweaking ns-3
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
     8
@c ========================================================================
3340
0b45016b6097 Table of content fixes
Tom Henderson <tomh@tomh.org>
parents: 3332
diff changeset
     9
@c The below chapters are under the major heading "Tweaking ns-3"
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    10
@c This is similar to the Latex \part command
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    11
@c
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    12
@c ========================================================================
3340
0b45016b6097 Table of content fixes
Tom Henderson <tomh@tomh.org>
parents: 3332
diff changeset
    13
@c Tweaking ns-3
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    14
@c ========================================================================
3340
0b45016b6097 Table of content fixes
Tom Henderson <tomh@tomh.org>
parents: 3332
diff changeset
    15
@node Tweaking ns-3
0b45016b6097 Table of content fixes
Tom Henderson <tomh@tomh.org>
parents: 3332
diff changeset
    16
@chapter Tweaking ns-3
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    17
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    18
@menu
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    19
* Using the Logging Module::
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    20
* Using Command Line Arguments::
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    21
* Using the Tracing System::
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    22
@end menu
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    23
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    24
@c ========================================================================
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    25
@c Using the Logging Module
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    26
@c ========================================================================
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    27
@node Using the Logging Module
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    28
@section Using the Logging Module
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    29
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    30
@cindex logging
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
    31
We have already taken a brief look at the @command{ns-3} logging module while
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
    32
going over the @code{first.cc} script.  We will now take a closer look and 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
    33
see what kind of use-cases the logging subsystem was designed to cover.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    34
3342
8762b90e6f7e formatting nits on the Tweaking chapter
Tom Henderson <tomh@tomh.org>
parents: 3340
diff changeset
    35
@node Logging Overview
8762b90e6f7e formatting nits on the Tweaking chapter
Tom Henderson <tomh@tomh.org>
parents: 3340
diff changeset
    36
@subsection Logging Overview
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
    37
Many large systems support some kind of message logging facility, and 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
    38
@command{ns-3} is not an exception.  In some cases, only error messages are 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
    39
logged to the ``operator console'' (which is typically @code{stderr} in Unix-
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
    40
based systems).  In other systems, warning messages may be output as well as 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
    41
more detailed informational messages.  In some cases, logging facilities are 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
    42
used to output debug messages which can quickly turn the output into a blur.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    43
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
    44
@command{Ns-3} takes the view that all of these verbosity levels are useful 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
    45
and we provide a selectable, multi-level approach to message logging.  Logging
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
    46
can be disabled completely, enabled on a component-by-component basis, or
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
    47
enabled globally; and it provides selectable verbosity levels.  The 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
    48
@command{ns-3} log module provides a straightforward, relatively easy to use
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
    49
way to get useful information out of your simulation.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    50
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    51
You should understand that we do provide a general purpose mechanism --- 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    52
tracing --- to get data out of your models which should be preferred for 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    53
simulation output (see the tutorial section Using the Tracing System for
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    54
more details on our tracing system).  Logging should be preferred for 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    55
debugging information, warnings, error messages, or any time you want to 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    56
easily get a quick message out of your scripts or models.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    57
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    58
There are currently seven levels of log messages of increasing verbosity
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    59
defined in the system.  
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    60
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    61
@itemize @bullet
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    62
@item NS_LOG_ERROR --- Log error messages;
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    63
@item NS_LOG_WARN --- Log warning messages;
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    64
@item NS_LOG_DEBUG --- Log relatively rare, ad-hoc debugging messages;
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    65
@item NS_LOG_INFO --- Log informational messages about program progress;
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    66
@item NS_LOG_FUNCTION --- Log a message describing each function called;
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
    67
@item NS_LOG_LOGIC -- Log messages describing logical flow within a function;
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    68
@item NS_LOG_ALL --- Log everything.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    69
@end itemize
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    70
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    71
We also provide an unconditional logging level that is always displayed,
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    72
irrespective of logging levels or component selection.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    73
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    74
@itemize @bullet
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
    75
@item NS_LOG_UNCOND -- Log the associated message unconditionally.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    76
@end itemize
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    77
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
    78
Each level can be requested singly or cumulatively; and logging can be set 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
    79
up using a shell environment variable (NS_LOG) or by logging system function 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
    80
call.  As was seen earlier in the tutorial, the logging system has Doxygen 
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
    81
documentation and now would be a good time to peruse the Logging Module 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
    82
documentation if you have not done so.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    83
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
    84
Now that you have read the documentation in great detail, let's use some of
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
    85
that knowledge to get some interesting information out of the @code{first.cc}
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
    86
example script you have already built.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    87
3342
8762b90e6f7e formatting nits on the Tweaking chapter
Tom Henderson <tomh@tomh.org>
parents: 3340
diff changeset
    88
@node Enabling Logging
3356
be3532c51a37 Tutorial TOC tweaks
Craig Dowell <craigdo@ee.washington.edu>
parents: 3355
diff changeset
    89
@subsection Enabling Logging
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    90
@cindex NS_LOG
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
    91
Let's use the NS_LOG environment variable to turn on some more logging, but
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
    92
to get our bearings, go ahead and run the script just as you did previously,
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    93
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    94
@verbatim
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
    95
  ~/repos/ns-3-dev > ./waf --run scratch/first
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
    96
  Entering directory `/home/craigdo/repos/ns-3-dev/build'
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    97
  Compilation finished successfully
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    98
  Sent 1024 bytes to 10.1.1.2
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
    99
  Received 1024 bytes from 10.1.1.1
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   100
  Received 1024 bytes from 10.1.1.2
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   101
  ~/repos/ns-3-dev >
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   102
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   103
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   104
It turns out that the ``Sent'' and ``Received'' messages are actually logging
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   105
messages from the @code{UdpEchoClientApplication} and 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   106
@code{UdpEchoServerApplication}.  We can ask the client application, for 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   107
example, to print more information by setting its logging level via the 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   108
NS_LOG environment variable.  
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   109
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   110
I am going to assume from here on that are using an sh-like shell that uses 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   111
the``VARIABLE=value'' syntax.  If you are using a csh-like shell, then you 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   112
will have to convert my examples to the ``setenv VARIABLE value'' syntax 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   113
required by those shells.
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   114
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   115
Right now, the UDP echo client application is responding to the following line
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   116
of code in @code{first.cc},
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   117
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   118
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   119
  LogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO);
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   120
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   121
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   122
This line of code enables the @code{LOG_LEVEL_INFO} level of logging.  When 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   123
we pass a logging level flag, we are actually enabling the given level and
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   124
all lower levels.  In this case, we have enabled @code{NS_LOG_INFO},
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   125
@code{NS_LOG_DEBUG}, @code{NS_LOG_WARN} and @code{NS_LOG_ERROR}.  We can
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   126
increase the logging level and get more information without changing the
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   127
script and recompiling by setting the NS_LOG environment variable like this:
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   128
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   129
@verbatim
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   130
  ~/repos/ns-3-dev > export NS_LOG=UdpEchoClientApplication=level_all
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   131
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   132
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   133
This sets the shell environment variable @code{NS_LOG} to the string,
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   134
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   135
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   136
  UdpEchoClientApplication=level_all
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   137
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   138
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   139
The left hand side of the assignment is the name of the logging component we
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   140
want to set, and the right hand side is the flag we want to use.  In this case,
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   141
we are going to turn on all of the debugging levels for the application.  If
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   142
you run the script with NS_LOG set this way, the @command{ns-3} logging 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   143
system will pick up the change and you should see the following output:
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   144
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   145
@verbatim
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   146
  ~/repos/ns-3-dev > ./waf --run scratch/first
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   147
  Entering directory `/home/craigdo/repos/ns-3-dev/build'
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   148
  Compilation finished successfully
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   149
  UdpEchoClientApplication:UdpEchoClient()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   150
  UdpEchoClientApplication:StartApplication()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   151
  UdpEchoClientApplication:ScheduleTransmit()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   152
  UdpEchoClientApplication:Send()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   153
  Sent 1024 bytes to 10.1.1.2
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   154
  Received 1024 bytes from 10.1.1.1
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   155
  UdpEchoClientApplication:HandleRead(0x62c640, 0x62cd70)
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   156
  Received 1024 bytes from 10.1.1.2
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   157
  UdpEchoClientApplication:StopApplication()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   158
  UdpEchoClientApplication:DoDispose()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   159
  UdpEchoClientApplication:~UdpEchoClient()
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   160
  ~/repos/ns-3-dev >
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   161
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   162
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   163
The additional debug information provided by the application is from
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   164
the NS_LOG_FUNCTION level.  This shows every time a function in the application
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   165
is called during script execution.  Note that there are no requirements in the
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   166
@command{ns-3} system that models must support any particular logging 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   167
functionality.  The decision regarding how much information is logged
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   168
is left to the individual model developer.  In the case of the echo 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   169
applications, a good deal of log output is available.
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   170
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   171
You can now see a log of the function calls that were made to the application.
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   172
If you look closely you will notice a single colon between the string 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   173
@code{UdpEchoClientApplication} and the method name where you might have 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   174
expected a C++ scope operator (@code{::}).  This is intentional.  
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   175
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   176
The name is not actually a class name, it is a logging component name.  When 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   177
there is a one-to-one correspondence between a source file and a class, this 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   178
will generally be the class name but you should understand that it is not 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   179
actually a class name, and there is a single colon there instead of a double
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   180
colon to remind you in a relatively subtle way to conceptually separate the 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   181
logging component name from the class name.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   182
3771
21f40ccb03b3 tutorial typos fixed (bug 379)
Tom Henderson <tomh@tomh.org>
parents: 3382
diff changeset
   183
It turns out that in some cases, it can be hard to determine which method
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   184
actually generates a log message.  If you look in the text above, you may
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   185
wonder where the string ``@code{Received 1024 bytes from 10.1.1.2}'' comes
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   186
from.  You can resolve this by ORing the @code{prefix_func} level into the
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   187
@code{NS_LOG} environment variable.  Try doing the following,
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   188
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   189
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   190
  export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func'
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   191
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   192
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   193
Note that the quotes are required since the vertical bar we use to indicate an
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   194
OR operation is also a Unix pipe connector.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   195
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   196
Now, if you run the script you will see that the logging system makes sure 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   197
that every message from the given log component is prefixed with the component
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   198
name.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   199
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   200
@verbatim
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   201
  ~/repos/ns-3-dev > ./waf --run scratch/first
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   202
  Entering directory `/home/craigdo/repos/ns-3-dev/build'
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   203
  Compilation finished successfully
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   204
  UdpEchoClientApplication:UdpEchoClient()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   205
  UdpEchoClientApplication:StartApplication()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   206
  UdpEchoClientApplication:ScheduleTransmit()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   207
  UdpEchoClientApplication:Send()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   208
  UdpEchoClientApplication:Send(): Sent 1024 bytes to 10.1.1.2
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   209
  Received 1024 bytes from 10.1.1.1
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   210
  UdpEchoClientApplication:HandleRead(0x62c710, 0x62ce40)
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   211
  UdpEchoClientApplication:HandleRead(): Received 1024 bytes from 10.1.1.2
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   212
  UdpEchoClientApplication:StopApplication()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   213
  UdpEchoClientApplication:DoDispose()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   214
  UdpEchoClientApplication:~UdpEchoClient()
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   215
  ~/repos/ns-3-dev >
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   216
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   217
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   218
You can now see all of the messages coming from the UDP echo client application
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   219
are identified as such.  The message ``Received 1024 bytes from 10.1.1.2'' is
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   220
now clearly identified as coming from the echo client application.  The 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   221
remaining message must be coming from the UDP echo server application.  We 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   222
can enable that component by entering a colon separated list of components in
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   223
the NS_LOG environment variable.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   224
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   225
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   226
  export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func:
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   227
                 UdpEchoServerApplication=level_all|prefix_func'
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   228
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   229
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   230
Note that you will need to remove the newline after the @code{:} in the
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   231
example text above.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   232
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   233
Now, if you run the script you will see all of the log messages from both the
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   234
echo client and server applications.  You may see that this can be very useful
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   235
in debugging problems.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   236
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   237
@verbatim
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   238
  ~/repos/ns-3-dev > ./waf --run scratch/first
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   239
  Entering directory `/home/craigdo/repos/ns-3-dev/build'
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   240
  Compilation finished successfully
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   241
  UdpEchoServerApplication:UdpEchoServer()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   242
  UdpEchoClientApplication:UdpEchoClient()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   243
  UdpEchoServerApplication:StartApplication()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   244
  UdpEchoClientApplication:StartApplication()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   245
  UdpEchoClientApplication:ScheduleTransmit()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   246
  UdpEchoClientApplication:Send()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   247
  UdpEchoClientApplication:Send(): Sent 1024 bytes to 10.1.1.2
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   248
  UdpEchoServerApplication:HandleRead(): Received 1024 bytes from 10.1.1.1
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   249
  UdpEchoServerApplication:HandleRead(): Echoing packet
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   250
  UdpEchoClientApplication:HandleRead(0x62c760, 0x62ce90)
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   251
  UdpEchoClientApplication:HandleRead(): Received 1024 bytes from 10.1.1.2
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   252
  UdpEchoServerApplication:StopApplication()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   253
  UdpEchoClientApplication:StopApplication()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   254
  UdpEchoClientApplication:DoDispose()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   255
  UdpEchoServerApplication:DoDispose()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   256
  UdpEchoClientApplication:~UdpEchoClient()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   257
  UdpEchoServerApplication:~UdpEchoServer()
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   258
  ~/repos/ns-3-dev >
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   259
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   260
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   261
It is also sometimes useful to be able to see the simulation time at which a
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   262
log message is generated.  You can do this by ORing in the prefix_time bit.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   263
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   264
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   265
  export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func|prefix_time:
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   266
                 UdpEchoServerApplication=level_all|prefix_func|prefix_time'
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   267
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   268
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   269
If you run the script now, you should see the following output:
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   270
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   271
@verbatim
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   272
  ~/repos/ns-3-dev > ./waf --run scratch/first
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   273
  Entering directory `/home/craigdo/repos/ns-3-dev/build'
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   274
  Compilation finished successfully
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   275
  0ns UdpEchoServerApplication:UdpEchoServer()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   276
  0ns UdpEchoClientApplication:UdpEchoClient()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   277
  1000000000ns UdpEchoServerApplication:StartApplication()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   278
  2000000000ns UdpEchoClientApplication:StartApplication()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   279
  2000000000ns UdpEchoClientApplication:ScheduleTransmit()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   280
  2000000000ns UdpEchoClientApplication:Send()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   281
  2000000000ns UdpEchoClientApplication:Send(): Sent 1024 bytes to 10.1.1.2
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   282
  2003686400ns UdpEchoServerApplication:HandleRead(): Received 1024 bytes 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   283
    from 10.1.1.1
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   284
  2003686400ns UdpEchoServerApplication:HandleRead(): Echoing packet
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   285
  2007372800ns UdpEchoClientApplication:HandleRead(0x62c8c0, 0x62d020)
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   286
  2007372800ns UdpEchoClientApplication:HandleRead(): Received 1024 bytes 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   287
    from 10.1.1.2
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   288
  10000000000ns UdpEchoServerApplication:StopApplication()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   289
  10000000000ns UdpEchoClientApplication:StopApplication()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   290
  UdpEchoClientApplication:DoDispose()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   291
  UdpEchoServerApplication:DoDispose()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   292
  UdpEchoClientApplication:~UdpEchoClient()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   293
  UdpEchoServerApplication:~UdpEchoServer()
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   294
  ~/repos/ns-3-dev >
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   295
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   296
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   297
You can see that the constructor for the UdpEchoServer was called at a 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   298
simulation time of 0 nanoseconds.  This is actually happening before the 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   299
simulation starts.  The same for the UdpEchoClient constructor.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   300
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   301
Recall that the @code{first.cc} script started the echo server application at
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   302
one second into the simulation.  You can now see that the 
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   303
@code{StartApplication} method of the server is, in fact, called at one second
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   304
(or one billion nanoseconds).  You can also see that the echo client 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   305
application is started at a simulation time of two seconds as we requested in
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   306
the script.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   307
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   308
You can now follow the progress of the simulation from the 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   309
@code{ScheduleTransmit} call in the client that calls @code{Send} to the 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   310
@code{HandleRead} callback in the echo server application.  Note that the 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   311
elapsed time as the packet is sent across the point-to-point link is 3.6864
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   312
milliseconds.  You see the echo server logging a message telling you that it
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   313
has echoed the packet and then, after a delay, you see the echo client receive
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   314
the echoed packet in its @code{HandleRead} method.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   315
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   316
There is a lot that is happening under the covers in this simulation that you
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   317
are not seeing as well.  You can very easily follow the entire process by
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   318
turning on all of the logging components in the system.  Try setting the 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   319
@code{NS_LOG} variable to the following,
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   320
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   321
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   322
  export 'NS_LOG=*=level_all|prefix_func|prefix_time'
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   323
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   324
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   325
The asterisk above is the logging component wildcard.  This will turn on all 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   326
of the logging in all of the components used in the simulation.  I won't 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   327
reproduce the output here (as of this writing it produces 772 lines of output
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   328
for the single packet echo) but you can redirect this information into a file 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   329
and look through it with your favorite editor if you like,
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   330
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   331
@verbatim
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   332
  ~/repos/ns-3-dev > ./waf --run scratch/first >& log.out
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   333
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   334
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   335
I personally use this quite a bit when I am presented with a problem and I
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   336
have no idea where things are going wrong.  I can follow the progress of the
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   337
code quite easily without having to set breakpoints and step through code
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   338
in a debugger.  When I have a general idea about what is going wrong, I 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   339
transition into a debugger for fine-grained examination of the problem.  This
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   340
kind of output can be especially useful when your script does something 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   341
completely unexpected.  If you are stepping using a debugger you may miss an
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   342
unexpected excursion completely.  Logging the excursion makes it quickly
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   343
visible.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   344
3342
8762b90e6f7e formatting nits on the Tweaking chapter
Tom Henderson <tomh@tomh.org>
parents: 3340
diff changeset
   345
@node Adding Logging to your Code
8762b90e6f7e formatting nits on the Tweaking chapter
Tom Henderson <tomh@tomh.org>
parents: 3340
diff changeset
   346
@subsection Adding Logging to your Code
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   347
@cindex NS_LOG
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   348
You can add new logging to your simulations by making calls to the log 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   349
component via several macros.  Let's do so in the @code{first.cc} script we
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   350
have in the @code{scratch} directory.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   351
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   352
Recall that we have defined a logging component in that script:
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   353
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   354
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   355
  NS_LOG_COMPONENT_DEFINE ("FirstScriptExample");
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   356
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   357
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   358
You now know that you can enable all of the logging for this component by
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   359
setting the @code{NS_LOG} environment variable to the various levels.  Let's
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   360
go ahead add some logging to the script.  The macro used to add an 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   361
informational level log message is @code{NS_LOG_INFO}.  Go ahead and add one 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   362
just before we start creating the nodes that tells you that the script is 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   363
``Creating Topology.''  This is done as in this code snippet,
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   364
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   365
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   366
  NS_LOG_INFO ("Creating Topology");
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   367
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   368
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   369
Now build the script using waf and clear the @code{NS_LOG} variable to turn 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   370
off the torrent of logging we previously enabled:
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   371
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   372
@verbatim
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   373
  ~/repos/ns-3-dev > export NS_LOG=
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   374
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   375
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   376
Now, if you run the script, you will not see your new message since its 
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   377
associated logging component (@code{FirstScriptExample}) has not been enabled.
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   378
In order to see your message you will have to enable the 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   379
@code{FirstScriptExample} logging component with a level greater than or equal
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   380
to @code{NS_LOG_INFO}.  If you just want to see this particular level of 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   381
logging, you can enable it by,
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   382
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   383
@verbatim
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   384
  ~/repos/ns-3-dev > export NS_LOG=FirstScriptExample=info
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   385
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   386
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   387
If you now run the script you will see your new ``Creating Topology'' log
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   388
message,
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   389
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   390
@verbatim
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   391
  ~/repos/ns-3-dev > ./waf --run scratch/first
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   392
  Entering directory `/home/craigdo/repos/ns-3-dev/build'
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   393
  Compilation finished successfully
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   394
  Creating Topology
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   395
  Sent 1024 bytes to 10.1.1.2
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   396
  Received 1024 bytes from 10.1.1.1
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   397
  Received 1024 bytes from 10.1.1.2
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   398
  ~/repos/ns-3-dev >
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   399
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   400
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   401
@c ========================================================================
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   402
@c Using Command Line Arguments
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   403
@c ========================================================================
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   404
@node Using Command Line Arguments
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   405
@section Using Command Line Arguments
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   406
3342
8762b90e6f7e formatting nits on the Tweaking chapter
Tom Henderson <tomh@tomh.org>
parents: 3340
diff changeset
   407
@subsection Overriding Default Attributes
3339
ff29f4ba75ed finish up with a wifi example
Craig Dowell <craigdo@ee.washington.edu>
parents: 3332
diff changeset
   408
@cindex command line arguments
3349
e6259dcffada more editing passes through tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3348
diff changeset
   409
Another way you can change how @command{ns-3} scripts behave without editing
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   410
and building is via @emph{command line arguments.}  We provide a mechanism to 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   411
parse command line arguments and automatically set local and global variables
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   412
based on those arguments.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   413
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   414
The first step in using the command line argument system is to declare the
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   415
command line parser.  This is done quite simply (in your main program) as
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   416
in the following code,
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   417
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   418
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   419
    int
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   420
  main (int argc, char *argv[])
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   421
  {
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   422
    ...  
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   423
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   424
    CommandLine cmd;
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   425
    cmd.Parse (argc, argv);
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   426
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   427
    ...
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   428
  }
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   429
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   430
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   431
This simple two line snippet is actually very useful by itself.  It opens the
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   432
door to the @command{ns-3} global variable and attribute systems.  Go ahead 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   433
and add that two lines of code to the @code{first.cc} script at the start of 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   434
@code{main}.  Go ahead and build the script and run it, but ask the script 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   435
for help in the following way,
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   436
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   437
@verbatim
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   438
  ~/repos/ns-3-dev > ./waf --run "scratch/first --PrintHelp"
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   439
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   440
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   441
This will ask Waf to run the @code{scratch/first} script and pass the command
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   442
line argument @code{--PrintHelp} to the script.  The quotes are required to 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   443
sort out which program gets which argument.  The command line parser will
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   444
now see the @code{--PrintHelp} argument and respond with,
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   445
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   446
@verbatim
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   447
  ~/repos/ns-3-dev > ./waf --run ``scratch/first --PrintHelp''
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   448
  Entering directory `/home/craigdo/repos/ns-3-dev/build'
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   449
  Compilation finished successfully
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   450
  --PrintHelp: Print this help message.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   451
  --PrintGroups: Print the list of groups.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   452
  --PrintTypeIds: Print all TypeIds.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   453
  --PrintGroup=[group]: Print all TypeIds of group.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   454
  --PrintAttributes=[typeid]: Print all attributes of typeid.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   455
  --PrintGlobals: Print the list of globals.
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   456
  ~/repos/ns-3-dev >
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   457
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   458
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   459
Let's focus on the @code{--PrintAttributes} option.  We have already hinted
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   460
at the @command{ns-3} attribute system while walking through the 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   461
@code{first.cc} script.  We looked at the following lines of code,
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   462
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   463
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   464
    PointToPointHelper pointToPoint;
3382
d5f8e5fae1c6 fix bug 234 which changes required methods on helpers to constructor parameters. Update tutorial content to reflect. Change RemoteIpv4 attribute to RemoteAddress.
Craig Dowell <craigdo@ee.washington.edu>
parents: 3356
diff changeset
   465
    pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
d5f8e5fae1c6 fix bug 234 which changes required methods on helpers to constructor parameters. Update tutorial content to reflect. Change RemoteIpv4 attribute to RemoteAddress.
Craig Dowell <craigdo@ee.washington.edu>
parents: 3356
diff changeset
   466
    pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   467
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   468
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   469
and mentioned that @code{DataRate} was actually an @code{Attribute} of the 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   470
@code{PointToPointNetDevice}.  Let's use the command line argument parser
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   471
to take a look at the attributes of the PointToPointNetDevice.  The help
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   472
listing says that we should provide a @code{TypeId}.  This corresponds to the
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   473
class name of the class to which the attributes belong.  In this case it will
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   474
be @code{ns3::PointToPointNetDevice}.  Let's go ahead and type in,
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   475
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   476
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   477
  ./waf --run "scratch/first --PrintAttributes=ns3::PointToPointNetDevice"
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   478
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   479
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   480
The system will print out all of the attributes of this kind of net device.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   481
Among the attributes you will see listed is,
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   482
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   483
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   484
  --ns3::PointToPointNetDevice::DataRate=[32768bps]:
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   485
    The default data rate for point to point links
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   486
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   487
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   488
This is the default value that will be used when a @code{PointToPointNetDevice}
3382
d5f8e5fae1c6 fix bug 234 which changes required methods on helpers to constructor parameters. Update tutorial content to reflect. Change RemoteIpv4 attribute to RemoteAddress.
Craig Dowell <craigdo@ee.washington.edu>
parents: 3356
diff changeset
   489
is created in the system.  We overrode this default with the attribute
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   490
setting in the @code{PointToPointHelper} above.  Let's use the default values 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   491
for the point-to-point devices and channels by deleting the 
3382
d5f8e5fae1c6 fix bug 234 which changes required methods on helpers to constructor parameters. Update tutorial content to reflect. Change RemoteIpv4 attribute to RemoteAddress.
Craig Dowell <craigdo@ee.washington.edu>
parents: 3356
diff changeset
   492
@code{SetDeviceAttribute} call and the @code{SetChannelAttribute} call from 
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   493
the @code{first.cc} we have in the scratch directory.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   494
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   495
Your script should now just declare the @code{PointToPointHelper} and not do 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   496
any @code{set} operations as in the following example,
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   497
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   498
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   499
  ...
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   500
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   501
  NodeContainer nodes;
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   502
  nodes.Create (2);
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   503
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   504
  PointToPointHelper pointToPoint;
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   505
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   506
  NetDeviceContainer devices;
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   507
  devices = pointToPoint.Install (nodes);
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   508
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   509
  ...
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   510
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   511
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   512
Go ahead and build the new script with Waf (@code{./waf}) and let's go back 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   513
and enable some logging from the UDP echo server application and turn on the 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   514
time prefix.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   515
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   516
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   517
  export 'NS_LOG=UdpEchoServerApplication=level_all|prefix_time'
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   518
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   519
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   520
If you run the script, you should now see the following output,
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   521
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   522
@verbatim
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   523
  ~/repos/ns-3-dev > ./waf --run scratch/first
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   524
  Entering directory `/home/craigdo/repos/ns-3-dev/build'
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   525
  Compilation finished successfully
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   526
  0ns UdpEchoServerApplication:UdpEchoServer()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   527
  1000000000ns UdpEchoServerApplication:StartApplication()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   528
  Sent 1024 bytes to 10.1.1.2
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   529
  2257324218ns Received 1024 bytes from 10.1.1.1
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   530
  2257324218ns Echoing packet
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   531
  Received 1024 bytes from 10.1.1.2
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   532
  10000000000ns UdpEchoServerApplication:StopApplication()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   533
  UdpEchoServerApplication:DoDispose()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   534
  UdpEchoServerApplication:~UdpEchoServer()
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   535
  ~/repos/ns-3-dev >
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   536
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   537
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   538
Recall that the last time we looked at the simulation time at which the packet
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   539
was received by the echo server, it was at 2.0036864 seconds.  Now it is
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   540
receiving the packet at about 2.257 seconds.  This is because we just dropped
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   541
the data rate of the @code{PointToPointNetDevice} down to its default of 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   542
32768 bits per second from five megabits per second.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   543
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   544
If we were to provide a new @code{DataRate} using the command line, we could 
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   545
speed our simulation up again.  We do this in the following way, according to
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   546
the formula implied by the help item:
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   547
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   548
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   549
  ./waf --run "scratch/first --ns3::PointToPointNetDevice::DataRate=5Mbps"
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   550
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   551
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   552
This will set the default value of the @code{DataRate} attribute back to 
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   553
five megabits per second.  To get the original behavior of the script back, 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   554
we will have to set the speed-of-light delay of the channel.  We can ask the 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   555
command line system to print out the @code{Attributes} of the channel just 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   556
like we did the net device:
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   557
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   558
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   559
  ./waf --run "scratch/first --PrintAttributes=ns3::PointToPointChannel"
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   560
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   561
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   562
We discover the @code{Delay} attribute of the channel is set in the following
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   563
way:
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   564
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   565
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   566
  --ns3::PointToPointChannel::Delay=[0ns]:
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   567
    Transmission delay through the channel
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   568
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   569
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   570
We can then set both of these default values through the command line system,
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   571
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   572
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   573
  ./waf --run "scratch/first
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   574
    --ns3::PointToPointNetDevice::DataRate=5Mbps
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   575
    --ns3::PointToPointChannel::Delay=2ms"
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   576
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   577
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   578
in which case we recover the timing we had when we explicitly set the
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   579
@code{DataRate} and @code{Delay} in the script:
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   580
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   581
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   582
  Compilation finished successfully
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   583
  0ns UdpEchoServerApplication:UdpEchoServer()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   584
  1000000000ns UdpEchoServerApplication:StartApplication()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   585
  Sent 1024 bytes to 10.1.1.2
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   586
  2003686400ns Received 1024 bytes from 10.1.1.1
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   587
  2003686400ns Echoing packet
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   588
  Received 1024 bytes from 10.1.1.2
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   589
  10000000000ns UdpEchoServerApplication:StopApplication()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   590
  UdpEchoServerApplication:DoDispose()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   591
  UdpEchoServerApplication:~UdpEchoServer()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   592
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   593
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   594
Note that the packet is again received by the server at 2.0036864 seconds.  We 
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   595
could actually set any of the attributes used in the script in this way.  In
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   596
particular we could set the @code{UdpEchoClient} attribute @code{MaxPackets} 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   597
to some other value than one.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   598
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   599
How would you go about that?  Give it a try.  Remember you have to comment 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   600
out the place we override the default attribute in the script.  Then you 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   601
have to rebuild the script using the default.  You will also have to find the
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   602
syntax for actually setting the new default atribute value using the command
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   603
line help facility.  Once you have this figured out you should be able to
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   604
control the number of packets echoed from the command line.  Since we're nice
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   605
folks, we'll tell you that your command line should end up looking something
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   606
like,
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   607
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   608
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   609
  ./waf --run "scratch/first 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   610
    --ns3::PointToPointNetDevice::DataRate=5Mbps 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   611
    --ns3::PointToPointChannel::Delay=2ms 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   612
    --ns3::UdpEchoClient::MaxPackets=2"
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   613
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   614
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   615
@subsection Hooking Your Own Values
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   616
You can also add your own hooks to the command line system.  This is done
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   617
quite simply by using the @code{AddValue} method to the command line parser.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   618
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   619
Let's use this facility to specify the number of packets to echo in a 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   620
completely different way.  Let's add a local variable called @code{nPackets}
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   621
to the @code{main} function.  We'll initialize it to one to match our previous 
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   622
default behavior.  To allow the command line parser to change this value, we
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   623
need to hook the value into the parser.  We do this by adding a call to 
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   624
@code{AddValue}.  Go ahead and change the @code{scratch/first.cc} script to
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   625
start with the following code,
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   626
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   627
@verbatim
3771
21f40ccb03b3 tutorial typos fixed (bug 379)
Tom Henderson <tomh@tomh.org>
parents: 3382
diff changeset
   628
  int
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   629
  main (int argc, char *argv[])
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   630
  {
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   631
    uint32_t nPackets = 1;
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   632
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   633
    CommandLine cmd;
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   634
    cmd.AddValue("nPackets", "Number of packets to echo", nPackets);
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   635
    cmd.Parse (argc, argv);
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   636
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   637
    ...
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   638
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   639
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   640
Scroll down to the point in the script where we set the @code{MaxPackets}
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   641
attribute and change it so that it is set to the variable @code{nPackets}
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   642
instead of the constant @code{1} as is shown below.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   643
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   644
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   645
  echoClient.SetAppAttribute ("MaxPackets", UintegerValue (nPackets));
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   646
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   647
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   648
Now if you run the script and provide the @code{--PrintHelp} argument, you 
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   649
should see your new @code{User Argument} listed in the help display.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   650
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   651
@verbatim
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   652
  ~/repos/ns-3-dev > ./waf --run "scratch/first --PrintHelp"
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   653
  Entering directory `/home/craigdo/repos/ns-3-dev/build'
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   654
  Compilation finished successfully
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   655
  --PrintHelp: Print this help message.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   656
  --PrintGroups: Print the list of groups.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   657
  --PrintTypeIds: Print all TypeIds.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   658
  --PrintGroup=[group]: Print all TypeIds of group.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   659
  --PrintAttributes=[typeid]: Print all attributes of typeid.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   660
  --PrintGlobals: Print the list of globals.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   661
  User Arguments:
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   662
      --nPackets: Number of packets to echo
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   663
  ~/repos/ns-3-dev >
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   664
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   665
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   666
If you want to specify the number of packets to echo, you can now do so by
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   667
setting the @code{--nPackets} argument in the command line,
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   668
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   669
@verbatim
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   670
  ~/repos/ns-3-dev > ./waf --run "scratch/first --nPackets=2"
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   671
  Entering directory `/home/craigdo/repos/ns-3-dev/build'
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   672
  Compilation finished successfully
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   673
  Sent 1024 bytes to 10.1.1.2
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   674
  Received 1024 bytes from 10.1.1.1
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   675
  Received 1024 bytes from 10.1.1.2
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   676
  Sent 1024 bytes to 10.1.1.2
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   677
  Received 1024 bytes from 10.1.1.1
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   678
  Received 1024 bytes from 10.1.1.2
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   679
  ~/repos/ns-3-dev >
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   680
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   681
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   682
You have now echoed two packets.
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   683
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   684
You can see that if you are an @command{ns-3} user, you can use the command 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   685
line argument system to control global values and attributes.  If you are a 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   686
model author, you can add new attributes to your Objects and they will 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   687
automatically be available for setting by your users through the command line
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   688
system.  If you are a script author, you can add new variables to your scripts
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   689
and hook them into the command line system quite painlessly.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   690
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   691
@c ========================================================================
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   692
@c Using the Tracing System
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   693
@c ========================================================================
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   694
@node Using the Tracing System
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   695
@section Using the Tracing System
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   696
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   697
The whole point of simulation is to generate output for further study, and 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   698
the @command{ns-3} tracing system is a primary mechanism for this.  Since 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   699
@command{ns-3} is a C++ program, standard facilities for generating output 
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   700
from C++ programs could be used:  
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   701
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   702
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   703
  #include <iostream>
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   704
  ...
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   705
  int main ()
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   706
  {
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   707
    ...
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   708
    std::cout << "The value of x is " << x << std::endl;
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   709
    ...
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   710
  } 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   711
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   712
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   713
You could even use the logging module to add a little structure to your 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   714
solution.  There are many well-known problems generated by such approaches
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   715
and so we have provided a generic event tracing subsystem to address the 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   716
issues we thought were important.
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   717
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   718
The basic goals of the @command{ns-3} tracing system are:
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   719
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   720
@itemize @bullet
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   721
@item For basic tasks, the tracing system should allow the user to generate 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   722
standard tracing for popular tracing sources, and to customize which objects
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   723
generate the tracing;
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   724
@item Intermediate users must be able to extend the tracing system to modify
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   725
the output format generated, or to insert new tracing sources, without 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   726
modifying the core of the simulator;
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   727
@item Advanced users can modify the simulator core to add new tracing sources
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   728
and sinks.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   729
@end itemize 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   730
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   731
The @command{ns-3} tracing system is built on the concepts of independent 
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   732
tracing sources and tracing sinks, and a uniform mechanism for connecting
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   733
sources to sinks.  Trace sources are entities that can signal events that
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   734
happen in a simulation and provide access to interesting underlying data. 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   735
For example, a trace source could indicate when a packet is received by a net
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   736
device and provide access to the packet contents for interested trace sinks.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   737
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   738
Trace sources are not useful by themselves, they must be ``connected'' to
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   739
other pieces of code that actually do something useful with the information 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   740
provided by the sink.  Trace sinks are consumers of the events and data
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   741
provided by the trace sources.  For example, one could create a trace sink 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   742
that would (when connected to the trace source of the previous example) print 
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   743
out interesting parts of the received packet.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   744
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   745
The rationale for this explicit division is to allow users to attach new
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   746
types of sinks to existing tracing sources, without requiring editing and 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   747
recompilation of the the core of the simulator.  Thus, in the example above, 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   748
a user could define a new tracing sink in her script and attach it to an 
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   749
existing tracing source defined in the simulation core by editing only the 
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   750
user script.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   751
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   752
In this tutorial, we will walk through some pre-defined sources and sinks and
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   753
show how they may be customized with little user effort.  See the ns-3 manual
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   754
or how-to sections for information on advanced tracing configuration including
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   755
extending the tracing namespace and creating new tracing sources.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   756
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   757
@cindex tracing
3339
ff29f4ba75ed finish up with a wifi example
Craig Dowell <craigdo@ee.washington.edu>
parents: 3332
diff changeset
   758
@cindex ASCII tracing
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   759
@subsection ASCII Tracing
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   760
@command{Ns-3} provides helper functionality that wraps the low-level tracing
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   761
system to help you with the details involved in configuring some easily 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   762
understood packet traces.  If you enable this functionality, you will see
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   763
output in a ASCII files --- thus the name.  For those familiar with 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   764
@command{ns-2} output, this type of trace is analogous to the @command{out.tr}
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   765
generated by many scripts.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   766
3339
ff29f4ba75ed finish up with a wifi example
Craig Dowell <craigdo@ee.washington.edu>
parents: 3332
diff changeset
   767
@cindex tracing packets
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   768
Let's just jump right in and add some ASCII tracing output to our 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   769
@code{first.cc} script.  The first thing you need to do is to add the 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   770
following code to the script just before the call to @code{Simulator::Run ()}.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   771
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   772
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   773
  std::ofstream ascii;
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   774
  ascii.open ("first.tr");
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   775
  PointToPointHelper::EnableAsciiAll (ascii);
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   776
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   777
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   778
The first two lines are just vanilla C++ code to open a stream that will be
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   779
written to a file named ``first.tr.''  See your favorite C++ tutorial if you
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   780
are unfamiliar with this code.  The last line of code in the snippet above
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   781
tells @command{ns-3} that you want to enable ASCII tracing on all 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   782
point-to-point devices in your simulation; and you want the (provided) trace
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   783
sinks to write out information about packet movement in ASCII format to the 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   784
stream provided. For those familiar with @command{ns-2}, the traced events are
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   785
equivalent to the popular trace points that log "+", "-", "d", and "r" events.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   786
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   787
Since we have used a @code{std::ofstream} object, we also need to include the
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   788
appropriate header.  Add the following line to the script (I typically add it
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   789
above the ns-3 includes):
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   790
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   791
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   792
  #include <fstream>
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   793
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   794
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   795
You can now build the script and run it from the command line:
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   796
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   797
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   798
  ./waf --run scratch/first
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   799
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   800
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   801
@cindex first.tr
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   802
Just as you have seen previously, you may see some messages from Waf and then
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   803
the ``Compilation finished successfully'' with some number of messages from 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   804
the running program.  
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   805
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   806
When it ran, the program will have created a file named @code{first.tr}.  
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   807
Because of the way that Waf works, the file is not created in the local 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   808
directory, it is created at the top-level directory of the repository by 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   809
default.  If you want to control where the traces are saved you can use the 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   810
@code{--cwd} option of Waf to specify this.  We have not done so, thus we 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   811
need to change into the top level directory of our repo and take a look at 
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   812
the ASCII trace file @code{first.tr} in your favorite editor.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   813
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   814
@subsubsection Parsing Ascii Traces
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   815
@cindex parsing ascii traces
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   816
There's a lot of information there in a pretty dense form, but the first thing
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   817
to notice is that there are a number of distinct lines in this file.  It may
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   818
be difficult to see this clearly unless you widen your window considerably.
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   819
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   820
Each line in the file corresponds to a @emph{trace event}.  In this case
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   821
we are tracing events on the @emph{transmit queue} present in every 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   822
point-to-point net device in the simulation.  The transmit queue is a queue 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   823
through which every packet destined for a point-to-point channel must pass.
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   824
Note that each line in the trace file begins with a lone character (has a 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   825
space after it).  This character will have the following meaning:
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   826
3339
ff29f4ba75ed finish up with a wifi example
Craig Dowell <craigdo@ee.washington.edu>
parents: 3332
diff changeset
   827
@cindex ascii trace enqueue operation
ff29f4ba75ed finish up with a wifi example
Craig Dowell <craigdo@ee.washington.edu>
parents: 3332
diff changeset
   828
@cindex ascii trace dequeue operation
ff29f4ba75ed finish up with a wifi example
Craig Dowell <craigdo@ee.washington.edu>
parents: 3332
diff changeset
   829
@cindex ascii trace drop operation
ff29f4ba75ed finish up with a wifi example
Craig Dowell <craigdo@ee.washington.edu>
parents: 3332
diff changeset
   830
@cindex ascii trace receive operation
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   831
@itemize @bullet
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   832
@item @code{+}: An enqueue operation occurred on the device queue;
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   833
@item @code{-}: A dequeue operation occurred on the device queue;
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   834
@item @code{d}: A packet was dropped, typically because the queue was full;
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   835
@item @code{r}: A packet was received by the net device.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   836
@end itemize
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   837
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   838
Let's take a more detailed view of the first line in the trace file.  I'll 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   839
break it down into sections (indented for clarity) with a two digit reference
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   840
number on the left side:
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   841
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   842
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   843
  00 + 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   844
  01 2 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   845
  02 /NodeList/0/DeviceList/0/$ns3::PointToPointNetDevice/TxQueue/Enqueue 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   846
  03 ns3::PppHeader (
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   847
  04   Point-to-Point Protocol: IP (0x0021)) 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   848
  05   ns3::Ipv4Header (
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   849
  06     tos 0x0 ttl 64 id 0 offset 0 flags [none] 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   850
  07     length: 1052 10.1.1.1 > 10.1.1.2)
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   851
  08     ns3::UdpHeader (
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   852
  09       length: 1032 49153 > 9) 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   853
  10       Payload (size=1024)
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   854
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   855
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   856
@cindex trace event
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   857
@cindex simulation time
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   858
The first line of this expanded trace event (reference number 00) is the 
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   859
operation.  We have a @code{+} character, so this corresponds to an
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   860
@emph{enqueue} operation on the transmit queue.  The second line (reference 01)
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   861
is the simulation time expressed in seconds.  You may recall that we asked the 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   862
@code{UdpEchoClientApplication} to start sending packets at two seconds.  Here
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   863
we see confirmation that this is, indeed, happening.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   864
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   865
@cindex node number
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   866
@cindex net device number
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   867
@cindex smart pointer
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   868
The next line of the example trace (reference 02) tell us which trace source
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   869
originated this event (expressed in the tracing namespace).  You can think
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   870
of the tracing namespace somewhat like you would a filesystem namespace.  The 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   871
root of the namespace is the @code{NodeList}.  This corresponds to a container
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   872
managed in the @command{ns-3} core code that contains all of the nodes that are
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   873
created in a script.  Just as a filesystem may have directories under the 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   874
root, we may have node numbers in the @code{NodeList}.  The string 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   875
@code{/NodeList/0} therefore refers to the zeroth node in the @code{NodeList}
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   876
which we typically think of as ``node 0.''  In each node there is a list of 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   877
devices that have been installed.  This list appears next in the namespace.
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   878
You can see that this trace event comes from @code{DeviceList/0} which is the 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   879
zeroth device installed in the node. 
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   880
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   881
The next string, @code{$ns3::PointToPointNetDevice} tells you what kind of 
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   882
device is in the zeroth position of the device list for node zero.
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   883
Recall that the operation @code{+} found at reference 00 meant that an enqueue 
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   884
operation happened on the transmit queue of the device.  This is reflected in 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   885
the final segments of the ``trace path'' which are @code{TxQueue/Enqueue}.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   886
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   887
The remaining lines in the trace should be fairly intuitive.  References 03-04
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   888
indicate that the packet is encapulated in the point-to-point protocol.  
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   889
References 05-07 show that the packet has an IP version four header and has
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   890
originated from IP address 10.1.1.1 and is destined for 10.1.1.2.  References
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   891
08-09 show that this packet has a UDP header and, finally, reference 10 shows
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   892
that the payload is the expected 1024 bytes.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   893
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   894
The next line in the trace file shows the same packet being dequeued from the
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   895
transmit queue on the same node. 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   896
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   897
The Third line in the trace file shows the packet being received by the net
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   898
device on the node with the echo server. I have reproduced that event below.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   899
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   900
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   901
  00 r 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   902
  01 2.25732 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   903
  02 /NodeList/1/DeviceList/0/$ns3::PointToPointNetDevice/Rx 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   904
  03 ns3::PppHeader (
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   905
  04   Point-to-Point Protocol: IP (0x0021)) 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   906
  05   ns3::Ipv4Header (
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   907
  06     tos 0x0 ttl 64 id 0 offset 0 flags [none] 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   908
  07     length: 1052 10.1.1.1 > 10.1.1.2)
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   909
  08     ns3::UdpHeader (
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   910
  09       length: 1032 49153 > 9) 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   911
  10       Payload (size=1024)
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   912
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   913
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   914
Notice that the trace operation is now @code{r} and the simulation time has
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   915
increased to 2.25732 seconds.  If you have been following the tutorial steps
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   916
closely this means that you have left the @code{DataRate} of the net devices
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   917
and the channel @code{Delay} set to their default values.  This time should 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   918
be familiar as you have seen it before in a previous section.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   919
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   920
The trace source namespace entry (reference 02) has changed to reflect that
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   921
this event is coming from node 1 (@code{/NodeList/1}) and the packet reception
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   922
trace source (@code{/Rx}).  It should be quite easy for you to follow the 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   923
progress of the packet through the topology by looking at the rest of the 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   924
traces in the file.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   925
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   926
@subsection PCAP Tracing
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   927
@cindex pcap
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   928
@cindex Wireshark
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   929
The @command{ns-3} device helpers can also be used to create trace files in the
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   930
@code{.pcap} format.  The acronym pcap (usually written in lower case) stands
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   931
for @emph{p}acket @emph{cap}ture, and is actually an API that includes the 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   932
definition of a @code{.pcap} file format.  The most popular program that can
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   933
read and display this format is Wireshark (formerly called Ethereal).
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   934
However, there are many traffic trace analyzers that use this packet format.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   935
We encourage users to exploit the many tools available for analyzing pcap
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   936
traces.  In this tutorial, we concentrate on viewing pcap traces with tcpdump.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   937
3339
ff29f4ba75ed finish up with a wifi example
Craig Dowell <craigdo@ee.washington.edu>
parents: 3332
diff changeset
   938
@cindex pcap tracing
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   939
The code used to enable pcap tracing is a one-liner.  
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   940
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   941
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   942
  PointToPointHelper::EnablePcapAll ("first");
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   943
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   944
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   945
Go ahead and insert this line of code after the ASCII tracing code we just 
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   946
added to @code{scratch/first.cc}.  Notice that we only passed the string
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   947
``first,'' and not ``first.pcap'' or something similar.  This is because the 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   948
parameter is a prefix, not a complete file name.  The helper will actually 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   949
create a trace file for every point-to-point device in the simulation.  The 
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   950
file names will be built using the prefix, the node number, the device number
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   951
 and a ``.pcap'' suffix.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   952
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   953
In our example script, we will eventually see files named ``first-0-0.pcap'' 
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   954
and ``first.1-0.pcap'' which are the pcap traces for node 0-device 0 and 
3348
fe47da29d783 cleaning up tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3343
diff changeset
   955
node 1-device 1, respectively.
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   956
3355
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   957
Once you have added the line of code to enable pcap tracing, you can run the
ea06eff669b3 some final tweaks to the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3354
diff changeset
   958
script in the usual way:
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   959
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   960
@verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   961
  ./waf --run scratch/first
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   962
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   963
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   964
If you look at the top level directory of your distribution, you should now
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   965
see three log files:  @code{first.tr} is the ASCII trace file we have 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   966
previously examined.  @code{first-0-0.pcap} and @code{first-1-0.pcap}
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   967
are the new pcap files we just generated.  
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   968
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   969
@subsubsection Reading output with tcpdump
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   970
@cindex tcpdump
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   971
The easiest thing to do at this point will be to use @code{tcpdump} to look
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   972
at the @code{pcap} files.  Output from dumping both files is shown below:
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   973
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   974
@verbatim
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   975
  ~/repos/ns-3-dev > /usr/sbin/tcpdump -r first-0-0.pcap -nn -tt
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   976
  reading from file first-0-0.pcap, link-type PPP (PPP)
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   977
  2.000000 IP 10.1.1.1.49153 > 10.1.1.2.9: UDP, length 1024
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   978
  2.514648 IP 10.1.1.2.9 > 10.1.1.1.49153: UDP, length 1024
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   979
  ~/repos/ns-3-dev > /usr/sbin/tcpdump -r first-1-0.pcap -nn -tt
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   980
  reading from file first-1-0.pcap, link-type PPP (PPP)
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   981
  2.257324 IP 10.1.1.1.49153 > 10.1.1.2.9: UDP, length 1024
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   982
  2.257324 IP 10.1.1.2.9 > 10.1.1.1.49153: UDP, length 1024
3354
f11e4def3fc4 tweak, tweak the tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents: 3351
diff changeset
   983
  ~/repos/ns-3-dev >
3332
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   984
@end verbatim
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   985
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   986
You can see in the dump of ``first-0.0.pcap'' (the client device) that the 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   987
echo packet is sent at 2 seconds into the simulation.  If you look at the
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   988
second dump (of ``first-1-0.pcap'') you can see that packet being received
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   989
at 2.257324 seconds.  You see the packet being echoed at 2.257324 seconds
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   990
in the second dump, and finally, you see the packet being received back at 
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   991
the client in the first dump at 2.514648 seconds.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   992
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   993
@subsubsection Reading output with Wireshark
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   994
@cindex Wireshark
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   995
If you are unfamilar with Wireshark, there is a web site available from which
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   996
you can download programs and documentation:  @uref{http://www.wireshark.org/}.
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   997
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   998
Wireshark is a graphical user interface which can be used for displaying these
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
   999
trace files.  If you have Wireshark available, you can open each of the trace
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
  1000
files and display the contents as if you had captured the packets using a
da67e8efa347 swap in new tutorial
Craig Dowell <craigdo@ee.washington.edu>
parents:
diff changeset
  1001
@emph{packet sniffer}.