1 NS-2: the network simulator 15 September 2005 Network Lab., SNU Changjee Joo

2 Contents Introduction Basic TCL script Getting started OTcl Linkage Basic network elements Summary

3 1. Introduction Based on NS version 2.26 Fonts  Bold Courier Tcl/otcl codes or screen display  Arial C++ codes  Italic Arial Directory path or file name

4 Duality: C++ and OTcl  Object-Oriented Reusability, Maintainability Careful planning ahead  C++ Fast to run, slower to change Protocol implementation Packet processing  OTcl Slower to run, fast to change Configuration Manipulate existing C++ object C++ otcl

5 tcl8.0 otcl tclcl ns-2 Event Scheduler Network Component C++ and otcl linkage (Interpreter) Discrete Event Scheduler Object-Oriented support

6 ns-allinone tcl8.3.2otcl-1.0a8ns-2.26 commontcl lib ex test … tools… nam-1.9tclcl-1.0b13… Directories tcl/otcl library example scripts validation test Directory for core C++ codes represented as “ $ns” otcl linkage

7 Contents Introduction Basic TCL script Getting started OTcl Linkage Basic network elements Summary

8 2. Basic TCL script Tcl/Tk, OTcl  For ns, you do not need to know Tcl in depth Comments – ‘ # ’ Variable – ‘ $ ’  All data types are stored in string  Use ‘ expr ’ command for calculation  Use ‘ global ’ for global variables Array – ‘ A(B) ’  2-dimensional – ‘ A(1,2) ’

9 Control statements  if {$x < 10} {…} elseif {$x == 10} {…} else {…}  switch $x { 1 {…} 2 {…} }  for {set x 1} {$x <= 5} {incr x} {…}  foreach y $x {…$y…}  while {$x < 10} {…} Output/Input  puts “…$x…”  puts [format “%d-th element” $x]  scan “…” “$d $f…” a b c

10 User defined function  proc multiply { a b } { return [expr $a*$b]}  puts “[multiply 3 4]” String commands  compare, first, index, last, length, match, range, …  append append x “0” List commands  set x {apple orange {banana mango}}  lappend, concat, split, llength, lindex, lsearch,…

11 File I/O commands  open, close, puts, gets, read, eof, flush, … Materials  프로그램 세계 1997 년 11 월, 12 월  Find above commands in/at Any Tcl/Tk book – Tutorial & Free book !!

12 Contents Introduction Basic TCL script Getting started OTcl Linkage Basic network elements Summary

13 3. Getting started “Hello World” example hello_world.tcl set ns [new Simulator] $ns at 1 “puts \“Hello World!\”” $ns at 2.5 “exit” $ns run Hello World % ns hello_world.tcl Hello World! %

14 basic_ex.tcl set ns [new Simulator] set n0 [$ns node] set n1 [$ns node] $ns duplex-link $n0 $n1 10Mb 2ms DropTail set udp0 [new Agent/UDP] $ns attach-agent $n0 $udp0 set cbr0 [new Application/Traffic/CBR] $cbr0 attach-agent $udp0 set null0 [new Agent/Null] $ns attach-agent $n1 $null0 $ns connect $udp0 $null0 $ns at 1.0 “$cbr0 start” $ns run Basic network simulation example

15 1) Create simulator instance (scheduler) set ns [new Simulator] set n0 [$ns node] set n1 [$ns node] $ns duplex-link $n0 $n1 10Mb 2ms DropTail set udp0 [new Agent/UDP] $ns attach-agent $n0 $udp0 set cbr0 [new Application/Traffic/CBR] $cbr0 attach-agent $udp0 set null0 [new Agent/Null] $ns attach-agent $n1 $null0 $ns connect $udp0 $null0 $ns at 1.0 “$cbr0 start” $ns run scheduler

16 2) Create network topology n0 n1 set ns [new Simulator] set n0 [$ns node] set n1 [$ns node] $ns duplex-link $n0 $n1 10Mb 2ms DropTail set udp0 [new Agent/UDP] $ns attach-agent $n0 $udp0 set cbr0 [new Application/Traffic/CBR] $cbr0 attach-agent $udp0 set null0 [new Agent/Null] $ns attach-agent $n1 $null0 $ns connect $udp0 $null0 $ns at 1.0 “$cbr0 start” $ns run 10Mb 2ms scheduler

