1. Module 9 Writing Protocols

2. Writing Protocols - Introduction
Goal
Add a simple application-layer protocol to QualNet & Exata on the Windows platform
Using minimal code
Steps are the same on UNIX as in Windows
Template files are provided
Cheat sheet is available

3. Writing Protocols – Introduction
Intended audience
Protocol model software developers
Managers
Prerequisites
QualNet or EXata Simulator Architecture & Code Lecture
C or C++ programming experience

4. Writing Protocols - Introduction
Functionality
Accept source node from user
Accept number of packets to send from user
Send 512 Bytes packet from source to all (broadcast) using UDP every 1 second, till user specified number of broadcast messages are sent or till end of simulation is reached
Note: This is a subset of CBR functionality

5. Writing Protocols - Introduction
Syntax
Read input from *.app file
Format:
SIMPLE <src> <dest> <items to send>
Usage:
SIMPLE 1 2 5
Send broadcast from node 1 , 5 times
Why Do We Need <dst>?
Dummy destination: Shall be ignored in our implementation
Only serves to provide understanding of how to read information from the .app file for a source->destination type application

6. Writing Protocols - Basics
QualNet & EXata are a C/C++ program
Source files (*.cpp) and header files (*.h)
Some source files are precompiled – the source files aren’t available in the distribution
Although QualNet & EXata are C++, it currently doesn’t use the more complicated features of C++, such as classes, templates, namespaces, and so on

7. Writing Protocols - QualNet & Exata API
The QualNet & Exata API, like other APIs, consists of functions, data types, etc.
QualNet & Exata API is not as large as other APIs, but it’s still hard to remember everything
Tip 1: Study another simple & similar model (
CBR: Application traffic generator
RIP: Application routing
Tip 2: Cut-and-paste commonly used code into new models

8. Writing Protocols - Confidence builder
Write Hello World in C and C++
Write a Hello World program in Windows (hello.c)
Use Visual C++’s cl command to compile at the command line
cl hello.cpp
This command creates a hello.exe file
If cl can’t be used on your workstation, check that Visual C++ is installed

9. Sys. Architecture & Code - Compiling QualNet & Exata
Requires
C++ Complier:
MS Visual C++ .NET 2002 or higher
MS Visual C Express (Requires Windows Platform SDK)
GNU gcc 3.2 or later
Need
New code/protocol is added to QualNet & Exata
Modifications are made to an existing model
Integrating patches

10. Sys. Architecture & Code - Compilation Steps
Step1: Open a command prompt
Step2: Go to the "product"_HOME/main directory.
Step3:
For Windows:
For .NET 2005 or Microsoft Visual C Express Edition with Windows Platform SDK, use the following command:
copy Makefile-windows-vc8 Makefile
For Microsoft Visual C++ .NET 2002 or Microsoft Visual C++ .NET 2003, use the following command:
copy Makefile-windowsnt-vc7 Makefile
For Linux, Solaris, MAC OS X :
Copy appropriate makefile:
cp Makefile-linux-glibc-2.3-gcc-3.2 Makefile OR
cp Makefile-linux-glibc-2.3-gcc-4.5 MakefileOR
cp Makefile-linux-x86_64-glibc-2.3-gcc-3.3 Makefile OR
cp Makefile-solaris Makefile
cp Makefile-darwin-ppc-gcc-4.5 Makefile
make
Result:
Creates the QualNet & Exata executable in the "product"_HOME/bin

11. nmake –f makefile-windows-vc8
Sys. Architecture & Code - Compilation Tips
TIP1: Copying makefile-* to makefile prevents specifying makefile each time such as:
nmake –f makefile-windows-vc8
TIP2: Sometimes it is useful to delete all object files before re-compiling:
Windows:
nmake clean
nmake
UNIX:
make clean
make

12. Sys. Architecture & Code -Compilation Tips
TIP3: Controlling Debugging & Optimization
From Makefile comment the line that is not needed by placing a # at the beginning of line. Use DEBUG & OPT mutually exclusively.
Example1: Windows (Debugging)
DEBUG = /Zi
#OPT = /Ox /Ob2
Example2: UNIX (Optimization)
#DEBUG = -g
OPT = -O3

13. Writing Protocols - Layers of the TCP/IP stack
QualNet & EXata are based on the Internet TCP/IP stack
The TCP/IP stack has five layers. They are as follows:
Application
Transport
Network
Data Link (includes MAC)
Physical

14. Writing Protocols - Directory Structure
Contains
addons
Components developed as custom addons for specific customers
bin
Executable and other runtime files such as DLLs
contributed
Models contributed by QualNet or EXata customers.
data
Data files for the Wireless library: antenna configurations, modulation schemes and sample terrain
documentation
User Guide, release notes, etc.
gui
Graphical components including icons, Java class files, and GUI configuration.
include
QualNet or EXata kernel header files.
interfaces
Code to interface QualNet or EXata to 3rd party tools or external networks, such as HLA, STK, or IP networks.
kernel
QualNet or EXata kernel objects used during the build process.
lib
3rd party software libraries used during the build process.
libraries
Source code for model libraries such as Developer, Multimedia & Enterprise, & Wireless.
license_dir
License files and license libraries required for the build process.
main
Kernel source files and Makefiles.
scenarios
Sample scenarios.

15. Writing Protocols - Which layer in the stack?
Which layer should be used?
The application layer is the easiest place to add a protocol
Why? We only need to worry about interfacing to a single layer.
A network-layer model would need to interface with two layers (transport and data-link (MAC))
Real protocols
If modeling a real-world protocol, where is it usually implemented?
RIPv2: Application-layer, uses UDP to send control packets
ping: Network-layer, uses ICMP packets

16. Writing Protocols - Define APP_SIMPLE
include/application.h contains an enum which lists application types
Client and server of same application need to process different events and have their own “internal names”
Add the *internal name* of simple client and server to the end of AppType:
… APP_SIMPLE_CLIENT, APP_SIMPLE_SERVER,
APP_PLACEHOLDER } AppType;

