Introduction of Protocol Module Development

Outline

Running A Protocol ModuleAdding a new moduleModule Information for Simulation Engine. ( .tcl file )

Developing A Protocol ModuleA Module classProcessing FlowsEvent and TimerRuntime Query

Steps for Running Protocol Modules (Step1)

In the GUI node editor:

use module icons to configure each node’s protocol stack.

Step2In the GUI node editor:

use module dialog box to set each module’s parameters.

Step 3 & 4Pass the configuration information of each node’s protocol stack and each parameter’s value to the simulation engine (S.E) .

The SE reads in the configuration information and then starts simulating the protocol behaviors defined in protocol modules.

Adding a new moduleWhat steps should a module developer take to add a module into the NCTUns ?

In Simulation EngineProvide a module class

Write protocol-specific proceduresRegister the new module

In GUIProvide a module icon and a module dialog boxAdd one entry to the module description file (mdf.cfg)

Module Description File (mdf.cfg)

Module developers can use the module description file (mdf.cfg) to describe the dialog box layout for each module.There are four sections for describing a module and the layout of its dialog box:

• ModuleSection• HeaderSection• InitVariableSection• ExportSection

Sections of a Module Description File Entry

HeaderSection( module name, group name, network type,parameter declaration,

etc. )EndHeaderSection

InitVariableSection( GUI objects : button obj, textline obj, radio/check box obj, etc. )

EndInitVariableSection

ExportSection( GUI objects for run time query and setting )

EndExportSection

ModuleSection

EndModuleSection

HeaderSectionHeaderSection

ModuleName ARPClassName arpNetType Wire/WirelessGroupName ARPAllowGroup XXXXXPortsNum MultiPortVersion SIMPLE-ARP_001Author NCTU_NSLCreateDate 2/28/02Introduction "This is an ARP module."Parameter arpMode RunARP localParameter flushInterval 3000 localParameter ArpTableFileName $CASE$.N$NID$_P$PID$.arp

autogendonotsaveEndHeaderSection

InitVariableSection (1/2)InitVariableSection

Caption "Parameters Setting"FrameSize 350 160…Begin TEXTLINE flushInterval

Caption "Flush Time Interval "Scale 40 55 180 30 ActiveOn MODE_EDITEnabled FALSE Type STRINGComment "Flush Interval"

End

InitVariableSection(2/2)…Begin BUTTON b_ok

Caption "OK"Scale 280 17 60 30 ActiveOn MODE_EDITEnabled TRUEAction okComment "OK Button"

End…

EndInitVariableSection

ExportSection (1/2)ExportSection

Caption "Run Time Query"FrameSize 350 60

Begin INTERACTIONVIEW iv_arpCaption "Arp Table"Scale 10 20 200 30ActiveOn MODE_SIMULATIONEnabled TRUEAction GETActionObj "arp-table"Fields "MAC Address" "IP address" Comment "Arp Table"

End

EndExportSection

ExportSection (2/2)ExportSection

Begin TEXTLINE t_ql…Begin ACCESSBUTTON ab_g

Caption "Get“Scale 215 23 70 20 ActiveOn MODE_SIMULATIONEnabled TRUE Action GETActionObj "cur-queue-length"Reference t_qlComment "get"

End…

EndExportSection

Tcl FileAfter manipulating the GUI node editor, the configuration information will be stored in a file with the suffix “.tcl”.

A tcl file mainly consists of three parts :global variable initializationnode protocol stack specificationnode connectivity specification

Global Variable InitializationFour global variables are used in the tcl file.Set SimSpeed =

AS_FAST_AS_POSSIBLESet TickToNanoSec = 100Set WireLogFlag = onSet WirelessLogFlag = on

Node Protocol Stack Specification

Create Node 1 as HOST with name = HOST1Define port 1

Module Interface : Node1_Interface_1Module ARP : Node1_ARP_1

Set Node1_ARP_1.arpMode = RunARPSet Node1_ARP_1.flushInterval = 3000Set Node1_ARP_1.ArpTableFileName = testInfra.N1_P1.arp

Module FIFO : Node1_FIFO_1Module MAC8023 : Node1_MAC8023_1Module TCPDUMP : Node1_TCPDUMP_1Module Phy : Node1_Phy_1Module Link : Node1_LINK_1

Bind Node1_Interface_1 Node1_ARP_1Bind Node1_ARP_1 Node1_FIFO_1Bind Node1_FIFO_1 Node1_MAC8023_1Bind Node1_MAC8023_1 Node1_TCPDUMP_1Bind Node1_TCPDUMP_1 Node1_Phy_1Bind Node1_Phy_1 Node1_LINK_1

EndDefineEndCreate

Node Connectivity Specification

Connect WIRE 1.Node1_LINK_1 2.Node2_LINK_1Connect WIRE 2.Node2_LINK_2 3.Node3_LINK_2Connect WIRE 2.Node2_LINK_3 4.Node4_LINK_2Connect WIRELESS 3.Node3_LINK_1 4.Node4_LINK_1 Connect WIRELESS 5.Node5_LINK_1

Simulation Engine (S.E)

The simulation engine (S.E) reads in the tcl file passed from GUI and then performs the following procedures :• node registration• module object construction• variable initialization• node connectivity• start simulation

Module Class

How to write a module class ?

C++ programming styleClass “NslObject” is the basic class, other module classes have to inherit from it.Class “NslObject” provides basic virtual member functions.