17 3) Stack up protocol (agent) and application for sender set ns [new Simulator] set n0 [$ns node] set n1 [$ns node] $ns duplex-link $n0 $n1 10Mb 2ms DropTail set udp0 [new Agent/UDP] $ns attach-agent $n0 $udp0 set cbr0 [new Application/Traffic/CBR] $cbr0 attach-agent $udp0 set null0 [new Agent/Null] $ns attach-agent $n1 $null0 $ns connect $udp0 $null0 $ns at 1.0 “$cbr0 start” $ns run n0 n1 10Mb 2ms udp0cbr0 scheduler

18 4) Stack up protocol (agent) for receiver and make a connection set ns [new Simulator] set n0 [$ns node] set n1 [$ns node] $ns duplex-link $n0 $n1 10Mb 2ms DropTail set udp0 [new Agent/UDP] $ns attach-agent $n0 $udp0 set cbr0 [new Application/Traffic/CBR] $cbr0 attach-agent $udp0 set null0 [new Agent/Null] $ns attach-agent $n1 $null0 $ns connect $udp0 $null0 $ns at 1.0 “$cbr0 start” $ns run n0 n1 10Mb 2ms udp0cbr0null0 scheduler

19 5) Schedule event and run the Scheduler set ns [new Simulator] set n0 [$ns node] set n1 [$ns node] $ns duplex-link $n0 $n1 10Mb 2ms DropTail set udp0 [new Agent/UDP] $ns attach-agent $n0 $udp0 set cbr0 [new Application/Traffic/CBR] $cbr0 attach-agent $udp0 set null0 [new Agent/Null] $ns attach-agent $n1 $null0 $ns connect $udp0 $null0 $ns at 1.0 “$cbr0 start” $ns run n0 n1 scheduler 10Mb 2ms udp0cbr0null0at 1.0 cbr0 start

20 How does it work with the scheduler ?  At time 0 n0 n1 Scheduler 10Mb 2ms udp0cbr0null0at 1.0 cbr0 start

21  At time 1.0 n0 n1 Scheduler time 1.0 cbr0 start 10Mb 2ms udp0cbr0null0at forward packet Control or command Packet move or function call

22  At time n0 n1 Scheduler time forward packet 10Mb 2ms udp0cbr0null0

23  Revisit time 1.0 n0 n1 Scheduler time 1.0 cbr0 start 10Mb 2ms udp0cbr0null0at forward packet at 1.01 cbr0 send another packet

24 Tracing with “trace-all” basic_ex.tcl set ns [new Simulator] $ns trace-all [open out.tr w] $ns namtrace-all [open out.nam w] set n0 [$ns node] set n1 [$ns node] $ns duplex-link $n0 $n1 10Mb 2ms DropTail set udp0 [new Agent/UDP] $ns attach-agent $n0 $udp0 set cbr0 [new Application/Traffic/CBR] $cbr0 attach-agent $udp0 set null0 [new Agent/Null] $ns attach-agent $n1 $null0 $ns connect $udp0 $null0 $ns at 1.0 “$cbr0 start” $ns run

25 trace-all  “out.tr” tcp r tcp …  Use $ns/bin/raw2xg to see packet’s input/output to links

26 namtrace-all  “out.nam” l –t * -s 0 –d 1 –p tcp –e 40 –c 0 –i 0 –a 0 –x {…} + -t 1 –s 0 –d 1 –p tcp –e 40 –c 0 –i 0 –a 0 –x {…} …  To visualize nodes/links/packets

27 What are we expecting from simulation?  Packet movements on links or network visualization Can use trace-all or namtrace-all  Internal operation network components, such as protocols at end-hosts and routers Require general methods to access C++ objects => OTcl linkage Not suitable for simulation of large network  Increase simulation time significantly  Result in huge output file

28 Contents Introduction Basic TCL script Getting started OTcl Linkage Basic network elements Summary

