Module 9 Writing Protocols Writing Protocols Introduction Goal

Module 9 Writing Protocols

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

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

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

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

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

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

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 n cl hello. cpp ¨ ¨ If This command creates a hello. exe file cl can’t be used on your workstation, check that Visual C++ is installed

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

Sys. Architecture & Code - Compilation Steps Step 1: Open a command prompt Step 2: Go to the "product"_HOME/main directory. Step 3: For Windows: ¨ For. NET 2005 or Microsoft Visual C++ 2005 Express Edition with Windows Platform SDK, use the following command: copy Makefile-windows-vc 8 Makefile ¨ For Microsoft Visual C++. NET 2002 or Microsoft Visual C++. NET 2003, use the following command: copy Makefile-windowsnt-vc 7 Makefile For Linux, Solaris, MAC OS X : ¨ Copy appropriate makefile: n cp Makefile-linux-glibc-2. 3 -gcc-3. 2 Makefile OR n cp Makefile-linux-glibc-2. 3 -gcc-4. 5 Makefile. OR n cp Makefile-linux-x 86_64 -glibc-2. 3 -gcc-3. 3 Makefile OR n cp Makefile-solaris Makefile n cp Makefile-darwin-ppc-gcc-4. 5 Makefile ¨ make Result: Creates the Qual. Net & Exata executable in the "product"_HOME/bin

Sys. Architecture & Code - Compilation Tips TIP 1: Copying makefile-* to makefile prevents specifying makefile each time such as: nmake –f makefile-windows-vc 8 TIP 2: Sometimes it is useful to delete all object files before recompiling: Windows: nmake clean nmake UNIX: make clean make

Sys. Architecture & Code -Compilation Tips TIP 3: 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. Example 1: Windows (Debugging) DEBUG = /Zi #OPT = /Ox /Ob 2 Example 2: UNIX (Optimization) #DEBUG = -g OPT = -O 3

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

Writing Protocols - Directory Structure Directory Contains addons Components developed as custom addons for specific customers bin Executable and other runtime files such as DLLs contributed Models contributed by Qual. Net 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 Qual. Net or EXata kernel header files. interfaces Code to interface Qual. Net or EXata to 3 rd party tools or external networks, such as HLA, STK, or IP networks. kernel Qual. Net or EXata kernel objects used during the build process. lib 3 rd 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. Confidential & Proprietary

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

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 App. Type: … APP_SIMPLE_CLIENT, APP_SIMPLE_SERVER, APP_PLACEHOLDER } App. Type;

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 Qual. Net & Exata ¨ If constants are inserted at the top of the list, values below may be offset by 1 n Some pre-built object files may depend on the original values

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

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” n Explanation api. h declares all standard Qual. Net & Exata types, functions app_util. h required for application-layer protocols using TCP and UDP partition. h: APIs & data structures for coordination between partitions

Writing Protocols - Tips: Qual. Net & 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 Qual. Net & 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

Writing Protocols - Understanding The Template Files Simple Application Has two parts: ¨ Client ¨ Server Create 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

Writing Protocols - Understanding The Parameters - I Node *node ¨ Pointer to the Node structure Message* msg ¨ Pointer to the message or event App. Info* app. Info ¨ Pointer to application information