NslObject Classclass NslObject {

…… < deleted > ……MBinder *recvtarget_; /* to upper component */MBinder *sendtarget_; /* to lower component */NslObject(u_int32_t, u_int32_t, u_int32_t, char *); NslObject();virtual ~NslObject();

virtual inline int init();virtual inline int recv(ePacket_ *); virtual inline int send(ePacket_ *); virtual int get(ePacket_ *, MBinder *);virtual int put(ePacket_ *, MBinder *);virtual ePacket_ *put1(ePacket_ *, MBinder *);virtual inline int command(int argc, char *argv[]); …… < deleted > ……

};

Some Members of NslObjectClass

sendtarget_ and recvtarget_module binders

send() and recv()protocol-specific procedures

get(), put() and put1()module-to-module interface function calls

command()default “Set command” processing functionrun-time query/setting processing function

Send & Receive Call Flows

Send flow Receive flow

Module-to-module Interface Function Calls

Variable InitializationUse vBind() macro to set variables’ valuese.g.

tcl file :Set Node1_ARP_1.arpMode = RunARPSet Node1_ARP_1.flushInterval = 3000Set Node1_ARP_1.ArpTableFileName = testInfra.N1_P1.arp

arp.cc init() :char *ARP_MODE;int flushInterval;char *fileName;

vBind("arpMode", &ARP_MODE);vBind("flushInterval", &flushInterval);vBind("ArpTableFileName", &fileName);

Default Variable Initialization

If there is no corresponding vBind list for a variable, the Set command for that variable in tcl file will be passed to command() function.e.g.

tcl file :Set Node1_ARP_1.special_purpose = yes

arp.cc command(int argc, char *argv[]) :argv = {Set, special_purpose, =, yes};

Shared Variables

Variables can be shared between modules under the same port.e.g.

module A :int aaa;REG_VAR(“AAA”, &aaa);

module B :int *get_aaa;get_aaa = GET_REG_VAR(get_port(),

“AAA”, int *);

Start SimulationThe NCTUns has an event-triggering simulation engine based on virtual time.

The event object is the only object passed among modules.

User-defined objects (e.g., packet objects ) should be included in the event objects.

User-defined protocol-specific procedures will be performed in send() or recv().

Event Structure(struct Event = Message_ = Frame_ = ePacket_ = Event_ )

typedef struct event {

…… < deleted > ……u_int64_t timeStamp_;u_int64_t perio_; NslObject *calloutObj_;int (NslObject::*memfun_)(struct event *);

int (*func_)(struct event *);void *DataInfo_; u_char priority_;…… < deleted > ……

} Event;

Timer Set a timer for triggering a function call in the future.e.g.

timerObj myTimer;BASE_OBJTYPE(type);

type = POINTER_TO_MEMBER(class_name,function_name);myTimer.setCallOutObj(this, type);myTimer.start(expire_time, period);

myTimer.cancel(); /* used for cancelling a timer */

Event Triggering

Set an event’s triggering time.e.g.

struct myPacket *myPacket;BASE_OBJTYPE(type);

type = POINTER_TO_MEMBER(class_name, function_name);Event_ *ep = createEvent();setObjEvent(ep, trigger_timestamp, period, this, type,(void*)myPacket);

setEventReuse(ep); /* periodically trigger event */

Event PrioritiesThere are four event priorities ranging from level 1 (lowest) to level 4 (highest).Setting event priority can be performed via the put1() function. e.g.

…………Event_ *ep = createEvent();setObjEvent(ep, trigger_timestamp, period, this, type, (void*)mystruct);SET_MLEVEL_1(ep); /* lowest priority */SET_MLEVEL_2(ep);SET_MLEVEL_3(ep);SET_MLEVEL_4(ep); /* highest priority */

Run-time QueryUse EXPORT() macro to register a query tag.

e.g. EXPORT("arp-table", E_RONLY);Run-time query command strings will be passed from GUI to command() in specific module. The command() will then locate the corresponding variable or object based on the query tag. Formats of command strings:• {Set} {query_tag} {value}• {Get} {query_tag}• {GetAll} {query_tag}Module developers can use the ExportStr object to collect the query results and send the results back to the GUI.

ExportStr ObjectThe ExportStr object provides a mechanism to frame multi-column information. (can be used for a file)

Retrieve cell information out of the ExportStr object to display them in a GUI object.

IP MAC1.0.1.1 1:1:1:1:1:11.0.1.2 2:2:2:2:2:21.0.1.3 3:3:3:3:3:3

# This is a run time query # results for arp-table.IP MAC1.0.1.1 ---------- 1:1:1:1:1:11.0.1.2 ---------- 2:2:2:2:2:21.0.1.3 ---------- 3:3:3:3:3:3

color 1 : commentcolor 2 : separatorcolor 3 : cell

Batch File for Run-time QueryThe batch file’s command format (.sct):

{Trigger Time(sec)} + tab + {Command} + tab + {Output Filename}

Formats of commands :{Set} {nodeID} {portID}{module_name} {query_tag} {value}{Get} {nodeID} {portID} {module_name} {query_tag}{GetAll} {module_name} {query_tag}

Combine A New Module into the S.E

MakefileOBJ_MODULE = module/myclass/myclass.oSRC_MODULE = module/myclass/myclass.ccclean:

./module/myclass/*.o

./module/myclass/*~~NCTUns/src/nctuns/nctuns.cc

REG_MODULE(“MYMODULE”, Myclass);

Q & A

Thanks