29 4. OTcl Linkage Important otcl linkages  Class TclClass  Class TclObject  Class Tcl Hierarchical structure of classes Other linkages  Class TclCommand  Class InstVar

30 How to connect two spaces ? basic_ex.tcl ……… set cbr0 [new Application/Traffic/CBR] $cbr0 attach-agent $udp0 $cbr0 set rate $cbr0 set packetSize_ 1000 ……… C++ otcl cbr_traffic.cc class CBR_Traffic : public TrafficGenerator { public: CBR_Traffic( ); protected: double rate_; ……… } HOW ?

31 Basic structure of C++ elements Class definition Define TclClass Connection to “construction function” TclObject: binding method Connection to “variables” TclObject: command method Connection to “functions” Class body

32 Example of C++ elements (CBR Traffic ) $ns/tools/cbr_traffic.cc class CBR_Traffic : public TrafficGenerator { public: CBR_Traffic(); protected: ……… } static class CBRTrafficClass : public TclClass { public: CBRTrafficClass() : TclClass(“Application/… ……… } CBR_Traffic::CBR_Traffic() { ……… } Class definition TclClass Class body

33 Class TclClass TclClass  Connect C++ and Tcl objects TclClass Tcl object Application/ Traffic/CBR Defined in C++ space Defined in Tcl space / Automatically generated CBRTrafficClass C++ object CBR_Traffic

34  C++ virtual class Construct interpreted class to mirror compiled class Method to instantiate new compiled objects $ns/tools/cbr_traffic.cc static class CBRTrafficClass : public TclClass { public: CBRTrafficClass() : TclClass(“Application/Traffic/CBR”) {} TclObject* create(int, const char* const) { return (new CBR_Traffic()); } } class_cbr_traffic; Object name in Tcl space Instantiate new TclObject Invoke the constructor

35  Initiating new instance Make shadow object in Tcl space Call TclClass for constructor of c++ object Make c++ object Return to Tcl basic_ex.tcl ……… set cbr0 [new Application/Traffic/CBR] $cbr0 attach-agent $udp0 $cbr0 set rate $cbr0 set packetSize_ 1000 ……… otcl

36 Tcl object Application/ Traffic/CBR rate_ packetSize_ maxpkts_ Class TclObject Connect variables  Between C++ and Tcl objects  Two methods – binding and command CBRTrafficClass TclClass C++ object CBR_Traffic rate_ size_ maxpkts_ binding

37 Variable bindings  Five data types real, integer, bandwidth, time, boolean  Set/get value of C++ variable from Tcl

38  Usually defined in constructor $ns/tools/cbr_traffic.cc CBR_Traffic::CBR_Traffic() : seqno_(0) { bind_bw(“rate_”, &rate_); bind(“random_”, &random_); bind(“packetSize_”, &size_); bind(“maxpkts_”, &maxpkts_); } Keyword used in the interpreter (otcl) Variable used in compiled (C++) object

39  Variable access from Tcl basic_ex.tcl Application/Traffic/CBR set maxpkts_ 1000 set cbr0 [new Application/Traffic/CBR] #set value of bound variables $cbr0 set rate_ 1Mb $cbr0 set random_ 1 $cbr0 set packetSize_ 500 #get value of bound variable puts “[$cbr0 set rate_]” Bound keyword in compiled (C++) object

40  Initiation Default variables are in $ns/tcl/lib/ns-default.tcl set to default values when created If not initiated, you will see a warning after compilation (but it may still work) $ns/tcl/lib/ns-default.tcl ……… Application/Traffic/CBR set rate_ 448Kb Application/Traffic/CBR set packetSize_ 210 Application/Traffic/CBR set random_ 0 Application/Traffic/CBR set maxpkts_ ………

41  Ex) Periodic variable probing proc_ex.tcl set ns [new Simulator] ……… proc procedure { } { global ns x set now [$ns now] puts “Value from x = [$x set value_]” $ns at [expr $now + 1] “procedure” } $ns at 1 “procedure” $ns run

