ns-2 Tutorial (2)

Multimedia Networking Group,

The Department of Computer Science, UVA
Jianping Wang

Jianping Wang, 2004 cs757 1

Contents:
• Objectives of this week
• What is ns-2?
• Working with ns-2
• Tutorial exercise
• ns-2 internals
• Extending ns-2
Today

Jianping Wang, 2004 cs757 2

1
 ns-2 Internals

Jianping Wang, 2004 cs757 3

Internals
• Discrete Event Scheduler
• Network Topology
• Routing
• Transport
• Application
• Packet Flow
• Packet Format
Jianping Wang, 2004 cs757 4

2
Discrete Event Scheduler Data Path

handler_ ->
time_, uid_, next_, handler_ handle()

Network
Object
head_ ->

Data Path
Event
Scheduler

insert handler_ ->

handle()
time_, uid_, next_, handler_ Network
Object

Jianping Wang, 2004 cs757 5

Data Path

Class Hierarchy (Partial)

TclObject

Other
Objects
NsObject

Connector Classifier

Queue Delay Agent Trace AddrClassifier McastClasifier

DropTail RED TCP Enq Dnq Drop

Reno SACK
Jianping Wang, 2004 cs757 6

3
 Network Topology - Node
n0 n1

Port
Classifier
Unicast Multicast dmux_

Addr Node Node classifier_

Classifier
Node entry Node entry
dmux_
entry_ entry_ Multicast
classifier_ Classifier

multiclassifier_

Jianping Wang, 2004 cs757 7

Network Topology - Link

n0 n1

n1
head_ entry_
enqT_ queue_ deqT_ link_ ttl_

drophead_ drpT_

Jianping Wang, 2004 cs757 8

4
 Routing
n0 n1

Port
Classifier
Addr
Classifier
Node entry n1
0 dmux_ head_ entry_
enqT_ queue_ deqT_ link_ ttl_
entry_ 1
classifier_ drophead_ drpT_

Jianping Wang, 2004 cs757 9

Routing (cont.)
n0 n1

Port Port
Classifier Classifier
Addr Addr
Classifier Classifier
0 dmux_ 1 dmux_
Link n0-n1
entry_ 1 entry_ 0
classifier_ classifier_

Link n1-n0

Jianping Wang, 2004 cs757 10

5
 Transport
n0 n1

Port Port
Classifier dst_=1.0 Classifier dst_=0.0
Addr Agent/TCP Addr Agent/TCPSink
Classifier 0 Classifier 0
agents_ agents_
0 dmux_ 1 dmux_
Link n0-n1
entry_ 1 entry_ 0
classifier_ classifier_

Link n1-n0

Jianping Wang, 2004 cs757 11

Application
n0 n1

Port Application/FTP Port

Classifier dst_=1.0 Classifier dst_=0.0
Addr Agent/TCP Addr Agent/TCPSink
Classifier 0 Classifier 0
agents_ agents_
0 dmux_ 1 dmux_
Link n0-n1
entry_ 1 entry_ 0
classifier_ classifier_

Link n1-n0

Jianping Wang, 2004 cs757 12

6
 Packet Flow
n0 n1

Port Application/FTP Port

Classifier dst_=1.0 Classifier dst_=0.0
Addr Agent/TCP Addr Agent/TCPSink
Classifier 0 Classifier 0
0 1
Link n0-n1
entry_ 1 entry_ 0

Link n1-n0

Jianping Wang, 2004 cs757 13

Packet Format
ts_
cmn header
header ptype_
ip header
data uid_
tcp header
size_
rtp header
iface_
trace header
...
Jianping Wang, 2004 cs757 14

7
 OTcl and C++: The Duality

Pure C++ Pure OTcl

objects objects

C++/OTcl split objects

C++ OTcl

ns2
Jianping Wang, 2004 cs757 15

C++/OTcl Linkage
Root of ns-2 object hierarchy
bind(): link variable values between
TclObject C++ and OTcl
command(): link OTcl methods to C++
implementations
Create an OTcl object, and create a
TclClass linkage between the OTcl object and
C++ Object
Tcl C++ methods to access Tcl interpreter
TclCommand Standalone global commands

EmbeddedTcl ns script initialization

Jianping Wang, 2004 cs757 16

8
 TclObject
• Basic hierarchy in ns for split objects
• Mirrored in both C++ and OTcl
• Example
set tcp [new Agent/TCP]

Jianping Wang, 2004 cs757 17

TclObject: Hierarchy and Shadowing

