ns-3のチュートリアル - Software Defined Laboratory

チュートリアルプログラムの実行方法 †

ns-3のチュートリアルは http://www.nsnam.org/docs/tutorial/singlehtml/index.html にあります。 ns-3.20/examples/tutorial に入っているプログラムを ns-3.20/scratch に移動すると

./waf --run "xxx"

で実行できるようになります。

↑

test-runner †

utilsに入ってる何もしないプログラムです。scratchフォルダに入ってなくても実行できます。

$ ./waf --run test-runner
Waf: Entering directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
Waf: Leaving directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
'build' finished successfully (2.064s)

test-runnerに対してコマンドライン引数を渡すテストができます。--command-templateを使うとプログラムに引数を渡せます。%sはプログラム本体を意味します。例えばプログラムに--helpを渡したい場合は以下のようにします。

$ ./waf --run test-runner --command-template="%s --help"
Waf: Entering directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
Waf: Leaving directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
'build' finished successfully (2.075s)
Usage: /home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build/utils/ns3.20-test-runner-debug [OPTIONS]

Options:
  --help                 : print these options
  --print-test-name-list : print the list of names of tests available
  --list                 : an alias for --print-test-name-list
  --print-test-types     : print the type of tests along with their names
  --print-test-type-list : print the list of types of tests available
  --print-temp-dir       : print name of temporary directory before running
                           the tests
  --test-type=TYPE       : process only tests of type TYPE
  --test-name=NAME       : process only test whose name matches NAME
  --suite=NAME           : an alias (here for compatibility reasons only)
～省略～

↑

hello-simulator.cc †

Hello Simulatorと表示するだけのテスト用のプログラムです。

$ pwd
ns-3.20

$ cp examples/tutorial/hello-simulator.cc ./scratch/
$ ./waf --run hello-simulator
Waf: Entering directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
Waf: Leaving directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
'build' finished successfully (2.813s)
Hello Simulator

gdb経由でプログラムを起動する時にも--command-templateを使います。

$ ./waf --run hello-simulator --command-template="gdb %s"
Waf: Entering directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
Waf: Leaving directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
'build' finished successfully (2.087s)
GNU gdb (GDB) 7.6.50.20130728-cvs (cygwin-special)
Copyright (C) 2013 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "i686-pc-cygwin".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
<http://www.gnu.org/software/gdb/documentation/>.
For help, type "help".
Type "apropos word" to search for commands related to "word".
..
Reading symbols from /home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build/scratch/hello-simulator...done.
(gdb)

↑

first.cc †

2ノード間でPoint-to-Pointでやりとりするだけの単純なプログラムです。本家のTutorialでは http://www.nsnam.org/docs/tutorial/singlehtml/index.html#document-tweaking に記載されています。

基本的なモジュールの使い方
Loggingの使い方
コマンドラインの使い方

などが学べます。

$ cp examples/tutorial/first.cc ./scratch/test1.cc
$ ./waf --run scratch/test1.cc

とやると大本のfirst.ccに変更を加えることなく、test1.ccを修正しつついろいろ試せるので便利です。

↑

Logging †

Loggingの機能を使うとモジュール内のいろいろなメッセージを出力させて実行を追うことができるのでデバッグに便利です。

Log Levelは以下の7つが存在します。

LOG_ERROR — Log error messages (associated macro: NS_LOG_ERROR);
LOG_WARN — Log warning messages (associated macro: NS_LOG_WARN);
LOG_DEBUG — Log relatively rare, ad-hoc debugging messages (associated macro: NS_LOG_DEBUG);
LOG_INFO — Log informational messages about program progress (associated macro: NS_LOG_INFO);
LOG_FUNCTION — Log a message describing each function called (two associated macros: NS_LOG_FUNCTION, used for member functions, and NS_LOG_FUNCTION_NOARGS, used for static functions);
LOG_LOGIC – Log messages describing logical flow within a function (associated macro: NS_LOG_LOGIC);
LOG_ALL — Log everything mentioned above (no associated macro).

LogComponentEnable ("UdpEchoClientApplication", LOG_LEVEL_INFO);

のようにプログラム中で設定することもできますが、環境変数で

export NS_LOG=UdpEchoClientApplication=level_all

とやっても設定できるようです。環境変数からのアクセスはデバッグ時に便利です。

% export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func:UdpEchoServerApplication=level_all|prefix_func'

のように|prefix_funcを付けると関数名がプレフィックスとして出力されるのでよりデバッグがやりやすくなります。

ありとあらゆる情報を出したい場合には