42 Variable tracing  Automatic record when the bound value changes Without explicit probing  Restrictions Variable must be visible in Tcl : bound variable, Tcl instance variable Variable must belongs to a kind of trace class: TracedVar, TracedInt, TracedDouble Require Tracer: generic tracer, object-specific tracer

43  How to trace set tracer_ [new Trace/Var] set tracefile [open FILENAME w] $tracer_ attach $tracefile $OBJECT trace VARNAME $tracer_  Ex) Trace cwnd_ of TCP set tracer_ [new Trace/Var] $tracer_ attach [open FILENAME w] $tcp0 trace cwnd_ $tracer_ (or $tcp0 trace cwnd_) TracedDouble cwnd_..... bind(“cwnd_”, &cwnd);

44  Tracer output (contents in FILENAME) ……… f t a_0128 nVARNAME v f t a_0128 nVARNAME v f t a_0128 nVARNAME v ……… Use script language to reform data: Tcl, awk

45 Command Method  Limitation of Variable binding (or tracing) Good for accessing variables How to access to function (or method) of the C++ object ?  Provide more generalized access  No initialization (no default value)  With help of Class Tcl

46  Special function “command” Override “command” of parent class $ns/tools/cbr_traffic.cc int CBR_Traffic::command(int argc, const char*const* argv) { Tcl& tcl = Tcl::instance(); if (argc == 3) { If(strcmp(argv[1], “pkt_size”) == 0) { size_ = atoi(argv[2]); tcl.retultf(“%d”, size_); return TCL_OK; } return (TrafficGenerator::command(argc, argv)); } ? argv[0], argv[1] Pass a value to interpreter Must return TCL_OK or TCL_ERROR If not matched, invoke parent’s command method

47  How to use command method command of compiled object is invoked set “size_” to 500 print 500 to Tcl by result() Return to Tcl *.tcl set cbr0 [new Application/Traffic/CBR] puts “packet size is [$cbr0 pkt_size 500]”

48 Summary of Class TclObject How to Set/Get value of variable  Variable binding Connect variables of C++ and Tcl  Variable tracing Automatic record of bound variables  Command method Provide generalized access to variable and function Override command method of parent’s class

49 Class Tcl Predefined communication channel from C++  Obtain a reference Tcl& tcl = Tcl::instance();  Invoking otcl procedures tcl.eval(char*) tcl.eval(const char*) tcl.evalf()  Passing results to/from the Interpreter tcl.result(const char*) tcl.result()

50 Passing value from interpreter EX) invoking otcl procedure Tcl& tcl = Tcl::instance(); tcl.evalc(“Simulator set NumberInterface_”); char* ni = tcl.result(); if (atoi(ni) != 1) tcl.evalc(“Simulator set NumberInterfaces_ 1”); Invoke otcl procedure Obtain a reference Invoke otcl procedure

51 Class TclCommand Used for top-level commands  such as ns-version, ns-random  Defined in $ns/common/misc.cc other top-level commands You can put a new top-level command  EX ) “say_hello” in the ns-document