C++ class
TclObject OTcl class TclObject
hierarchy hierarchy

Agent Agent

Agent/TCP TcpAgent

_o123 *tcp
Agent/TCP OTcl Agent/TCP C++
shadow object object

Jianping Wang, 2004 cs757 18

9
 TclClass
C++ Static classTcpClass
mirroring
Static class TcpClass
OTcl ::public
publicTclClass
TclClass{{
public:
public:
TclObject TclObject
TcpClass()
TcpClass() ::TclClass(“Agent/TCP”)
TclClass(“Agent/TCP”){}{}
TclObject*create(int,
TclObject* create(int,const
constchar*const*)
char*const*){{
return
return (new TcpAgent());
(new TcpAgent());
NsObject ??
}}
}}class_tcp;
class_tcp;
Agent Agent

TcpAgent Agent/TCP

Jianping Wang, 2004 cs757 19

The Creation of New Object

static class_tcp
ns starts TcpClass

OTcl
Agent/TCP
new Agent/TCP
TcpClass::create() C++
TCPAgent

Jianping Wang, 2004 cs757 20

10
 TclObject::bind()
• Link C++ member variables to OTcl object
variables
• C++
TcpAgent::TcpAgent() {
bind(“window_”, &wnd_);
… …
}
– bind_time(), bind_bool(), bind_bw()
• OTcl
set tcp [new Agent/TCP]
$tcp set window_ 200
Jianping Wang, 2004 cs757 21

Initialization of Bound Variables

• Initialization through OTcl class variables
Agent/TCP set window_ 50
• Do all initialization of bound variables in
~/ns-2.1b8/tcl/lib/ns-default.tcl
– Otherwise a warning will be issued when the
shadow object is created

Jianping Wang, 2004 cs757 22

11
 TclObject::command()