% export 'NS_LOG=*=level_all|prefix_func|prefix_time'

を使います。 LOGの機能をデフォルトにしたい場合にはコマンドラインから

% unset NS_LOG

を実行します。

NS_LOG_COMPONENT_DEFINE ("FirstScriptExample");

はLogの機能使うために必要です。例えば

NS_LOG_INFO ("saru: Creating Topology");

をソースコードに記述して、コマンドラインから

% export NS_LOG=FirstScriptExample=info

を実行しておくと、シミュレーション実行時に「saru: Creating Topology」が出力されます。

↑

コマンドライン †

ns-3はコマンドラインを簡単に扱えるツールも提供しています。まずは↓の2行をmain関数に追加してみて下さい。

  CommandLine cmd;
  cmd.Parse (argc, argv);

コマンドラインから既に組み込まれているオプションを指定することができます。

↑

--PrintHelpは †

% ./waf --run "scratch/test1 --PrintHelp"
Waf: Entering directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
Waf: Leaving directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
'build' finished successfully (4.628s)
test1 [Program Arguments] [General Arguments]

General Arguments:
    --PrintGlobals:              Print the list of globals.
    --PrintGroups:               Print the list of groups.
    --PrintGroup=[group]:        Print all TypeIds of group.
    --PrintTypeIds:              Print all TypeIds.
    --PrintAttributes=[typeid]:  Print all attributes of typeid.
    --PrintHelp:                 Print this help message.

な感じでコマンドラインから指定できるオプションが出力されます。多分上記の記述は

$ ./waf --run "scratch/test1" --command-template="%s --PrintGlobals"

と等価です。

↑

--PrintGlobals †

グローバル変数が出力されます。おそらくコマンドラインからいろいろ設定できるのではないかと。

$ ./waf --run "scratch/test1 --PrintGlobals"
Waf: Entering directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
Waf: Leaving directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
'build' finished successfully (1.935s)
Global values:
    --RngSeed=[1]
        The global seed of all rng streams
    --RngRun=[1]
        The run number used to modify the global seed
    --SimulatorImplementationType=[ns3::DefaultSimulatorImpl]
        The object class to use as the simulator implementation
    --SchedulerType=[ns3::MapScheduler]
        The object class to use as the scheduler implementation
    --ChecksumEnabled=[false]
        A global switch to enable all checksums for all protocols

↑

--PrintGroups †

良く分からないです。

$ ./waf --run "scratch/test1 --PrintGroups"
Waf: Entering directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
Waf: Leaving directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
'build' finished successfully (1.773s)
Registered TypeId groups:
    Mobility
    Building

↑

--PrintGroup=[group] †

PrintGroupsで出力されたものをgroupに指定するとより詳細なリストが出力されます。 PrintTypeIdsとの違いやなぜNetDeviceとかが無いのかが謎です。

$ ./waf --run "scratch/test1 --PrintGroup=Mobility"
Waf: Entering directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
Waf: Leaving directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
'build' finished successfully (1.778s)
TypeIds in group Mobility:
    ns3::WaypointMobilityModel
    ns3::SteadyStateRandomWaypointMobilityModel
    ns3::RandomWaypointMobilityModel
    ns3::RandomWalk2dMobilityModel
    ns3::RandomDirection2dMobilityModel
    ns3::GridPositionAllocator
    ns3::RandomRectanglePositionAllocator
    ns3::RandomBoxPositionAllocator
    ns3::RandomDiscPositionAllocator
    ns3::UniformDiscPositionAllocator
    ns3::GaussMarkovMobilityModel
    ns3::RandomBuildingPositionAllocator
    ns3::RandomRoomPositionAllocator
    ns3::SameRoomPositionAllocator
    ns3::FixedRoomPositionAllocator

↑

--PrintTypeIds †

使えるモジュールが出力されます。

$ ./waf --run "scratch/test1 --PrintTypeIds"
Waf: Entering directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
Waf: Leaving directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
'build' finished successfully (1.778s)
Registered TypeIds:
    ns3::RealtimeSimulatorImpl
    ns3::SimulatorImpl
    ns3::Object
    ns3::ObjectBase
    ns3::RandomVariableStream
    ns3::UniformRandomVariable
    ns3::ConstantRandomVariable
    ns3::SequentialRandomVariable
    ns3::ExponentialRandomVariable
    ns3::ParetoRandomVariable
    ns3::WeibullRandomVariable
    ns3::NormalRandomVariable
    ns3::LogNormalRandomVariable
～ 省略 ～

↑

--PrintAttributes=[typeid] †