17. Writing Protocols - Tip: Inserting macro values
Add constants to the end of lists in header files (but before the “placeholder”)
This prevents compilation errors with QualNet & Exata
If constants are inserted at the top of the list, values below may be offset by 1
Some pre-built object files may depend on the original values

18. Writing Protocols - Create C++ source files
“Simple” protocol
Create files: /libraries/developer/src/app_simple.cpp /libraries/developer/src/app_simple.h
simple.h:
#ifndef SIMPLE_H #define SIMPLE_H // Source code goes here #endif /* SIMPLE_H */

19. Writing Protocols - Header Files: simple.cpp
Header files included in simple.cpp
Source:/libraries/developer/src/app_simple.cpp/libraries/developer/src/
app_cbr.h
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "api.h"
#include "partition.h"
#include "app_util.h“
#include “app_simple.h”
#include “network_ip.h”
Explanation
api.h declares all standard QualNet & Exata types, functions
app_util.h required for application-layer protocols using TCP and UDP
partition.h: APIs & data structures for coordination between partitions

20. Writing Protocols - Tips: QualNet & Exata header files
Keep the following tips in mind:
Omitting a header file can cause strange problems, even if there are no problems indicated by the compiler
Keeping protocol small at first helps to locate problems
When including header files for QualNet & Exata models, start with api.h, then go from the bottom up (physical layer to application layer)
Some #include's may not be obvious (app_util.h); See similar models for guidance

21. Writing Protocols - Understanding The Template Files
Simple Application Has two parts:
Client
Server
Create the three required functions for Simple Client:
Init function
Process event
Finalize functions
Repeat the process for Simple protocol Server
Function prototypes are in the header file and function body is in the simple.cpp file

22. Writing Protocols - Understanding The Parameters - I
Node *node
Pointer to the Node structure
Message* msg
Pointer to the message or event
AppInfo* appInfo
Pointer to application information