• OTcl
set tcp [new Agent/TCP]
$tcp advance 10
• C++
int TcpAgent::command(int argc,
const char*const* argv) {
if (argc == 3) {
if (strcmp(argv[1], “advance”) == 0) {
int newseq = atoi(argv[2]);
……
return(TCL_OK);
}
}
return (Agent::command(argc, argv);
}
Jianping Wang, 2004 cs757 23

TclObject::command()
OTcl space
no such
$tcp send TclObject::unknown{} $tcp cmd send
procedure

C++ space
TcpAgent::command()

Yes match No
“send”?

process and return Invoke parent:

return Agent::command()

Jianping Wang, 2004 cs757 24

12
 Extending ns-2

Jianping Wang, 2004 cs757 25

ns Directory Structure
ns-allinone

Tcl8.3.2 TK8.3.2 OTcl tclcl ns-2.1b8 nam-1

tcl ... C++ code

ex test lib mcast ...

examples validation tests

OTcl code

Jianping Wang, 2004 cs757 26

13
 Two ways to Extend ns-2
OTcl or C++?
• OTcl
– Simple Configuration, Setup, Scenario
– If it’s something that can be done without
modifying existing Tcl module.
• C++
– Anything that requires processing each packet
– Needs to change behavior of existing module

Jianping Wang, 2004 cs757 27

Ping Protocol

1 (send echo)
Time

Ping Agent 2
Ping Agent 1

0 (send echo)
Time

Jianping Wang, 2004 cs757 28

14
 What to extend?
• Create a new header object to store
– Type of message (request or echo)
– Timestamp
• Extend the Agent object
– Implement methods
• command()
• recv()
• Create the Otcl object
– Implement the recv{} procedure
Jianping Wang, 2004 cs757 29

The new header for ping

• A Header is required by the new protocol, since

new information needs to travel.
• Information to store
struct hdr_ping {
char ret;
double send_time;
};

• Header object
static class PingHeaderClass : public PacketHeaderClass {
public:
PingHeaderClass() : PacketHeaderClass("PacketHeader/Ping",
sizeof(hdr_ping)) {}
} class_pinghdr;

Jianping Wang, 2004 cs757 30

15
 Register Ping Header
enum packet_t {
PT_TCP,
……
PT_PING
PT_NTYPE // this must be the last one
};

class p_info {
p_info() {
name_[PT_TCP] = “tcp ”;
……
name_[PT_PING ] = “ping ”;
name_[PT_NTYPE] = “undefined ”;
}
};

Add to ns-allinone~/ns2-2.1b8/packet.h
foreach prot {
AODV
……
Ping
}{
add-packet-header $prot
}

Add to ns-allinone~/ns2-2.1b8/tcl/lib/ns-packet.tcl
Jianping Wang, 2004 cs757 31

Ping Header in PingAgent

cmn header
header
ip header
data offset: off_ping_
tcp header

...

ping header
...
Jianping Wang, 2004 cs757 32

16
 Class Hierarchy
TclObject

NsObject

Connector Classifier

Queue Delay Agent Trace AddrClassifier McastClasifier

DropTail RED TCP Enq Dnq Drop

Reno SACK PingAgent

Jianping Wang, 2004 cs757 33

Ping Agent - overview

• class PingAgent
– PingAgent()
– recv() PingAgent Agent/Ping
– send()
command(): send
– command()
• send {send()} C++ otcl

• TclClass(“Agent/Ping”) set msg [new Agent/Ping]

$msg send

Jianping Wang, 2004 cs757 34

17
 Agent Ping (1/4)
• The Class
static class PingClass : public TclClass {
public:
PingClass () : TclClass("Agent /Ping") {}
TclObject * create(int, const char*const*) {
return (new PingAgent());
}
} class_ping;

• Constructor for the class 'PingAgent' binds

the variables which have to be accessed both
in Tcl and C++
PingAgent::PingAgent () : Agent(PT_PING)
{
bind("packetSize _", &size_);
bind("off_ping_", &off_ping_);
Jianping
} Wang, 2004 cs757 35

Agent Ping (2/4)

• Implementing the command() method
int PingAgent::command(int argc, const char*const* argv)
{
if ( argc == 2) {
if (strcmp(argv[1], "send") == 0) {
// Create a new packet
Packet* pkt = allocpkt();
// Access the Ping header for the new packet:
hdr_ping * hdr = (hdr_ping*)pkt->access(off_ping_);
// Set the 'ret' field to 0, so the receiving node knows
// that it has to generate an echo packet
hdr->ret = 0;
// Store the current time in the 'send_time' field
hdr->send_time = Scheduler::instance().clock();
// Send the packet
send(pkt , 0);
// return TCL_OK, so the calling function knows that the
// command has been processed
return (TCL_OK);
}
}
// If the command hasn't been processed by PingAgent()::command,
// call the command() function for the base class
return ( Agent::command(argc , argv));
}Jianping Wang, 2004 cs757 36

18
 Agent Ping (3/4)
• Receiving a Request Packet
void PingAgent::recv(Packet* pkt, Handler*)
{
// Access the IP header for the received packet:
hdr_ip* hdrip = (hdr_ip*)pkt->access(off_ip_);
// Access the Ping header for the received packet:
hdr_ping * hdr = (hdr_ping*)pkt->access(off_ping_);
// Is the 'ret' field = 0 (i.e. the receiving node is being pinged)?
if ( hdr->ret == 0) {
// Send an 'echo'. First save the old packet's send_time
double stime = hdr->send_time;
// Discard the packet
Packet::free(pkt);
// Create a new packet
Packet* pktret = allocpkt ();
// Access the Ping header for the new packet:
hdr_ping* hdrret = (hdr_ping *)pktret->access(off_ping_);
// Set the 'ret' field to 1, so the receiver won't send another echo
hdrret->ret = 1;
// Set the send_time field to the correct value
hdrret->send_time = stime ;
// Send the packet
send(pktret, 0);

} … continues
Jianping Wang, 2004 cs757 37

Agent Ping (4/4)

• Receiving a Confirmation Packet
else {
// A packet was received. Use tcl.eval to call the Tcl
// interpreter with the ping results.
// Note: In the Tcl code, a procedure 'Agent/Ping recv {from rtt}'
// has to be defined which allows the user to react to the ping
// result.
char out[100];
// Prepare the output to the Tcl interpreter. Calculate the round
// trip time
sprintf(out, "%s recv %d %3.1f", name(),
hdrip->src_.addr_ >> Address::instance().NodeShift_[1],
(Scheduler::instance().clock()-hdr->send_time) * 1000);
Tcl& tcl = Tcl::instance();
tcl.eval(out);
// Discard the packet
Packet::free(pkt);
}
}

Jianping Wang, 2004 cs757 38

19
 Create the Otcl object

• Add this to your main tcl simulation script.

Agent/Ping instproc recv {from rtt} {

$self instvar node_
puts "node [$node_ id] received ping answer from \
$from with round-trip -time $rtt ms."
}

Jianping Wang, 2004 cs757 39

The End

Jianping Wang, 2004 cs757 40

20