Writing Protocols - Common function code fragments & APIs Node *node Each node has node structure – 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->node. Id get. Sim. Time(node) TIME_Print. Clock. In. Second(get. Sim. Time(node), buf); printf(“Time is %s Seconds n", node->node. Id, buf);

Writing Protocols - Common function code fragments & APIs Message *msg ¨ Packet or Timer events ¨ Examples: n switch (msg->event. Type) { case MSG_APP_Timer. Expired: n n n MESSAGE_Packet. Alloc MESSAGE_Info. Alloc MESSAGE_Send

Writing Protocols - Understanding The Parameters Optional Parameters We Added: n Address client. Addr n Address server. Addr n Int 32 items. To. Send The client shall accept these from the user

Writing Protocols - Common function parameters Commonly used prototypes – Function. Name(Node* node) Function. Name(Node* node, Message* msg) • • – . . . are common motifs in Qual. Net & Exata “node” is referred to as a node pointer “msg” is referred to as a message pointer Function. Name(Node* node, Node. Input* node. Input) • • . . . is used frequently in init functions node. Input contains default. config, default. app, . . . information

Writing Protocols - Write Simple. Init() code Insert preliminary (easy) code ¨ app_simple. cpp, n printf(“Simple Client Initializing at Node %d n”, node->node. Id); ¨ app_simple. cpp, n in App. Simple. Client. Init () in App. Simple. Server. Init () printf(“Simple Server Initializing at Node %d n”, node->node. Id);

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.

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

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

Writing Protocols - Call Init

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

Writing Protocols - Call Finalize

Writing Protocols - Call Process Event Application. cpp - APP_Process. Event ¨ 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

Writing Protocols - Call Process Event

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

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

Writing Protocols - Test Simple. Init() Compile Qual. Net & 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 Qual. Net or EXata mydefault. config Expected output: Simple protocol initialization message is printed Review the code so far!

Writing Protocols - Writing message code Sending a message ¨ Purposes: n n n . . . 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 2. Send it 1.

Writing Protocols - Create and allocate message (1) Create / allocate memory for a message ¨ simple. cpp, in App. Simple. Client. Init (): n Message* new. Msg = MESSAGE_Alloc( node, APP_LAYER, // layer APP_SIMPLE_CLIENT, // protocol MSG_APP_Timer. Expired); // event MSG_APP_Timer. Expired is already defined in include/api. h

Writing Protocols - Send message (2) Send the message ¨ simple. cpp, n in Simple. Init(): … MESSAGE* new. Msg = MESSAGE_Alloc(…) MESSAGE_Send(node, new. Msg, delay); delay is in units of clocktype n Replace delay with 1 * SECOND for now n

Writing Protocols - Time in Qual. Net & Exata A clocktype is a long . . . an int is a signed 32 -bit integer. . . a clocktype is a signed 64 -bit integer – In Qual. Net & 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->node. Id Sometimes PROCESS_IMMEDIATELY is used This constant is a macro for 0 (either is fine)

Writing Protocols - Receive message When the message arrives, handle it… ¨ simple. cpp, n in App. Layer. Simple. Client (): Always call MESSAGE_Free() after handling a message. ¨ Otherwise the program leaks memory

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

Writing Protocols - Send UDP packet

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

Writing Protocols - Send UDP packet What was done? APP_Udp. Send. New. Data. With. Priority() requests UDP to send a broadcast packet – UDP will send to IP, IP will send to 802. 11 MAC, going to 802. 11 b PHY, and enter the Qual. Net 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 –

Writing Protocols - Receive UDP Packet When UDP gives a packet to our Simple protocol, handle the packet in App. Layer. Simple. Server(): ¨ UDP packets are delivered with an event type of MSG_APP_From. Transport

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

Writing Protocols - Adding Statistics Add stat to show number of packets sent ¨ Use static variable: n static int packets. Sent; WARNING: Use static for training only. Production code should store information in state variable and register the same. n In App. Simple. Client. Init set: n n ¨ packets. Sent = 0; ¨ APP_Register. New. App(node, APP_SIMPLE_CLIENT, NULL); Print stat in finalize function

Writing Protocols - Controlling Packets Sent n n Store packets. Remaining in information field of message Initialize in App. Simple. Client. Init Decrement by one each time in App. Layer. Simple. Client If it is 0 do not schedule more timer alerts

Writing Protocols - Controlling Packets Sent App. Simple. Client. Init

Writing Protocols - Controlling Packets Sent

Writing Protocols - Test the message code Compile Qual. Net & Exata and test > cd. . bin > nmake > Qual. Net 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

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 n All changes have been in C/C++ files n Configuring SIMPLE protocol in GUI requires editing the JAVA program through "product"_HOMEguisettingschoices. xml file. n Refer to Programmer’s Guide Chapter “Integrating a New Protocol into Qual. Net or EXata GUI” for details.

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

Writing Protocols - 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) n Writing a MAC protocol n

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

Sys. Architecture & Code - Reference For more details, please refer to: n Qual. Net or EXata Programmer’s Guide n Qual. Net or EXata API Guide n Source Code n Programmer’s Section Of Qual. Net or EXata Community Forums ¨ www. Qual. Net. com/training_and_support/forums/index. php