The Protocol Developer Manual for
the NCTUns 6.0 Network Simulator
and Emulator
Authors:
Prof. Shie-Yuan Wang
Chih-Liang Chou, Chih-Che Lin, and Chih-Hua Huang
Last update date: January 15, 2010
Produced and maintained by Network and System Laboratory, Department of Computer Science,
National Chiao Tung University, Taiwan
Table of Contents
Chapter 1 Overview ..................................................................... 1
1. Development History ............................................................................................. 1
1.1 Introduction .......................................................................................................... 2
1.2 Overview of the Components of NCTUns........................................................... 3
1.3 Simulation Network Description File (.tcl) ......................................................... 4
Chapter 2 Adding a New Module .............................................. 24
2.1 Register a New Module with the Simulation Engine......................................... 24
2.2 Register a New Module with the GUI Node Editor ........................................... 26
2.3 An Example of Adding a New Module .............................................................. 34
2.4 Run a Simulation Case without the Use of the GUI .......................................... 39
2.5 Formats and Usages of Simulation Description Files ........................................ 54
Chapter 3 High-level Architecture of NCTUns ......................... 70
3.1 Simulation Methodology ................................................................................... 71
3.2 Job Dispatcher and Coordinator......................................................................... 73
3.3 Simulation Engine Design ................................................................................. 74
3.4 Kernel Modifications ......................................................................................... 78
3.5 Discrete Event Simulation ................................................................................. 80
Chapter 4 Simulation Engine – S.E ........................................... 81
4.1 Architecture of the Simulation Engine ............................................................... 81
4.2 Event .................................................................................................................. 82
4.3 Scheduler............................................................................................................ 94
4.4 Dispatcher .......................................................................................................... 97
4.5 Module Manager ................................................................................................ 98
4.6 Script Interpreter .............................................................................................. 101
4.7 The NCTUns APIs ........................................................................................... 104
Chapter 5 Module-Based Platform .......................................... 105
5.1 Introduction ...................................................................................................... 105
5.2 Module Framework .......................................................................................... 107
5.3 Module Communication (M.C) ....................................................................... 116
Chapter 6 NCTUns Simulation Engine APIs .......................... 120
2
6.1 Timer APIs ....................................................................................................... 120
6.2 Packet APIs ...................................................................................................... 123
6.3 NCTUns APIs .................................................................................................. 136
6.4 Packet Transmission/Reception Log Mechanism ............................................ 155
Chapter 7 Tactical and Active Mobile Ad hoc Networks ........ 157
7.1 Introduction ...................................................................................................... 157
7.2 Tactical MANET Simulation ........................................................................... 158
7.3 Design Principles ............................................................................................. 162
7.4 Design and Implementation ............................................................................. 163
7.5 Writing a Tactical Agent .................................................................................. 167
7.6 Tactical MANET API Functions ...................................................................... 169
7.7 Five Examples .................................................................................................. 189
Chapter 8 IEEE 802.16(d) WiMAX Networks........................ 226
8.1 Introduction ...................................................................................................... 226
8.2 Protocol Stacks of IEEE 802.16 Network Nodes ............................................ 227
8.3 Simulation Description File for IEEE 802.16 Networks ................................. 232
Chapter 9 Multi-interface Mobile Node .................................. 236
9.1 Introduction ...................................................................................................... 236
9.2 The Design of the Multi-interface Network Node ........................................... 237
9.3 Exploiting Multiple Heterogeneous Network Interfaces ................................. 240
9.4 Simulation Description File for the Multi-Interface Network Node ............... 241
Reference ................................................................................. 244
3
Chapter 1 Overview
1. Development History
The NCTUns network simulator and emulator (NCTUns) is a high-fidelity and
extensible network simulator capable of simulating various devices and protocols
used in both wired and wireless networks. Its core technology is based on the
kernel-reentering simulation methodology invented by Prof. S.Y. Wang at Harvard
University in 1999 when Wang was pursuing his Ph.D. degree. Due to this novel
methodology, NCTUns provides many unique advantages that cannot be easily
achieved by traditional network simulator such as OPNET Modeler and ns-2.
The predecessor of NCTUns is the Harvard network simulator, which Wang
authored in 1999. As feedback about the Harvard network simulator came back, it
was found that the Harvard network simulator had several limitations and drawbacks
that need to be overcome and solved, and some important features and functions need
to be implemented and added to it. For these reasons, after joining National Chiao
Tung University (NCTU), Taiwan in February 2000, Prof. S.Y. Wang has been
leading his students to develop NCTUns since then.
NCTUns removes many limitations and drawbacks in the Harvard network
simulator. It uses a distributed architecture to support remote simulations and
concurrent simulations. It uses an open-system architecture to enable protocol
modules to be easily added to the simulator. In addition, it has a highly-integrated
GUI environment for editing a network topology, specifying network traffic, plotting
performance curves, configuring the protocol stack used inside a network node, and
playing back animations of logged packet transfers.
To make NCTUns run simulations quickly, Prof. S.Y. Wang invented an
approach to combine the discrete event simulation methodology and the
kernel-reentering simulation methodology. The Harvard network simulator used a
time-stepped method to implement its simulation engine. As a result, its simulation
speed is low. In contrast, using this approach, NCTUns can generate high-fidelity
simulation results at high speeds when the network traffic load is not heavy.
NCTUns was first released to the networking community on November 1, 2002.
Its web site is set up at http://NSL.csie.nctu.edu.tw/nctuns.html. As of January 12,
2010, according to the download user database, 16,246 people from 137 countries
1
have registered at the web site and downloaded it, and these numbers are still
growing.
Initially, NCTUns was developed for the FreeBSD operating system. As the
Linux operating system is getting popular, NCTUns now only supports the Linux
operating system. Specifically, the version of Linux distribution that NCTUns 6.0
currently supports is Red Hat‟s Fedora 12 with kernel version 2.6.31.6.
Although officially NCTUns only supports Fedora distribution, it is possible to
port it to other Linux distributions such as Debian or Ubuntu. This is because all
Linux distributions use the same Linux kernel and they differ only in system
configurations and settings. Some advanced Linux users have successfully ported
NCTUns to other Linux distributions and show people how to do it on their web sites.
1.1 Introduction
NCTUns is a software tool that integrates user-level processes, operating system
kernel, and the user-level simulation engine into a cooperative network simulation
system. This manual aims to provide knowledge about NCTUns to help researchers
develop their own protocol modules on top of NCTUns. The formats of various
simulation-related files are explained in this document. These simulation-related files
are used to specify and describe a complete simulation case. Normally, these files are
automatically generated by the GUI program of NCTUns without bothering the user
to manually creating them. However, sometimes it may be needed (or useful) for a
developer to create or modify these files manually.
The rest of this document is organized as follows. In Chapter 1 and Chapter 2,
we explain and show the detailed procedures for developing a protocol module,
registering it with the simulation engine, and registering it with the GUI program.
These two chapters are the most important chapters for developers. In Chapter 3, we
present the architecture of NCTUns to let a developer understand how a protocol
module works. In Chapter 4 and Chapter 5, we present the internal design and
implementation of the NCTUns simulation engine and the protocol module platform.
In Chapter 6, we provide a complete explanation of the API functions provided by the
NCTUns simulation engine. Chapter 6 is also very important to the developer. In
Chapter 7, we introduce tactic and active mobile ad hoc networks (MANET)
simulations, which are useful for studying future combat systems (FCS). The tactic
MANET API functions provided by NCTUns and five tactic examples are explained
in detail in this chapter. In Chapter 8, we explain the design, implementation, and
usage of IEEE 802.16(d) WiMAX networks and related configuration files. Finally, in
2
Chapter 9, we explain the design, implementation, and usage of multi-interface
mobile nodes, which are becoming increasingly popular.
The design, architecture, and implementation of NCTUns has been constantly
improved and changed since its initial release. As a result, some information may be
missing in this manual or some information in this manual may not reflect its latest
status. The reader is encouraged to read the many papers included in the NCTUns
package to obtain the latest information about NCTUns. Understanding the source
code of NCTUns is the best way to understand the latest design and implementation
of NCTUns. To let a user easily develop his (her) protocol modules, the source code
of all supported protocol modules is released in the NCTUns package. A user can
quickly learn how to develop a new module by learning the design and
implementation of existing modules.
1.2 Overview of the Components of NCTUns
1.2.1 Simulation Engine
NCTUns is an open-system network simulator and emulator. Through a set of
API functions provided by its simulation engine, a researcher can develop a new
protocol module and add the module into the simulation engine. The simulation
engine can be thought of as a small operating system kernel. It performs basic tasks
such as event processing, timer management, packet manipulation, etc. Its API plays
the same role as the system call interface provided by an UNIX operating system
kernel. By executing API functions, a protocol module can request services from the
simulation engine without knowing the details of the implementation of the
simulation engine.
1.2.2 Protocol Modules
NCTUns provides a module-based platform. A module corresponds to a layer in
a protocol stack. For example, an ARP module implements the ARP protocol while a
FIFO module implements the FIFO packet scheduling and buffer management
scheme. Modules can be linked together to form a protocol stack to be used by a
network device. A researcher can insert a new module into an existing protocol stack,
delete an existing module from a protocol stack, or replace an existing module in a
protocol stack with his (her) own module. Through these operations, a researcher can
control and change the behavior of a network device.
1.2.3 GUI Program
3
NCTUns provides a highly-integrated GUI program for users to conveniently
and efficiently conduct simulation studies. The GUI program contains four main
components. They are the “Topology Editor,” “Node Editor,” “Performance Monitor,”
and “Packet Animation Player,” respectively. Among these four components, the
Node Editor is relevant to module developers.
The Node Editor is a graphical tool by which a researcher can easily construct a
network device‟s protocol stack. By this tool, he (she) can easily insert, remove, or
replace a protocol module by manipulating the computer mouse. With a graphical
representation of a node‟s protocol stack, the Node Editor generates a text description
of a node‟s protocol stack and exports it to a simulation network description file
(the .tcl file). At the beginning of a simulation, the text description file will be read by
the simulation engine to construct the specified protocol stack for each simulated
node.
1.3 Simulation Network Description File (.tcl)
The output of the GUI program is a set of files that together describe and specify
the simulation job. Among these files, the file with the “.tcl” suffix is the file that
describes the relationship among the modules used inside a node (i.e., the node‟s
internal protocol stack) and the connectivity among all nodes in a network. The GUI
program generates the .tcl file automatically when a GUI user finishes drawing his
(her) network topology. Normally, it is unnecessary for a user to understand the
details of a .tcl file. However, for an advanced user, he (she) may want to understand
what a .tcl file defines and describes. The rest of this section explains the format and
meanings of a .tcl file.
A .tcl file consists of three parts. They are (1) global variable initialization, (2)
node protocol stack specification, and (3) node connectivity specification.
Global Variable Initialization
The “Set” keyword is used to set the initial value for a global variable. For
example, Set TickToNanoSec = 100 means that a variable named “TickToNanoSec” is
set to the value of “100.” Several global variables are used in NCTUns and their
meanings are explained in the following table. They need to be initialized in the .tcl
file.
Variable name
SimSpeed
Possible values
AS_FAST_AS_POSSIBLE
Meaning
This
option
indicates that the
4
simulation
engine
should
run as fast as
possible.
AS_FAST_AS_REAL_CLOCK Normally, this is
the
preferred
mode and is the
default mode.
This
option
indicates that the
simulation
engine
should
run as fast as the
real
clock.
Normally, this
mode is chosen
when the user
wants to use the
simulator as an
emulator. Note
that this mode is
effective
only
when
the
simulation
engine is able to
run
the
simulation faster
than the real
clock. In such a
case,
the
simulation
engine
can
purposely slow
down
its
simulation speed
so that its speed
matches the real
clock.
5
If
the
simulation
engine
runs
slower than the
real clock, there
is really no way
to
ask
the
simulation
engine to run as
fast as the real
clock.
This option is
also useful for
some simulation
cases.
For
example, when a
user wants to use
the
command
console function
during
a
simulation, he
(she) may want
to
purposely
slow down the
simulation
speed.
TickToNanoSec
1, 10, or 100
This
variable
specifies
the
ratio between a
virtual clock tick
and
a
nanosecond in
virtual time. The
default value is
100,
which
means that 1 tick
represents 100
nanoseconds in a
simulation.
6
Using a smaller
value for this
variable
may
increase
the
precision
of
simulation
results at the
cost of decreased
simulation
speed. As such,
it is suggested
that a small
value such as 1
should be used
only when the
simulated link
bandwidth
is
very high (e.g.,
above 1 Gbps).
WireLogFlag
on , off
This variable
specifies
whether the
simulation
engine should
turn on or off its
logging
mechanism to
log packet
transfers on
wired networks.
WirelessLogFlag
on , off
This
variable
specifies
whether
the
simulation
engine
should
turn on or off its
logging
mechanism
7
to
log
packet
transfers
on
802.11
(a/b/p)
wireless
networks.
GPRSLogFlag
on , off
This variable
specifies
whether the
simulation
engine should
turn on or off its
logging
mechanism to
log GPRS packet
transfers.
OphyLogFlag
on , off
This variable
specifies
whether the
simulation
engine should
turn on or off its
logging
mechanism to
log optical
network packet
transfers.
RandomNumberSeed
0, or any other integer
If
the
chosen
random number
seed
for
a
simulation case
is greater than 0
and
fixed,
NCTUns‟s
results
are
repeatable. This
means that no
matter
how
many
8
times
a
simulation case
is run, its results
are always the
same.
A
user
can
choose a specific
random number
seed
for
a
simulation case
in
the
GUI
program. If the
chosen number
is 0, which is
also the default
value,
the
simulation
engine
will
internally choose
a
random
number for the
random number
seed each time
when
the
simulation case
is run. This is
useful
for
studying
a
network‟s
behavior under
different
stochastic
conditions.
DynamicMovingPath
on, off
This option is
used for tactic
and
active
mobile ad hoc
network
simulations,
9
where
the
moving paths of
mobile nodes are
dynamically
generated
and
controlled by the
tactic
agents
running
on
mobile nodes. If
this option is
tuned on, the
run-time node
location
information will
be periodically
transmitted from
the simulation
engine to the
GUI so that the
GUI can update
the locations of
mobile nodes on
screen.
OnLinePacketTransmission
on, off
This option is
used for tactic
and
active
mobile ad hoc
network
simulations
If
this option is
tuned on, the
run-time wired
and
wireless
packet
transmission
informati
on
will
be
periodically
10
transmitted from
the simulation
engine to the
GUI so that the
GUI
can
graphically show
these
packet
transmissions
over linkes on
screen.
ptrLogFileName
Any file name string
If this variable
appears
in
the .tcl file, it
specifies
the
name of the file
which stores the
packet
transmission
information
needed by the
GUI program‟s
Packet
Animation
Player. If this
variable does not
appear in the .tcl
file, the default
file name will be
used, which is
XXX.ptr, where
XXX is the case
name of this
simulation case.
ObstacleFlag
on, off
If there is an
obstacle in the
field
of the
simulation case
(used by tactic
11
mobile ad hoc
networks), this
variable
will
appear in the .tcl
file with its
value set to
“on.”
PCluster
An integer, the default value is
1024.
This
variable
specifies
the
length
of
a
packet‟s memory
cluster buffer in
bytes used in the
simulation
engine.
The
default value for
this variable is
1024. If needed,
this value can be
increased.
WiFiChannelCoding
on, off
Disable
or
enable 802.11a
wireless channel
coding.
WAVEChannelCoding
on, off
Disable
or
enable 802.11p
wireless channel
coding.
WiMAXLogFlag
on, off
Disable
or
enable
the
function
of
logging
the
packet transfers
on
WiMAX
(802.16d)
networks.
WiMAXChannelCoding
on, off
12
Disable
or
enable WiMAX
(802.16d)
wireless channel
coding.
MobileWIMAXLogFlag
on, off
Disable
or
enable
the
function
of
logging
the
packet transfers
on
mobile
WiMAX
(802.16e)
networks.
MobileWIMAXChannelCoding
on, off
Disable or enable
WiMAX
(802.16e)
wireless channel
coding.
MobileRelayWIMAXLogFlag
on, off
Disable or enable
the function of
logging
the
packet transfers
on
transparent
mode
mobile
relay
WiMAX
networks
(802.16j
transparent
mode).
MobileRelayWIMAXChannel
Coding
on, off
Disable or enable
transparent mode
mobile
relay
WiMAX
(802.16j
transparent
mode) wireless
channel coding.
MR_WIMAX_NT_LogFlag
on, off
13
Disable or enable
the function of
logging
the
packet transfers
on
non-transparent
mode
mobile
relay
WiMAX
networks
(802.16j
non-transparent
mode).
MR_WIMAXChannelCoding_
NT
on, off
Disable or enable
non-transparent
mode
mobile
relay
WiMAX
(802.16j
non-transparent
mode) wireless
channel coding.
SatLogFlag
on, off
Disable
or
enable
the
function
of
logging
the
packets transfers
on
DVB-RCS
satellite
networks.
DVBChannelCoding
on, off
Disable
or
enable
DVB-RCS
satellite wireless
channel coding.
GdbStart
on, off
The
default
value for this
variable is off.
When this value
is on, every time
when
the
14
simulation
engine forks a
traffic generator
application
program, right
before and right
after the fork
operation, it will
pause and ask
the user to click
a
button
to
continue
the
simulation.
During the pause
time, the user
can start the gdb
program
to
debug
the
operations of the
simulation
engine process
and the forked
application
program. More
details about this
advanced
capability can be
referenced in the
“using_gdb_over
_nctuns5.pdf”
document, which
is located in the
doc/Debug
directory of the
NCTUns
package.
TABLE 1.3.1 THE GLOBAL VARIABLES USED AT INITIALIZATION-TIM
15
Node Protocol Stack Specification
The creation block describes the protocol stack of a node, which starts with the
“Create” keyword and ends with the “EndCreate” keyword. The first line of such a
block specifies the node ID, the type of the node, and the name of the node. The
following is an example:
Create Node 1 as HOST with name = HOST1
This statement asks the simulation engine to create a node whose node ID is 1,
type is HOST, and name is HOST1. A node‟s name is constructed by concatenating
the node‟s type with its node ID, which is unique in a simulation. To ensure
uniqueness of node IDs, different nodes use different node IDs regardless of their
types. For example, in a simulation it is impossible to have two nodes whose names
are HOST1 and ROUTER1, respectively. On the other hand, having HOST1 and
ROUTER2 or ROUTER1 and HOST2 in a simulation is possible. The node types that
are currently supported are shown in the following table:
Node Type
Explanation
HOST
An end-user computer or a workstation
that is located on a fixed network.
MOBILE
An IEEE 802.11 (b) mobile station that
operates in the ad-hoc mode
MOBILE_INFRA
An IEEE 802.11 (b) mobile station that
operates in the infrastructure mode
AP
An IEEE 802.11 (b) access point.
SWITCH
A layer-2 switch
HUB
A layer-1 hub
ROUTER
A layer-3 router
WAN
A layer-2 device that simulates the
various properties of a Wide Area
Network. This device can purposely
delay, drop, and/or reorder passing
packets according to a specified statistics
distribution.
Currently,
uniform,
exponential, and normal distributions are
supported.
EXTHOST
EXTMOBILE
An external end-user computer that is in
the real world and connected to a
16
EXTMOBILE_INFRA
EXTROUTER
simulated fixed network.
These node types are provided for
emulation purposes. In emulation, an
external real machine (not the machine
that is simulating the specified network)
can interact with any node in a simulated
network. For example, the external real
machine can set up a TCP connection to
a host in the simulated network and
exchange data with it.
To graphically specify to which node in
a simulated network an external machine
connects, each external machine is
represented
by
an
EXTHOST,
EXTMOBILE, EXTMOBILE_INFRA,
and EXTROUTER node in simulated
network. Packets generated and sent out
by the external machine will be received
by the simulation machine and from now
on can be viewed that they are generated
and sent by the EXTHOST node in the
simulated network.
An external machine must be connected
to the simulation machine via some
networks such as a 100 Mbps Fast
Ethernet cable. Also, some routing
entries and IP address settings must be
set on both the external and simulation
machines. For these details, please refer
to NCTUns‟s GUI user manual.
OPT_SWITCH
An optical switch used in an optical
circuit-switching network.
OBS_OPT_SWITCH
An optical switch used in an optical
burst switching (OBS) network.
QBROUTER
A boundary router used in a QoS
Diffserv network.
QIROUTER
An interior router used in a QoS Diffserv
network.
17
PHONE
A GPRS phone used in a GPRS network.
BS
A GPRS base station used in a GPRS
network.
SGSN
A SGSN device used in a GPRS
network.
GGSN
A GGSN device used in a GPRS
network.
GSWITCH
A GPRS pseudo switch used in a GPRS
network. SGSNs and GGSNs must use
this device to connect to each other even
though there is only one SGSN and
GGSN in the network.
QoS_AP
An IEEE 802.11 (b) access point
supporting IEEE 802.11(e) QoS MAC.
QoS_MOBILE_INFRA
An IEEE 802.11 (b) mobile station that
operates in the infrastructure mode and
supports IEEE 802.11(e) QoS MAC
MESH_OSPF_AP
A dual-radio IEEE 802.11 (b) access
point which supports wireless mesh
networks and runs OSPF as its routing
protocol in the mesh network.
MESH_STP_AP
A dual-radio IEEE 802.11 (b) access
point which supports wireless mesh
networks and runs Spanning Tree
Protocol as its routing protocol in the
mesh network.
MESHSWITCH
A switch that must be used between a
multi-gateway wireless mesh network
and the fixed Internet. In a
multi-gateway wireless mesh network,
multiple mesh access points may
connect to the Internet to provide a
higher bandwidth to the Internet. In such
a case, these mesh access points should
connect to this particular switch. Also,
the Internet should connect to this
switch.
WIMAX_PMP_BS
A base station of 802.16d WiMAX
18
networks operating in the PMP mode.
WIMAX_PMP_SS
A subscriber station of 802.16d WiMAX
networks operating in the PMP mode.
WIMAX_MESH_BS
A base station of 802.16d WiMAX
networks operating in the mesh mode
WIMAX_MESH_SS
A subscriber station of 802.16d WiMAX
networks operating in the mesh mode.
MobileWIMAX_PMPBS
A base station of 802.16e mobile
WiMAX networks operating in the PMP
mode.
MobileWIMAX_PMPMS
A mobile station of 802.16e mobile
WiMAX networks operating in the PMP
mode.
MobileRelayWIMAX_PMPBS
A
base
station
of
802.16j
transparent-mode
mobile
WiMAX
networks operating in the PMP mode.
MobileRelayWIMAX_PMPMS
A
mobile
station
of
transparent-mode
mobile
802.16j
WiMAX
networks operating in the PMP mode.
MobileRelayWIMAX_PMPRS
A
relay
station
of
802.16j
transparent-mode
mobile
WiMAX
networks operating in the PMP mode.
MR_WIMAX_NT_PMPBS
A
base
station
of
802.16j
non-transparent-mode mobile WiMAX
networks operating in the PMP mode.
MR_WIMAX_NT_PMPMS
A
mobile
station
of
802.16j
non-transparent-mode mobile WiMAX
networks operating in the PMP mode.
MR_WIMAX_NT_PMPRS
A
relay
station
of
802.16j
non-transparent-mode mobile WiMAX
networks operating in the PMP mode.
DVB_RCS_SP
The service provider of a DVB_RCS
satellite networks.
DVB_RCS_NCC
The network control center
DVB_RCS satellite networks.
DVB_RCS_RCST
The return channel satellite ternimal of a
of
a
DVB_RCS satellite networks.
DVB_RCS_GATEWAY
The traffic gateway of a DVB_RCS
19
satellite networks.
DVB_RCS_FEEDER
The feeder of a DVB_RCS satellite
networks.
DVB_RCS_SAT
The satellite of a DVB_RCS satellite
networks.
SUPERNODE
A mobile node that has multiple wireless
interfaces.
CAR_INFRA
An Intelligent Transportation System
(ITS) car that is equipped with an
802.11(b) wireless interface operating in
the infrastructure mode.
CAR_ADHOC
An Intelligent Transportation System
(ITS) car that is equipped with an
802.11(b) wireless interface operating in
the ad hoc mode.
CAR_GPRS_PHONE
An Intelligent Transportation System
(ITS) car that is equipped with a GPRS
phone raido.
CAR_RCST
An Intelligent Transportation System
(ITS) car that is equipped with a
DVB-RCS satellite raido.
WAVE_OBU
An Intelligent Transportation System
(ITS) car that is equipped with an IEEE
802.11(p)/1609 On-Board-Unit radio.
WAVE_RSU
An Intelligent Transportation System
(ITS) Road-Side-Unit that is equipped
with an IEEE 802.11(p)/1609 radio.
VIRROUTER
A virtual router used in distributed
emulations. There are two modes with a
virtual router. In the first mode, a virtual
router represents a real-world router.
However, in the second mode, a virtual
router represents no node in the real
world. For more information about
“distributed emulation,” the reader can
consult the NCTUns GUI user manual.
TABLE 1.3.2 THE NODE TYPES THAT ARE CURRENTLY SUPPORTED BY NCTUNS
20
A node can have one or multiple “ports.” The term “port” mentioned here refers
to a hardware network interface, not a transport-layer port (e.g., a TCP or UDP port)
that means a specific type of network service. For example, a host with only one
network interface has only one “port” while an 8-port switch has 8 “ports.” Therefore,
a creation block for a node is composed of one or several “port” blocks.
A port block starts with the “Define port portid” statement, where portid refers to
the ID of this port, and ends with the “EndDefine” keyword. A port block is composed
of a number of module blocks, each of which corresponds to a protocol module that
has been registered with the simulation engine.
In optical networks where a WDM optical link has several wavelength channels,
the concept of a port is extended to a two-layer structure. One can define several
subport blocks under each port block. A first-layer port corresponds to an interface of
an optical switch (router). A second-layer subport under a first-layer port corresponds
to a wavelength channel of the WDM optical link that the first-layer port connects.
The following is an example showing how to define a two-layer port structure:
Define port 1
Define port 1
EndDefine
Define port 2
EndDefine
EndDefine
// there are two subports under port 1
// first subport
// second subport
Inside a module block, there may be one or several statements that initialize the
module‟s parameters. The following is an example that initializes the parameters of a
module named “Interface”:
Module Interface : Node1_Interface_1
Set Node1_Interface_1.ip = 1.0.1.1
Set Node1_Interface_1.netmask = 255.255.255.0
A module block starts with the “Module” keyword and ends with an empty line.
The first line of this block indicates that the type of this module is “Interface,” and the
name of this module instance is “Node1_Interface_1.” Conceptually, this type/name
relationship corresponds to class/object relationship in C++. In a module block, a user
can specify the local variables (parameters) of a module object. In this example, an
object named “Node1_Interface_1” contains two variables that need to be initialized,
21
which are “ip” and “netmask.” The next statement, “Set Node1_Interface_1.ip =
1.0.1.1“, initializes “ip” to “1.0.1.1”. Similarly, the third statement assigns
“255.255.255.0” to “netmask.” If there is no parameter to be initialized, a module
block has only one statement to indicate its type and name, which is then directly
followed by an empty line.
After defining all module blocks used inside a “port,” the connectivity
relationship among them is then specified by the “Bind” statements. For example, the
following red-color statements specify the connectivity relationship among the
protocol modules used inside the “port1” of “Node1.” In this example, the “interface”
module connects with the “arp” module. The “arp” module connects with the “fifo”
module, which in turn connects with the “mac802.3” module. The remaining
statements chain the “tcpdump” module, “physical” module, and the “link” module in
sequence. With these “Bind” statements, the module instances defined in the module
blocks are chained together to form a protocol stack for this port.
Bind Node1_Interface_1 Node1_ARP_1
Bind Node1_ARP_1 Node1_FIFO_1
Bind Node1_FIFO_1 Node1_MAC8023_1
Bind Node1_MAC8023_1 Node1_TCPDUMP_1
Bind Node1_TCPDUMP_1 Node1_Phy_1
Bind Node1_Phy_1 Node1_LINK
With these module block definitions and “Bind” statements, the definition of a
port block is finished. If a node has multiple ports, these ports are defined in the same
way. After all ports of a node have been defined, the definition of that node‟s protocol
stack is finished.
Node Connectivity Specification
After the internal structures (i.e., the protocol stack) of all nodes are defined, the
connectivity relationship among these nodes (i.e., the topology) should be specified.
This is done through the “Connect” statements.
The following is an example:
Connect WIRE 1.Node1_LINK_1 4.Node4_LINK_1
Connect WIRE 2.Node2_LINK_1 4.Node4_LINK_2
Connect WIRE 3.Node3_LINK_1 4.Node4_LINK_3
A “Connect” statement specifies two nodes and the type of the link that connects
these
two
nodes.
The
format
22
is
“Connect
LinkType
nodeid1.link_module_instance_name
nodeid2.link_module_instance_name,”
where LinkType can be WIRE or WIRELESS.
For the WIRE link type, the first statement indicates that node1 and node4
connect to each other through a wired link. On node1, the wired link is attached to the
“LINK_1” module instance, which is defined in port 1. On node4, the wired link is
attached to the “LINK_1” module instance, which is defined in port 1. Similarly, the
second and the third statements specify that there are wired links between node2 and
node4, and node3 and node4, respectively.
For the WIRELESS link type, all mobile nodes (each mobile node uses a
wireless network interface) that use the same frequency channel will be collected
together and put after the “Connect Wireless” statement.
After these “Connect” statements, finally comes the “Run” statement. The value
after the keyword “RUN” specifies the total time that should be simulated. For
instance, “RUN 100” means that one would like the simulation case to simulate 100
seconds of the real network. Note that depending on the simulation machine‟s speed
and the simulation case‟s complexity, the time required to finish a 100-second
simulation case in the real life may be smaller or larger than 100 seconds.
23
Chapter 2 Adding a New Module
Because learning from examples is the best way to understand a new scheme,
the source code of the simulation engine and all supported protocol modules are
released in the package of NCTUns. A module developer can thus create his (her) own
module by simply copying an existing module‟s source code and then modifying the
source code to suit his (her) needs. Based on our experiences, this is the most
effective way to create a new protocol module and make it work correctly with the
simulation engine.
In this chapter, we present the required procedures to add a new module and
explain how to conduct a simulation without the use of the GUI program. In Section
2.1, we present how to register a new module with the simulation engine. In Section
2.2, we present how to register it with the GUI‟s Node Editor. In Section 2.3, we
present a simple example in which we add a new module named “myFIFO” to
NCTUns (including both the simulation engine and the GUI‟s Node Editor). Finally,
in Section 2.4, we present how to run a simulation case manually without the use of
the GUI program.
2.1 Register a New Module with the Simulation Engine
Three actions are required to add a new module into the simulation engine -module name registration, start-time parameter registration, and run-time get/set
variable registration. They will be discussed in later sections.
2.1.1 Module Name Registration
All modules must be registered with the simulation engine before NCTUns can
use them to generate simulation results. Two steps are required to register a module in
the simulation engine. A module developer first needs to add a REG_MODULE
statement for his (her) new module into the main() function in nctuns.cc (this file is
in the package‟s “src/nctuns/” directory) and rebuild the simulation engine.
The REG_MODULE (name, type) is a macro and has two parameters. The first
one is the name of the module used in the .tcl file while the second one is the C++
class name of the corresponding module. For example,
REG_MODULE ("SIMPLE-PHY", phy);
The above statement registers a module whose class name is “phy” and whose module
name is “SIMPLE-PHY.” From now on, the “SIMPLE-PHY” module name can be
24
used in a .tcl file to refer to this type of module (not to a particular instance of this
type of module).
The second step is to add a MODULE_GENERATOR(name) macro into the file
where the new module is implemented. The argument name is the name of the newly
added module. For example, if one implements a module named “myfifo” in
myfifo.cc, he needs to add MODULE_GENERATOR(myfifo) in myfifo.cc. Note also
that, if the myfifo.cc is not included in the Makefile, one should manually add it in the
Makefile properly so that the compiler can include it in the compilation process.
2.1.2 Start-Time Parameter Registration
A module may have several parameters whose values need to be initialized at
start-time, that is, at the beginning of a simulation. For example, a FIFO module
normally has a parameter to specify the maximum queue length allowed for its FIFO
queue. Such parameters need to be explicitly registered with the simulation engine so
that their values can be specified in the simulation network description file (the .tcl
file). This kind of registration can be accomplished by using the vBind() macro. The
usage of the vBind() macro is explained below:
vBind (exported_name , the address of the corresponding parameter variable );
The first parameter (exported_name) is the exported name of the parameter
variable while the second one is the address of the parameter variable. Note that a
parameter variable‟s exported name can be different from its real name declared in the
C++ program. After performing this operation, the value of this start-time parameter
can be specified in a .tcl file by assigning the value to the exported name. Later on,
when the simulation begins, the value specified in the .tcl file will be taken by the
corresponding parameter variable and set as its initial value.
2.1.3 Run-Time Get/Set Variable Registration
Sometimes it is useful to observe the status of a variable, a node, or a protocol
while a simulation is running. For example, a user may be interested in seeing how
the current queue length of a FIFO queue varies during a simulation. To support this
functionality, a module developer can register these variables with the simulation
engine so that they can be exported and accessed at run-time. The simulation engine
provides the macro EXPORT() to support this functionality. Its usage is explained
below:
25
EXPORT (variable name, permission mode);
In the above macro, the first parameter is the name of the exported variable while
the second one is a flag to indicate the access permission mode for this variable. Two
access permission modes are supported. They are the READ_ONLY and
WRITE_ONLY, respectively and can be combined.
2.2 Register a New Module with the GUI Node Editor
This section explains how to register a new module with the GUI node editor.
This step is necessary because an NCTUns user normally uses the GUI node editor to
specify a node‟s protocol stack (i.e., the used protocol modules) and the parameter
values used by these modules. Registering a new module with the simulation engine
alone does not automatically let the GUI node editor know that a new module has
been added to the simulation engine. It is required that a module developer also
register a new module with the GUI node editor.
To do so, three operations are required. First, a module developer should add a
block of information describing the new module into the simulator‟s module
description file (the mdf.cfg). Second, the developer should design a GUI layout for
the module‟s parameter dialog box. Third, if the developer wants to make this module
parameter dialog box look “beautiful,” he (she) may need to spend some time
adjusting the “appearance” of the dialog box. The following sections present the
details about registering a new module with the GUI node editor.
2.2.1 The Module Description File (mdf.cfg)
The module description file (mdf.cfg) is used to describe all of the modules that
have been registered with the simulation engine. Originally, the module description
file was a file containing several module description blocks. However, starting from
NCTUns 3.0, it has been broken into many smaller files stored in several
subdirectories of the mdf directory. By default, the mdf directory is created at
/usr/local/nctuns/etc/mdf. When a user develops a new module and wants to add the
descriptions of this module to this mdf file (now has become a directory), he (she) can
choose to 1) add the descriptions of this module to any file that is already stored in
any subdirectory of the mdf directory, or 2) create a new subdirectory under the mdf
directory and store the descriptions of this module as a file in the newly created
subdiretory. The names of the newly created subdirectory and the file holding the
descriptions of the module can be any. They have no relationship at all with the
module group names used in the GUI node editor. This new mdf directory design is to
allow the user to add his (her) module description file independently without touching
26
other existing module description files. The GUI program will automatically collect
all module description files under the mdf directory and concatenate their contents
together into one “big” module description file. Then it will read this “big” module
description file to know the descriptions of all modules, just like what it did before in
the original design. With this explanation, in the rest of this document, conceptually
we will still treat the mdf as a file rather than a directory.
When the GUI main program starts, it will read this file only once to learn what
modules are already registered with the simulation engine. In contrast, the GUI node
editor will read this file each time when it is invoked in the GUI program. Due to this
design, after a user modifies a module‟s description (e.g., its parameter dialog box
layout) and wants to see its effects immediately, he (she) can just invoke the GUI
node editor again to see the effects without exiting the GUI main program and then
restarting it.
A module description block starts with the “ModuleSection” keyword and ends
with the “EndModuleSection” keyword. A module description block is divided into
three parts – the HeaderSection, InitVariableSection, and ExportSection, respectively.
Similarly, these sections start with the “HeaderSection,” “InitVariableSection,” and
the “ExportSection” keywords, respectively, and end with the “EndHeaderSection,”
“EndInitVariableSection,” and the “EndExportSection” keywords, respectively.
The possible set of values for each parameter variable will be explained in detail
in Section 2.2.3.
2.2.2 The Try-and-Error Module Dialog Layout Designing Process
NCTUns provides a convenient environment to enable a user to easily perform
many tasks. However, right now, due to lack of manpower and research fund, there is
still one thing that cannot be performed easily, which is to generate the GUI layout of
a module‟s parameter dialog box.
Ideally, a module‟s parameter dialog box GUI layout should look “beautiful.”
That is, its parameter input fields should be concisely and neatly arranged in the
dialog box. However, it is very difficult for the GUI program to automatically design
a “beautiful” GUI layout for a module‟s parameter dialog box. This is because
whether or not the appearance of a parameter dialog box looks beautiful is highly
subjective. As such, this job must be done by (and is left to) the user.
NCTUns adopts a flexible way to specify the layout of a dialog box. A module
developer can specify the layout for variables that need to be initialized in the
“InitVariableSection” section. He (she) can also specify the layout for the variables
that allow run-time accesses in the “ExportSection” section. These are done through
27
the use of some XML-like layout description statements. (The detailed syntax and
semantic of these layout description statements are presented in the following section.)
A user can edit these statements to manually design and adjust the GUI layout of a
dialog box. Since the node editor will re-read the mdf.cfg file each time when it is
invoked, a user can use a try-and-error process to adjust the dialog box‟s GUI layout
until it looks “beautiful” enough for him (her). To be more precise, after a user makes
some changes to the dialog box‟s GUI layout, he (she) can re-invoke the node editor
to see how the new GUI layout looks like.
Apparently, this approach is not as intuitive as some commercial GUI layout
builder programs, which can easily build a dialog box by dragging GUI objects
around on a dialog box. In the future, if manpower and research fund permit, we
certainly will provide our own GUI layout builder. Right now, since normally a
module has only a few parameters to be set, we have no problem using the
try-and-error process to make “beautiful” dialog boxes.
2.2.3 The Syntax and Semantic of the Layout Description Statements
HeaderSection
The first table collects the relevant variables and their meanings. The second
table lists the set of possible values for each variable.
Field Name
Meaning
ModuleName
The name of this module
ClassName
The name of the class corresponding to this module. Normally,
the name of this module class in the C++ program is entered.
However, the GUI program does not use this information at
present.
NetType
The network type that the module can support
GroupName
The name of the group this module belongs to
AllowGroup
An option for future use. To indicate which module groups can
connect to this module group
PortsNum
The number of ports that this module can support
Version
The version of this module
Author
The author of this module
CreateDate
The creation date of the module
Introduction
A short description or comment about this module
Parameter
A start-time parameter variable. The GUI program reads this
28
part to know what parameters will be used at start-time. With
this information, it will export these start-time parameters in
the generated .tcl file.
TABLE 2.2.3.1 THE MEANINGS OF THE VARIABLES USED IN THE HEADERSION
Field Name
Possible Values
ModuleName
Any user-specified string
ClassName
Any user-specified string
NetType
Wire , Wireless , or Wire/Wireless
GroupName
AP, ARP, PSBM, MROUTED, HUB, MAC80211, MAC8023,
MNODE, SW, PHY, WPHY, INTERFACE, nctunsdep, User
specified. (A user can create a new module group.)
AllowGroup
XXXXX (not used now)
PortsNum
SinglePort, MultiPort
Version
Any user-specified string
Author
Any user-specified string
CreateDate
Any user-specified string. The recommend format is as
follows: dd/mm/yy_seq#
Introduction
Any user specified comment description string
Parameter
The format of a parameter statement is explained as follows:
Parameter Name Value Attribute
The possible attributes are listed below:
“local,” “global,” “autogen,” and “autogendonotsave”.
“local” means that this parameter is used only in this module
and if its value is updated, it will not be copied to other
modules of the same kind.
“global” means that the value of this parameter, if updated,
will be copied to the same parameter of the same modules in
the network.
”autogen” means that the value of this parameter will be
automatically generated by the GUI program. However, a user
can still replace the auto-generated value with his (her) desired
value.
“autogendonotsave” is similar to “autogen.” However, a user
cannot change its value. No matter how a user replaces the
auto-generated value with his (her) desired one, the final value
is still determined by a pre-defined formula.
29
TABLE 2.2.3.2 THE POSSIBLE VALUES FOR THE VARIABLES USED IN THE HEADERSION
Normally, a possible value of an autogendonotsave parameter is a formula
consisting of the three predefined variables: $CASE$, $NID$, and $PID$.
$CASE$ represents the main file name of a simulation case‟s topology file. It
will be replaced by the main file name when this variable is accessed. For example, if
a simulation case‟s topology file is saved with the filename “test.tpl”, $CASE$ will
be replaced by “test.” $NID$ represents the ID of the node to which this module is
attached. Analogously, $PID$ represents the ID of the port to which this module is
attached.
InitVariableSection
Normally, a user should specify the caption and the size of the diabox. The key
word “Caption” indicates the caption of the dialog box, and “FrameSize width
height” indicates the size of the dialog box. For example,
Caption
"Parameters Setting"
FrameSize
340 80
These statements will generate a dialog box of 340x80 pixels with a caption of
“Parameters Setting.” After specifying the caption and the size of the dialog box, a
user can arrange the layout inside the dialog box. A dialog box would contain a
number of GUI objects, such as an OK button, a Cancel button, a textline, etc. Each
GUI object corresponds to a description block in “InitVariableSection” and always
starts with “Begin” and ends with “End.” The following shows an example:
Begin BUTTON
Caption
Scale
ActiveOn
Enabled
Action
Comment
b_okL
"OK"
270 12 60 30
MODE_EDIT
TRUE
ok
"OK Button"
End
The description blocks for different objects share several common and basic
attributes. For example, the caption and scale commands are used commonly. A
30
“BUTTON”-like object is an example of an object consisting of only basic attributes.
Let‟s take the simple “BUTTON” object as an example. More specific attributes will
be discussed later.
For a “BUTTON” object, the keyword “BUTTON” follows the keyword “Begin”
and it is followed by the object name “b_ok”. The following table lists its attributes:
Attribute name
Possible values
Comment
Caption
User-specified
The caption of this object
Scale
User-specified
The four numbers represent (x, y, width,
height).
ActiveOn
MODE_EDIT,
An option to specify in which mode this
MODE_SIMULATION object should is active. MODE_EDIT
stands for the period of time before a
simulation is run.
MODE_SIMULATION stands for the
period of time during which a
simulation is running.
Enabled
TRUE, FALSE
If an object is not enabled, it will not be
displayed (dimmed). That is, a user
cannot operate this object.
Action
Ok , cancel
An attribute used by button-like objects,
such as the OK button and cancel
buttons to indicate which action it
should perform when a user presses it.
Comment
User-specified
Comment for this object
TABLE 2.2.3.3 THE BASIC ATTRIBUTES USED TO DESCRIBE AN OBJECT
a. LABEL
“LABEL” is used to display some comment in a dialog box. The attributes of a
LABEL object are the same as those of a “BUTTON” object.
b. RADIOBOX/CHECKBOX
In RADIOBOX/CHECKBOX, there are some new attributes. Let‟s take the
following example to explain:
Begin RADIOBOX
arpMode
Caption
"ARP Mode"
Scale
10 15 260 135
31
ActiveOn
MODE_EDIT
Enabled
TRUE
Option
"Run ARP Protocol"
Enable
flushInterval
Enable
l_ums
Disable ArpTableFileName
OptValue
"RunARP"
EndOption
Option
"Build ARP Table In Advance"
Disable flushInterval
Disable l_ums
Enable
ArpTableFileName
OptValue
"KnowInAdvance"
VSpace
40
EndOption
Type
STRING
Comment
"ARP Mode"
End
It is a RADIOBOX block whose name is “arpMode.” The first four statements
describe the caption, size, in which mode this radiobox should be active, and when it
should be enabled. Then two option blocks follow, each of which starts with the
“Option” keyword and ends with the “EndOption” keyword. The string following the
“Option” keyword specifies the string that should be shown in the dialog box for this
option. The “OptValue” specifies the value that will be assigned to the radiobox
option variable “arpMode” if this option is selected. The “Enable” and “Disable”
statements inside an “Option” block specify that, when a user selects this option, the
variable objects following these statements should be enabled or disabled (When an
object is enabled, its input field is enabled in the parameter dialog box, otherwise, its
input field is disabled). The term “VSpace” is used to specify the vertical height of the
area used for this option.
b. TEXTLINE
TEXTLINE provides a text field for inputting or outputting data. A module
developer can indicate the type of the data to be read from a textline. The data will be
32
interpreted as a value of the type indicated by the “TYPE” key word.
c. GROUP
GROUP is used to organize related objects together. It can contain a number of
objects that are related to an area. Like other objects, it has four basic attributes
“Caption,” “Scale,” “ActiveOn,” and “Enabled” to define the caption, the size of its
area, the active mode, and the enabled/disabled conditions.
ExportSection
“ExportSection” provides an area in a dialog box in which a user can get/set the
current value of a variable at run-time. “Caption” and “FrameSize” are the two basic
attributes for this section. If a module doesn‟t have any variable that can be accessed
during simulation, “Caption” should be set to “”, a null string, and “FrameSize”
should be set to 0 0. In addition to the objects discussed above, there are two useful
objects that are new in this section. They are the “ACCESSBUTTON” and
“INTERACTIONVIEW.” The formats of these two objects are shown in the
following examples:
Begin ACCESSBUTTON
Caption
Scale
ActiveOn
Enabled
ab_g2
"Get"
215 55 70 20
MODE_SIMULATION
TRUE
Action
ActionObj
GET
"max-queue-length"
Reference
t_mq
Comment
"get"
End
Begin INTERACTIONVIEW
iv_arp
Caption
"Arp Table"
Scale
10 20 200 30
ActiveOn
MODE_SIMULATION
Enabled
TRUE
Action
GET
33
ActionObj
"arp-table"
Fields
Comment
"MAC Address" "IP address"
"Arp Table"
End
For an “ACCESSBUTTON” object, it is used to get or set the value of a
single-value run-time variable. There are three new attributes for
“ACCESSBUTTON.” They are “Action,” “ActionObj,” and “Reference,”
respectively. The value of “Action” can be “GET” or “SET” to indicate when a user
presses this button which operation should be performed. “ActionObj” indicates the
name of the object that the GET/SET operation should operate on in the simulation
engine. Finally, “Reference” points to the name of the GUI object (e.g., a TEXTLINE
object) in which the retrieved value should be displayed. For example, the current
queue length of a FIFO module may be gotten and displayed at a TEXTLINE GUI
object named “curqlen”
For an “INTERACTIONVIEW” object, it is used to display the content of a
multi-column table at run-time. Normally, it is used to get a switch table, an ARP
table, or an AP‟s association table. Besides “Action” and “ActionObj,” there is a new
attribute called “Fields” to specify the names of the fields (columns) of the table.
Several quoted strings, each of which represents the name of a field, follow the
“Fields” attribute.
2.3 An Example of Adding a New Module
In this section, we use a step-by-step example to show how to add a new module
named “myFIFO” to NCTUns. We hope that this example can help a module
developer easily add his (her) module into NCTUns.
2.3.1 Adding a myFIFO Module
To save time, we clone the source code of the existing “FIFO” module
and give it a new name called “myFIFO.” We illustrate how to
integrate the “myFIFO” module (a new module) into NCTUns in the
following.
1. Determine a C++ class name for the new module. In this case, the class name of the
module is set to “myFIFO.” This class name must be different from all class names
34
that are already used in the simulation engine C++ program. Then consider the
group to which the new module should belong and store the source code in an
appropriate directory. If it should belong to a new module group, its module group
name specified in the mdf module description file can be a new name. In this case,
the GUI node editor will create a new group category for it and place it in that
category. The source code of this module can be placed in any directory. In this
example, since myFIFO belongs to the existing “PSBM” (which means packet
scheduling and buffer management) group, we store the module source code in the
directory “src/nctuns/module/ps/myFIFO.” Actually, it can be stored in any place
under the “src/nctuns” directory as long as the directory_path/name of this file is
added to “makefile” so that the compiler can find it when invoked by the user
running the “make” utility to rebuild the simulation engine.
2. After determining the class name, a user should register the new module with the
simulation engine. First, the user opens the file “src/nctuns/nctuns.cc”. In main(),
he (she) should add the following statement:
REG_MODULE(“myFIFO”, myFIFO);
3. Add MODULE_GENERATOR(myFIFO) in the file implementing the myFIFO
module. For example, if this module is implemented in myfifo.cc, one needs to add
MODULE_GENERATOR(myFIFO) in the myfifo.cc.
4. The user then determines which variables to be exported at start-time. In the
constructor of the class, the user should use the vBind() macro to register these
run-time variables. In this example, the following lines are added:
/* bind variable */
vBind("qmax", &if_snd.ifq_maxlen);
vBind("log_qlen", &log_qlen_flag);
vBind("log_option", &log_option);
vBind("samplerate", &log_SampleRate);
With these macros, the local variable “if_snd.ifq_maxlen” is exported as a start-time
variable named “qmax”, which will be used by the simulation engine. Similarly,
“log_qlen_flag” is exported as “log_qlen,” “log_option” is exported as the same name
“log_option,” and “log_SampleRate” is exported as “samplerate.”
35
5. Determine which variables to be exported as run-time accessible variables. In this
example, the “queue_length” in myFIFO::init() function is exported:
EXPORT("queue-length", E_RONLY|E_WONLY);
The variable “queue-length”is exported with its access mode set to “readable and
writable”.
6. Next, the user should write a command handler to deal with run-time access events.
By default, the simulation engine knows that a module‟s command() method is its
run-time-access event handler. Here is the relevant piece of source code in
myFIFO::command().
/* The Get implementation of Exported Variable */
if (!strcmp(argv[0], "Get")&&(argc>=2)) {
if (!strcmp(argv[1], "queue-length")) {
sprintf(buf, "queue-length: %d\n",
if_snd.ifq_maxlen);
EXPORT_ADDLINE(buf);
return(1);
}
}
/* The Set implementation of Exported Variable */
if (!strcmp(argv[0], "Set")&&(argc==4)) {
if (!strcmp(argv[1], "queue-length")) {
if_snd.ifq_maxlen = atoi(argv[3]);
return(1);
}
}
The above piece of source code first decides whether the input command is a “GET”
or “SET” command. It then performs appropriate processes.
7. Register with the GUI node editor. This can be done by adding a module
description block for “myFIFO” to any file in the “/usr/local/nctuns/etc/mdf”
directory. Because in this example, the “myFIFO” module is a module cloned
from the “FIFO” module, we simply copy and paste the description block of “FIFO”
36
and alter the values of some fields in its “HeaderSection” section. The header
section modified for “myFIFO” is shown below. The red-color parts are the fields
that are modified. They include the module name, class name, and the information
for version control.
HeaderSection
ModuleName
myFIFO
ClassName
ANY
NetType
Wire/Wireless
GroupName
PSBM
AllowGroup
XXXXX
PortsNum
MultiPort
Version
myFIFO_001
Author
NCTU_NSL
CreateDate
10/12/2002
Introduction
"This is a cloned FIFO module."
Parameter
max_qlen 50
local
Parameter
log_qlen
local
Parameter
log_option FullLog
Parameter
samplerate 1
Parameter logFileName
off
local
local
$CASE$.fifo_N$NID$_P$PID$_qlen.log autogendonotsave
EndHeaderSection
8. Rebuild (recompile and relink) the “nctuns” program (the simulation engine) and
the “myFIFO” module. Notice that if the file implementing the myFIFO module is not
included in the Makefile, one should manually add it in the Makefile. For example,
suppose that the myfifo.cc file is located in the src/nctuns/module/ps/myFIFO
directory. One needs to add the “myFIFO\” statement into the Makefile in the
src/nctuns/module/ps/ directory. The modified Makefile is shown as follows:
obj-y
=\
DRR/ \
DS/ \
FIFO/ \
37
myFIFO/ \
RED/ \
WAN/
Then the “myFIFO” module will be registered with the simulation engine. To
rebuild the simulation engine, a user can re-run the install.sh installation script
program provided in the NCTUns package. Because in this case we just want to
rebuild the simulation engine, during the installation script execution, we can select to
skip the time-consuming kernel building and tunnel interface creation steps. A user
can also enter the directory holding the source files of the simulation engine and
execute the “make” command to build the new simulation engine program. When the
compilation is finished, be sure to copy the newly-built simulation engine program
(nctuns) to the /usr/local/nctuns/bin directory and rename it to “nctunsse.”
9. Execute the “nctunsclient” program (the GUI program) and then invoke the node
editor. With the above operations, a user should find that the new module “myFIFO”
is now listed in the node editor‟s “PSBM” category. This means that the “myFIFO”
module has already been registered with the GUI node editor successfully.
From the above simple example, one sees that adding a new module to NCTUns
is straightforward. A user first registers it with the GUI node editor and then registers
it with the simulation engine of NCTUns. After rebuilding (compiling and making)
the simulation engine, the new module can be invoked and used during simulations.
38
2.4 Run a Simulation Case without the Use of the GUI
NCTUns provides a convenient simulation environment. Its simulation engine is
coupled with the GUI program to increase a user‟s productivity when he (she) creates
and runs a simulation case. Everything can be easily specified and configured in the
GUI program. For example, instead of using a text editor to create and edit a
simulation description file (.tcl), users can easily do this job via the GUI‟s Topology
Editor.
In some situations, however, manually executing simulations without using the
GUI is necessary. An example is when one needs to simulate a new type of nodes that
is not supported by NCTUns yet. In this situation, the GUI‟s Node Editor cannot
generate the needed protocol stack for the new node and hence a user must
“hand-craft” the .tcl file. The user then needs to bypass the use of the GUI and feed
the manually-crafted .tcl file to the simulation engine for execution.
Some steps must be performed first before a simulation can be manually started.
Section 2.4.1 describes how to manually perform a simulation in details. Section 2.4.2
explains the meanings and formats of the many configuration files that together
specify a simulation case.
2.4.1 Execute a Simulation Case Manually
To make the simulation engine suitable for manual executions (i.e., let it execute
without using the GUI), one needs to modify its source code files, which are located
in the “src/nctuns” subdirectory of the downloaded package.
2.4.1.1 Set the value of “IPC” to 0 in nctuns_api.h
This IPC variable in nctuns_api.h defines whether or not the compiled binary
of the simulation engine should run with the GUI via the IPC (Inter-Process
Communication) mechanism. If IPC is set to 1, the newly-built simulation engine
program will run with the GUI via IPC. On the other hand, if IPC is set to 0, the
newly-built program will be an independent simulation engine program, which
means that it will not take input from the GUI and will not generate output to the
GUI.
After setting IPC to 0, one should execute “make clean all” in the “src/nctuns”
directory to re-compile the simulation engine. Notice that the resulting binary is
named “nctuns” instead of “nctunsse” and is placed in the “src/nctuns” directory.
After the compilation finishes successfully, one can copy this stand-alone
39
simulation engine program to a directory for later uses.
2.4.1.2 Set up five environment variables
The simulation engine needs five environment variables to function correctly.
These five variables specify important file paths. First, $NCTUNSHOME indicates
where the installed directory of NCTUns is. Second, $NCTUNS_BIN indicates the
path of the directory that stores the binary of the main components of NCTUns
such as “nctunsse,” “dispatcher,” “coordinator,” and “nctunsclient.”
Next, $NCTUNS_TOOLS indicates the path of the directory that contains
user-level application programs that will be forked and executed by the simulation
engine during simulation. Next, $NCTUNS_WORKDIR indicates the directory in
which the configuration files used by application programs (if needed) are stored.
Taking the “stg” application program (Source Traffic Generator) as an example. If
stg is configured to generate a traffic pattern based on a traffic-pattern description
file and the file name is given as a command argument to stg, then the
traffic-pattern description file should be placed in $NCTUNS_WORKDIR.
Otherwise, stg will fail to find the configuration file and thus will execute
incorrectly. Finally, $LD_LIBRARY_PATH, indicates the path of the directory
where the library files used by the GUI program and the simulation engine are
stored.
The following is an example showing how to set up these environment
variables in bash/Linux.
> export NCTUNSHOME=/usr/local/nctuns
> export NCTUNS_BIN=/usr/local/nctuns/bin
> export NCTUNS_TOOLS=/usr/local/nctuns/tools
> export NCTUNS_WORKDIR=/tmp
> export LD_LIBRARY_PATH=/usr/local/nctuns/lib
The above example assumes that the installed directory of NCTUns is
/usr/local/nctuns. $NCTUNS_BIN, $NCTUNS_TOOLS, $LD_LIBRARY_PATH
are set as subdirectories of $NCTUNSHOME by default. The working directory of
the simulation engine can be arbitrarily chosen. It is set to “/tmp” in this example.
2.4.1.3 Start a simulation manually
40
After the above steps are performed, one can start a simulation manually. In
this section, two different methods for starting a manual simulation are illustrated.
Using the first method, one can separate the directory that stores the files describing
a simulation case from the directory that stores simulation result files generated by
user-level application programs. Note that the simulation result files generated by
the simulation engine and protocol modules are still placed in the same directory as
the files describing a simulation case.
On the other method, by using the second method one can run a simulation
manually without paying attention to where those input files should be placed. In
step (3.1), we explain the detailed steps for the first method. In step (3.2), we show
an example for the fist method. In step (3.3), we describe the required steps for the
second method and explain why the second method is simpler than the first method.
In step (3.4), we demonstrate an example using the second method step by step.
2.4.1.3.1 The first method
The first method differentiates between the directory where the simulation
engine reads and writes files from the directory where user-level applications do.
After the value of the IPC variable is set to 0 and the five environment variables are
properly set, one can enter the directory where the stand-alone version of the
simulation engine is stored and then execute the “./nctuns demo_case1.tcl”
command (assuming that the new binary is named “nctuns”). The only argument
needed by the “nctuns” program is the file name of the simulation network
description file (.tcl file). Other files required by the simulation engine such as
the .sce file, which describes the moving paths of mobile nodes, should also be
placed in the same directory as the .tcl file so that the simulation engine can find
them. If all of the files that are required by a simulation case are generated and
placed correctly as described above, one will be able to run up the simulation
manually.
In the following, we describe the internal interaction between the GUI, the
coordinator, and the simulation engine with respect to input/output file handling.
When the simulation engine runs with the GUI, the GUI generates two directories
for a simulation case, which are named $CASENAME.sim and
$CASENAME.results, respectively, where $CASENAME denotes the name of the
case. The first one, $CASENAME.sim, is used to store the files generated by the
GUI which together describe a simulation case. They include .tcl, .tfc, .sce files,
and so on. The GUI will package the files in $CASENAME.sim into a single tar
file via the “tar” utility and then send this packed tar file to the coordinator.
Upon receiving this packed tar file, the coordinator creates a directory as the
41
working directory for this simulation case and sets $NCTUNS_WORKDIR to this
new directory. The coordinator then extracts files from this packed tar file and put
them into the working directory. Next, the coordinator runs up a process of the
simulation engine and feeds it with “$NCTUNS_WORKDIR/$CASENAME.tcl” as
the only argument to start a simulation. When the simulation is finished, the
coordinator packs the simulation result files in this working directory into a tar file
and then sends it to the GUI. Upon receiving the packed tar file, the GUI extracts
files from this file, which may include various log files generated by modules, the
packet trace animation file (.ptr file) generated by the simulation engine, and the
various output files generated by user-level application programs during the
simulation. The GUI then creates the $CASENAME.results directory and put these
extracted files into it.
Note that the $CASENAME.sim directory does not store the configuration
files that are needed by user-level applications. Rather, these files should be stored
in the working directory specified by $NCTUNS_WORKDIR when the simulation
starts. In the automatic simulation mode (i.e., running a simulation with the GUI),
the GUI will automatically copy these files from their current locations (e.g.,
/usr/shieyuan/testdir, which is specified by the user using the “File Browse” button
in the GUI) to the $CASENAME.sim directory before packing these files in the
$CASENAME.sim directory and transferring the packed file to the coordinator. As
such, these files will be in the $NCTUNS_WORKDIR working directory by the
time when the simulation starts. However, in a manual simulation, because the GUI
is not used, one has to copy these files to the $NCTUNS_WORKDIR working
directory by himself (herself) before starting the simulation.
In the manual simulation mode, the simulation engine tries to read all the files
required for a simulation case from the same directory as the given .tcl file. The
simulation engine assumes that the prefixes (i.e., directory path) of these files are
the same as that of the given .tcl file. For example, if the given .tcl file is named
“democase1.tcl” and placed in “/tmp/democase1,” the simulation engine will try to
read the .tfc and .sce files by opening “/tmp/democase1/democase1.tfc” and
“/tmp/democase1/democase1.sce, respectively. On the other hand, executed
user-level application programs will try to read their configuration files from the
$NCTUNS_WORKDIR directory by default, and the output files of a simulation
case will no longer be stored in the $CASENAME.results directory because the
GUI is not used. Instead, those files generated by the simulation engine will be
stored in the same directory as the .tcl file but those files generated by user-level
application programs will be stored in the $NCTUNS_WORKDIR directory. Later
on, we will use an example to illustrate how to run a simulation case manually and
42
show where output files are generated.
2.4.1.3.1.1 An example showing how to use the first method
In this example, we assume that the new binary of NCTUns simulation
engine is named “nctuns” and placed in “/usr/local/demo_manual_sim/bin.” The
case is named “Demo29_GPRS_1_ms” and placed in the directory
“/root/NCTUns/example/”.
I.
Set the value of IPC to zero
We first open the “nctuns_api.h” file and search the IPC variable. Then we
set the value of IPC to zero.
II. Set up five environment variables
For convenience, we can add shell commands that set the five NCTUns
environment variables to the .bashrc file. The following example shows that we
add these commands to the tail of the .bashrc file.
43
One can use the “printenv” command (a system utility that shows the
values of environment variables) to check whether or not the settings of these
environment variables are correct. The following shows that we use the “printenv
| grep NCTUNS” command to dump the values of NCTUns-related environment
variables ($LD_LIBRARY_PATH is not shown because it does not contain the
“NCTUns” string).
One can then use the “printenv LD_LIBRARY_PATH” command to show
the value of the $LD_LIBRARY_PATH environment variable.
44
III. Create the $NCTUNS_WORKDIR directory
One has to make sure that the directory specified by
$NCTUNS_WORKDIR really exists. Otherwise, the user-level application
programs that will be run during the simulation will not run correctly. This is
because they will not be able to find and read their configuration files and
output their files in the specified directory.
IV. Re-compile the simulation engine
One then enters the directory storing the source codes of the simulation
engine, which is usually “src/nctuns” in the downloaded package. One should
execute the “make clean all” command to re-compile the simulation engine.
45
V.
Copy the new simulation engine to a directory
After a successful compilation, one then copies the new simulation engine
to the “/usr/local/demo_manual_sim/bin” directory, which is arbitrarily chosen
for this example. Actually, one can place the new program into any directory.
VI. Put the configuration files required by user-level applications into the
$NCTUNS_WORKDIR directory
From the content of the following .tfc file, which describes what
applications should be run during the simulation (the detailed format of this file
is explained in section 2.4.2), it can be seen that the “stg” program needs a
configuration file named “stg.config” and the “rtg” program will generate a log
file named “log1.” Remember that all the files required by user-level programs
should be placed in $NCTUNS_WORKDIR and the output files generated by
user-level programs will be placed in $NCTUNS_WORKDIR. Because in this
example $NCTUNS_WORKDIR is “/tmp/nctuns_manual_sim_workdir/,” we
copy “stg.config” into “/tmp/nctuns_manual_sim_workdir.”
46
VII. Run a simulation manually
Here, we run a simulation case specified by a .tcl file, whose full path is
“/root/NCTUns/examples/Demo29_GPRS_1_ms.sim/Demo29_GPRS_1_ms.tcl
.” The following figure shows the command used to run this simulation.
VIII.
Check output files
Remember that the output files generated by the simulation engine are placed
in the same directory as the given .tcl file and the output files generated by
user-level programs are placed in the $NCTUNS_WORKDIR directory. As
shown in the following two figures, the packet trace file (.ptr file) is placed in
“/root/NCTUns/examples/Demo29_GPRS_1_ms.sim,” and the “log1” output file,
which is generated by the “rtg” program, is placed in
the
$NCTUNS_WORKDIR directory (“/tmp/nctuns_manual_sim_workdir”).
47
2.4.1.3.2 The second method
When describing the first method, we show that the directory where the
files describing a simulation case are stored can be different from the
directory where configuration files required by user-level application
programs are stored. Although the first method is correct, it may confuse
users because normally these files are regarded as “input files” for a
simulation case and most users would think that they should all be placed in
the same directory. As such, here we show the second method by which these
files can all be stored in the same directory. Actually, the second method is
the method used by the coordinator to manage the placement of files when
the GUI is used.
Using the second method, one needs to create a new directory for a
simulation case first. Then, one has to set $NCTUNS_WORKDIR to the path
of this directory so that this new directory will be used as the working
directory for a simulation. Next, one has to put the files that are used to
describe a simulation case, such as $CASENAME.tcl, $CASENAME.tfc, etc,
into this directory. Since this directory is the working directory for a
simulation case, the files required by user-level application programs should
be placed into this directory as well. Finally, one can enter the directory in
which the stand-alone version of the simulation engine is stored and then
start a simulation manually with
$NCTUNS_WORKDIR/$CASENAME.tcl”.
the
command,
“./nctuns
48
Using the second method, one need not worry about where to store these
files because they are all placed in the same directory. Also, the output files
generated by the simulation engine, protocol modules, and user-level
programs will all be placed in the $NCTUNS_WORKDIR directory as well.
Although the second method is not as flexible as the first method, it
simplifies the placement of input and output files and may be more
acceptable for some users.
2.4.1.3.2.1 An example showing how to use the second method
I.
Set the value of IPC to zero
We first open the “nctuns_api.h” file and search the IPC variable. Then we
set the value of IPC to zero.
II. Set up environment variables properly
For convenience, we can add shell commands that set the five NCTUns
environment variables to the .bashrc file. Note that in the second method, the
path specified by $NCTUNS_WORKDIR is no longer fixed. Instead, it may
need to be changed each time when one wants to start a new simulation. The
following example shows that we add the commands for setting up these
variables to the tail of the .bashrc file.
49
One can use the “printenv” command (a system utility that shows the
values of environment variables) to check whether or not the settings of these
environment variables are correct. The following shows that we use the “printenv
| grep NCTUNS” command to dump the values of NCTUns-related environment
variables ($LD_LIBRARY_PATH is not shown because it does not contain the
“NCTUns” string).
One can use the “printenv LD_LIBRARY_PATH” command to show the
value of the environment variable $LD_LIBRARY_PATH.
50
III. Re-compile the simulation engine
One then enters the directory storing the source codes of the simulation
engine, which is usually “src/nctuns” in the downloaded package. One should
execute the “make clean all” command to re-compile the simulation engine.
IV. Copy the new simulation engine to a directory
After a successful compilation, one then copies the new simulation engine
to the “/usr/local/demo_manual_sim/bin” directory, which is arbitrarily chosen
for this example. Actually, one can place the new program into any directory.
51
V.
Create a new directory as the working directory
Using the second method, one has to create a new directory to be the
working directory for the simulation case. In this case, we create a new
directory named “demo_method2” in the “/usr/local/demo_manual_sim”
directory.
VI. Set $NCTUNS_WORKDIR to the path of this new directory
To make the new created directory as the working directory, one then
needs to set $NCTUNS_WORKDIR to the path of this new directory. In
bash/Linux, setting up an environment variable can be done with the “export”
command, which is a built-in command of bash. In this case, the command
used
is
“export
NCTUNS_WORKDIR=/usr/local/demo_manual_sim/demo_method2”.
As mentioned above, one can use “printenv NCTUNS_WORKDIR”
command to check if $NCTUNS_WORKDIR is properly configured or not.
VII. Put files required by the simulation engine and user-level application
programs into the $NCTUNS_WORKDIR directory
52
Using the second method, one needs to generate and put the files that
describe a simulation case (i.e., the files required by the simulation engine)
into the $NCTUNS_WORKDIR directory. We assume that these files have
been properly generated by some way (e.g., they may have been generated by
the GUI and thus we can simply copy them into this directory).
Also note that one has to make sure that the configuration files required
by user-level application programs should also be placed into the
$NCTUNS_WORKDIR directory. In this case, we copy stg.config, which is
required by stg program, into the $NCTUNS_WORKDIR directory.
Finally, one needs to make sure that all required files are placed in the
$NCTUNS_WORKDIR directory. One should double-check to make sure
that every setting is correct before starting a simulation.
VIII.
Run a simulation manually using the second method
53
If all of the above steps have been performed, one can enter the
directory where the stand-alone version of the simulation engine is placed
and then manually start a simulation with the “./nctuns
$NCTUNS_WORKDIR/$CASENAME.tcl” command. ($CASENAME
denotes the prefix of the file name of “.tcl file” for the simulation case.) The
following figure shows the command used in this example.
IX. Check output files
Remember that the output files generated by the simulation engine and the
output files generated by user-level programs will be placed in the same
$NCTUNS_WORKDIR directory using the second method. As shown in the
following figure, the packet trace file (.ptr file) and the “log1” output file, which
is generated by the user-level “rtg” program, are both placed in the
$NCTUNS_WORKDIR
directory,
which
is
“/usr/local/demo_manual_sim/demo_method2” in this example.
2.5 Formats and Usages of Simulation Description Files
In this section, we present the usages of the files that together describe a
simulation case and explain their formats.
54
(1) Simulation Network Description File
A simulation network description file is named $CASE.tcl. Here, $CASE
denotes the case name for a simulation case. A simulation network description
file is the main description file for a simulation, inside which the connectivity
of nodes, types of nodes, and configurations of protocol stacks of all nodes are
specified in this plain text file. The detailed format of a simulation network
description file is described in previous sections of this chapter.
(2) Traffic Description File
A traffic description file has the “.tfc” as its filename suffix. A traffic
description file describes when to execute what user-level application programs
on which nodes. Every line is independent and represents an execution
invocation of a user-level application program. The format of a line is:
$node_(NID) + starting time + termination time + the command line for
executing this application program.
An example is shown as follows:
$node_(1) 10.0 100.0 stg –u 1400 100 1.0.1.2
The first field in the above line specifies that the application should be run
on node 1. The next two fields specify that this application should be executed at
10th second and terminated at 100th second in simulation time. The command line
to execute this application then follows the “termination time” field. The
arguments given to this application are “stg,” “-u,” “1400,” “100,” and “1.0.1.2”
in sequence. The first argument is “stg” (“stg” is the abbreviation of “Sending
side traffic generator”), the name of this application program. The second one
indicates that this traffic generator is configured to generate UDP packets, and
the following argument specifies that the length of each packet is 1400 bytes.
The fourth one specifies that the execution duration of this “stg” application is
100 seconds in simulation time. The last argument specifies the IP address of the
destination node of these UDP packets. This example shows how to specify in
a .tfc file to run up the “stg” application during simulation. Actually, any
real-world user-level application program can be run up with NCTUns.
(3) Scenario Description File
55
A scenario description file has the “.sce” as its filename suffix and is used to
describe the static movements of mobile nodes. The detailed format is shown in
the following:
$node_(NID) + x + y + z + arrival time + pause time + speed
The fields, x, y, z, forms a triplet (x, y, z) that represents a location in the
simulated field. The arrival time specifies the time when this node should arrive
at the (x, y, z) location, and the pause time specifies how long this node should
stay at (x, y, z). The speed specifies how fast this node should move to the next
point after the pause. Here, the next point is specified in the next line for the
same node.
Note that for tactic and active mobile ad hoc networks where the moving
paths of mobile nodes are dynamically generated and controlled by the tactic
agent running on the mobile nodes, the moving paths of mobile nodes need not
be set.
(4) Obstacle Description File
An obstacle description file has the “.obs” as its filename suffix. This file
describes locations, lengths, and properties of obstacles in the simulation field. In
an obstacle description file, each obstacle is represented by a 9-tuple (sx, sy, dx,
dy,
width,
whether_block_view,
whether_block_movement,
whether_block_wireless_signal, attenuation).
The pairs of (sx, sy) and (dx, dy) denote the two end points of an obstacle,
respectively. The width field indicates the width of this obstacle. Besides, there
are several fields to describe the properties of an obstacle. The
whether_block_view field indicates whether this obstacle should block the line
of sight of nodes; the whether_block_movement field indicates whether this
obstacle
should
block
the
movements
of
nodes,
and
the
whether_block_wireless_signal field indicates whether this obstacle should
reduce the strength of the wireless signal or not. If so, the attenuation field
specifies the amount of signal loss in dbm that a wireless signal should
experience when going through the obstacle.
Note that the intelligence of not going through an obstacle that is specified
to block a mobile node‟s movement is implemented by the tactic agent program
(see the chapter about tactic agent in this manual) running on the mobile node,
rather than implemented by the simulation engine. Similarly, the effects of a
56
mobile node not being able to see the things behind an obstacle that is specified
to block a node‟s view is implemented by the tactic agent program rather than by
the simulation engine. This design makes the simulation engine clean and easy to
manage. In contrast, the effect that a wireless signal is blocked or attenuated by
an obstacle that is specified to block or attenuate wireless signal is implemented
and enforced by the simulation engine.
(5) System Routing Table Description File
A system routing table description file has the “.srt-l” as its filename suffix.
(Note: “-l” means that the route command format of this .srt file is for Linux
operating system.) Routing entries for each node are specified in the “.srt-l file.”
Each entry is represented in the same format used by the “route” command,
which is a system utility program provided on most UNIX systems. We show
two examples in the following to demonstrate the two most common formats
used in this file.
The first example shows the first format. It is a route command in Linux.
This command specifies that the packets sent from the node whose IP is 1.0.1.1
and destined to subnet 1.0.2.X should be directed to the tun1 interface in the
kernel for transmission.
route add -net 1.1.2.0/24 tun1
The second example shows the second format.
route add -net 2.1.1.0/24 gw 2.1.2.2
This routing entry specifies that if packets are sent from the node whose IP
is 1.0.2.1 and destined to the subnet 1.0.1.X, these packets should be routed to
the node whose IP is 1.0.2.2.
(6) Mobile Routing Table Description File
A mobile routing table description file has the “.mrt” as its filename suffix.
This file describes the changes of routing entries on each mobile node and is
used only by the GOD routing module. A simulation case that does not use the
GOD routing module for the mobile nodes need not provide this file. Its format
is shown as follows:
57
$node_(NID) + entry-changing time + "set-next-hop" + SrcNode + DstNode
+ NextHop + "chan" + channel
An example is shown below:
$node_(1) 3.000000000 set-next-hop 1 3 2 chan 1
The above line specifies that a routing entry on node 1 is added or changed
at the 3rd second in simulation time. The entry shows that node 1 chooses node 2
as the next hop for its routes to node 3. In addition, the channel used by the
wireless interface is channel 1. Another special example is shown below:
$node_(1) 3.000000000 set-next-hop 1 3 999999 chan 0
The above example specifies that there is no route from node 1 to node 3
when the simulation time advances to the 3rd second. Using 999999 for the
NextHop indicates that no node can be the next hop for the route from node 1 to
node 3.
The routing entry updates in this file are the most “perfect” routing entry
updates that could only be calculated by the god. In the real life, no routing
protocol can detect node movements so quickly to generate these precise routing
entry updates. However, these perfect routing entry updates represent the best
performance that any routing protocol could possibly achieve. As such, the GOD
routing daemon can be used as a comparison target when one would like to see
how well a new routing protocol performs as compared with the most “perfect”
routing protocol.
When generating thie file, the GUI program by default updates the locations
of mobile nodes and updates the routing entries every 0.1 second. Because
starting from NCTUns 5.0 the wireless channel models used by moble nodes are
more realistic models and need heavy CPU computation, generating this file
becomes very time-consuming. To solve this problem, the GUI program now
provides a option window in which the user can choose how often to update the
locations of mobile nodes and do the recalculation. The update interval can be set
to 0.1 second, 1 second, or other values, or even “no update at all” if no mobile
node moves during the simulation to save time.
(7) Optical Switching Protection Ring File
58
An optical switching protection ring file has the “.osr” as its filename
suffix. To specify a protection ring, one has to describe the configuration of
optical protection rings in this file. Each line in the “.osr” file represents a
protection ring. A protection ring is composed of several triplets. Each triplet
is made up of the incoming port number, node ID, and the outgoing port
number. The following example shows how to specify a protection ring:
2
12
1 2
14
1 2
13
1 2
11
1 1
10
2 1
8
2
The above line specifies a protection ring containing nodes 12, 14, 13, 11,
10, and 8. Every three numbers form a triplet. For the first triplet, the first
number “2” is an incoming port number of node “12,” which is specified by the
following number, and the third number “1” is the outgoing port number of
node “12.” The second triplet (2, 14, 1) describes that packets departing from
port 1 of node 12 (the previous node on the ring) will enter node 14 via port 2
and leave node 14 via port 1. To close the ring, the last triplet indicates that
packets that depart from node 8 via port 2 will enter node 12 via port 2.
(8) Optical Switching Edge Router-to-Edge Router File
An optical switching edge router-to-edge router file has the “.osp” as its
filename suffix. Each line in this file describes an edge router-to-edge router
routing path, in which the first two numbers denote the node ID and the
outgoing port number of the first router on the path and the last two numbers
denote the incoming port number and the node ID of the last router on the path.
The middle part of a line is composed of several triplets, each of which
represents (incoming port number, node ID of optical switch, outgoing port
number). The following shows an example.
15 1
411
123
142
152
172
183
291
2 10 3 1 16
This example path is from router 15 to router 16. The first number “15” is
the node ID of the first router and the second number “1” is the outgoing port
number of node 15. The last number “16” denotes the node ID of the last router
and the number next to it indicates that the incoming port number is “1.”
(9) GPRS-phone Action Table Description File
59
A GPRS-phone action table description file has the “.pat” as its filename
suffix. This file describes when and which GPRS action should be performed on
which GPRS node during simulation. In a “.pat” file, each GPRS phone node has
its own action table. The format of an action table is shown below:
NODE$NID
The number of action entries
Action entry 1
Action entry 2
…
The first line is a keyword “NODE,” followed by the node ID of this phone.
The second line is a single field indicating the number of action entries in this
action table. An action entry is composed of the starting time, action type,
NSAPI, and the chosen QoS level.
(10)
Base Station Configuration File
A base station configuration file has the “.bsscfg” as its filename suffix. It
specifies several important parameters for a GPRS base station. This
configuration file is composed of base station description blocks (BSDB) of all
base stations in a simulation. A BSDB consists of two sections. The first (local)
section describes the attributes of a base station. It contains the node ID, the base
station identity code (BSIC), the routing area identity (RAI), and the assigned
channel range for the base station. The second (neighbor) section contains a list
of the local sections of neighboring base stations.
GSM/GPRS system divides the wireless frequency into two groups, each of
which has 125 channels. The first channel group ranging from 0 to 124 is
dedicated to uplink traffic while the second group ranging from 125 to 249 is
dedicated to downlink traffic. An uplink channel with a channel ID ch1 and a
downlink channel with the (ch1+125) channel ID form a pair of bi-directional
link for a connection. Since the assignment of uplink/downlink channels is
symmetric, the configuration file describes the assigned channel range by
specifying only the range of uplink channels. Note that the lowest downlink
channel ID assigned to a base station implicitly specifies the broadcast channel
ID of a base station. For example, if a base station is assigned some uplink
channels ranging from 1 to 5, its broadcast channel ID is (1+125), i.e., 126.
The following is an example of a base station description file. The key
words BSS_DES_START and BSS_DES_END denote the start and the end of a
60
base station description block. A block has exactly one local section but may
have zero or multiple neighbor sections. The key word pair, LOCAL_SECTION
and END_LOCAL_SECTION, forms a local section that describes several
important attributes of a base station. In this example, a base station node with
NID 2 is assigned a BSIC 0 and RAI 3. Its assigned uplink channels are 1 to 5
and its downlink channel range is from 126 to 130. The base station with NID 8
is included in this block as a neighbor section. The meanings of the fields in a
neighbor section are the same as those in a local section. If base station A is
included as a neighbor section for base station B, base station A is viewed as a
neighboring base station of base station B. That is, base station B should have the
system information of base station A and similarly base station A should have the
system information of base station B. A base station should periodically
broadcast the system information of its neighboring base stations so that its
mobile phones know which base stations are close to the current base station and
providing services. Using this information, a mobile phone can constantly
monitor the signal strength of these neighboring base stations and roam quickly
to a better base station if necessary.
BSS_DES_START
LOCAL_SECTION
NID 2
BSIC 0
RAI 3
CHANNEL_RANGE 1 5
END_LOCAL_SECTION
NEIGHBOR_SECTION
NID 8
BSIC 0
RAI 7
CHANNEL_RANGE 11 15
END_NEIGHBOR_SECTION
BSS_DES_END
(11)
Traffic Stream Classifier Description File
61
A traffic stream classifier description file has the “.tsc” as its filename suffix.
This file defines the classification of traffic flows on network nodes that supports
IEEE 802.11(e) protocol. The format of this file is explained in the following.
The traffic flow definition for a node is composed of several node traffic flow
description blocks, which have at least two separated lines. The first line stores the
node ID of this description block, and the second line stores the number of traffic
flows defined in the successive lines.
Consequently, if a node does not have any pre-defined traffic flows, the second
line will store the number zero, and the description block ends. A traffic flow is
defined by a set of parameters, listed in the table below in sequence. Note that these
parameters should be stored in the same line and should be separated by “blank space”
symbol or “tab” symbol only. They cannot be separated by the “end-of-line” marker
such as “carriage return” or “line feed” ASCII codes.
Parameter Name
Meaning
Start Time
The time that this flow classification is
activated.
Finish Time
The time that this flow classification is
deactivated.
Direction
Downlink (the direction from an AP to
an MS) or uplink (the direction from an
MS to an AP)
Transport Protocol
TCP or UDP
Source Port Number
The transport layer protocol port number
on the source node
Destination Port Number
The transport layer protocol port number
on the destination node
Traffic Stream ID
The ID assigned to this traffic stream,
ranged from 8 to 16
Mean Data Rate (kbps)
The average throughput that this traffic
stream requests
Nominal Packet Size (byte)
The size of packets sent by the
application program
Maximum Delay Bound
The maximum allowable interval, used
by the IEEE 802.11(e) MAC layer,
between the time a packet is enqueued
into the transmission queue of the MAC
62
layer and the time it is successfully
transmitted
Maximum Service Interval
The maximum interval between the two
successive polling requests sent by an
IEEE 802.11(e) AP
The following is an example of the traffic stream classifier description file.
4
0
5
1`
0.000000 80.000000 Uplink UDP 0 8001 8 200 1024 1024 20
6
2
0.000000 80.000000 Downlink TCP 0 8001 9 200 1460 1460 20
0.000000 80.000000 Uplink TCP 0 8000 8 100 1460 1460 20
There are three node traffic flow description blocks. The first one is defined for
node with node ID 4. The second line of this block indicates that node 4 does not have
any pre-defined traffic stream.
The second one is composed of three lines. The first line indicates that the this
block is for node with ID 5 while the second line shows that there is one traffic stream
defined in this block. The third line defines this traffic stream, which is activated and
deactivated at the 0‟th second and at the 8‟th second, respectively. It indicates that this
traffic stream is an uplink UDP flow and the destination port number is 8001.
The 7‟th parameter specifies that the traffic stream ID is 8; the 8‟th parameter
shows that the average throughput that this traffic stream requests is 200 kbps; and,
the 9‟th parameter defines the nominal packet size, which is 1024 byte. The last two
parameters define the maximum delay bound and the maximum service interval,
whose values are 1024 milliseconds and 20 milliseconds, respectively. The final block
defines node 6‟s traffic streams. Since the meanings of the parameters are explained
previously, we do not repeat the explanation for the description block of node 6.
(12)
Address Resolution Protocol File
An address resolution protocol (ARP) file has the “.arp” as its filename suffix
and is used to describe the mapping between an IP address and its corresponding
MAC address. The detailed format is shown in the following example:
63
IP
1.0.1.1.1
(13)
MAC
0:1:0:0:0:2
Car Agent Configuration Profile File
A car agent configuration profile file has the “.car_prof_cfg” as its filename
suffix and is used to describe how many percentages of car agents use which profile$,
where $ stands for a number. A profile$ is used to describe the moving characteristics
of the car. The detailed format is shown below.
The Car Agent Configuration Profile.
In this example, car agent 2 uses profile1.
Node number
2
profile
profile1
An example content of one profile
MaxSpeed=18 (m/sec)
MaxAcceleration=1 (m/sec2)
MaxDeceleration=4 (m/sec2)
(14)
WAVE Service Configuration File
A WAVE Service configuration file has the “.wme_cfg” as its filename suffix and
is used to describe the WAVE‟s application primitives. The detailed format and
examples are shown in the following:
WAVE service configuration profile format.
Parameter Name
Meaning
SIB_Begin
The service information block begins
here.
NID
It specifies the Node ID. The
information following this NID
statement until the next NID statement
applies to this particular node.
CDB
The configuration description begins
here.
Time
It specifies the start time for an
64
application to execute this primitive
(e.g., wme_app_req) to create a
service. (The time unit is 10-7 seconds.)
CMD
It specifies the WME-Application
primitive that should be executed. The
supported primitives for this variable
are “wme_app_req” (for making a
request) and “wme_app_reg” (for
making a registration).
PSID
It specifies the identifier of this created
provider
service.
(0X00000001
through 0X7FFFFFFF.)
RegAction
Its value is Add_provider (for
registering a provider with the WME)
or Add_user (for registering a user with
the WME).
AppPriority
It specifies the priority of the created
service. (63 is the highest value; 0 is
the lowest value.)
Channel
It specifies the channel number used by
this service. (174, 175, 176, 180, 181,
182)
SerProMacAdd
It specifies the MAC address of the
device on which this application,
which creates this service) is run.
PSC
It specifies the application‟s provider
service context and can be any string.
ReqType
The action supported by the
“wme_app_req” primitive. Currently,
only “active” is supported.
PeerMacAdd
It specifies the MAC address of the
device on which the WME is run.
Repeats
It specifies how many times (0~7) this
service announcement should appear in
a control channel interval.
Persistence
It
specifies
whether
the
service
announcement should be sent only
once in the current control interval (0)
65
or periodically in every control channel
interval (1).
CBJ
It specifies whether the WME should
confirm with the application before
joining a provider service. This option
is for a device that registers with WME
expressing that it is interested in
becoming a WAVE user. Currently, its
value is always set to FALSE.
CDE
The configuration description ends
here.
SIB_End
The service information block ends
here.
An example of “WAVE user” settings.
In this example, node 16 registers for PSID 1 and PSID 2 at 1‟st second during
simulation, expressing that it is interested in joining a service whose PSID is 1 or
joining a service whose PSID is 2.
NID 16
CDB
Time 10000000
CMD wme_app_reg
PSID 1
RegAction Add_user
CBJ
0
CDE
CDB
Time 10000000
CMD wme_app_reg
PSID 2
RegAction Add_user
CBJ
0
CDE
An example of “WAVE provider” settings.
In this example, node 12 registers one service whose PSID is 1 at 1st second during
simulation. Then, at 2nd second during simulation, it starts to provide the service.
66
NID 12
CDB
Time 10000000
CMD wme_app_reg
PSID 1
RegAction Add_provider
AppPriority 1
Channel 174
SerProMacAdd 0:1:0:0:0:12
CDE
CDB
Time 20000000
CMD wme_app_req
PSID 1
PSC ""
ReqType active
PeerMacAdd 0:1:0:0:0:12
Repeats 3
Persistence 1
Channel 174
CDE
(15)
DVB-RCS Frequency Configuration File
A DVB-RCS frequency configuration file has the “.dvbrcs.freq” as its filename
suffix and is used to describe the mapping between a channel number and its
corresponding frequency in DVB-RCS satellite networks.
(16)
IEEE 802.16 Network Description File
An IEEE 802.16 network description file has the “.ieee80216_network_des” as
its filename suffix and is used to describe the setting for IEEE 802.16 networks. It
includes the network ID, subscriber station list, and authentication method.
(17)
IEEE 802.16 Mesh Routing Tree File
An IEEE mesh routing tree file has the “.meshrt” as its filename suffix and is
used to describe the next hop routing information for WiMAX mesh routing
67
.
(18)
WiMAX Neighbor Base Station List File
A WiMAX neighbor base station list file has the “.nbrbs_list” as its filename
suffix and is used to describe the node ID, channel ID and MAC address of a WiMAX
base station.
(19)
Node Type List File
A node type list file has the “.ndt” as its filename suffix and is used to describe
the mapping between node type and node id in an optical network.
(20)
WiMAX Node Configuration File
A WiMAX node configuration file has the “.nodecfg” as its filename suffix and
is used to describe the WiMAX mapping between the node ID and the MAC address.
(21)
Road Position File
A road position file has the “.road” as its filename suffix and is used to describe
the positions, directions, and other properties of all roads and intersections in the GUI
program.
(22)
Road Structure File
A road structure file has the “.road_structure” as its filename suffix and is used to
describe the construction relations between a road‟s block, lane and edge.
(23)
System Command File
A system command file has the “.sct” as its filename suffix and is used to
describe the system commands to be issued during simulation. These system
commands can be specified in the GUI program. The format of “.sct” file is: Target
Time (second) + Command + Output file name.
(24)
Signal Agent Configuration File
A signal agent configuration file has the “.sig” as its filename suffix and is used
68
to describe the position and direction of a traffic signal agent. Signal agents are used
in an Intelligent Transportation Systems (ITS) simulation, where cars move on roads
and pass intersections.
(25)
WiMAX Configuration File
A WiMAX configuration file has the “.wimax-config” as its filename suffix and
specifies classes of QoS provisioning, classes of QoS service, and rules for
classification.
(26)
Mobile WiMAX Configuration File
A mobile WiMAX configuration file has the “.mobilewimax_cfg” as its filename
suffix and is used to describe the setting of mobile station‟s QoS in mobile WiMAX
networks.
(27)
Mobile WiMAX Neighboring Base Station List File
A mobile WiMAX neighboring base station list file has the “.nbrbs_list” as its
filename suffix and is used to list each base station‟s node ID, channel ID, and MAC
address.
(28)
Mobile Relay WiMAX Transparent Mode Configuration File
A mobile relay WiMAX transparent mode configuration file has the
“.mobilerelaywimax_cfg” as its filename suffix and is used to describe the setting of
mobile station‟s QoS in mobile relay WiMAX transparent mode networks.
(29)
Mobile Relay WiMAX Transparent Mode Neighboring Base Station
List File
A mobile relay WiMAX transparent mode neighboring base station list file has
the “.mr_nbrbs_list” as its filename suffix and is used to list each base station‟s node
ID, channel ID, and MAC address.
(30)
Mobile Relay WiMAX Non-transparent Mode Configuration File
A mobile relay WiMAX non-transparent mode configuration file has the
69
“.mr_wimax_nt_cfg” as its filename suffix and is used to describe the setting of
mobile station‟s QoS in mobile relay WiMAX non-transparent networks.
(31)
Mobile Relay WiMAX Non-transparent Mode Neighboring Base
Station List File
A mobile relay WiMAX non-transparent mode neighboring base station list file
has the “.mr_nbrbs_nt_list” as its filename suffix and is used to list each base station‟s
node ID, channel ID, and MAC address.
(32)
Emulation Configuration File
An emulation configuration file has the “.emu” as its filename suffix and is used
to describe the external routing table settings. This file is used when emulation rather
than simulation is performed.
(33)
Satellite Module Connection File
A satellite module connection file has the “.smc” as its filename suffix and is
used to describe the DVB-RCS networks connection configuration.
(34)
Wired Link Graph File
A wired link graph file has the “.gph” as its filename suffix and is used to
describe the wired link connection in an optical network. The detailed format is
shown in the following:
1st line: The number of links that follow.
Each following line: FromNodeID, ToNodeID, FromPortID, ToPortID, which
means that this link starts at the “FromNodeID” node and the “FromPortID” port, and
ends at the “ToNodeID” node and the “ToPortID” port.
(35)
GPRS GGSN Service Table File
A GPRS GGSN service table file has the “.gst” as its filename suffix and is used
to describe the NSAPI, QoS level, and GGSN IP address mapping in each line.
Currently, the NSAPI and QoS level are all set to 0.
Chapter 3 High-level Architecture of
70
NCTUns
NCTUns uses a distributed architecture to support remote simulations and
concurrent simulations. It also uses an open-system architecture to enable protocol
modules to be easily added to the simulator. In the following we describe some
important features and components of NCTUns.
3.1 Simulation Methodology
NCTUns is based on a novel simulation methodology -- the kernel re-entering
simulation methodology. It uses the existing real-world Linux protocol stack to
generate high-fidelity TCP/IP network simulation results. Figure 3.1.1 depicts this
concept.
1
Figure 3.1.1. The kernel re-entering simulation methodology
In Figure 3.1.1, the TCP/IP protocol stack used in the simulation is the existing
real-life stack in the kernel. Although there are two TCP/IP protocol stack depicted,
actually they are the same one – the protocol stack inside the Linux kernel. The tunnel
interface is a pseudo network interface that does not have a real physical network
attached to it. From the kernel‟s point of view, the tunnel interface is no different from
any real Ethernet network interface.
In Figure 3.1.1, the TCP sender sends a packet into the kernel, and the packet
71
goes through the kernel‟s TCP/IP protocol stack just as an Ethernet packet would do.
Because we configure the tunnel interface 1 as the packet‟s output device, the packet
will be inserted to tunnel interface 1‟s output queue. The simulation engine will
immediately detect such an event and issue a read system call to get this packet
through tunnel interface 1‟s special file. (Note that every tunnel interface has a
corresponding device special file in the /dev directory.) After experiencing the
simulation of transmission delay and link‟s propagation delay, the simulation engine
will issue a write system call to put the packet into tunnel interface 2‟s input queue.
The kernel will then raise a software interrupt and put the packet into the TCP/IP
protocol stack. Then, the packet will be put into the receive queue of the socket that
the TCP receiver creates. Finally, the TCP receiver will use a read system call to get
packet out of the kernel.
In the case of Figure 3.1.1, the packet sent by the TCP sender passes through the
kernel two times. This is the property of the kernel re-entering simulation
methodology. By re-entering the kernel multiple times, we can create an illusion that
a packet passes through several different hosts (i.e., the packet thinks that it passes
through several different TCP/IP protocol stack). Actually, the packet is always in the
same machine and passes through the same TCP/IP protocol stack. The following
figures (Figure 3.1.2 and Figure 3.1.3) further illustrate this concept.
Figure 3.1.2 shows an example simulation network topology and Figure 3.1.3
illustrates how the kernel re-entering simulation methodology works in Figure 3.1.2.
In the example topology, host 1, host 2 and the router are layer-3 devices while the
switch is a layer-2 device. (Here we use the OSI 7-layer standard.) We directly use
those protocols that are higher than the layer-3 protocol (i.e., the network or IP layer)
in the kernel. As such, if any device is a layer-3 device, we only need to simulate its
layer-1 and layer-2 protocol in the simulation engine and its other protocols can be
simulated by directly using those protocols already in the kernel. Therefore, in Figure
3.1.2, when a packet is passed through the two hosts or the router, it will be passed
into the kernel. As we can see in Figure 3.1.3, if a packet wants to traverse the
simulation network from host 1 to host 2, it needs to be put into the kernel three
times.
72
Figure 3.1.2. The simulation network topology
Figure 3.1.3. The packet trace of a packet that will traverse the simulation
network from host 1 to host 2.
3.2 Job Dispatcher and Coordinator
NCTUns uses a distributed architecture to support remote simulations and
concurrent simulations. The job dispatcher is used to do this task. It should be
executed and remain alive all the time to manage multiple simulation machines. On
every simulation machine, the coordinator needs to be executed and remain alive to
let the job dispatcher know whether currently this machine is busy running a
simulation case or not. Figure 3.2 depicts the distributed architecture of NCTUns.
73
Figure 3.2. The distributed architecture of NCTUns
For example, the job dispatcher in the simulation service center can accept
simulation jobs from the whole world. When a user submits a simulation job to the
job dispatcher, the dispatcher selects an available simulation machine to service the
job. If there is no available simulation machine, the job will be put into the job queue
of the job dispatcher. Every simulation machine always has a running coordinator to
communicate with the GUI program and the job dispatcher. The coordinator will
notify the job dispatcher whether the simulation machine managed by itself is
available or not. When the coordinator receives a simulation job from the job
dispatcher, it forks (executes) a simulation engine process to simulate the specified
network and protocols. When the simulation engine process is running, the
coordinator will communicate with the job dispatcher and the GUI program. For
example, periodically the simulation engine process will send the current virtual time
of the simulation network to the coordinator. Then the coordinator will relay the
information to the GUI program. This enables the GUI user to know the progress of
the simulation. During a simulation, the user can also on-line set or get a protocol
module‟s value (e.g. to query or set a switch‟s switch table). Message exchanges
happening between the simulation engine process and the GUI program are all done
via the coordinator.
3.3 Simulation Engine Design
The simulation engine is a user-level program and has complex functions. It
functions like a small operating system. Through a defined API, it provides useful and
74
basic simulation services to protocol modules. These services contain virtual clock
maintenance, timer management, event scheduling, variable registration, script
interpreter, IPC interface, etc. At the same time, it manages all of the tools and
daemons that are used in a simulation case and decides when to start these programs,
when to finish them, and when to run them. Figure 3.3.1 shows an architecture
diagram of NCTUns.
Figure 3.3.1. The architecture of NCTUns
75
Figure 3.3.2: The module based platform
In Figure 3.3.1, we can see the whole architecture of NCTUns. In the section, we
first describe the organization of the simulation engine. In section 3.4, we will explain
how the kernel supports the simulation engine. We can simply divide the simulation
engine into several components:
I. Script Interpreter
The script interpreter reads a script file of a simulation case to construct the
simulation network environment, the network conditions, protocol module settings,
and the network traffic.
II. Module Manager
The module manager manages all protocol modules that users registered and
used in a simulation. When the script interpreter parses the script file, the module
manager dynamically constructs the corresponding C++ objects and organizes them
to build a simulation network environment. In Figure 3.3.1, those modules in the box
of the module-based platform form a simple simulation network.
III. Command Dispatcher
76
The command dispatcher is used to communicate with other external
components such as the coordinator, command console (It is a modified tcsh.), and
the GUI program.
IV. NCTUns APIs
All protocol modules can ask for the simulation engine‟s services via the
NCTUns APIs such as registering modules, processing events, setting timers,
creating/freeing packets, etc.
V. Event Queue
The event queue has three kinds of data structure type inside it: event, timer, and
event packet. The event is used to encapsulate messages that are exchanged between
protocol modules. Every event has a timestamp inside it used to decide when to
process it. The timer can be used to set what to do at a specified time. If an event
encapsulates a packet (e.g., an IP packet), such an event is an event packet. In the
event queue, all events or timers are sorted according to their timestamps.
VI. Scheduler
The main job of the scheduler is to execute the event or timer in the event queue.
The scheduler always picks up the event or timer that has the smallest timestamp to
execute. In the meantime, the scheduler will advance the simulation time to the
timestamp of the event.
VII. System calls and tunnel interface t0e0
Two approaches are used to enable the simulation engine to communicate with
the Linux kernel. The first approach is through system calls. The simulation engine
can use system calls that are added or modified to register/get information into/from
the kernel. This approach suits the situation when the simulation engine actively
wants to get or set some kernel parameters. The second approach is through using a
tunnel interface. If the kernel wants to actively inform the simulation engine of some
information, the tunnel interface t0e0 is used. The kernel can fill a packet with some
information and insert it into the tunnel interface t0e0. Then the simulation engine can
issue a read() system call to get the packet and further get the information inside it.
77
This mechanism is mostly used by the kernel timeout event and the tunnel check
event. (We will describe this in section 3.5 of part I).
VIII. IPC (Inter-Process Communication)
The IPC in the simulation engine is used to communicate with the coordinator.
When a GUI user wants to send a command to the simulation engine such as pause a
simulation, stop a simulation, send command to a protocol module etc., the GUI
should send the command to the coordinator and then the coordinator relays the
command to the simulation engine via IPC. After the simulation engine processes the
command, it will send the result back to the coordinator and then the coordinator will
relay the result to GUI.
Due to the module-based platform, we can dynamically construct or change the
network protocol of a device. For example, Figure 3.3.2 shows a simple simulation
case: the switch is a two-port layer-2 device and is connected with the host 1 and host
2 (host 1, 2 are both layer-3 devices). We can easily change the protocol module
settings of host 1. We can just replace the FIFO module with a RED (Random Early
Drop) module in the script file and then the module manager will dynamically
construct corresponding protocol module settings according to the script file. We can
also build a network device via the module-based platform. The switch device in
Figure 3.3.2 is a layer-2 device and all components of the device are represented by
modules. In addition to protocol modules, the layer-3 devices (such as host 1, host 2)
will need kernel supports because we directly use the layer-3 protocols in the kernel.
Figure 3.3.2 also shows the flow path that a packet will take when it is
exchanged between the two traffic generators via the module-based platform. We
already explained how a packet will pass through the kernel in section 3.1. When the
packet is read by the simulation engine from tunnel interface 1 (tun1), the packet will
follow the trace of Figure 3.3.2 and then the simulation engine will insert it into
tunnel interface 2. Finally, the kernel will send it to the traffic generator.
3.4 Kernel Modifications
In order to enable the kernel re-entering simulation methodology to properly
work, some kernel source needs to be modified according to these requirements.
These requirements include:
78
I. Allow the S.S.D.S IP Scheme to Work
In order to route packets in the same kernel, we proposed a special IP scheme -S.S.D.D IP format. Readers can refer to [1] and [13] to get the detailed definition.
As such, we should add some mechanisms into the TCP/IP protocol stack to
correctly translate the IP address of a packet.
II. Modify the Tunnel Interface Device Driver
Modifying the tunnel driver is necessary to enable the S.S.D.D IP scheme to
work because we want the packet to have the normal IP scheme when it is read
by the simulation engine. Also, we want the packet to have the S.S.D.D format
when it is inserted into a tunnel interface.
III. Perform Port Number Mapping
We use an example to illustrate this requirement. If there are two Web servers
running on the same simulation network, both of them may want to use the
default port number 80 as their listening port number. However, because they are
running on the same system (using the same TCP/IP protocol stack), only one of
them can successfully bind to port number 80. To solve this problem, we should
do port mapping in the kernel to enable the program running on different
simulated nodes to use the same port number.
IV. Add or Modify System Calls
We need to add or modify some system calls to provide services that the
simulation engine will require. For example, when a traffic generator is forked
by the simulation engine, the simulation engine immediately needs to tell the
kernel that the traffic generator belongs to which node. This operation is needed
because we have to use this information to translate the IP address of those
packets sent by the traffic generator.
V. Let Kernel Timers to be based on the Virtual Time
Because all of the events or timers in the simulation engine‟s event queue are
based on the virtual time, all of kernel timers used for NCTUns should also use
the virtual time. For example, when the TCP control block (i.e., a TCP socket
handler) transmits out a packet, it may set a retransmission timer. If the TCP
control block is used for a simulation network, the timer should use the virtual
time. In addition, all of the system calls that are involved with real time may
need to use virtual time. These system calls include select(), alarm(), sleep(),
79
gettimeofday(), etc.
VI. Kernel Events
There are two kinds of kernel event. The first is the kernel timeout event. When
the kernel wants to schedule a timer and the timer is based on the virtual time,
we should use the tunnel interface t0e0 to tell the simulation engine when to
trigger this event. The second is the tunnel check event. When any packet is
queued into a tunnel interface‟s output queue, the kernel will insert a tunnel
check event into the tunnel interface t0e0 to let the simulation engine know
which tunnel interface has packets to send.
3.5 Discrete Event Simulation
The discrete event simulation methodology is applied to NCTUns to speed up its
simulations. The challenge is to combine the kernel re-entering simulation
methodology with the discrete event simulation methodology. The objects simulated
in NCTUns are not contained in a single program; rather, they are contained in
multiple independent programs running concurrently on a UNIX machine such as
traffic generators, the simulation engine, the UNIX kernel, etc. Therefore, we need
the kernel to provide some information or services to communicate with the
simulation engine. As such, the simulation engine can manage all events and timers at
user level. In other words, our goal is to manage and trigger all of the events in the
simulation engine regardless of whether the events are kernel events or not.
80
Chapter 4 Simulation Engine – S.E
4.1 Architecture of the Simulation Engine
The Simulation Engine (S.E) is the core of NCTUns. It provides a module-based
platform for users to develop their protocols and integrate them into our simulator. By
linking modules in a controlled way, users can easily create any arbitrary network
device on our network simulator. Similarly, by connecting network devices together,
users can arbitrarily create a network topology and simulate it. Figure 4.1 depicts the
architecture of the Simulation Engine in NCTUns. As this figure shows, the S.E is
composed of six components. They are Scheduler, Event, Module Manager, Script,
Interpreter, Dispatcher, and NCTUns APIs, which we already discussed roughly in
Chapter 3.
When the simulator starts, the Script Interpreter component will parse a topology
file. The parsing results from the Script Interpreter are then passed to the M.M
component. The M.M component creates a simulation network according to these
information. After that, the S.E initiates its Scheduler component to start its timer.
Then the scheduler will poll each tunnel network interface periodically to try to read a
packet from a tunnel network interface. Upon reading a packet from a tunnel interface,
the scheduler calls the first module in a node and passes the packet to it. After
processing the packet, the first module continues to pass the packet to the second
module, third module and so on in the same node. In the modules, modules could
request a service from the S.E. through the NCTUns APIs. For example, they could set
up a timer through the timer APIs. When the timer expires, the scheduler will call a
function which is specified by a function pointer in the timer structure.
FIGURE 4.1: THE ARCHITECTURE OF THE SIMULATION ENGINE.
81
4.2 Event
The event is the most basic interface in the S.E that is used to communicate with
the Scheduler component. For a module, the module could ask for an event from the
S.E to notify the scheduler when to call a handler function. For example, a module
may get an event for simulating packet transmissions (Upon expiration time, a handler
function is called to transmit a packet). As another example, a module may ask for an
event from the S.E to implement its polling mechanism. Hence, if a module wants to
request a service from the S.E, it should encapsulate its request as an event. Then the
scheduler will accept and provide services for it.
In addition, an event also provides a platform for easily building a high-level
service for modules. As Figure 4.1 shows, the event component contains three smaller
components – Packet, Timer and Event Manager. These components provide a
high-level service to modules based on the event interface:
1. For the Packet component, it encapsulates packet as an event. We name this
kind of event “ePacket”. By encapsulating a packet as an ePacket, the packet
can directly be scheduled in the Scheduler component.
2. For the Timer component, it provides a timer mechanism for modules. For
modules, they may have many chances to use the timer mechanism. For
example, in a MAC (Media access control) module, we may ask for a timer
to know if the MAC should retransmit a packet that was sent before – (While
the MAC sends a packet, it also sets a timer. When the timer expires but no
ACK has been received yet, the MAC will know that the outgoing packet
was lost and should be retransmitted again).
3. For the Event Manager, users can register a periodical event with the Event
manager. The periodical event is an event which will be periodically
processed by the event Scheduler. Under the control of the Event manager,
users can dynamically enable or disable a scheduling event through either a
tcsh command interpreter or a GUI environment.
struct event {
u_int64_t
timeStamp_;
u_int64_t
perio_;
NslObject
*calloutObj_;
int
(NslObject::*memfun_)(struct event *);
int
(*func_)(struct event *);
82
void
*DataInfo_;
u_char
priority_;
struct event
*next_ep;
};
The above data structure lists the declaration of an event structure. In this data
structure, the „timeStamp_‟ is the expiration time of an event. Note that there is a
system global virtual time maintained in the Scheduler component. Once this virtual
time equals to this „timeStamp_‟, the scheduler component will call the handler
function which is specified in the event structure. The middle fields of the above
declaration are used to specify a handler function. In these statements we can see that
the handler function could be either a normal function or a member function of an
object. If a handler function is a normal function, the „func_‟ is used and this handler
function that the „func_‟ points to should be in the following form:
int (Event *ep) {
…………………………………
…………………………………
}
Similarly, if a handler function is a member function of an object, both the
„calloutObj_‟ and the „memfun_‟ are used and the handler function which both the
„calloutObj_‟ and the „memfun_‟ specify should be in the following form:
int
Source Exif Data:
File Type : PDF
File Type Extension : pdf
MIME Type : application/pdf
PDF Version : 1.5
Linearized : No
Page Count : 248
Language : zh-TW
Tagged PDF : Yes
Title : Chapter 1 Introduction
Author : SuperXP
Creator : Microsoft® Office Word 2007
Create Date : 2010:01:12 06:04:20
Modify Date : 2010:01:12 06:04:20
Producer : Microsoft® Office Word 2007
.