各モジュールに設定できる項目とデフォルト値を出力します。

$ ./waf --run "scratch/test1 --PrintAttributes=ns3::PointToPointNetDevice"
Waf: Entering directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
Waf: Leaving directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
'build' finished successfully (1.781s)
Attributes for TypeId ns3::PointToPointNetDevice
    --ns3::PointToPointNetDevice::Mtu=[1500]
        The MAC-level Maximum Transmission Unit
    --ns3::PointToPointNetDevice::Address=[ff:ff:ff:ff:ff:ff]
        The MAC address of this device.
    --ns3::PointToPointNetDevice::DataRate=[32768bps]
        The default data rate for point to point links
    --ns3::PointToPointNetDevice::ReceiveErrorModel=[0]
        The receiver error model used to simulate packet loss
    --ns3::PointToPointNetDevice::InterframeGap=[+0.0ns]
        The time to wait between packet (frame) transmissions
    --ns3::PointToPointNetDevice::TxQueue=[0]
        A queue to use as the transmit queue in the device.

プログラム中で設定することもできます。例えばfirst.ccだと

  PointToPointHelper pointToPoint;
  pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
  pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));

がこれに該当します。

これをコメントアウトするとコマンドラインからAttributeを設定できるようになります。

DataRateを500Mbpsに設定すると0.00001 secでパケットが届きますが...

$ ./waf --run "scratch/test1 --ns3::PointToPointNetDevice::DataRate=500Mbps"
Waf: Entering directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
Waf: Leaving directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
'build' finished successfully (1.810s)
saru: Creating Topology
At time 2s client sent 1024 bytes to 10.1.1.2 port 9
At time 2.00002s server received 1024 bytes from 10.1.1.1 port 49153
At time 2.00002s server sent 1024 bytes to 10.1.1.1 port 49153
At time 2.00003s client received 1024 bytes from 10.1.1.2 port 9

DataRateを500kbpsに設定すると届くのに0.01687 secかかるようになります。

$ ./waf --run "scratch/test1 --ns3::PointToPointNetDevice::DataRate=500kbps"
Waf: Entering directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
Waf: Leaving directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
'build' finished successfully (1.791s)
saru: Creating Topology
At time 2s client sent 1024 bytes to 10.1.1.2 port 9
At time 2.01686s server received 1024 bytes from 10.1.1.1 port 49153
At time 2.01686s server sent 1024 bytes to 10.1.1.1 port 49153
At time 2.03373s client received 1024 bytes from 10.1.1.2 port 9

↑

コマンドラインオプションの独自拡張 †

CommandLineクラスで独自のコマンドラインオプションを実装できます。例えば

  uint32_t nPackets = 1;

  CommandLine cmd;
  cmd.AddValue("nPackets", "Number of packets to echo", nPackets);
  cmd.Parse (argc, argv);

のように追加すると--nPackets=で値を渡すことができるようになります。--PrintHelpでもオプションが出るようになります。

$ ./waf --run "scratch/test1 --PrintHelp"
Waf: Entering directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
Waf: Leaving directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
'build' finished successfully (1.830s)
test1 [Program Arguments] [General Arguments]

Program Arguments:
    --nPackets:  Number of packets to echo [1]

General Arguments:
    --PrintGlobals:              Print the list of globals.
    --PrintGroups:               Print the list of groups.
    --PrintGroup=[group]:        Print all TypeIds of group.
    --PrintTypeIds:              Print all TypeIds.
    --PrintAttributes=[typeid]:  Print all attributes of typeid.
    --PrintHelp:                 Print this help message.

nPackets=2などとするとnPacketsに値を設定することができます。

$ ./waf --run "scratch/test1 --nPackets=2"
Waf: Entering directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
Waf: Leaving directory `/home/saru/2014/ns-3/ns-allinone-3.20/ns-3.20/build'
'build' finished successfully (1.843s)
saru: Creating Topology
At time 2s client sent 1024 bytes to 10.1.1.2 port 9
At time 2.25732s server received 1024 bytes from 10.1.1.1 port 49153
At time 2.25732s server sent 1024 bytes to 10.1.1.1 port 49153
At time 2.51465s client received 1024 bytes from 10.1.1.2 port 9
At time 3s client sent 1024 bytes to 10.1.1.2 port 9
At time 3.25732s server received 1024 bytes from 10.1.1.1 port 49153
At time 3.25732s server sent 1024 bytes to 10.1.1.1 port 49153
At time 3.51465s client received 1024 bytes from 10.1.1.2 port 9

↑