23. Writing Protocols - Common function code fragments & APIs
Node *node
Each node has node structure
struct struct_node_str is defined in include/node.h
Provides access to all node specific information including states of all protocols at all layers
Examples:
node->nodeId
getSimTime(node)
TIME_PrintClockInSecond(getSimTime(node), buf);
printf(“Time is %s Seconds \n", node->nodeId, buf);

24. Writing Protocols - Common function code fragments & APIs
Message *msg
Packet or Timer events
Examples:
switch (msg->eventType) {
case MSG_APP_TimerExpired:
MESSAGE_PacketAlloc
MESSAGE_InfoAlloc
MESSAGE_Send

25. Writing Protocols - Understanding The Parameters
Optional Parameters We Added:
Address clientAddr
Address serverAddr
Int32 itemsToSend
The client shall accept these from the user

26. Writing Protocols - Common function parameters
Commonly used prototypes
FunctionName(Node* node) FunctionName(Node* node, Message* msg)
... are common motifs in QualNet & Exata
“node” is referred to as a node pointer “msg” is referred to as a message pointer
FunctionName(Node* node, NodeInput* nodeInput)
... is used frequently in init functions
nodeInput contains default.config, default.app, ... information

27. Writing Protocols - Write SimpleInit() code
Insert preliminary (easy) code
app_simple.cpp, in AppSimpleClientInit ()
printf(“Simple Client Initializing at Node %d \n”,node->nodeId);
app_simple.cpp, in AppSimpleServerInit ()
printf(“Simple Server Initializing at Node %d \n”,node->nodeId);

28. Writing Protocols - Calling The Functions
Where are the functions being called?
… they aren’t being called from anywhere yet
Need to register the three main functions with the layer
Application layer protocols are handled in main/application.cpp
Process is similar for all protocols at same layer. Task is easier by copying existing code and then modifying it.

29. Writing Protocols - Application.cpp
Needs to be aware of your header file
Add #include “app_simple.h“ at the end of list of include files

30. Writing Protocols - Call Init
Application.cpp - APP_InitializeApplications
Starts applications on nodes
Just before if (strcmp(appStr, "CBR") == 0) add code to initialize SIMPLE
Copy and paste from CBR code in the function
Final output included on next slide

31. Writing Protocols - Call Init

32. Writing Protocols - Call Finalize
Application.cpp - APP_Finalize
Called for all protocols at end of simulation
Just before case APP_CBR_CLIENT add code to finalize SIMPLE
Copy and edit CBR code in the function to achieve this
Final output included on next slide

33. Writing Protocols - Call Finalize

34. Writing Protocols - Call Process Event
Application.cpp - APP_ProcessEvent
Called for all protocols at application layer when there is an event (packet or timer) for them
Just before case APP_CBR_CLIENT add code to process events for SIMPLE
Copy and edit CBR code in the function to achieve this
Final output included on next slide

35. Writing Protocols - Call Process Event

36. Writing Protocols - Edit Makefile-common - I
Modify libraries/developer/Makefile-common:
We will add protocol to developer library
Insert app_simple.cpp in list of cpp files
Don’t forget the backslash character “\”
The files are sorted alphabetically for neatness, but it doesn’t matter where the two lines are inserted in each list

37. Writing Protocols - Compile QualNet & Exata
Test the protocol by compiling QualNet & Exata
cd main
Copy Makefile-windows-vc8 to Makefile
After performing this step, “nmake” can be run without arguments
Run nmake
Can also run nmake from the bin directory
Linux: Copy Makefile-linux-… to Makefile, run “make”
Compile frequently for testing purposes

38. Writing Protocols - Test SimpleInit()
Compile QualNet & Exata and test
Make a copy of the default scenario. Call it mydefault.
Edit mydefault.app to ONLY contain
SIMPLE 1 2 5
cd ..\bin nmake QualNet or EXata mydefault.config
Expected output: Simple protocol initialization message is printed
Review the code so far!

39. Writing Protocols - Writing message code
Sending a message
Purposes:
... set a timer for an internal protocol event
... communicate with protocols at other layers
Steps in sending a message
Create / allocate memory for a message
Send it

40. Writing Protocols - Create and allocate message
(1) Create / allocate memory for a message
simple.cpp, in AppSimpleClientInit ():
Message* newMsg = MESSAGE_Alloc( node, APP_LAYER, // layer APP_SIMPLE_CLIENT, // protocol MSG_APP_TimerExpired); // event MSG_APP_TimerExpired is already defined in include/api.h

41. Writing Protocols - Send message
(2) Send the message
simple.cpp, in SimpleInit():
… MESSAGE* newMsg = MESSAGE_Alloc(…) MESSAGE_Send(node, newMsg, delay);
delay is in units of clocktype
Replace delay with 1 * SECOND for now

42. Writing Protocols - Time in QualNet & Exata
A clocktype is a long long
... an int is a signed 32-bit integer ... a clocktype is a signed 64-bit integer
In QualNet & Exata, 1 unit of clocktype == 1 nanosecond
In previous code, delay was 1 second
To use larger units, multiply the number by the unit
e.g., 5 * SECOND 15 * MILLI_SECOND 1 * SECOND * node->nodeId
Sometimes PROCESS_IMMEDIATELY is used This constant is a macro for 0 (either is fine)

43. Writing Protocols - Receive message
When the message arrives, handle it…
simple.cpp, in AppLayerSimpleClient ():
Always call MESSAGE_Free() after handling a message.
Otherwise the program leaks memory

44. Writing Protocols - Test the message code
Compile QualNet & Exata and test
> cd ..\bin
> nmake
> QualNet or EXata mydefault.config
Expected output: Node gets Timer Expired Message every 1 second

45. Writing Protocols - Send UDP packet

46. Writing Protocols - Define TRACE_SIMPLE
include/trace.h contains a declaration which lists trace types for QualNet & Exata protocols
Add TRACE_SIMPLE to the end of the TraceProtocolType enum:
… TRACE_SIMPLE, // Must be last one!!! TRACE_ANY_PROTOCOL } TraceProtocolType;

47. Writing Protocols - Send UDP packet
What was done?
APP_UdpSendNewDataWithPriority() requests UDP to send a broadcast packet
UDP will send to IP, IP will send to MAC, going to b PHY, and enter the QualNet or EXata propagation models.
The UDP packet should arrive at destination nodes (no routing used since it’s a broadcast destination), and go back up the stack, to the Simple Server protocol on the other node

48. Writing Protocols - Receive UDP Packet
When UDP gives a packet to our Simple protocol, handle the packet in AppLayerSimpleServer():
UDP packets are delivered with an event type of MSG_APP_FromTransport

49. Writing Protocols - Test UDP packet code
Compile and test QualNet & Exata
Expected output:
Some nodes receive the sent packet

50. Writing Protocols - Adding Statistics
Add stat to show number of packets sent
Use static variable:
static int packetsSent;
WARNING: Use static for training only. Production code should store information in state variable and register the same.
In AppSimpleClientInit set:
packetsSent = 0;
APP_RegisterNewApp(node, APP_SIMPLE_CLIENT, NULL);
Print stat in finalize function

51. Writing Protocols - Controlling Packets Sent
Store packetsRemaining in information field of message
Initialize in AppSimpleClientInit
Decrement by one each time in AppLayerSimpleClient
If it is 0 do not schedule more timer alerts

52. Writing Protocols - Controlling Packets Sent
AppSimpleClientInit

53. Writing Protocols - Controlling Packets Sent

54. Writing Protocols - Test the message code
Compile QualNet & Exata and test
> cd ..\bin
> nmake
> QualNet or EXata mydefault.config
Expected output: Node gets Timer Expired Message every 1 second
Packets get delivered
Required number of packets are sent and stats are collected
Visualize scenario in the GUI
Visualize statistic in the GUI

55. Writing Protocols - Configuring In The GUI
Visualization of the scenario and viewing statistics in GUI is possible by executing the .config file in the GUI
All changes have been in C/C++ files
Configuring SIMPLE protocol in GUI requires editing the JAVA program through "product"_HOME\gui\settings\choices.xml file.
Refer to Programmer’s Guide Chapter “Integrating a New Protocol into QualNet or EXata GUI” for details.

56. Writing Protocols - Files Modified
List of files modified in this tutorial
main/application.cpp
libraries/developer/src/app_simple.cpp
libraries/developer/src/app_simple.h
include/application.h
include/trace.h
libraries/developer/makefile-common

57. Writing Protocols - Not covered
Not covered in this tutorial:
Saving state for the Simple protocol
Writing an application-layer routing protocol (modifying the route table at the IP layer)
Protocols at other layers
Network-layer routing (ad hoc and non ad hoc)
Writing a MAC protocol

58. Writing Protocols - Further exercises
Transmit and recover packet contents
Try copying a string to char buf[512];
Cause nodes to transmit to a non-broadcast destination

59. Sys. Architecture & Code - Reference
For more details, please refer to:
QualNet or EXata Programmer’s Guide
QualNet or EXata API Guide
Source Code
Programmer’s Section Of QualNet or EXata Community Forums