52 $ns/common/misc.cc class say_hello : public TclCommand { public: say_hello() : TclCommand(“hi”) {} int command(int argc, const char*const* argv) { cout << “hello world\n”; return TCL_OK; } … void init_misc(void) { … (void) new say_hello; } % hi hello world % Keyword to invoke Print out “hello world” Register as top-level command

53 Contents Introduction Basic TCL script Getting started OTcl Linkage Basic network elements Summary

54 5. Basic network elements Node Link Queue

55 Node Node basics  Class Node Standalone class in otcl Most components are TclObjects  Creating set ns [new Simulator] $ns node  Basic structure Address & Port classifier Address or ID, list of neighbors, list of agents, type identifier, routing module

56 Structure of (unicast) node

57 Classifier  Examine the incoming packet’s field, map it to an outgoing interface object (or slot number)  Many different kinds of classifier Class Classifier Class AddressClassifier Class MCastClassifier Class MultiPathForwarder Class HashClassifier Class Replicator …

58 Link Link Basics  Class Link Standalone in otcl Class SimpleLink: point-to-point link  Creating set ns [new Simulator] $ns simplex-link  Basic structure Sequence of connectors Variables: head_, queue_, link_, ttl_, drophead_

59 Connector  Operations (unlike classifier) Receive a packet Perform some functions Deliver the packet to neighbor, or drop the packet  Queues, DelayLink, TTLChecker, DynaLink, … queue_ drophead_ link_ttl_rcvT_ drpT_ deqT_enqT_ head_ Class Link

60 Class LinkDelay  Present time required to traverse a link (packet size) / (link speed in bps) + (propagation delay) Schedule two events  Derived from class Connector see $ns/link/delay.cc queue_ drophead_ link_ttl_rcvT_ drpT_ deqT_enqT_ head_

61 Queue Packet scheduling and queue management  Support for FIFO, RED, CBQ, FQ, SFQ, DRR Class Queue  Inherit class Connector  Virtual functions of enque and deque  Queue blocking Simulate transmission time Blocked / unblocked by downstream neighbor queue_ drophead_ link_ttl_rcvT_ drpT_ deqT_enqT_ head_

62 n0 n1 10Mb 2ms 0 1 queue_ drophead_ link_ttl_ classifier_ demux_ head_ entry_ 0 1 classifier_ demux_ entry_ Link(n1:n0) Link(n0:n1) Example 1: Create topology

63 n0 n1 10Mb 2ms tcp0ftp0sink0 0 1 classifier_ demux_ entry_ 0 1 classifier_ demux_ entry_ Link(n1:n0) Link(n0:n1) 0 0 tcp0 ftp0 sink0 Example 2: Attach agents

64 Example 3: Transmit packets 0 1 classifier_ demux_ entry_ 0 1 classifier_ demux_ entry_ Link(n1:n0) Link(n0:n1) 0 0 tcp0 ftp0 sink0

65 Contents Introduction Basic TCL script Getting started OTcl Linkage Basic network elements Summary

66 NS Class Hierarchy TclTclObject NsObject Classifier AddrClassifier McastClassifier Replicator … Connector Delay Queue Agent Trace … TclClassTclCommandHandler TimerHandler 6. Summary

67 Resources  NS official document See also $ns/doc  Polly Hwang’s WEB page She worked with the VINT project (ns) Many valuable figures come from her presentation  Other resources

68 Thank you Any Questions ? Ask the class TA for further questions

69 Appendix

70 Periodic probing vs. Variable tracing  What kind of data do you want?  Periodic probing Sampled values Time averaging  Variable tracing Show detailed changes Event averaging

71 Hierarchical structure of classes Class hierarchy TclObject NsObject Connector Classifier DelayAddrClassifierAgentMcastClasifierQueueTrace DropTailREDTCPEnqDeqDrop RenoSACK

72 Class hierarchy and object shadowing TclObject Agent Agent/TCP TclObject Agent TcpAgent Agent/TCP otcl shadow object TcpAgent C++ object otcl class hierarchyC++ class hierarchy $tcp0O23_

 Creation TCP C++ object and its shadow object Agent/TCP constructor TclObject (C++) constructor Agent (otcl) constructor Agent (C++) constructor TclObject (otcl) constructor TcpAgent constructor Invoke parent Complete initialization Invoke parent Complete initialization Create C++ object Create otcl shadow object Invoke parent Bind variables Invoke parent Bind variables Do nothing Return otcl C++

74  Ex) CBR command Method $cbr pkt_size 10 match ? run otcl procedure TclObject::unknown { } $cbr cmd pkt_size 10 CBR_Traffic::command { } match ? run C++ procedure invoke parent’s command { } return N N Y Y C++

75 Scheduler Event-driven scheduler  Single-thread A single event is in execution at a time After execution, take the next earliest event  Schedulers List Heap Calendar Queue (default) Real-Time Event structure Class Event { Public: Event* next_, prev_; Handler* handler_; double time_; scheduler_uid_t uid_; Event(): time_(0), uid_(0) { } };

76 Class Simulator’s Methods  Scheduling Simulator instproc at args Simulator instproc run args Simulator instproc now Simulator instproc halt see $ns/tcl/lib/ns-lib.tcl for others  Create and manage topology Manage nodes and links  Perform tracing