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

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

3. 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. 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. 5 tcl8.0 otcl tclcl ns-2 Event Scheduler Network Component C++ and otcl linkage (Interpreter) Discrete Event Scheduler Object-Oriented support

6. 6 ns-allinone- 2.26 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. 7 Contents Introduction Basic TCL script Getting started OTcl Linkage Basic network elements Summary

8. 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. 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. 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. 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 http://hegel.ittc.ukans.edu/topics/tcltk/ – Tutorial & Free book !! http://hegel.ittc.ukans.edu/topics/tcltk/ http://users.belgacom.net/bruno.champagne/tcl.html

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

13. 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. 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. 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. 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. 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. 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. 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. 20 How does it work with the scheduler ?  At time 0 n0 n1 Scheduler 10Mb 2ms udp0cbr0null0at 1.0 cbr0 start

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

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

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

24. 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. 25 trace-all  “out.tr” + 1.000032 0 1 tcp 1040 ----- 0 0.0 1.0 1 1 r 1.000232 0 1 tcp 40 ----- 0 0.0 1.0 0 0 …  Use $ns/bin/raw2xg to see packet’s input/output to links

26. 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. 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. 28 Contents Introduction Basic TCL script Getting started OTcl Linkage Basic network elements Summary

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

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

31. 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. 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. 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. 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. 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 1000000 $cbr0 set packetSize_ 1000 ……… otcl

36. 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. 37 Variable bindings  Five data types real, integer, bandwidth, time, boolean  Set/get value of C++ variable from Tcl

38. 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. 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. 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_ 268435456 ………

41. 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. 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. 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. 44  Tracer output (contents in FILENAME) ……… f t12.00128 a_0128 nVARNAME v1200203 f t12.00132 a_0128 nVARNAME v1201204 f t12.00135 a_0128 nVARNAME v1200042 ……… Use script language to reform data: Tcl, awk

45. 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. 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. 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. 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. 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. 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. 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. 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. 53 Contents Introduction Basic TCL script Getting started OTcl Linkage Basic network elements Summary

54. 54 5. Basic network elements Node Link Queue

55. 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. 56 Structure of (unicast) node

57. 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. 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. 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. 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. 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. 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. 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. 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. 65 Contents Introduction Basic TCL script Getting started OTcl Linkage Basic network elements Summary

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

67. 67 Resources  NS official document http://www.isi.edu/nsnam/ns/ns-documentation.html See also $ns/doc  Polly Hwang’s WEB page http://www.tik.ee.ethz.ch/~huang/ She worked with the VINT project (ns) Many valuable figures come from her presentation  Other resources http://www.isi.edu/nsnam/ns/

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

69. 69 Appendix

70. 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. 71 Hierarchical structure of classes Class hierarchy TclObject NsObject Connector Classifier DelayAddrClassifierAgentMcastClasifierQueueTrace DropTailREDTCPEnqDeqDrop RenoSACK

72. 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_

73.  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. 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. 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. 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