Beruflich Dokumente
Kultur Dokumente
1 Users Manual
Table of Contents
1. Overview of QualNet.................................................................................................. 8 1.1. QualNet Features ................................................................................................ 8 1.2. Chapter Outline................................................................................................... 9 1.3. How To Install QualNet.................................................................................... 10 1.4. Windows NT 4.0/2000 Notes ..................................................................... 11 1.5. Solaris Notes ................................................................................................. 11 1.6. Linux Notes....................................................................................................... 11 2. Command-Line Execution and File-Based Specification......................................... 12 2.1. Directory Structure of QualNet......................................................................... 13 2.2. Command-Line Compilation and Execution .................................................... 14 2.3. Scenario Input File Syntax................................................................................ 15 2.3.1. Configuration File Converter.................................................................... 15 2.3.2. Comments ................................................................................................. 17 2.3.3. QualNet Time Format ............................................................................... 17 2.3.4. QualNet Coordinate Format...................................................................... 18 2.3.5. Identifying Nodes and Networks .............................................................. 18 2.3.5.1. Node Identifiers .................................................................................... 19 2.3.5.2. IP Addresses and Subnets ..................................................................... 19 2.3.6. Specifying Nodes and Networks............................................................... 20 2.3.6.1. QualNet Subnet Shorthand ................................................................... 21 2.3.6.2. Subnets.................................................................................................. 22 2.3.6.3. Point-to-Point Links.............................................................................. 22 2.3.7. Network-Specific Parameterization .......................................................... 25 2.3.8. Node-Specific Parameterization ............................................................... 26 2.3.9. Instance ID Parameterization.................................................................... 27 3. Global Simulation Parameters .................................................................................. 28 3.1. Experiment Name ............................................................................................. 28 3.2. Version.............................................................................................................. 28 3.3. Coordinate System ............................................................................................ 29 3.4. Terrain Corners ................................................................................................. 29 3.5. Terrain Dimensions........................................................................................... 30 3.6. Irregular Terrain................................................................................................ 30 3.7. Random Number Seed ...................................................................................... 31 3.8. Maximum Simulation Time.............................................................................. 31 3.9. File-based Node Placement............................................................................... 32 3.10. Protocol Stack ............................................................................................... 33 3.11. Statistics Filtering ......................................................................................... 34 3.12. Mobility Options........................................................................................... 35 3.12.1. Random Drunken ...................................................................................... 36 3.12.2. Random Waypoint .................................................................................... 36 3.12.3. Trace ......................................................................................................... 37 3.13. Mobility Position Granularity ....................................................................... 38 3.14. Application Setup File .................................................................................. 38 4. Application Models................................................................................................... 39 4.1. Traffic Generators............................................................................................. 39
4.1.1. FTP............................................................................................................ 40 4.1.2. FTP/Generic.............................................................................................. 41 4.1.3. HTTP......................................................................................................... 43 4.1.4. Telnet ........................................................................................................ 44 4.1.5. CBR........................................................................................................... 45 4.2. Routing Protocols.............................................................................................. 46 4.2.1. RIPv2 ........................................................................................................ 46 4.2.2. Bellman-Ford ............................................................................................ 47 4.2.3. Fisheye State Routing ............................................................................... 47 4.2.4. BGPv4....................................................................................................... 48 4.2.4.1. BGP Global Parameters ........................................................................ 48 4.2.4.2. BGP Config File Parameters................................................................. 50 4.2.4.3. Example BGP Config File .................................................................... 52 5. Transport Protocols................................................................................................... 53 5.1. TCP ................................................................................................................... 53 5.1.1. TCP Tahoe ................................................................................................ 54 5.1.2. TCP Reno.................................................................................................. 55 5.1.3. TCP Lite.................................................................................................... 55 5.1.4. TCP NewReno .......................................................................................... 56 5.1.5. TCP SACK................................................................................................ 56 5.1.6. TCP Parameters ........................................................................................ 57 5.1.6.1. Delay ACKs Option.............................................................................. 57 5.1.6.2. Nagle Algorithm Option ....................................................................... 57 5.1.6.3. Keep-alive Probes Option ..................................................................... 58 5.1.6.4. TCP Header Push Bit Option................................................................ 58 5.1.6.5. Maximum Segment Size ....................................................................... 58 5.1.6.6. RFC 1323 option................................................................................... 58 5.1.6.7. Send Buffer Size ................................................................................... 59 5.1.6.8. Receive Buffer Size .............................................................................. 59 5.1.7. TCP ECN .................................................................................................. 60 5.2. UDP................................................................................................................... 60 6. Network Protocols .................................................................................................... 61 6.1. IPv4 ................................................................................................................... 61 6.1.1. Static Routes ............................................................................................. 62 6.1.2. Default Routes .......................................................................................... 63 6.2. Network Queue Scheduler ................................................................................ 64 6.2.1. Strict Priority Scheduler............................................................................ 65 6.2.2. Round Robin Scheduler ............................................................................ 66 6.2.3. Weighted Fair Queuing Scheduler............................................................ 66 6.2.4. Self-Clocked Fair Queuing Scheduler ...................................................... 67 6.2.5. Weighted Round Robin Scheduler............................................................ 68 6.3. Network Queue Disciplines .............................................................................. 69 6.3.1. FIFO.......................................................................................................... 69 6.3.2. RED........................................................................................................... 70 6.3.3. RIO............................................................................................................ 72 6.3.4. WRED....................................................................................................... 73
6.4. Routing Protocols.............................................................................................. 76 6.4.1. OSPFv2 ..................................................................................................... 76 6.4.2. AODV ....................................................................................................... 77 6.4.3. DSR........................................................................................................... 77 6.4.4. LAR1......................................................................................................... 78 6.4.5. STAR ........................................................................................................ 78 6.5. Multicast Routing Protocols ............................................................................. 79 6.5.1. Multicast Group Membership Configuration............................................ 79 6.5.2. ODMRP .................................................................................................... 80 6.5.3. DVMRP .................................................................................................... 81 6.5.4. MOSPF ..................................................................................................... 82 6.6. Quality of Service (QoS) Routing Protocols .................................................... 83 6.6.1. QOSPF ...................................................................................................... 83 7. MAC Protocols ......................................................................................................... 85 7.1. IEEE 802.11-1997 DCF.................................................................................... 85 7.2. CSMA ............................................................................................................... 86 7.3. Switched Ethernet ............................................................................................. 87 8. Physical Layer Models.............................................................................................. 88 8.1. Channel Properties ............................................................................................ 88 8.1.1. Propagation Channel Frequency ............................................................... 89 8.1.2. Propagation Model.................................................................................... 89 8.1.3. Propagation Limit ..................................................................................... 90 8.1.4. Path Loss Model Selection........................................................................ 91 8.1.5. Shadowing Model ..................................................................................... 92 8.1.6. Fading Model ............................................................................................ 92 8.2. Physical Layer Properties and Parameters........................................................ 93 8.2.1. Channel Masks.......................................................................................... 93 8.2.2. Temperature .............................................................................................. 94 8.2.3. Noise Factor .............................................................................................. 94 8.2.4. Packet Reception Model ........................................................................... 95 8.2.4.1. Bit Error Rate Tables ............................................................................ 95 8.2.5. Data Rate................................................................................................... 96 8.2.6. Transmission Power.................................................................................. 96 8.2.7. Reception Sensitivity ................................................................................ 96 8.2.8. Reception Threshold ................................................................................. 97 8.2.9. Antenna Model.......................................................................................... 97 8.2.10. Antenna Gain ............................................................................................ 97 8.2.11. Antenna Height ......................................................................................... 97 8.2.12. Energy Consumption Model ..................................................................... 98 9. QualNet API Reference ............................................................................................ 99 9.1. QualNet File Extensions ................................................................................... 99 9.2. Time Functions ............................................................................................... 100 9.2.1. getSimTime(node) .................................................................................. 100 9.2.2. ctoa() ....................................................................................................... 101 9.3. Configuration Related Functions .................................................................... 102 9.3.1. IO_ReadString()...................................................................................... 102
9.3.2. IO_ReadInt() ........................................................................................... 104 9.3.3. IO_ReadDouble().................................................................................... 105 9.3.4. IO_ReadTime() ....................................................................................... 107 9.4. Message Related Functions............................................................................. 109 9.4.1. MESSAGE_Alloc() ................................................................................ 110 9.4.2. MESSAGE_InfoAlloc().......................................................................... 111 9.4.3. MESSAGE_PacketAlloc()...................................................................... 113 9.4.4. MESSAGE_AddHeader()....................................................................... 115 9.4.5. MESSAGE_RemoveHeader() ................................................................ 117 9.4.6. MESSAGE_Copy()................................................................................. 119 9.4.7. MESSAGE_Send() ................................................................................. 121 9.4.8. MESSAGE_Free() .................................................................................. 123 9.4.9. MESSAGE_GetEvent() .......................................................................... 125 9.4.10. MESSAGE_ReturnInfo()........................................................................ 126 9.4.11. MESSAGE_ReturnPacket().................................................................... 128 9.5. Graphical User Interface API Functions......................................................... 130 9.5.1. GUI_Initialize ......................................................................................... 130 9.5.2. GUI_SetEffect......................................................................................... 132 9.5.3. GUI_InitNode ......................................................................................... 133 9.5.4. GUI_MoveNode ..................................................................................... 134 9.5.5. GUI_SetNodeOrientation ....................................................................... 135 9.5.6. GUI_SetNodeIcon................................................................................... 136 9.5.7. GUI_SetNodeLabel................................................................................. 137 9.5.8. GUI_SetNodeRange ............................................................................... 138 9.5.9. GUI_SetNodeType ................................................................................. 139 9.5.10. GUI_SetPatternIndex.............................................................................. 140 9.5.11. GUI_SetPatternAndAngle ...................................................................... 141 9.5.12. GUI_AddLink ......................................................................................... 142 9.5.13. GUI_DeleteLink ..................................................................................... 143 9.5.14. GUI_Broadcast ....................................................................................... 144 9.5.15. GUI_EndBroadcast ................................................................................. 145 9.5.16. GUI_Multicast ........................................................................................ 146 9.5.17. GUI_Unicast ........................................................................................... 147 9.5.18. GUI_Receive........................................................................................... 148 9.5.19. GUI_Drop ............................................................................................... 149 9.5.20. GUI_Collision......................................................................................... 150 9.5.21. GUI_CreateSubnet.................................................................................. 151 9.5.22. GUI_CreateHierarchy ............................................................................. 152 9.5.23. GUI_AddApplication.............................................................................. 153 9.5.24. GUI_DeleteApplication .......................................................................... 154 9.5.25. GUI_AddInterfaceQueue........................................................................ 155 9.5.26. GUI_QueueInsertPacket ......................................................................... 156 9.5.27. GUI_QueueDequeuePacket .................................................................... 157 9.5.28. GUI_QueueDropPacket .......................................................................... 158 9.5.29. GUI_DefineMetric.................................................................................. 159 9.5.30. GUI_SendIntegerData............................................................................. 160
9.5.31. GUI_SendRealData................................................................................. 161 9.5.32. GUI_SendUnsignedData......................................................................... 162 9.6. Statistics Output API Functions...................................................................... 163 9.6.1. IO_PrintStat ............................................................................................ 163 9.7. Error/Assertion Related API Functions .......................................................... 164 9.7.1. ERROR_ReportError.............................................................................. 165 9.7.2. ERROR_Assert ....................................................................................... 165
Table of Figures
Figure 1: Examples of the QualNet Time Format ............................................................ 17 Figure 2: Mobility Options ............................................................................................... 35 Figure 3: Mapping to Detailed Algorithm for RED Gateways......................................... 71 Figure 4: The Life Cycle of a Packet .............................................................................. 109
1. Overview of QualNet
1.1. QualNet Features
QualNet is a state-of-the-art simulator for large, heterogeneous networks and the distributed applications that execute on such networks. heterogeneous networks: Robust set of wired and wireless network protocol and device models, useful for simulating diverse types of networks. Optimized for speed and scalability on one processor, QualNet executes equivalent scenarios 5-10x times faster than commercial alternatives Designed from the ground-up as a parallel simulator, QualNet executes your simulation multiples faster as you add processors. A robust graphical user interface covers all aspects of the simulation, from scenario creation and topology setup, integration of custom protocols, through real-time execution of network models from within the GUI, animation, to postsimulation statistical analysis. See the QualNet Visual Environment Users Manual for more details. QualNet has been used to simulate high-fidelity models of wireless networks with as many as 50,000 mobile nodes. QualNet executes on all commonly used platforms including Windows NT/2000/XP Professional, Solaris, Linux, and most UNIX variants. The following QualNet features provide a unique capability for accurate, efficient simulation of large-scale,
1.2.
Chapter Outline
Chapter One provides an introduction to the QualNet simulation environment, and a description of its key features. Following this section is the installation reference and platform-specific notes.
Chapter Two introduces the directory structure, command-line compilation and execution of experiments, and provides a file format and syntax reference for the specification and execution of a network modeling scenario.
Chapter Three covers global simulation parameters, such as network topology, length of the simulation, and mobility, if applicable.
Chapters Four through Eight cover the protocol model library, including the parameters, features, statistics collected, specifications, and references for the standard protocols and models. o Chapter Four introduces application models, such as FTP, TELNET, and Web browser and server models. This chapter also covers application layer routing protocols, such as RIPv2, which utilize a transport protocol (TCP or UDP) to transmit messages. o Chapter Five covers transport protocol models, such as TCP and UDP. o Chapter Six covers network layer protocols, such as routing protocols, queue and scheduling algorithms, which utilize or perform IP services directly. o Chapter Seven covers the MAC layer protocols, such as CSMA, IEEE 802.11 DCF, and the switched Ethernet and point-to-point link models. o Chapter Eight covers the radio and propagation layer protocols and services.
Chapter Nine provides a technical reference, for the advanced user. It covers the simulators inter-layer APIs and all API functions.
1.3.
QualNet has the following system requirements: Operating System Choices: o Solaris 2.5.1 and up o Windows NT 4.0 / 2000 / XP Professional o RedHat, Mandrake, and compatible Linux 6.0-8.1 The Graphical User Interface, including the QualNet Statistical Analysis Package, requires Java 2, version 1.3 or later, which is available for free from Sun Microsystems1 for all of the listed operating systems. Memory Requirements: 64MB for LAN size simulations, 128MB+ for MAN size networks Disk Requirements: 100 MB Processor Requirements: Pentium-class or UltraSPARC Platform-specific Requirements: see the notes for your Operating System below
QualNet has an automatic installation program called setup.exe (Windows)for the Windows operating system. Please see the Release Notes for Installation on UNIX based systems. Run the setup program from the Installation CD, and follow the prompts to complete installation. You will need to know the desired installation location for the software.
http://java.sun.com/products/
1.4.
QualNet on Windows NT 4.0 and Windows 2000 requires that the Visual C/C++ 6.0 compiler be installed on the system first. Follow the instructions in your Visual C/C++ or Visual Studio manual to ensure proper installation of your compiler. QualNet also requires at least Visual Studio 6.0 Service Pack 52 be installed. Near the end of the installation process, the Visual C++ installer will provide a checkbox for command-line utilities. Make sure to select this option, since it is not included by default.
1.5.
Solaris Notes
QualNet on Solaris requires installation of the GNU C/C++ compilers, version 2.8.1 and above or the Sun Forte / SparcWorks C++ compiler, version 5.0 or 6.0. We recommend using the most recent version of the compiler.3,4
1.6.
Linux Notes
QualNet on Linux requires installation of the GNU C/C++ compilers version 2.95.2 or greater, which are standard on Mandrake Linux distributions and RedHat distributions starting with version 6.2. Please check the GCC Homepage for the most recent version of the compiler, if necessary.3
2 3
default.config doesnt have to be named default.config. It could be named my-scenario-Feb10.config, for example. The same freedom applies to default.app, and so on.
2.1.
The QualNet source tree appears under the directory you chose during QualNet installation. The main subdirectories and a brief description of their contents and purpose are listed below: /application /bin /data /doc /gui /include /mac /main /mobility /network /phy /transport /verification code for the application layer protocols and traffic generators executable and configuration or input/output files supplementary data files for experiments and utility programs the documentation the Visual Environment Toolset common include files the code for the MAC layer protocols the basic framework design the code for the mobility models the code for the network layer protocols and routing protocols the code for the physical layer models the code for the transport layer protocols (TCP/UDP, RSVP, etc) Sample files and outputs to verify protocol correctness
2.2.
If you are running QualNet for the first time, or if you have created or modified protocol models in QualNet, and placed their source code in the relevant directories, you will need to compile QualNet from the main/ subdirectory to include them. Change to the main/ subdirectory using cd, and then: Windows NT/2000: Solaris/Linux: run nmake from the command-line run make from the command-line
To run the simulation you should change directory to the bin/ subdirectory. The executable produced by the previous step is called "qualnet" (Solaris/Linux) or qualnet.exe (Windows). This executables takes one required command line parameter, which is the filename of the relevant Scenario Input File. Scenario Input Files describe the network being modeled, the length of time to simulate this network, and all other scenario specific parameters, and are described in Section 2.3. This executable also takes a second, optional, command line parameter as a single word name for the experiment that this simulation execution represents. This parameter overrides the EXPERIMENT-NAME configuration parameter if it also appears in the Scenario Input File, and serves the same purpose. Type "qualnet default.config" from a command prompt within the bin/ subdirectory to run the program with the sample scenario file. A file called "default.stat" will be produced at the end of the simulation, and contains all the statistics generated by the current experiment. You can use a text editor to make modifications to the default.config file to vary the parameters for running the simulation.
2.3.
This section explains the syntax for specifying network scenarios in the Scenario Input File. It also covers the network-specific (Section 2.3.7) and node-specific (Section 2.3.8) parameterization syntax that allows users to select different options for different device models, in order to specify the heterogeneous elements such as hosts, routers, and radios that make up the network you are modeling.
The converted file orders its variables according to the standard format, and will print all the qualified versions of a variable consecutively. For example, assume the user's file contains the following. LINK N2-1.0 { 1, 2 } [N2-1.0] LINK-BANDWIDTH 1000000 LINK N2-2.0 { 2, 3 } [N2-2.0] LINK-BANDWIDTH 1000000 LINK N2-3.0 { 3, 4 } [N2-3.0] LINK-BANDWIDTH 1000000 The converter will print these as follows: LINK N2-1.0 { 1, 2 } LINK N2-2.0 { 2, 3 } LINK N2-3.0 { 3, 4 } [N2-1.0] LINK-BANDWIDTH 1000000 [N2-2.0] LINK-BANDWIDTH 1000000 [N2-3.0] LINK-BANDWIDTH 1000000 Note that this conversion utility only updates the variables in the main configuration file. It does not update the format of any auxiliary files, such as the application configuration file, or BGP.
2.3.2. Comments
In the input file anything following a "#" is treated as a comment. The sample default.config file contains descriptive information about the parameters that can be selected, using this style of commenting. It also contains all of the available options for each parameter, all of which are commented, except for the parameter currently selected. In order to select a different option than the one already selected, just add a # symbol in front of the current selection, and remove it from the selection you wish to use instead.
100 nanoseconds 100 microseconds 100 milliseconds 100 seconds 100 seconds (default case) 100 minutes 100 hours 100 days
Therefore, the example subnet mask of 255.255.255.0 indicates that 8 bits are used to determine host IP addresses, and these hosts would have IP addresses from 192.168.0.1 through 192.168.0.254, for a maximum of 254 hosts on this subnet. 192.168.0.0 is the network address and 192.168.0.255 is the broadcast address for this subnet.
2.3.6.2. Subnets
The SUBNET keyword is used to describe a network composed of two or more nodes. It also instantiates the network interfaces on those nodes, and instantiates the nodes themselves, if they have not appeared in an earlier SUBNET or LINK declaration. It takes two arguments: the QualNet Subnet Shorthand specification of the network address and subnet mask, and the nodeIds of the two or more nodes that compose the network separated by commas, and surrounded by curly braces {}. An Example illustrating the usage of the SUBNET keyword is given below, with explanations and supporting details to follow: SUBNET N8-1.0 { 1, 2, 3 thru 10 } QualNet auto-assigns IP addresses based on the network address to the nodes in the subnet represented by the SUBNET declaration by assigning network_address.1 through network_address.10 to the ten nodes. Notice the use of the thru keyword, indicating that there are seven additional nodes numbered from 3 through 7, without having to explicitly enumerate them. In this example, node 1 is assigned IP address 0.0.1.1. Node 2 is assigned IP address 0.0.1.2. Node 10 is assigned IP address 0.0.1.10.
Associated with the LINK declaration are the following configuration parameters, which define the properties of the link: LINK-BANDWIDTH LINK-PROPAGATION-DELAY LINK-RETURN-BANDWIDTH LINK-RETURN-PROPAGATION-DELAY 1544000 1MS 1000000 5MS
LINK-BANDWIDTH defines the bandwidth in bits per second, of the link between the first nodeId and the second nodeId between the curly braces. If LINK-RETURN-BANDWIDTH is not specified, then the link is assumed to have identical bandwidth in both directions. If it is specified, then LINKRETURN-BANDWIDTH defines the bandwidth in bits per second, from the second nodeId to the first nodeId, for an asymmetrical link. LINK-PROPAGATION-DELAY specifies the time in QualNet Time Format (See Section 2.3.3) it takes one bit to traverse the link from the first nodeId to the second nodeId between the curly braces. The amount of time it takes to transmit a packet from the idle state to arrival at the receiver is the (packet size / bandwidth) + propagation delay. identical propagation delay in both directions. If LINK-RETURNPROPAGATION-DELAY is not specified, then the link is assumed to have Otherwise, LINK-RETURNPROPAGATION-DELAY specifies the propagation delay in QualNet Time Format (See Section 2.3.3) from the second nodeId to the first nodeId, for an asymmetrical link.
An Example illustrating the usage of the LINK keyword is given below, with explanations and supporting details to follow: LINK N2-1.0 { 1, 2 } LINK N2-2.0 { 2, 3 } LINK-BANDWIDTH 1544000
In the first LINK statement, the two nodes connected have nodeIds 1 and 2. From the second LINK statement, we see that nodeId 2 and nodeId 3 are connected. NodeId 2 is connected to both nodeId 1 and nodeId 3, by separate links, and can switch packets between them. QualNet auto-assigns IP addresses based on the network address to the nodes in the subnet represented by the LINK declaration by assigning network_address.1 and network_address.2 to the two nodes. For the first LINK statement in the example, node 1 is assigned IP address 0.0.1.1. Node 2 is assigned IP address 0.0.1.2. The LINK-BANDWIDTH and LINK-PROPAGATION-DELAY lines LINK-BANDWIDTH LINK-PROPAGATION-DELAY 1544000 1MS
specify the default properties for point-to-point links (in this case they have T1 bandwidth and delay). The lines
[N8-2.0] [N8-2.0]
LINK-BANDWIDTH LINK-PROPAGATION-DELAY
112000 50MS
indicate that the link on the 0.0.2.0 subnet should operate at 112 kbps with a 50 ms propagation delay (ISDN speed), for each direction.7 (See Section 2.3.7 for more information on this syntax)
Thats 112 kbps one way, 112 kbps the other way.
3.1.
Experiment Name
The following parameter specifies the name of the experiment that this configuration file describes. It is used as the prefix (followed by .stat) of the statistical output file produced at the end of the simulation. # EXPERIMENT-NAME myExperiment #
3.2.
Version
The following parameter specifies the version number of this configuration file. Each release of QualNet has an associated version number, and this parameter allows the Configuration File Converter (See Section 2.3.1) to port any changes that you have made to your configuration file to the newest version. Please do not alter the value of this field yourself. # VERSION 3.0 #
3.3.
Coordinate System
The following parameter specifies the coordinate system to use for all coordinates in this scenario. The two options are LATLONALT, which specifies the standard latitude, longitude, and altitude coordinates, and CARTESIAN, which specifies that coordinates are given in positive values that represent the distance in meters from the origin (0, 0, 0) on a flat plain. However, the Z or altitude coordinate can be negative in both the Cartesian and Lat/Lon/Alt coordinate systems, or omitted entirely. If the third coordinate is omitted, it is assumed to be 0. # COORDINATE-SYSTEM CARTESIAN # COORDINATE-SYSTEM LATLONALT #
3.4.
Terrain Corners
The following parameter specifies the coordinates of the southwest and northeast corners of the simulated terrain, when using the LATLONALT coordinate system specified in Section 3.3. All node positions will have coordinate values between the southwest corner and northeast corner coordinates for their latitude and longitude coordinates. The altitude coordinate should be omitted in this parameter. # TERRAIN-SOUTH-WEST-CORNER TERRAIN-NORTH-EAST-CORNER #
3.5.
Terrain Dimensions
The following parameter specifies the size of the physical terrain in which the elements are being simulated, in the CARTESIAN coordinate system specified in Section 3.3. The coordinate unit is meters. The altitude coordinate should be omitted in this parameter.
3.6.
Irregular Terrain8
The following three parameters allow integration with irregular terrain files for propagation and mobility modeling. The TERRAIN-DATA-TYPE parameter specifies the type of terrain data to interface with. The only available setting for this parameter is CTDB. CTDB-FILENAME specifies the relative or absolute path and filename for the CTDB data file for the selected terrain. MOBILITY-GROUND-NODE if turned on (YES) uses the terrain file to determine the altitude coordinates of nodes. # # TERRAIN-DATA-TYPE CTDB # CTDB-FILENAME nebosnia_mes # MOBILITY-GROUND-NODE YES #
Terrain Support is not included in the basic QualNet product. Please contact sales@scalablenetworks.com for more information. Access to these models is also restricted.
3.7.
The following is a random number seed for generating random numbers as needed by the simulation. Specifying the same parameters and seed over two simulations guarantees that the simulators result will be exactly the same no matter how many times you execute the specific scenario. Varying the seed, and averaging the resulting metrics over several runs can reduce the number of outliers in the statistical analysis of network behavior. # SEED 1 #
3.8.
The following parameter represents the maximum simulation time. It is specified in the QualNet Time Format (See Section 2.3.3) described above. When QualNet has simulated your network for this amount of time, the simulation will terminate and record all of the statistics you have collected. See Section 3.11 regarding filtering options so that you do not collect unwanted statistics from layers or protocols you are not interested in. # SIMULATION-TIME 100M #
3.9.
The following parameter represents the method used to automate or specify node placements. For automatic placement of nodes, select RANDOM, UNIFORM, or GRID. To place nodes manually, choose FILE, specify NODE-PLACEMENTFILE with the filename of your text file containing all of the initial coordinates for all of your nodes. # NODE-PLACEMENT RANDOM # RANDOM UNIFORM Nodes are placed randomly within the physical terrain. Based on the number of nodes in the simulation, the physical terrain is divided into a number of cells. Within each cell, a node is placed randomly. This yields a topology that is random, but with a somewhat uniform density of nodes. Node placement starts at (0, 0) and the nodes are placed in grid format with each node GRID-UNIT away from its neighbors. GRIDUNIT must also be specified numerically, with the unit in meters or degrees, depending on the value of COORDINATE-SYSTEM. The number of nodes specified for the simulation also must be square of an integer (i.e. 4, 9, 16, 25, ) Position of nodes is read from the NODE-PLACEMENT-FILE. NODE-PLACEMENT-FILE is specified as a filename, which can have a relative or absolute path. The filename is given without quotes, and cannot contain spaces. On each line of the referenced text file, the node address is given, followed by a space, then the time value 0, and then the (x, y, z) or (lat, lon, alt) coordinates for the position of the node. Optionally, the azimuth and elevation values can follow the coordinates.
GRID
FILE
3.10.
Protocol Stack
The
available protocols at each layer are discussed in Chapter 4. Note that you can combine these selections with the node specific parameterization discussed in Section 2.3.4 to define the set of protocols running at every node in the simulated network. # MAC-PROTOCOL TCP NETWORK-PROTOCOL IP-QUEUE-TYPE IP-QUEUE-SCHEDULER ROUTING-PROTOCOL #
3.11.
Statistics Filtering
The following parameters determine if you are interested in the statistics of each layer in QualNet. By specifying YES for some or all of the following parameters, the simulation will provide you with statistics for the selected layers. All of the statistics are compiled together into a file called "default.stat" that is produced at the end of the simulation. If EXPERIMENT-NAME is defined in the configuration file, the compiled statistics file will be named <experiment_name>.stat instead of default.stat. The statistics filtering options are listed below: # APPLICATION-STATISTICS TCP-STATISTICS UDP-STATISTICS RSVP-STATISTICS ROUTING-STATISTICS IGMP-STATISTICS EXTERIOR-GATEWAY-PROTOCOL-STATISTICS NETWORK-LAYER-STATISTICS QUEUE-STATISTICS MAC-LAYER-STATISTICS PHY-LAYER-STATISTICS MOBILITY-STATISTICS # YES YES YES NO YES NO YES YES YES YES YES NO
3.12.
Mobility Options
The following sections cover mobility related parameters. QualNet provides the Random-Drunken and Random-Waypoint models of mobility as part of the standard package, and also provides Trace-based mobility for users who wish to interface with existing mobility logs or third-party mobility generators. Pathloss-Matrix mobility is a special case, in which the radio nodes look up a precalculated path loss from a timeindexed table when they wish to transmit data. MOBILITY PATHLOSS-MATRIX requires PATHLOSS PATHLOSS-MATRIX to be selected as well. # MOBILITY # NONE RANDOMDRUNKEN RANDOMWAYPOINT
NONE
TRACE
PATHLOSSMATRIX
The nodes remain fixed in place for the duration of the simulation A node has equal likelihood of remaining at its current position, or moving 1 meter in any direction that lies within the simulated terrain boundaries A node randomly selects a destination from the physical terrain. It moves in the direction of the destination in a speed uniformly chosen between MOBILITY-WP-MIN-SPEED and MOBILITY-WPMAX-SPEED (both specified in meter/sec). After it reaches its destination, the node stays there for MOBILITY-WP-PAUSE (specified in QualNet Time Format) time period. The mobility patterns are contained in a time-ordered trace file specified by MOBILITY-TRACE-FILE. Each line of the trace file has the following format: <nodeId> <time> (<destination x coord>, <dest y>, <dest z>) where time is in QualNet Time Format, and speed is in meters/second. Used in conjunction with the PATHLOSS-MATRIX Propagation function. With propagation determined by the matrix, QualNet does not need to track node positions to calculate path loss analytically.
3.12.1.
Random Drunken
Random Drunken mobility simply selects randomly at each interval among five possibilities: movement in any of the four directions (assuming they lie within the simulated terrain), or remaining at its current position. To select Random Drunken mobility as the mobility model, place the following entry in default.config: MOBILITY MOBILITY-INTERVAL RANDOM-DRUNKEN 30S
In addition to this specification, this protocol requires that MOBILITYINTERVAL be specified in QualNet Time Format (See Section 2.3.3). This parameter specifies the interval between mobility selections. Smaller values specify that node positions be updated more frequently.
3.12.2.
Random Waypoint
Random Waypoint mobility selects random destinations and speeds for each node. After the nodes reach their selected destinations, they pause for a given amount of time, specified by MOBILITY-WP-PAUSE and then repeat the process. To select Random Waypoint mobility as the mobility model, place the following entry in default.config: MOBILITY MOBILITY-WP-PAUSE MOBILITY-WP-MIN-SPEED MOBILITY-WP-MAX-SPEED MOBILITY-POSITION-GRANULARITY RANDOM-WAYPOINT 30S 1 10 0.5
In addition to this specification, this protocol requires that MOBILITYPOSITION-GRANULARITY be defined in meters. This unit determines the resolution at which node positions are updated. Smaller figures mean that node positions are updated more often at smaller increments. Speed entries are specified in meters/second, with the model choosing uniformly between these, and pause time is given in QualNet Time Format (See Section 2.3.3).
3.12.3.
Trace
Trace-based mobility allows node mobility to be read from a user-readable text file format. This format allows for easy import from external models of node movements and patterns. To select trace-based mobility as the mobility model, place the following entry in default.config: MOBILITY MOBILITY-TRACE-FILE MOBILITY-POSITION-GRANULARITY TRACE default.mobility 0.5
In addition to this specification, this protocol requires that MOBILITYPOSITION-GRANULARITY be defined in meters. This unit determines the resolution at which node positions are updated. Smaller figures mean that node positions are updated more often at smaller increments. MOBILITY-TRACE-FILE refer to a text file (in the prior example, called default.mobility) that contains the following entries, each on its own line: <nodeId> <time> (<destination x coord>, <dest y>, <dest z>) where the destination coordinates are in the coordinate system specified by COORDINATE-SYSTEM (See Section 3.3) and time is specified in QualNet Time Format (See Section 2.3.3).
3.13.
The MOBILITY-POSITION-GRANULARITY (in meters) is used for QualNet to calculate the frequency of updating the position of each network node. The smaller the value selected, the greater the number of position update events, and the greater the accuracy of the simulated node position throughout the simulation. However, selecting extremely small values can slow down the simulation without providing sufficient benefit in improved accuracy of results. # #MOBILITY-POSITION-GRANULARITY #
0.5
3.14.
In order to set up applications (traffic generators) on nodes in a text-based QualNet simulation execution, specify the filename for the application configuration file with the APP-CONFIG-FILE parameter in the configuration file as follows: # APP-CONFIG-FILE default.app #
4. Application Models
The QualNet Standard Protocol Model Library is organized on a number of layers, based on the TCP/IP stack. At the top of the QualNet hierarchy is the application layer, which includes traffic generating applications, and routing protocols that use the transport layer services to send and receive messages. This chapter covers these protocol models, their configuration, statistical output, and includes references to the literature, where applicable.
4.1.
Traffic Generators
Traffic generators produce the data that you would expect to flow across your network. These traffic generators fall into two categories: models of the representative applications you are using, and theoretical or trace-based models of traffic.
The first category includes the web-browsing, file transfer, and Telnet connections that make up the vast majority of Internet traffic. The latter category includes models that use randomized generation, from exponential random distributions to self-similar behavior to model background, multimedia, or Internet-based traffic without the ability to sample or measure it. This category also includes trace-based traffic generation, which can be used to model the traffic characteristics of a network over which you have administrative authority. A user can also combine trace-based models with any of the other models to experiment with the effects of increasing traffic loads on a realistic model of your network.
4.1.1. FTP
FTP represents the File Transfer Protocol server and client. The size of the items sent is taken from network traces, distributions given from the tcplib9 library. If the <items_to_send> parameter is specified as 0, then tcplib9 also determines the number of items to send. In order to specify FTP traffic in the default.app application configuration file, make entries according to the following format: FTP <src> <dest> <items_to_send> <start_time> <src> <dest> refers to the the client server nodes nodes nodeId nodeId (See (See Section Section 2.3.5.1) 2.3.5.1)
or IP Address. You can use these interchangeably in this file. indicates or IP Address. <items_to_send> specifies the number of items to send. <start_time> indicates when the transmissions should begin, in simulation time (QualNet Time Format Section 2.3.3). The following example specifies that the node with nodeId 1 (node 1) will send 10 items to node 2, and begin these transmissions 50 simulation seconds into the total simulation time: FTP 1 2 10 50S The following example specifies that node 1 will send a random number of items to node 2, and begin these requests 100 simulation seconds into the total simulation time: FTP 0 1 0 100S
The FTP model collects the following statistics: Time when session is started Time when session is closed Number of bytes sent Number of bytes received Throughput.
4.1.2. FTP/Generic
FTP/Generic represents a more configurable model of the File Transfer Protocol server and client. The size of the items sent is not determined by network traces, but instead are specified by the user. format: FTP/GENERIC <src> <dest> <items_to_send> <item_size> <start_time> <end_time> <src> <dest> refers to the the client server nodes nodes nodeId nodeId (See (See Section Section 2.3.5.1) 2.3.5.1) In order to specify FTP/Generic traffic in the default.app application configuration file, make entries according to the following
or IP Address. You can use these interchangeably in this file. indicates or IP Address. <items_to_send> specifies the number of items to send. <item_size> specifies the size of each item in bytes <start_time> indicates when the transmissions should begin, in simulation time (QualNet Time Format Section 2.3.3). <end_time> indicates when the transmissions should end (QualNet Time Format Section 2.3.3).
If <items_to_send> is set to 0, FTP/Generic will run until the specified <end_time> or until the end of the simulation, whichever comes first. If <end_time> is set to 0, FTP/Generic will run until all <items_to_send> have been sent, or until the end of the simulation, whichever comes first. If both <items_to_send> and <end_time> are greater than 0, FTP/Generic will run until either <items_to_send> items have been sent, <end_time> is reached, or the simulation ends, whichever comes first. The following example specifies that the node with the nodeId 1 (node 1) will send 10 1460byte items to node 2, and begin these transmissions at the start of the simulation (note that the start time is specified in QualNet Time Format): FTP/GENERIC 1 2 10 1460 0S 600S If the 10 items are sent before the 600 simulation seconds elapse, no other items will be sent. The FTP/Generic model collects the following statistics: Time when session is started Time when session is closed Number of bytes sent Number of bytes received Throughput.
4.1.3. HTTP
HTTP represents a single-thread web-browser and a set of web-servers that the browser will connect to. generator. This model is ported from the INSANE10 HTTP traffic The model considers think time between client requests, and varying
numbers of pages, items per page, and size of items, in the server responses. The client also considers varying lengths of sessions during which it makes requests of the same server for a given number of pages. This behavior is based on collected traffic traces11. In order to specify web-traffic in the default.app application configuration file, make entries according to the following format: HTTPD <nodeId> HTTP <nodeId> <n = num_of_servers> <server_1> <server_n> <nodeId> can refer either to the desired nodes nodeId (See Section 2.3.5.1) or IP Address. You can use these interchangeably in this file. <server {1..n}> indicates the server nodes nodeId(s) (See Section 2.3.5.1) or IP Address. An example follows, in which there are web servers placed on the nodes with nodeIds 1, 2, and 3 (nodes 1, 2, and 3). Node 4 has a web client that can choose among these three servers when deciding to request web pages. HTTPD 1 HTTPD 2 HTTPD 3 HTTP 4 3 1 2 3
10
INSANE: An Internet Simulated ATM Networking Environment. http://www.employees.org/~bmah/Software/Insane/ 11 B. Mah. An Empirical Model of HTTP Network Traffic'', Proceedings of INFOCOM 97, Kobe, Japan, April 1997. http://www.employees.org/~bmah/Papers/Http-Infocom.pdf
4.1.4. Telnet
Telnet represents the cleartext terminal server and client. The typing rate and sizes of server responses are taken from distributions created from network traces, given rom the tcplib9 library. In order to specify Telnet traffic in the default.app application configuration file, make entries according to the following format: TELNET <src> <dest> <session_duration> <start_time> <src> <dest> refers to the the client server nodes nodes nodeId nodeId (See (See Section Section 2.3.5.1) 2.3.5.1)
or IP Address. You can use these interchangeably in this file. indicates or IP Address. <session_duration> indicates the length of the entire session, in simulation time (QualNet Time Format Section 2.3.3). <start_time> indicates when the transmissions should begin, in simulation time (QualNet Time Format Section 2.3.3). The following example specifies that the node with nodeId 1 (node 1) will initiate a 5-minute telnet session to node 2, and begin the session 50 simulation seconds into the total simulation time: TELNET 1 2 5M 50S The TELNET model collects the following statistics: Time when session is started Time when session is closed Number of bytes sent Number of bytes received Throughput.
4.1.5. CBR
CBR represents constant-bit-rate traffic. It is generally used to either fill in background traffic to affect the performance of other applications being analyzed, or to simulate the performance of generic multimedia traffic. In order to specify CBR traffic in the default.app application configuration file, make entries according to the following format: CBR <src> <dest> <items_to_send> <item_size> <interval> <start time> <end time> <src> <dest> refers to the the client server nodes nodes nodeId nodeId (See (See Section Section 2.3.5.1) 2.3.5.1)
or IP Address. You can use these interchangeably in this file. indicates or IP Address. <items_to_send> specifies the number of items to send. <item_size> specifies the size of each item. <interval> indicates the pause time between transmission of each item, in simulation time. <start_time> indicates when the transmissions should begin, in simulation time (QualNet Time Format Section 2.3.3). <end_time> indicates when the transmissions should cease, in simulation time (QualNet Time Format Section 2.3.3).
The following example specifies that the node with nodeId 1 (node 1) will send 500 2-kilobyte items to node 2, sending one per minute, starting from 50 simulation seconds into the total simulation time, and ending 500 minutes later: CBR 1 2 500 2048 1M 50S 501M
The CBR model collects the following statistics: Time when session is started Time when session is closed Number of bytes sent Number of bytes received Throughput.
4.2.
Routing Protocols
4.2.1. RIPv212
This is the Internet standard implementation of the Bellman-Ford (a.k.a. Ford Fulkerson) routing algorithm. It is a distance vector routing algorithm utilizing UDP for control packet transmission, and its specification in default.config follows: ROUTING-PROTOCOL RIPv2 It takes no parameters.
12
http://www.ietf.org/rfc/rfc2453.txt
4.2.2. Bellman-Ford
This is a generic Bellman-Ford (a.k.a. Ford Fulkerson) routing algorithm. This algorithm is the underlying mechanism of RIP, but this protocol is not RIPv2 compliant. It is a distance vector routing algorithm utilizing UDP for control packet transmission, and its specification in default.config follows: ROUTING-PROTOCOL BELLMANFORD It takes no parameters. Bellman-Ford takes the following statistics: numRTBroadcast numTriggerUpdate numRTUpdate numFromUdp Total number of routing table broadcasts Total number of triggered routing table updates Total number of routing table updates Total number of routing table packets received
13
A. Iwata, C.-C. Chiang, G. Pei, M. Gerla, and T.-W. Chen, Scalable Routing Strategies for Ad-hoc Wireless Networks in IEEE Journal on Selected Areas in Communications, Special Issue on Ad-Hoc Networks, August 1999. http://www.cs.ucla.edu/NRL/wireless/PAPER/jsac99.ps.gz
4.2.4. BGPv414
BGPv4 (Border Gateway Protocol version 4) is a routing protocol used to route packets between autonomous systems. If you are modeling an existing network which spans autonomous systems or a very large one that you wish to partition based on administrative control, activating and configuring BGPv4 can give you a more accurate picture of expected network operation. To select BGPv4 as the exterior gateway routing protocol in default.config, place the following entry in default.config: EXTERIOR-GATEWAY-PROTOCOL BGPv4 It takes many parameters.
http://www.ietf.org/rfc/rfc1771.txt
BGP-MIN-RT-ADVERTISEMENT-INTERVAL 30S The interval between two subsequent update messages for internal peers is specified using the following parameter in QualNet Time Format (See Section 2.3.3). If omitted, this parameter will default to a value of 15 seconds. BGP-MIN-AS-ORIGINATION-INTERVAL 15S The interval between two successive keep alive message is specified using the following parameter in QualNet Time Format (See Section 2.3.3). If omitted, this parameter will default to a value of 30 seconds. BGP-KEEPALIVE-INTERVAL 30S The amount of time to wait before re-opening a TCP connection is specified using the following parameter in QualNet Time Format (See Section 2.3.3). If omitted, this parameter will default to a value of 120 seconds. BGP-CONNECT-RETRY-INTERVAL 120S The amount of time to wait to determine if a neighbor is no longer reachable is specified using the following parameter in QualNet Time Format (See Section 2.3.3). If omitted, this parameter will default to a value of 15 seconds. BGP-ROUTE-WAITING-INTERVAL 15S The remaining parameters for BGPv4 involve the configuration of individual BGP routers. specified below. BGP-CONFIG-FILE ./default.bgp These parameters are read from the BGP-CONFIG-FILE
NEIGHBOR <neighbor_ip_addr> REMOTE-AS <remote_as_id> The NEIGHBOR parameter can also specify the BGP Weight of a neighboring BGP speaker as follows: NEIGHBOR <neighbor_ip_address> WEIGHT <weight_value> By default, BGP synchronizes routes with the Interior Gateway Protocol (IGP). This is the Routing Protocol running inside the Autonomous System that the BGP Router belongs to. By adding the following statement, the user can disable this route synchronization: NO SYNCHRONIZATION The following statement indicates the local preference for internal paths as an unsigned integer. DEFAULT LOCAL-PREFERENCE <unsigned_integer> The following statement specifies the multi-exit discriminator (MED). DEFAULT-METRIC <unsigned integer> The following statement disables IGP route injection into BGP. By default, the IGP does inject routes into BGP. NO-ADVERTISEMENT-FROM-IGP
The following statement sets the probe time interval if IGP route injection into BGP is active: BGP-PROBE-IGP-INTERVAL <time>
The following specifies that node 4 is a BGP speaker in AS 1. Node 4 is advertising N8-2.0 to neighbor BGP speaker 1.2, which is located in AS 2. ROUTER 4 BGP 1 NETWORK N8-2.0 NEIGHBOR 1.2 REMOTE-AS 2 Here, it specifies that node 5 is a BGP speaker in AS 2. Node 5 is advertising N8-3.0 to neighbor BGP speaker 1.1, which is located in AS 1. ROUTER 5 BGP 2 NETWORK N8-3.0 NEIGHBOR 1.1 REMOTE-AS 1
5. Transport Protocols
5.1. TCP
QualNets TCP is converted from the FreeBSD 2.2.215 source code implementation for TCP. The differences between the QualNet code and the FreeBSD code are improvements for simulation performance, configurability via QualNet configuration files and GUI, interface code to the simulator, and modifications to offer additional flavors of TCP. FreeBSDs TCP variant is known as TCP Lite. Applications that require TCP include FTP and Telnet. TCP statistics collected are part of the port from FreeBSD 2.2.2 tcps_sndtotal tcps_sndpack tcps_sndbyte tcps_sndrexmitpack tcps_sndrexmitbyte tcps_sndacks tcps_sndprobe tcps_sndurg tcps_sndwinup tcps_sndctrl tcps_rcvtotal tcps_rcvpack tcps_rcvbyte tcps_rcvbadsum tcps_rcvbadoff tcps_rcvshort tcps_rcvctrl tcps_rcvduppack tcps_rcvdupbyte tcps_rcvpartduppack tcps_rcvpartdupbyte
15
Total number of packets sent Total number of data packets sent, excluding retransmissions and probes Total number of data bytes sent, excluding retransmissions and probes Total number of retransmitted packets Total number of retransmitted bytes Total number of ACK only packets sent Total number of window probes sent Total number of packets sent with URG Total number of window update packet sent Total number of control (SYN|FIN|RST) packets sent Total number of packets received Total number of data packets received, excluding retransmissions and probes Total number of data bytes received, excluding retransmissions and probes Total number of packets dropped due to checksum errors Total number of packets dropped due to bad offset Total number of packets dropped due to being too short Total number of control packets received Total number of duplicate packets received Total number of bytes received in duplicate packets Total number of packets received with partial duplication Total number of bytes received in packets with partial
http://www.freebsd.org/
tcps_rcvoopack tcps_rcvoobyte tcps_rcvpackafterwin tcps_rcvbyteafterwin tcps_rcvafterclose tcps_rcvwinprobe tcps_rcvdupack tcps_rcvackpack tcps_rcvackbyte tcps_rcvacktoomuch tcps_rcvwinupd tcps_pawsdrop tcps_predack tcps_preddat tcps_persistdrop tcps_badsyn
duplication Total number of out-of-order packets received Total number of bytes received in out-of-order packets Total number of packets received after the window Total number of bytes received after the window Total number of packets dropped due to already closed TCP session Total number of window probe packets received Total number of duplicate ACK packets received Total number of in-sequence ACK packets received Total number of bytes acknowledged by ACK packets received Total number of erroneous ACKs received for unsent data Total number of window update packets received Total number of segments dropped due to PAWS Total number of times the header predicts ok for ACKs Total number of times the header predicts ok for data packets Total number of timeouts in persist state Total number of bogus SYN packets, e.g. premature ACKs
The QualNet TCP models include many variants, which are described in the following sections:
To select TCP Tahoe, place the following entry in the default.config: TCP TAHOE You can also modify the TCP parameters (Section 5.1.6).
To select TCP Reno, place the following entry in the default.config: TCP RENO You can also modify the TCP parameters (Section 5.1.6).
16
http://www.ietf.org/rfc/rfc1323.txt
To select TCP Lite, either ensure that no other TCP specification exists, or place the following entry in the default.config: TCP LITE You can also modify the TCP parameters (Section 5.1.6).
To select TCP Reno, place the following entry in the default.config: TCP NEWRENO You can also modify the TCP parameters (Section 5.1.6).
To select TCP SACK, place the following entry in the default.config: TCP SACK You can also modify the TCP parameters (Section 5.1.6).
5.2.
UDP
The User Datagram Protocol (UDP) is a simple, low-overhead, packet-switched transport protocol that assumes that the Internet Protocol (IP) is the underlying network protocol. Applications that require UDP include CBR or routing protocols such as RIP, UDP. UDP collects the following statistics: numPktFromApp numPktToApp Total Number of packets received from applications Total Number of packets sent to application layer
17
http://www.ietf.org/rfc/rfc2481.txt
6. Network Protocols
6.1. IPv4
packet-
The Internet Protocol is designed for use in interconnected systems of switched computer communication networks.
transmitting blocks of data called datagrams from sources to destinations, where sources and destinations are hosts identified by fixed length addresses. The Internet Protocol also provides for fragmentation and reassembly of long datagrams, if necessary, for transmission through "small packet" networks. Selection of this protocol is currently mandatory, and is achieved by placing the following entry in the default.config: NETWORK-PROTOCOL It takes no parameters. IP statistics collected are taken from the standard MIB statistics, and listed below: ipInReceives ipInHdrErrors ipInForwardDatagrams ipInDelivers ipOutRequests ipOutDiscards ipOutNoRoutes ipReasmReqds ipReasmOKs ipReasmFails IpFragOKs Packets received from the MAC protocol Packets dropped due to header errors Packets forwarded by this intermediate node towards its destination Packets sent to the applicable transport layer protocol (TCP, UDP) Packets sent by IP to the MAC protocol Packets lost to IP queue overflow Packets dropped due to unreachable destination Fragments of packets received Successful reassembly of fragments into a data packet Unsuccessful reassembly of fragments into a data packet Successful receptions of fragments IP
The static routing model requires that STATIC-ROUTE-FILE refer to a text file (in the prior example, called "default.routes-static") that contains the following entries, each on its own line: <source nodeId> <destination IP/Subnet Address> <nextHop IP Address> In the following example, the route for node 1 to the networks 0.0.2.0 and 0.0.3.0 use node 1s outgoing interface identified by the IP Address 0.0.1.2. (See QualNet Subnet Shorthand in Section 2.3.6.1 for more information on how N2-2.0 translates to the 0.0.2.0 network) 1 1 N2-2.0 N2-3.0 1.2 1.2
The default routing model requires that DEFAULT-ROUTE-FILE refer to a text file (in the prior example, called "default.routes-default") that contains the following entries, each on its own line: <source nodeId> <destination IP/Subnet Address> <nextHop IP Address> In the following example, the default route for node 1 to the networks 0.0.2.0 and 0.0.3.0 use node 1s outgoing interface identified by the IP Address 0.0.1.2. translates to the 0.0.2.0 network) 1 1 N2-2.0 N2-3.0 1.2 1.2 (See QualNet Subnet Shorthand in Section 2.3.6.1 for more information on how N2-2.0
6.2.
For each network interface in QualNet, IP maintains a set of priority queues. These queues can represent the greater priority that real-time or control (routing-protocol, ACKs, etc) packets can have over the normal IP best-effort datagrams. They can also represent the various flows that Quality of Service scheduling disciplines distinguish between, using a round robin or other scheduling discipline. The Network Queue Scheduler is the scheduling discipline, implemented as a set of functions that IP uses to enqueue and dequeue packets from its various priority queues for a given network interface. The number of these priority queues is determined by the parameter IP-QUEUE-NUM-PRIORITIES. Given that generic QualNet traffic generators and protocols generate three different priorities of traffic (CONTROL, REAL_TIME, NON_REAL_TIME), the default value of 3 is useful here. Defining less than three would cause different traffic priorities to share the same queue. Quality of Service applications can either add or remove priority queues during simulation execution as well. Specification of a value for this parameter is currently mandatory, and is achieved by placing the following entry in the default.config: IP-QUEUE-NUM-PRIORITIES 3 It can be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7).
In addition to the IP-QUEUE-NUM-PRIORITIES parameter, you must also specify the size of these priority queues. This is accomplished by setting the value of the IP-QUEUE-PRIORITY-QUEUE-SIZE parameter. This value is specified in bytes. Once the buffer space is filled with data packets whose aggregate size exceeds this value, the priority queue must drop subsequent packets. default.config: IP-QUEUE-PRIORITY-QUEUE-SIZE 50000 # bytes Specification of a value for this parameter is currently mandatory, and is achieved by placing the following entry in the
It can be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7).
It takes no parameters. It can be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7).
It takes no parameters. It can be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7).
It can be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7). It requires no parameters. If no parameters are given, the weight of each queue is the ((priority value of the queue)+ 1) / (sum of all the priority_values for all the queues). Otherwise, users must specify the weight for all of the queues on that interface, such that the sum of the weights equals one, using the following parameter: QUEUE-WEIGHT[priority] # weight_between_zero_and_one
Where priority is the integer value of the priority assigned to each queue (numbered from 0num_of_priority_queues-1), and the weight is a floating point number between zero and one. This parameter can also be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7).
It can be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7). It requires no parameters. If no parameters are given, the weight of each queue is the ((priority value of the queue)+ 1) / (sum of all the priority_values for all the queues). Otherwise, users must specify the weight for all of the queues on that interface, such that the sum of the weights equals one, using the following parameter: QUEUE-WEIGHT[priority] # weight_between_zero_and_one
Where priority is the integer value of the priority assigned to each queue (numbered from 0num_of_priority_queues-1), and the weight is a floating point number between zero and one. This parameter can also be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7).
It can be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7). It requires no parameters. If no parameters are given, the weight of each queue is the ((priority value of the queue)+ 1) / (sum of all the priority_values for all the queues). Otherwise, users must specify the weight for all of the queues on that interface, such that the sum of the weights equals one, using the following parameter: QUEUE-WEIGHT[priority] # weight_between_zero_and_one
Where priority is the integer value of the priority assigned to each queue (numbered from 0num_of_priority_queues-1), and the weight is a floating point number between zero and one. This parameter can also be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7).
6.3.
Network Queue Disciplines can be distinguished from Queue Scheduling Disciplines by the fact that they deal exclusively with the enqueue and dequeue functions of a single priority queue, rather than the choice between all of the existing priority queues. These parameters can be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7). In addition, it can be specified using Instance ID Specification (See Section 2.3.9), if you wish to have different values for certain parameters, for each priority queue.
6.3.1. FIFO
FIFO queues operate on a First In, First Out basis. The FIFO queue accepts packets until it is full (the packets occupying the queue total an aggregate number of bytes that prevent the next packet from being admitted). The size of the queue is specified by the IP-QUEUE-PRIORITY-QUEUE-SIZE parameter. (See Section 6.2) At that point, all packets that arrive at the queue are dropped, until packets are dequeued, and space becomes available. To select FIFO as the Network Queue Discipline, place the following entry in default.config: IP-QUEUE-TYPE It takes no parameters. The FIFO queue model collects the following statistics, per priority queue, per node: NumPktsQueued NumPktsDequeued NumPktsDropped AvgQueueLen AvgTimeInQueue PeakTimeInQueue Number of Packets Queued Number of Packets Dequeued Number of Packets Dropped Average Queue Length in Bytes Average Time Spent By Packets in the Queue (in seconds) Longest Time Spent in Queue by a Packet (in seconds) FIFO
6.3.2. RED18
RED is an acronym for Random Early Detection18. This implementation drops packets at the current router based on drop probabilities, rather than at a subsequent congested router, if ECN (See Section 5.1.7) is off (default). If ECN is active, packets are marked instead of dropped, and the source of the TCP traffic will throttle back based on the notification. RED is a congestion avoidance algorithm that calculates average queue sizes in order to address incipient congestion. The algorithm also attempts to address global synchronization as well as maintaining fairness across data flows, without bias against bursty flows. To select RED as the Network Queue Discipline, place the following entry in default.config: IP-QUEUE-TYPE RED
It takes five parameters, which can be defined using network-specific or nodespecific parameterization. The following example illustrates a RED configuration where the maximum dropping probability is 1/50 (0.02 as specified by RED-MAXPROBABILITY). The possibility of random early drops begins when the RED queue average algorithm determines that the queue size (number of packets in the queue, not the bytes used by those packets) average is greater than or equal to RED-MINTHRESHOLD and less than RED-MAX-THRESHOLD. The RED-QUEUEWEIGHT determines the bias towards recent or historical queue lengths in calculating the average queue size. The RED-SMALL-PACKET-TRANSMISSION-TIME is the time it would take to transmit a typical small packet, and this value is used to estimate the queue average during idle periods (when the queue is completely empty). RED-MIN-THRESHOLD RED-MAX-THRESHOLD RED-MAX-PROBABILITY RED-QUEUE-WEIGHT RED-SMALL-PACKET-TRANSMISSION-TIME
18
Sally Floyd and Van Jacobson, "Random Early Detection For Congestion Avoidance", IEEE/ACM Transactions on Networking, August 1993. http://www.aciri.org/floyd/papers/red/red.html
Figure 3 below is a mapping between these parameters and the variable and parameter names given for the Detailed algorithm for RED gateways18. QualNet Configuration File Parameter RED-MIN-THRESHOLD RED-MAX-THRESHOLD RED-MAX-PROBABILITY RED-QUEUE-WEIGHT RED-SMALL-PACKET-TRANSMISSION-TIME Detailed algorithm for RED
RED queues collect the following statistics, per priority queue, per node: NumPktsQueued NumPktsDequeued NumPktsDropped AvgQueueLen AvgTimeInQueue PeakTimeInQueue PeakQueueSize Number of Packets Queued Number of Packets Dequeued Number of Packets Dropped Average Queue Length in Bytes Average Time Spent By Packets in the Queue (in seconds) Longest Time Spent in Queue by a Packet (in seconds) Largest number of bytes stored in the queue at any time (the upward bound on this stat would be the queue size itself)
6.3.3. RIO19
RIO is a queue discipline that implements two instances of the RED algorithm with different parameter settings. The first instance uses a set of parameters to specify the marking/dropping behavior of packets which are marked as being in-profile. Inprofile packets conform to existing agreements between networks for level of service, i.e. fall within certain bandwidth, burstiness, and delay characteristics. Out-profile packets exceed the existing agreements for level of service between networks, and the dropping/marking behavior for these ill-behaved packets is specified by the set of parameters for the second instance of the RED algorithm. This latter set of parameters tends to specify more aggressive marking/dropping probabilities and thresholds. To select RIO as the Network Queue Discipline, place the following entry in default.config: IP-QUEUE-TYPE RIO
It takes eight parameters, which can be defined using network-specific or nodespecific parameterization. The following example illustrates a RIO configuration where the maximum dropping probability for in-profile packets is 1/50 (0.02 as specified by RIO-IN-MAX-PROBABILITY). The possibility of random early drops for in-profile packets begins when the RED queue average algorithm determines that the queue size (number of packets in the queue, not the bytes used by those packets) average is greater than or equal to RIO-IN-MIN-THRESHOLD and less than RIO-IN-MAXTHRESHOLD. The thresholds and probabilities for the out-profile packets are RIOOUT-MAX-PROBABILITY, RIO-OUT-MIN-THRESHOLD, and RIO-OUTMAX-THRESHOLD. The last two parameters are shared with RED (Section 6.3.2). The RED-QUEUE-WEIGHT determines the bias towards recent or historical queue lengths in calculating the average queue size. The RED-SMALL-PACKETTRANSMISSION-TIME is the time it would take to transmit a typical small packet,
19
David D. Clark and Wenjia Fang, Explicit Allocation of Best Effort Packet Delivery Service, ACM Transactions on Networking, August, 1998. http://diffserv.lcs.mit.edu/Papers/exp-alloc-ddc-wf.pdf
and this value is used to estimate the queue average during idle periods (when the queue is completely empty). RIO-IN-MIN-THRESHOLD RIO-IN-MAX-THRESHOLD RIO-IN-MAX-PROBABILITY RIO-OUT-MIN-THRESHOLD RIO-OUT-MAX-THRESHOLD RIO-OUT-MAX-PROBABILITY 10 20 0.02 5 10 0.1
RED-QUEUE-WEIGHT 0.002 RED-SMALL-PACKET-TRANSMISSION-TIME 10MS RIO queues collect the following statistics, per priority queue, per node: NumPktsQueued NumPktsDequeued NumPktsDropped AvgQueueLen AvgTimeInQueue PeakTimeInQueue PeakQueueSize Number of Packets Queued Number of Packets Dequeued Number of Packets Dropped Average Queue Length in Bytes Average Time Spent By Packets in the Queue (in seconds) Longest Time Spent in Queue by a Packet (in seconds) Largest number of bytes stored in the queue at any time (the upward bound on this stat would be the queue size itself)
6.3.4.
WRED20
WRED is a queue discipline that implements three instances of the RED algorithm with different parameter settings. The first instance uses a set of parameters to specify the marking/dropping behavior of packets which are marked as being within / below the committed target rate. The committed target rate is an agreement between networks for level of service. These packets are considered to be green, and the dropping/marking behavior is governed by the green instance of RED parameters. Yellow packets fall between the committed target rate, and a higher peak rate, and the
20
http://www.ieng.com/univercd/cc/td/doc/product/software/ios112/ios112p/gsr/wred_gs.htm
dropping/marking behavior is governed by the yellow instance of RED parameters. Red packets exceed the peak rate, and the dropping/marking behavior for these illbehaved packets is specified by the set of parameters for the red instance of RED parameters. The yellow and red sets of parameters tend to specify increasingly aggressive marking/dropping probabilities and thresholds. To select WRED as the Network Queue Discipline, place the following entry in default.config: IP-QUEUE-TYPE WRED
It takes eleven parameters, which can be defined using network-specific or nodespecific parameterization. The following example illustrates a WRED configuration where the maximum dropping probability for green packets is 1/50 (0.02 as specified by WRED-GREEN-MAX-PROBABILITY). The possibility of random early drops for green packets begins when the RED queue average algorithm determines that the queue size (number of packets in the queue, not the bytes used by those packets) average is greater than or equal to WRED-GREN-MIN-THRESHOLD and less than WRED-GREEN-MAX-THRESHOLD. yellow packets are The thresholds and probabilities for the WREDWRED-YELLOW-MAX-PROBABILITY,
YELLOW-MIN-THRESHOLD, and WRED-YELLOW-MAX-THRESHOLD. The thresholds and probabilities for the red packets are WRED-RED-MAXPROBABILITY, WRED-RED-MIN-THRESHOLD, and WRED-RED-MAXTHRESHOLD. The last two parameters are shared with RED (Section 6.3.2). The RED-QUEUE-WEIGHT determines the bias towards recent or historical queue lengths in calculating the average queue size. The RED-SMALL-PACKETTRANSMISSION-TIME" is the time it would take to transmit a typical small packet, and this value is used to estimate the queue average during idle periods (when the queue is completely empty).
RED-QUEUE-WEIGHT 0.002 RED-SMALL-PACKET-TRANSMISSION-TIME 10MS WRED queues collect the following statistics, per priority queue, per node: NumPktsQueued NumPktsDequeued NumPktsDropped AvgQueueLen AvgTimeInQueue PeakTimeInQueue PeakQueueSize Number of Packets Queued Number of Packets Dequeued Number of Packets Dropped Average Queue Length in Bytes Average Time Spent By Packets in the Queue (in seconds) Longest Time Spent in Queue by a Packet (in seconds) Largest number of bytes stored in the queue at any time (the upward bound on this stat would be the queue size itself)
6.4.
Routing Protocols
6.4.1. OSPFv221
OSPF is a link-state routing protocol. It is designed for intra-Autonomous System Routing, and requires that each OSPF router maintain a database describing the Autonomous System's topology. From this database, a routing table is calculated by constructing a shortest-path tree. To select OSPF as the routing protocol in default.config, place the following entry in default.config: ROUTING-PROTOCOL It takes no parameters. OSPFv2 collects the following statistics: numHelloPktSent numHelloPktRecvd numLSDOrig numLSDRecvd numLSROrig numLSRRecvd numLSUOrig numLSURecvd numLSAOrig numLSARecvd Total number of Hello packets sent Total number of Hello packets received Total number of Link State Description packets originated Total number of Link State Description packets received Total number of Link State Request packets originated Total number of Link State Request packets received Total number of Link State Update packets originated Total number of Link State Update packets received Total number of Link State ACK packets originated Total number of Link State ACK packets received OSPFv2
21
http://www.ietf.org/rfc/rfc2328.txt
6.4.2. AODV22
The Ad-Hoc On Demand Distance Vector (AODV) routing algorithm is a routing protocol designed for ad-hoc mobile networks. AODV is an on-demand algorithm To select capable of both unicast and multicast routing. This implementation of AODV followed the specification of AODV Internet Draft draft-ietf-manet-aodv-03.txt. default.config: ROUTING-PROTOCOL AODV It takes no parameters. AODV as the routing protocol in default.config, place the following entry in
6.4.3. DSR23
Dynamic Source Routing (DSR) is an on-demand routing protocol that builds routes only by flooding ROUTE REQUEST packets if a sender wishes to send data to a destination with no known route, accumulating node IDs in its header, and returning ROUTE REPLY packets from the destination to the source via the recorded reverse route. In addition to the on-demand algorithm, DSR implements a set of optimizations to attempt to route packets more efficiently, and reduce the control overhead. To select DSR as the routing protocol in default.config, place the following entry in default.config: ROUTING-PROTOCOL DSR It takes no parameters.
22 23
http://alpha.ece.ucsb.edu/~eroyer/aodv.html draft-ietf-manet-dsr-03.txt, Josh Broch, David B. Johnson, and David A. Maltz, October 22, 1999. http://www.monarch.cs.cmu.edu/internet-drafts/draft-ietf-manet-dsr-03.txt
6.4.4. LAR124
Location-Aided Routing (LAR) is an on-demand routing protocol which exploits location information. It is similar to DSR, but with the additional requirement of GPS information. In scheme 1 (implemented), the source defines a circular area in which the destination may be located, determined by the following information: (a) the destination location known to the source; (b) the time instant when the destination was located at that position; and (c) the average moving speed of the destination. The smallest rectangular area that includes this circle and the source is the request zone. This information is attached to a ROUTE REQUEST by the source and only nodes inside the request zone propagate the packet. If no ROUTE REPLY is received within the timeout period, the source retransmits a ROUTE REQUEST via pure flooding. To select LAR1 as the routing protocol in default.config, place the following entry in default.config: ROUTING-PROTOCOL LAR1 It takes no parameters.
6.4.5. STAR25
Source Tree Adaptive Routing (STAR) is a partial link state, table driven protocol, in which the routers exchange only the changes in their own shortest path trees with their neighbors. STAR operates in either the Least Overhead Routing Approach (LORA) and Optimum Routing Approach (ORA) modes. In LORA mode, STAR attempts to provide viable, if not necessarily optimal (according to performance, delay matrics) paths to each destination, while in ORA mode, STAR attempts to provide optimal paths based on the chosen metric. To select FSR as the routing protocol in default.config, place the following entry in default.config:
24
Youngbae Ko and N. H. Vaidya, Location-Aided Routing (LAR) Mobile Ad Hoc Networks, MOBICOM'98, October 1998, Dallas. http://www.cs.tamu.edu/faculty/vaidya/papers/mobilecomputing/mobicom98.pdf 25 J.J. Garcia-Luna-Aceves and M. Spohn, "Source-Tree Routing in Wireless Networks", Proc. IEEE ICNP 99: 7th International Conference on Network Protocols, Toronto, Canada, October 31--November 3, 1999. http://www.cse.ucsc.edu/research/ccrg/publications/spohn.icnp99.pdf
PROTOCOL-SEND-FREQUENCY, and NEIGHBOR-PROTOCOL-ENTRY-TTL. The latter two parameters concern the rate at which the neighbor protocol broadcasts hello packets to all neighbors within range, and how long the entries for neighbors remain valid after hearing a hello message. We recommend that the TTL be longer than the SEND-FREQUENCY to be sure that the neighbor protocol does not provide erroneous neighbor up and neighbor down messages to STAR. STAR-ROUTING-MODE LORA # STAR-ROUTING-MODE ORA NEIGHBOR-PROTOCOL-SEND-FREQUENCY 2S NEIGHBOR-PROTOCOL-ENTRY-TTL 4S
6.5.
Multicast routing protocols address the problem of delivering messages from senders to a set of interested receivers, without individually sending duplicate messages from the sender to each receiver. This set of interested receivers subscribes to one or more multicast groups of interest, and the senders address their messages to the multicast group address. The multicast routing protocol handles the delivery of these messages to the multicast group members.
In order to specify which Multicast Group Membership File to use in a given experiment, place the following entry in default.config: MULTICAST-GROUP-FILE ./default.member
This parameter specifies the filename in either relative or absolute path. The Multicast Group Membership File takes the following format: <nodeId> <group IP address to join> <join time> <leave time>
6.5.2. ODMRP26
The On-Demand Multicast Routing Protocol (ODMRP) is a wireless multicast routing protocol. It is designed for single subnet, wireless ad-hoc multicast routing, and operates similarly to an on-demand unicast wireless routing protocol. ODMRP is a mesh-based, rather than a conventional tree-based, multicast scheme and uses a forwarding group concept (only a subset of nodes forwards the multicast packets via scoped flooding). It applies on-demand procedures to dynamically build routes and uses soft state to maintain multicast group membership. To select ODMRP as the multicast routing protocol in default.config, place the following two entries in default.config: MULTICAST-PROTOCOL MULTICAST-GROUP-FILE It takes no parameters. ODMRP ./default.member
MULTICAST-GROUP-FILE parameter.
26
http://www.cs.ucla.edu/NRL/wireless/PAPER/draft-ietf-manet-odmrp-02.txt
ODMRP collects the following statistics: numQueryTxed numReplySent numAckSent numDataTxed numDataSent numDataReceived Number of Join Query (with piggybacked data) packets sent Number of Join Reply packets sent Number of ACK packets sent Total Number of ODMRP data packets sent or relayed Number of data packets sent as the source of the data Number of data packets received as the destination of the data
6.5.3. DVMRP27
The Distance Vector Multicast Routing Protocol (DVMRP) is a multicast routing protocol. It is designed for traditional wired network multicast routing, and operates similarly to a distance vector routing protocol like RIPv2. DVMRP is a tree-based, multicast scheme that utilizes Reverse Path Multicasting (RPM)28. To select DVMRP as the multicast routing protocol in default.config, place the following three entries in default.config: MULTICAST-PROTOCOL DVMRP MULTICAST-GROUP-FILE ./default.member GROUP-MANAGEMENT-PROTOCOL IGMP It takes no parameters. See Section 6.5.1 for more information about the GROUP-MANAGEMENT-PROTOCOL
IGMP activates IGMP (Internet Group Management Protocol), which is necessary for
27 28
http://www.ietf.org/internet-drafts/draft-ietf-idmr-dvmrp-v3-10.txt Deering, S., Cheriton, D., "Multicast Routing in Datagram Internetworks and Extended LANs", ACM Transactions on Computer Systems, Vol. 8, No. 2, May 1990, pp. 85-110.
DVMRP collects the following statistics: totalPacketSent totalPacketReceive probePacketSent probePacketReceive routingUpdateSent routingUpdateReceive numTriggerUpdate pruneSent pruneReceive graftSent graftReceive graftAckSent graftAckReceive numOfDataPacketOriginated numOfDataPacketForward numOfDataPacketDiscard Number of packets sent Number of packets received Number of Probe packets sent Number of Probe packets received Routing Updates sent Routing Updates received Triggered Updates sent Prunes sent Prunes received Grafts sent Grafts received Graft ACKs sent Graft ACKs received Multicast packets sent as data source Multicast data packets forwarded Multicast data packets discarded
6.5.4. MOSPF29
The Multicast Extensions to OSPF (MOSPF) create a multicast routing protocol by extending OSPFv2. These extensions are designed for traditional wired network multicast routing, and operate on top of the link state routing algorithm of OSPFv2. MOSPF is a pruned tree-based, multicast scheme that takes advantage of commonality of paths from source to destinations. To select MOSPF as the multicast routing protocol in default.config, place the following two entries in default.config: MULTICAST-PROTOCOL MULTICAST-GROUP-FILE It takes no parameters. MOSPF ./default.member
MULTICAST-GROUP-FILE parameter.
29
http://www.ietf.org/rfc/rfc1584.txt
MOSPF collects the following statistics: numGroupMembershipLSAGenerated numGroupJoin numGroupLeave numOfMulticastPacketGenerated numOfMulticastPacketReceived numOfMulticastPacketDiscard numOfMulticastPacketForwarded Group Membership LSAs sent Group Joins Group Leaves Multicast packets sent as data source Multicast Packets received Multicast data packets discarded Multicast Packets forwarded
6.6.
Quality of Service (QoS) routing protocols address the path selection process problem of providing bandwidth and delay guarantees to QoS flows. QoS routing protocols handle the unreserved resource advertisements, path calculation, and possibly resource reservation issues of providing QoS services.
6.6.1. QOSPF30
The Quality Of Service Path First Routing (QOSPF) protocol is a set of extensions to OSPFv2 that address QoS flow support. This includes the acquisition of information needed to compute QoS paths, the selection of appropriate paths to meet the QoS requirements of a flow, and the maintenance of these paths. To select QOSPF as the QoS routing protocol in default.config, place the following two entries in default.config:
QUALITY-OF-SERVICE Q-OSPF QOSPF-COMPUTATION-ALGORITHM EXTENDED_BREADTH_FIRST_SEARCH_SINGLE_PATH
30
http://www.ietf.org/rfc/rfc2676.txt
The QOSPF-FLOODING-INTERVAL parameter specifies the interval for flooding of Q-OSPF Link State Advertisements (LSAs). The default is two seconds. The QUEUEING-DELAY-FOR-QOS-PATH-CALCULATION parameter specifies whether or not to include queue delays in the path calculation and LSAs. QOSPF collects the following statistics: numActiveConnection numRejectedConnection linkBandwidth bandwidthUtilization Number of Active Connections Number of Rejected Connections Link Bandwidth Utilization of Bandwidth
7. MAC Protocols
7.1. IEEE 802.11-1997 DCF
IEEE 802.11-1997 is a wireless LAN media access protocol. The Distributed Coordination Function (DCF), implemented in QualNet, is a carrier-sensing protocol with acknowledgements, and provides optional channel reservation capability using Requestto-Send (RTS) / Clear-to-Send Packets, (CTS) and fragmentation. To select IEEE 802.11 DCF as the MAC protocol in default.config, place the following entry in default.config: MAC-PROTOCOL MAC802.11 It takes no parameters. The IEEE 802.11-1997 DCF model produces the following statistics: Packets received from Network Layer Protocol, i.e. IPv4 Packets Lost to Buffer Overflow Packets dropped at the MAC layer due to buffer overflow Unicast packets to channel Packets with a specific destination address transmitted on the channel Broadcast packets to channel Packets broadcast to all radios within transmission range Unicast packets from channel Packets destined for this specific radio and successfully received Broadcast packets from channel Packets destined for all radios and successfully received by this radio Retransmitted Packets due to CTS Packets rescheduled for transmission timeout due to lack of CTS response to RTS transmission Retransmitted Packets due to ACK Packets rescheduled due to lack of ACK timeout response to packet transmission Retransmitted Fragments due to Fragments of packets retransmitted due Frag ACK timeout to lack of acknowledgement of the fragment Packets drops due to excessive Packets not rescheduled after exceeding retransmission attempts the maximum number of attempts Packet drops due to excessive Packets not rescheduled after exceeding retransmission attempts of fragments the maximum number of unsuccessfully delivered fragments Packets From Network
7.2.
CSMA
Carrier Sense Multiple Access (CSMA) is a generic carrier-sensing protocol. When a radio wishes to send data, it senses the channel. If the channel is busy, it backs off for a random time period before sensing the channel again. If the channel is free, the radio transmits the packet. To select CSMA as the MAC protocol in default.config, place the following entry in default.config: MAC-PROTOCOL CSMA It takes no parameters. The CSMA model produces the following statistics: Packets From Network Packets Lost to Buffer Overflow Unicast packets to channel Broadcast packets to channel Unicast packets from channel Broadcast packets from channel Packets received from Network Layer Protocol, ie IP Packets dropped at the MAC layer due to buffer overflow Packets with a specific destination address transmitted on the channel Packets broadcast to all radios within transmission range Packets destined for this specific radio and successfully received Packets destined for all radios and successfully received by this radio
7.3.
Switched Ethernet
Switched Ethernet is an abstract store and forward single switch-based 802.3 LAN with fixed bandwidth and propagation delay. The model considers the switching fabric to be equivalent to a set of point-to-point links connecting all sources and receivers, except that when multiple sources attempt to send to a single receiver, their transmissions are serialized without additional buffering overhead. To select Switched Ethernet as the MAC protocol in default.config, place the following entry in default.config: MAC-PROTOCOL SWITCHED-ETHERNET It takes two parameters: SUBNET-DATA-RATE 10000000 SUBNET-PROPAGATION-DELAY 1MS These two parameters specify the data rate and propagation delay for the model, respectively. The Switched Ethernet model produces the following statistics: Frames Sent Frames Received Packets sent to the switch Packets received from the switch
8.1.
Channel Properties
Each channel in QualNet is uniquely identified by its frequency. Each channel is assumed to be orthogonal to the others (no inter-channel interference). Users can instantiate channels by initializing a propagation model for each, starting with the mandatory PROPAGATION-CHANNEL-FREQUENCY parameter (See Section 8.1.1). Users can simulate spectrum overlapping by using multiple channels.
STATISTICAL
-111.0 -121.0
The Friss free space model. Path loss is calculated with (path loss exponent, sigma) = (2.0, 0.0) Two ray model. It uses the free space path loss (2.0, 0.0) for near sight, and plane earth path loss (4.0, 0.0) for far sight. This model considers ground reflection on flat earth. Three-dimensional matrix indexed by source node, destination node, and time. The value assigned to each triplet is the path loss value between the given source, destination pair at the given simulation time. The Terrain Integrated Rough Earth Model. This model considers terrain effects, transmitter and receiver attributes such as antenna height and frequency, and atmospheric and ground constants. This model is distributed by the Joint Spectrum Center of the Department of Defense (http://www.jsc.mil/), and is interfaced with QualNet.
(*) Access restricted. Please consult with QualNet Support regarding availability and distribution requirements for these models.
8.2.
Radio models simulate the hardware that performs channel sensing, radio transmissions, receptions, and battery usage, and have parameters specified below. These models and parameters are not specified on a per-channel basis, using Instance ID Specification (See Section 2.3.9). They can be specified using node-specific (Section 2.3.8) and network-specific (Section 2.3.7) parameterization. The radio model available in the standard version of QualNet is: PHY802.11b A WaveLAN II / IEEE 802.11 compatible radio device model PHY802.11b
# PHY-MODEL #
8.2.2. Temperature
The following parameter defines the temperature of the physical radio model in degrees K. This parameter is used in the calculation of thermal noise, along with the Boltzmann Constant and PHY-NOISE-FACTOR. # PHY-TEMPERATURE #
290
10.0
If the Signal to Noise ratio (SNR) is more than PHY-RXSNR-THRESHOLD (specified in dB), it receives the signal without error. Otherwise, the packet is dropped. The calculated Signal to Noise ratio is used to look up an associated Bit Error Rate (BER) from a table located in filename BER-TABLE-FILE.
2000000
15.0
-91.0
-81.0
8.2.10.
Antenna Gain
The following parameter represents the antenna gain in dB. # ANTENNA-GAIN # 0.0
8.2.11.
Antenna Height
The following parameter represents the antenna height in meters. # ANTENNA-HEIGHT # 1.5
8.2.12.
A simple energy consumption model is included in phy_802_11b.c. It is intended for use with the IEEE 802.11 MAC DCF without power management, so it assumes that the physical device in idle mode (not receiving any signal) consumes the same power as it does in receive mode. This pattern of energy consumption is consistent with the constantly sensing IEEE 802.11 MAC DCF operation. specifications. The default energy consumption values in phy_802_11.h were derived from WaveLAN
9.1.
9.2.
Time Functions
This Section covers some useful functions for manipulating simulation time variables.
9.2.1.
getSimTime(node)
Routine getSimTime
Return Value This function returns the current simulation time in the clocktype data format. Parameters None Remarks The getSimTime function returns a clocktype, which is a 64-bit integral data type. QualNet sets the resolution of this clock to indicate the number of nanoseconds that have passed since the start of the simulation. Note that the preferred method for outputting clocktypes to the screen is to use ctoa (See Section 9.2.2) to convert a clocktype to its string representation. Example /* GETSIMTIME.PC: This program uses the getSimTime function * to return the current simulation time. */ #include <stdio.h> void show_the_current_time(Node *node) { clocktype curTime; char buf[80]; curTime = getSimTime(node); ctoa(curTime, buf); } printf(The current time is %s.\n, buf);
9.2.2.
void ctoa(
ctoa()
clocktype cVal, char *buffer);
Routine ctoa
Return Value None
Parameters cVal The clocktype integral variable to convert to its string representation buffer A pointer to a character array of sufficient size to store the string representation of the clocktype. Be sure to allocate space for this array before passing in a pointer. Remarks The ctoa function behaves similarly to sprintf, printing the value of the clocktype parameter into the string parameter. Example /* GETSIMTIME.PC: This program uses the getSimTime function * to return the current simulation time. */ #include <stdio.h> void show_the_current_time(Node *node) { clocktype curTime; char buf[80]; curTime = getSimTime(node); ctoa(curTime, buf); } printf(The current time is %s.\n, buf);
9.3.
At the simulations initialization phase, QualNet reads the text-based Configuration File that was specified as a command-line parameter. Users who execute QualNet via the GUI have their text-based Configuration File generated automatically by the GUI, and fed to the simulator transparently when they hit the Action! button (See the Animator Manual.). This Configuration File contains the information about the protocols that run at each layer of the protocol stack, and at each node in the simulation. It also contains protocol specific parameters that the protocol designers wish to allow end users to modify. This section covers the QualNet Functions that allow you, as a protocol designer, to interface with the text-based Configuration File.
9.3.1. IO_ReadString()
void IO_ReadString( const NodeAddress nodeId, const NodeAddress interfaceAddress, const NodeInput *nodeInput, const char *index, BOOL &retVal, char *readVal);
Routine IO_ReadString
Return Value None
Parameters nodeId Either the unique Node Identifier of the Node calling this function, or ANY_NODE, which specifies that the default value of this parameter should be returned, rather than one which is specific to this node. interfaceAddress Either the IP address of the interface for which the function is being called (you can specify different parameter values in the configuration file for different interfaces on the same node) or ANY_INTERFACE, which specifies the default value of this parameter for the given node, rather than one which is specific to one of this nodes interfaces. nodeInput The pointer to the data structure which contains the configuration file. This pointer is passed to all initialization functions. index A character array containing the name of the parameter whose value should be retrieved by this function. retVal The pointer to a Boolean variable. This function will place TRUE or FALSE at this memory location to indicate whether or not the parameter specified by index was found, and the value placed in readVal. readVal A pointer to the character array where this parameters value should be written. Remarks It is safest to allocate character arrays of size MAX_STRING_LENGTH to pass in as the readVal parameter, in order to ensure that no memory violations occur. Example /* READSTRING.PC: This program uses the IO_ReadString function * to return the value of a parameter in the simulation configuration file. */ #include <stdio.h> #include fileio.h void lookup_a_string_parameter(Node *node, const NodeInput *nodeInput) { char buf[MAX_STRING_LENGTH]; bool retVal; IO_ReadString(ANY_NODE, ANY_IP, nodeInput, TCP-STATISTICS, &retVal, buf); if (retVal) { printf(The parameter \TCP-STATISTICS\ has the value \%s\\n, buf); } else printf(Could not find the parameter \TCP-STATISTICS\ in the configuration file.\n); } Output The parameter TCP-STATISTICS has the value NO
9.3.2. IO_ReadInt()
void IO_ReadInt( const NodeAddress nodeId, const NodeAddress interfaceAddress, const NodeInput *nodeInput, const char *index, BOOL &retVal, int *readVal);
Routine IO_ReadInt
Return Value None
Parameters nodeId Either the unique Node Identifier of the Node calling this function, or ANY_NODE, which specifies that the default value of this parameter should be returned, rather than one which is specific to this node. interfaceAddress Either the IP address of the interface for which the function is being called (you can specify different parameter values in the configuration file for different interfaces on the same node) or ANY_INTERFACE, which specifies the default value of this parameter for the given node, rather than one which is specific to one of this nodes interfaces. nodeInput The pointer to the data structure which contains the configuration file. This pointer is passed to all initialization functions. index A character array containing the name of the parameter whose value should be retrieved by this function. retVal The pointer to a Boolean variable. This function will place TRUE or FALSE at this memory location to indicate whether or not the parameter specified by index was found, and the value placed in readVal. readVal A pointer to the integer memory location where this parameters value should be written.
Example /* READINT.PC: This program uses the IO_ReadInt function * to return the value of a parameter in the simulation configuration file. */ #include <stdio.h> #include fileio.h void lookup_an_int_parameter(Node *node, const NodeInput *nodeInput) { int count; bool retVal; IO_ReadInt(ANY_NODE, ANY_IP, nodeInput, IP-QUEUE-NUM-PRIORITIES, &retVal, &count); if (retVal) { printf(The parameter \ IP-QUEUE-NUM-PRIORITIES\ has the value \%d\\n, count); } else printf(Could not find the parameter \IP-QUEUE-NUM-PRIORITIES\ in the configuration file.\n);
9.3.3. IO_ReadDouble()
void IO_ReadDouble( const NodeAddress nodeId, const NodeAddress interfaceAddress, const NodeInput *nodeInput, const char *index, BOOL &retVal, double *readVal);
Routine IO_ReadDouble
Return Value None
Parameters nodeId Either the unique Node Identifier of the Node calling this function, or ANY_NODE, which specifies that the default value of this parameter should be returned, rather than one which is specific to this node. interfaceAddress Either the IP address of the interface for which the function is being called (you can specify different parameter values in the configuration file for different interfaces on the same node) or ANY_INTERFACE, which specifies the default value of this parameter for the given node, rather than one which is specific to one of this nodes interfaces. nodeInput The pointer to the data structure which contains the configuration file. This pointer is passed to all initialization functions. index A character array containing the name of the parameter whose value should be retrieved by this function. retVal The pointer to a Boolean variable. This function will place TRUE or FALSE at this memory location to indicate whether or not the parameter specified by index was found, and the value placed in readVal. readVal A pointer to the double floating point memory location where this parameters value should be written. Example /* READDOUBLE.PC: This program uses the IO_ReadDouble function * to return the value of a parameter in the simulation configuration file. */ #include <stdio.h> #include fileio.h void lookup_a_double_parameter(Node *node, const NodeInput *nodeInput) { double temp; bool retVal; IO_ReadDouble(ANY_NODE, ANY_IP, nodeInput, TEMPERATURE, &retVal, &temp); if (retVal) { printf(The parameter \ TEMPERATURE\ has the value \%lf\\n, temp); } else printf(Could not find the parameter \TEMPERATURE\ in the configuration file.\n);
9.3.4. IO_ReadTime()
void IO_ReadTime( const NodeAddress nodeId, const NodeAddress interfaceAddress, const NodeInput *nodeInput, const char *index, BOOL &retVal, double *readVal);
Routine IO_ReadTime
Return Value None
Parameters nodeId Either the unique Node Identifier of the Node calling this function, or ANY_NODE, which specifies that the default value of this parameter should be returned, rather than one which is specific to this node. interfaceAddress Either the IP address of the interface for which the function is being called (you can specify different parameter values in the configuration file for different interfaces on the same node) or ANY_INTERFACE, which specifies the default value of this parameter for the given node, rather than one which is specific to one of this nodes interfaces. nodeInput The pointer to the data structure which contains the configuration file. This pointer is passed to all initialization functions. index A character array containing the name of the parameter whose value should be retrieved by this function. retVal The pointer to a Boolean variable. This function will place TRUE or FALSE at this memory location to indicate whether or not the parameter specified by index was found, and the value placed in readVal. readVal A pointer to the clocktype memory location where this parameters value should be written. Remarks This function converts between the Qualnet Time Format (See Section 2.3.3) and the clocktype data type that represents the internal simulation clock. The Qualnet Time Format is used by end users in the configuration text files, while the clocktype data type is used internally for timer scheduling and modeling processing and propagation delays.
Example /* READTIME.PC: This program uses the IO_ReadTime function * to return the value of a parameter in the simulation configuration file. */ #include <stdio.h> #include fileio.h void lookup_a_time_parameter(Node *node, const NodeInput *nodeInput) { clocktype simTime; char clockStr[MAX_STRING_LENGTH]; bool retVal; IO_ReadTime(ANY_NODE, ANY_IP, nodeInput, SIMULATION-TIME, &retVal, &simTime); if (retVal) { ctoa(simTime, clockStr); printf(The parameter \SIMULATION-TIME\ has the value \%s\\n, clockStr); } else printf(Could not find the parameter \SIMULATION-TIME\ in the configuration file.\n);
9.4.
Messages are the events that are passed between nodes, and between layers in a single node as events. A Message is composed of a Packet Field, which is the combination of the data payload and all headers, Event Information that the QualNet kernel uses to call the appropriate function to process the Message, and additional user-specified space (Info Field) where optional information about the event can be stored. Two examples of Messages are Packets and Timers. Figure 4 illustrates the function calls that manipulate a Packet, from its creation, through the various layers in a node, through the transmission medium, up the protocol stack of the receiving node, to its final destination and destruction.
GLOMO_MsgFree()
Transport
GLOMO_MsgAddHeader() GLOMO_MsgSend()
Routing IP
GLOMO_MsgRemoveHeader() GLOMO_MsgSend()
IP
GLOMO_MsgAddHeader() GLOMO_MsgSend()
MAC
GLOMO_MsgRemoveHeader() GLOMO_MsgSend()
MAC
GLOMO_MsgAddHeader() GLOMO_MsgSend()
Physical
GLOMO_MsgRemoveHeader() GLOMO_MsgSend()
Physical
9.4.1. MESSAGE_Alloc()
Message* MESSAGE_Alloc( Node *node, LAYER_TYPE layertype, int protocol, EVENT_TYPE eventType);
Routine MESSAGE_Alloc
Return Value This function returns the pointer to the newly created Message structure, and halts simulation execution on failure. Parameters node Pointer to the Node structure containing the calling nodes data space layertype This parameter specifies the destination layer for this Message. LAYER_TYPE is an enumeration listed in main.h (in the include/ subdirectory of the QualNet Directory Structure) of all of the QualNet layers. Examples of these include APP_LAYER, TRANSPORT_LAYER, and so on. protocol This field determines the destination protocol running at the above-referenced layertype for this Message. Examples of these are APP_FTP_SERVER, and TRANSPORT_PROTOCOL_UDP. eventType This field determines the event that this Message represents to the above-referenced protocol and layer. Remarks The MESSAGE_Alloc function creates a pointer to a new Message, and initializes its event, layer, and protocol information. This Message is reusable, as a single Message can traverse the Life Cycle illustrated in Figure 4.
Example /* MSG_ALLOC.PC: This program uses the MESSAGE_Alloc function * to create a new Message for the Application Layer FTP Server. The event * type represented by this Message is a Timer Expiration. */ #include <stdio.h> #include main.h #include message.h Message* create_a_message(Node *node) { Message* newMsg = MESSAGE_Alloc( node, APP_LAYER, APP_FTP_SERVER, MSG_APP_TimerExpired); printf(Created a new Message.\n); return newMsg; } Output Created a new Message.
9.4.2. MESSAGE_InfoAlloc()
void MESSAGE_InfoAlloc( Node *node, Message *msg, int infoSize);
Routine MESSAGE_InfoAlloc
Return Value None. This function halts simulation execution on failure to allocate sufficient memory. The simulation cannot continue when out of memory. Parameters node Pointer to the Node structure containing the calling nodes data space msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. infoSize This field determines the size in bytes of the data space to be allocated. This info field is used for user-specified event information.
Remarks The MESSAGE_InfoAlloc function either allocates or resizes additional userspecified event information space. On the first call to this function, the space is created, while all subsequent calls replace the prior space with a new space of the desired size. Since this space is allocated for event information, it can be adjusted throughout the life cycle of the Message, and one cannot assume that it contains the same information at the destination as it does at the sender. Also, storage of information in this space does not affect the size of the data packet, and does not increase the transmission delay over wire or wireless media. See MESSAGE_ReturnInfo (Section 9.4.9) for information about accessing the Info Field. Example /* MSG_INFO_ALLOC.PC: This program uses the MESSAGE_InfoAlloc function * to create a new info field for a Message created for the Application Layer FTP Server. * The event type represented by this Message is a Timer Expiration. */ #include <stdio.h> #include main.h #include message.h typedef struct timer_information_str { clocktype generation_time; /* The creation time for this Timer */ int timerType; /* A subtype for the Timer */ NodeAddress neighbor; /* The neighbor IP address that this Timer is concerned with */ } MyTimerInfo; Message *create_a_message_with_info(Node *node) { MyTimerInfo *timerInfoPtr; Message* newMsg = MESSAGE_Alloc( node, APP_LAYER, APP_FTP_SERVER, MSG_APP_TimerExpired); printf(Created a new Message.\n); MESSAGE_InfoAlloc( node, newMsg, sizeof(MyTimerInfo)); timerInfoPtr = (MyTimerInfo *)MESSAGE_ReturnInfo(newMsg); timerInfoPtr->generation_time = getSimTime(node); } return newMsg;
9.4.3. MESSAGE_PacketAlloc()
void MESSAGE_PacketAlloc( Node *node, Message *msg, int packetSize);
Routine MESSAGE_PacketAlloc
Return Value None. This function halts simulation execution on failure to allocate sufficient memory. The simulation cannot continue when out of memory. Parameters node Pointer to the Node structure containing the calling nodes data space msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. packetSize This field determines the initial size in bytes of the packet to be allocated. This field is used to store the data and all headers that will be transmitted from one node to other node(s). Remarks The MESSAGE_PacketAlloc function allocates the Packet to an initial size given by the packetSize parameter. Unlike MESSAGE_InfoAlloc (Section 9.4.2) this function should be called only once. If you wish to adjust the size of the packet, use MESSAGE_AddHeader (Section 9.4.4) and MESSAGE_RemoveHeader (Section 9.4.5). Storage of information in this space directly affects the size of the data packet, and its transmission delay over wire or wireless media. See MESSAGE_ReturnPacket (Section 9.4.11) for information about accessing the Packet Field.
Example /* MSG_PACKET_ALLOC.PC: This program uses the MESSAGE_PacketAlloc function * to create a new packet field for a Message created for the Application Layer Constant Bit Rate * generator. The event type represented by this Message is a Packet sent to UDP for * transmission. */ #include <stdio.h> #include main.h #include message.h typedef struct my_cbr_packet_fields { clocktype generation_time; /* The creation time for this Packet */ char buf[512]; /* Padding to make the cbr packet total * 512 bytes + sizeof(clocktype) */ } MyCbrPacket; Message *create_a_cbr_message (Node *node) { Message* msg; MyCbrPacket *packet; msg = MESSAGE_Alloc ( node, TRANSPORT_LAYER, TRANSPORT_PROTOCOL_UDP, MSG_TRANSPORT_FromAppSend); MESSAGE_PacketAlloc (node, msg, sizeof(MyCbrPacket)); /* Allocate the packet */ packet = (MyCbrPacket *) MESSAGE_ReturnPacket (msg); packet->generation_time = getSimTime(node); printf(Created a new Message.\n); return msg; } Output Created a new Message.
9.4.4. MESSAGE_AddHeader()
void MESSAGE_AddHeader( Node *node, Message *msg, int hdrSize);
Routine MESSAGE_AddHeader
Return Value None. This function halts simulation execution on failure to allocate sufficient memory. The simulation cannot continue when out of memory. Parameters node Pointer to the Node structure containing the calling nodes data space msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. hdrSize This field determines the additional size in bytes to add to the front of the data space already allocated for this Packet. Referencing the Packet Field returns a pointer to this space, with the original, smaller Packet Field appended after it. Remarks The MESSAGE_AddHeader function adds additional data space to the front of an already allocated Packet. Packets are allocated first by MESSAGE_PacketAlloc (Section 9.4.3) and MESSAGE_AddHeader and MESSAGE_RemoveHeader (Section 9.4.5) modify the size of the data space. Storage of information in this space directly affects the size of the data packet, and the transmission delay over wire or wireless media. See MESSAGE_ReturnPacket (Section 9.4.11) for information about accessing the Info Field.
Example /* MSG_ADD_HEADER.PC: This program uses the MESSAGE_AddHeader function * to add a header to a Packet. */ typedef struct my_cbr_packet_fields { clocktype generation_time; /* The creation time for this Packet */ char buf[512]; /* Padding to make the cbr packet total * 512 bytes + sizeof(clocktype) */ } MyCbrPacket; typedef struct my_cbr_header_fields { NodeAddress src_addr; /* The source address of this packet */ } MyCbrHeader; Message *create_a_cbr_message (Node *node) { Message* msg; MyCbrPacket *packet; MyCbrHeader *header; msg = MESSAGE_Alloc ( node, TRANSPORT_LAYER, TRANSPORT_PROTOCOL_UDP, MSG_TRANSPORT_FromAppSend); MESSAGE_PacketAlloc ( node, msg, sizeof(MyCbrPacket)); /* Allocate the packet */ packet = (MyCbrPacket *) MESSAGE_ReturnPacket (msg); packet->generation_time = getSimTime(node); MESSAGE_AddHeader( node, msg, sizeof(MyCbrHeader)); /* Adds a header */ header = (MyCbrHeader *) MESSAGE_ReturnPacket(msg); header->src_addr = node->nodeAddr; printf(Created a new Message.\n); return msg; } Output Created a new Message.
9.4.5. MESSAGE_RemoveHeader()
void MESSAGE_RemoveHeader( Node *node, Message *msg, int hdrSize);
Routine MESSAGE_RemoveHeader
Return Value None.
Parameters node Pointer to the Node structure containing the calling nodes data space msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. hdrSize This field determines the size in bytes to remove from the front of the data space already allocated for this Packet. Referencing the Packet Field returns a pointer to the front of this reduced space, with hdrSize bytes removed. Remarks The MESSAGE_RemoveHeader function removes data space from the front of an already allocated Packet. Packets are allocated first by MESSAGE_PacketAlloc (Section 9.4.3) and MESSAGE_AddHeader and MESSAGE_RemoveHeader (Section 9.4.5) modify the size of the data space. Storage of information in this space directly affects the size of the data packet, and the transmission delay over wire or wireless media. See MESSAGE_ReturnPacket (Section 9.4.11) for information about accessing the Info Field.
Example /* MSG_REMOVE_HEADER.PC: This program uses the MESSAGE_RemoveHeader * function to remove a header from a Packet. */ typedef struct my_cbr_packet_fields { clocktype generation_time; /* The creation time for this Packet */ char buf[512]; /* Padding to make the cbr packet total * 512 bytes + sizeof(clocktype) */ } MyCbrPacket; typedef struct my_cbr_header_fields { NodeAddress src_addr; /* The source address of this packet */ } MyCbrHeader; Message *create_a_cbr_message (Node *node) { Message* msg; MyCbrPacket *packet; MyCbrHeader *header; msg = MESSAGE_Alloc ( node, TRANSPORT_LAYER, TRANSPORT_PROTOCOL_UDP, MSG_TRANSPORT_FromAppSend); MESSAGE_PacketAlloc ( node, msg, sizeof(MyCbrPacket)); /* Allocate the packet */ packet = (MyCbrPacket *) MESSAGE_ReturnPacket (msg); packet->generation_time = getSimTime(node); MESSAGE_AddHeader( node, msg, sizeof(MyCbrHeader)); /* Adds a header */ header = (MyCbrHeader *) MESSAGE_ReturnPacket(msg); header->src_addr = node->nodeAddr; MESSAGE_RemoveHeader( node, msg, sizeof(MyCbrHeader)); /* Removes a header */ printf(Created a new Message.\n); } return msg;
9.4.6. MESSAGE_Copy()
Message *MESSAGE_Copy( Node *node, const Message *msg);
Routine MESSAGE_Copy
Return Value This function returns the pointer to the newly created Message structure, and halts simulation execution on failure. The newly created Message structure will have identical contents to the original Message, including Packet and Info fields, and event, layer, and protocol information. Parameters node Pointer to the Node structure containing the calling nodes data space msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. It represents the original Message to be copied. Remarks The MESSAGE_Copy function creates a pointer to a new Message, and copies its event, layer, and protocol information from the original Message (msg). This function creates an exact duplicate of this original Message. This Message is reusable, as a single Message can traverse the Life Cycle illustrated in Figure 4.
Example /* MSG_COPY.PC: This program uses the MESSAGE_Copy function * to create a new packet field for a Message created for the Application Layer Constant Bit Rate * generator. The event type represented by this Message is a Packet sent to UDP for * transmission. */ #include <stdio.h> #include main.h #include message.h typedef struct my_cbr_packet_fields { clocktype generation_time; /* The creation time for this Packet */ char buf[512]; /* Padding to make the cbr packet total * 512 bytes + sizeof(clocktype) */ } MyCbrPacket; Message *create_a_cbr_message (Node *node) { Message* msg; Message* newMsg; MyCbrPacket *packet; msg = MESSAGE_Alloc ( node, TRANSPORT_LAYER, TRANSPORT_PROTOCOL_UDP, MSG_TRANSPORT_FromAppSend); MESSAGE_PacketAlloc (node, msg, sizeof(MyCbrPacket)); /* Allocate the packet */ packet = (MyCbrPacket *) MESSAGE_ReturnPacket (msg); packet->generation_time = getSimTime(node); printf(Created a new Message.\n); newMsg = MESSAGE_Copy(node, msg); printf(Copied the Message.\n); } return msg;
9.4.7. MESSAGE_Send()
void MESSAGE_Send( Node *node, Message *msg, clocktype delay);
Routine MESSAGE_Send
Return Value None. This function will abort simulation execution if the delay value is negative, implying that the sender wishes the Message to arrive earlier than the time it was actually sent. Parameters node Pointer to the Node structure containing the calling nodes data space msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. It represents the Message to be sent, according to its event, protocol, and layer information delay This is the delay between the current simulation time and the time that the Message should be delivered. This parameter can be used to simulate the processing delay required in a real system to deliver this Message. The unit of time is the nanosecond, and these can be specified by multiplying a numeric value with the defined constants {DAY, HOUR, MINUTE, SECOND, MILLI_SECOND, MICRO_SECOND}. For example, (3*SECOND) would indicate a three-second delay. Remarks The MESSAGE_Send function schedules the Message (msg) for delivery to the layer, and protocol specified by the Message, and delivers it after the delay. This function delivers the Message to the layer and protocol indicated, as an event of the type assigned to this Message. Please note that once you have sent a message, it has left your codes control. It would be incorrect to modify a data or info space in the message, copy the message, send it again, or delete it after you have sent it.
Example /* MSG_SEND.PC: This program uses the MESSAGE_Send function * to create a new packet field for a Message created for the Application Layer Constant Bit Rate * generator. The event type represented by this Message is a Packet sent to UDP for * transmission. */ #include <stdio.h> #include main.h #include message.h typedef struct my_cbr_packet_fields { clocktype generation_time; /* The creation time for this Packet */ char buf[512]; /* Padding to make the cbr packet total * 512 bytes + sizeof(clocktype) */ } MyCbrPacket; void create_a_cbr_message_and_send_it (Node *node) { Message* msg; AppToUdpSend *info; MyCbrPacket *packet; msg = MESSAGE_Alloc ( node, TRANSPORT_LAYER, TRANSPORT_PROTOCOL_UDP, MSG_TRANSPORT_FromAppSend); MESSAGE_PacketAlloc (node, msg, sizeof(MyCbrPacket)); /* Allocate the packet */ packet = (MyCbrPacket *) MESSAGE_ReturnPacket (msg); packet->generation_time = getSimTime(node); printf(Created a new Message.\n); MESSAGE_InfoAlloc (node, msg, sizeof(AppToUdpSend)); info = (AppToUdpSend *) MESSAGE_ReturnInfo(msg); info->sourceAddr = node->nodeAddr; info->sourcePort = APP_CBR_SERVER; /* My Own application type */ info->destAddr = ANY_DEST; /* A broadcast to all destinations within range */ info->destPort = APP_CBR_CLIENT; /* The destination application type */ info->priority = NON_REAL_TIME; /* CONTROL, and DATA are the other two priorities */ MESSAGE_Send(node, msg, (1*MILLI_SECOND)); /* Simulate 1ms processing delay */ printf(Sent the Message.\n); } Output Created a new Message. Sent the Message.
9.4.8. MESSAGE_Free()
void MESSAGE_Free( Node *node, Message *msg);
Routine MESSAGE_Free
Return Value None. This function deallocates memory assigned to the Message, and returns. Parameters node Pointer to the Node structure containing the calling nodes data space msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. It represents the Message to be deallocated. Remarks The MESSAGE_Free function is called by the final destination for the Message. An example of this is shown at the receiving end of Figure 4: The Life Cycle of a Packet. This Message cannot be sent or copied after its memory has been released by this Function.
Example /* MSG_FREE.PC: This program uses the MESSAGE_Free function * to free a Message created for the Application Layer Constant Bit Rate * generator. */ #include <stdio.h> #include main.h #include message.h typedef struct my_cbr_packet_fields { clocktype generation_time; /* The creation time for this Packet */ char buf[512]; /* Padding to make the cbr packet total * 512 bytes + sizeof(clocktype) */ } MyCbrPacket; void create_a_cbr_message_and_free_it (Node *node) { Message* msg; MyCbrPacket *packet; msg = MESSAGE_Alloc ( node, TRANSPORT_LAYER, TRANSPORT_PROTOCOL_UDP, MSG_TRANSPORT_FromAppSend); MESSAGE_PacketAlloc (node, msg, sizeof(MyCbrPacket)); /* Allocate the packet */ packet = (MyCbrPacket *) MESSAGE_ReturnPacket (msg); packet->generation_time = getSimTime(node); printf(Created a new Message.\n); MESSAGE_Free (node, msg); /* Note that there is no MESSAGE_Send in this function */ printf(Freed the Message.\n); } Output Created a new Message. Freed the Message.
9.4.9. MESSAGE_GetEvent()
short MESSAGE_ReturnEvent( Message *msg);
Routine MESSAGE_GetEvent
Return Value A short integer value corresponding to the type of event represented by the msg. Parameters msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. Remarks A list of the return values is given in the file include/structmsg.h. Example /* MSG_GET_EVENT.PC: This program uses the MESSAGE_GetEvent function * to determine what kind of event is represented by a certain Message. * The event type represented by this Message is a Timer Expiration. */ #include <stdio.h> #include main.h #include message.h typedef struct timer_information_str { clocktype generation_time; /* The creation time for this Timer */ int timerType; /* A subtype for the Timer */ NodeAddress neighbor; /* The neighbor IP address that this Timer is concerned with */ } MyTimerInfo; void create_a_message_and_print_its_eventType(Node *node) { MyTimerInfo *timerInfoPtr; Message* newMsg = MESSAGE_Alloc( node, APP_LAYER, APP_FTP_SERVER, MSG_APP_TimerExpired); printf(Created a new Message of event type %d.\n, MESSAGE_GetEvent(newMsg)); }
9.4.10.
MESSAGE_ReturnInfo()
Routine MESSAGE_ReturnInfo
Return Value A char pointer which points to the allocated data space for additional user-specified Event information. This space is allocated by MESSAGE_InfoAlloc (Section 9.4.2). This Function will return NULL if the space has not been previously allocated by MESSAGE_InfoAlloc (Section 9.4.2). Parameters msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. Remarks The MESSAGE_ReturnInfo function returns a character pointer, but is typically casted to a pointer to a user-defined data structure, as in the example below.
Example /* MSG_RETURN_INFO.PC: This program uses the MESSAGE_ReturnInfo function * to access a new info field for a Message created for the Application Layer FTP Server. * The event type represented by this Message is a Timer Expiration. */ #include <stdio.h> #include main.h #include message.h typedef struct timer_information_str { clocktype generation_time; /* The creation time for this Timer */ int timerType; /* A subtype for the Timer */ NodeAddress neighbor; /* The neighbor IP address that this Timer is concerned with */ } MyTimerInfo; Message *create_a_message_with_info(Node *node) { MyTimerInfo *timerInfoPtr; Message* newMsg = MESSAGE_Alloc( node, APP_LAYER, APP_FTP_SERVER, MSG_APP_TimerExpired); printf(Created a new Message.\n); MESSAGE_InfoAlloc( node, newMsg, sizeof(MyTimerInfo)); timerInfoPtr = (MyTimerInfo *)MESSAGE_ReturnInfo(newMsg); /* Casted to a structure */ timerInfoPtr->generation_time = getSimTime(node); values to the /* Assigning * User-Defined Event Info * Space */
return newMsg;
9.4.11.
MESSAGE_ReturnPacket()
Routine MESSAGE_ReturnPacket
Return Value A char pointer which points to the allocated data space for the Packet. This space is allocated by MESSAGE_PacketAlloc (Section 9.4.3). This Function will return NULL if the space has not been previously allocated by MESSAGE_PacketAlloc (Section 9.4.3). Parameters msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. Remarks The MESSAGE_ReturnPacket function returns a character pointer, but is typically casted to a pointer to a user-defined data structure, as in the example below.
Example /* MSG_RETURN_PACKET.PC: This program uses the MESSAGE_ReturnPacket function * to access a packet, and a header to a Packet. */ typedef struct my_cbr_packet_fields { clocktype generation_time; /* The creation time for this Packet */ char buf[512]; /* Padding to make the cbr packet total * 512 bytes + sizeof(clocktype) */ } MyCbrPacket; typedef struct my_cbr_header_fields { NodeAddress src_addr; /* The source address of this packet */ } MyCbrHeader; Message *create_a_cbr_message (Node *node) { Message* msg; MyCbrPacket *packet; MyCbrHeader *header; msg = MESSAGE_Alloc ( node, TRANSPORT_LAYER, TRANSPORT_PROTOCOL_UDP, MSG_TRANSPORT_FromAppSend); MESSAGE_PacketAlloc ( node, msg, sizeof(MyCbrPacket)); /* Allocate the packet */ packet = (MyCbrPacket *) MESSAGE_ReturnPacket (msg); /* Casted to a structure */ packet->generation_time = getSimTime(node); the /* Assigning values to * User-Defined Event Info * Space
MESSAGE_AddHeader( node, msg, sizeof(MyCbrHeader)); /* Adds a header */ header = (MyCbrHeader *) MESSAGE_ReturnPacket(msg); /* Casted to a structure */ header->src_addr = node->nodeAddr; /* Assigning values to the * User-Defined Event Info * Space */
9.5.
The Graphical User Interface API Functions are used by application programmers to animate the network activity in their protocols. Most of the API function calls represent events in the simulation, such as radio broadcasts, packet arrivals, packet drops, etc. Events are also tagged with the protocol layer where they occur, and a type. The purpose of these types is to allow the protocol designer to distinguish between different types of objects/data. The system uses zero as a generic default type for nodes, data, and links. The user may define custom types beginning at 1.
9.5.1. GUI_Initialize
void GUI_Initialize( int numNodes, int coordinateSystem, Coordinates origin, Coordinates dimensions, char* terrainMap, clocktype maxClock);
Routine GUI_Initialize
Return Value None
Parameters numNodes This is the number of nodes in the current simulation. coordinateSystem This is the coordinate system in place for the current simulation. Options are CARTESIAN and LATLONALT, which are two defined constants. origin This is the coordinates for the origin of the current simulation terrain. dimensions This is the dimensions of the current simulation in the coordinateSystem specified above. terrainMap A string containing the path of an image file to use as a terrain background. More full featured terrain support will be included in subsequent versions. maxClock This is the time that the simulation ends. Remarks The GUI_Initialize function initializes the GUI in order to start the animation. This function is called by the QualNet kernel first, and needs to be called before any other GUI API call. Its syntax is provided here for reference only. It is likely to be modified as QualNet and its GUI become more sophisticated. Example /* This is the call to GUI_Initialize that exists in the QualNet kernel. There is no need to use or * modify this function call. */ GUI_Initialize(nodeNum, coordinateSystemType, terrainOrigin, terrainDimensions, NULL, maxSimClock); Output None.
9.5.2. GUI_SetEffect
void GUI_SetEffect( GuiEvents event, GuiLayers layer, int type, GuiEffects effect, GuiColors color);
Routine GUI_SetEffect
Return Value None
Parameters event This is the semantic event for which the user would like to define the behavior of the GUI. layer This is the protocol layer affected by the change. type This specifies the type of the data or object. effect This is the graphical effect that will be display (such as drawing an arrow, circle, or line) for the given (event, layer, type). color This assigns a color to effect. Remarks This function has been implemented, but is not yet completed supported by the Animator. The Animator maintains a three dimensional table of effects that it will execute when the given (event, layer, type) occurs. This method allows the protocol designer to specify the graphical effect that will occur for each event. Not all effects apply to all events.
Example #define CTS_TYPE 1 #define RTS_TYPE 2 #define ACK 3 GUI_SetEffect(GUI_BROADCAST, GUI_MAC_LAYER, CTS_TYPE, GUI_DEFAULT_EFFECT, GUI_BLUE); GUI_SetEffect(GUI_BROADCAST, GUI_MAC_LAYER, RTS_TYPE, GUI_DEFAULT_EFFECT, GUI_YELLOW); GUI_SetEffect(GUI_BROADCAST, GUI_MAC_LAYER, ACK, GUI_DEFAULT_EFFECT, GUI_RED); Output This code defines three types of messages, and then sets the default behavior of the GUI to display a broadcast of each type of message with a different color. Note that this example is figurative, since the function hasn't been implemented.
9.5.3. GUI_InitNode
void GUI_InitNode( Node* node, NodeInput* nodeInput, clocktype time);
Routine GUI_InitNode
Return Value None
Parameters node Pointer to the Node structure containing the calling nodes data space nodeInput This is the structure containing all the configuration variable input. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1).
Remarks Provides the initial location of the node, the time of creation, and other information. Example GUI_InitNode(node, nodeInput, getSimTime(node)); Output The nodes initial position will be reflected in the GUI.
9.5.4. GUI_MoveNode
void GUI_MoveNode( NodeAddress id, Coordinates position, clocktype time);
Routine GUI_MoveNode
Return Value None
Parameters id This is the numeric identifier for the given node. In the Node structure, it is the nodeId struct member. position This is the new position of the given node. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Moves the node to a new position. Example GUI_MoveNode(node->nodeAddr, node->position, getSimTime(node)); Output The nodes new position will be reflected in the GUI.
9.5.5. GUI_SetNodeOrientation
void GUI_SetNodeOrientation( NodeAddress id, Orientation orientation, clocktype time);
Routine GUI_SetNodeOrientation
Return Value None
Parameters id This is the numeric identifier for the given node. In the Node structure, it is the nodeId struct member. orientation Specifically for directional antenna systems, this specifies the direction the node is facing. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function is not yet supported. When it is, it will be used to specify the direction a wireless node (typically one with a directional antenna) is facing. Example Orientation thisOrientation = {15, 0}; // 15 degrees clockwise from north. GUI_SetNodeOrientation(node->nodeId, thisOrientation, getSimTime(node)); Output Rotates the icon to the correct orientation, and uses the orientation for displaying antenna patterns.
9.5.6. GUI_SetNodeIcon
void GUI_SetNodeIcon( NodeAddress id, char* iconFile, clocktype time);
Routine GUI_SetNodeIcon
Return Value None
Parameters id This is the numeric identifier for the given node. In the Node structure, it is the nodeId struct member. iconFile This is the path to an image file to use to represent the node graphically. It can be specified either as an absolute path, or a relative path from QUALNET_HOME. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function is not yet supported. When it is, it will change the icon being used for a node. Output Changes the icon used to display the node graphically.
9.5.7. GUI_SetNodeLabel
void GUI_SetNodeLabel( NodeAddress id, char* label, clocktype time);
Routine GUI_SetNodeLabel
Return Value None
Parameters id This is the numeric identifier for the given node. In the Node structure, it is the nodeId struct member. label This is a name to display next to the node in lieu of its ID. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function is not yet supported by the GUI. When it is, it will set the string to be used as a label for the node. Output Changes the label on the node.
9.5.8. GUI_SetNodeRange
void GUI_SetNodeRange( NodeAddress id, double range, clocktype time);
Routine GUI_SetNodeRange
Return Value None
Parameters id This is the numeric identifier for the given node. In the Node structure, it is the nodeId struct member. range The uninhibited propagation range, in meters, of this nodes wireless radio, assuming that both the sender and receiver are using omni-directional antennas. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Changes the range of a wireless node, which is used to display wireless transmissions. Output Changes the circumference of the circles used to display a wireless broadcast.
9.5.9. GUI_SetNodeType
void GUI_SetNodeType( NodeAddress id, int type, clocktype time);
Routine GUI_SetNodeType
Return Value None
Parameters id This is the numeric identifier for the given node. In the Node structure, it is the nodeId struct member. type A user-defined integer value representing the type of the node, for example a role the node is playing. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function is not yet supported by the Animator. When it is, it will specify the type of the node, which might be used to change the way the node is displayed on the screen. Example #define GATEWAY_NODE 1 #define SIMPLE_NODE 2 node->guiProperties.type = GATEWAY_NODE; GUI_SetNodeType(node->nodeId, node->guiProperties.type, getSimTime(node)); Output This is an example of a hypothetical ad hoc protocol that dynamically assigns roles to nodes. Most are simple nodes, but others are gateways between node groups. Used in conjunction with GUI_SetEffect, the developer can specify how nodes of different types are displayed.
9.5.10.
GUI_SetPatternIndex
Routine GUI_SetPatternIndex
Return Value None
Parameters nodeID This is the numeric identifier for the given node. In the Node structure, it is the nodeId struct member. index This is an index into the nodes antenna pattern array. The value 1 is defined as the omni-directional pattern. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks If Antenna pattern animation is enabled, this function may change the shape of the antenna pattern displayed for this node. For proper operation, the node should have specified an antenna pattern file in the GUI_InitNode function. Example GUI_SetPatternIndex(node->nodeId, ANTENNA_OMNIDIRECTIONAL_PATTERN, getSimTime(node)); Output This example sets the nodes antenna pattern to the default omni-directional pattern.
9.5.11.
GUI_SetPatternAndAngle
void GUI_SetPatternAndAngle( NodeAddress nodeID, int index, int angleInDegrees, clocktype time);
Routine GUI_SetPatternIndex
Return Value None
Parameters nodeID This is the numeric identifier for the given node. In the Node structure, it is the nodeId struct member. index This is an index into the nodes antenna pattern array. The value 1 is defined as the omni-directional pattern. angleInDegrees This represents the azimuth angle to which the antenna is steered. It is relative to the orientation of the node. Thus if the nodes azimuth is 30 degrees, and this value is 40 degrees, the antenna pattern will be focused at 70 degrees. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks If Antenna pattern animation is enabled, this function may change the shape of the antenna pattern displayed for this node. For proper operation, the node should have specified an antenna pattern file in the GUI_InitNode function. This version of the function is typically used for steerable antennas, where the selected pattern can also be steered to focus at a different angle. Example GUI_SetPatternAndAngle(node->nodeId, ANTENNA_OMNIDIRECTIONAL_PATTERN, 0, getSimTime(node)); Output This example sets the nodes antenna pattern to the default omni-directional pattern with no steering angle.
9.5.12.
GUI_AddLink
void GUI_AddLink( NodeAddress source, NodeAddress dest, GuiLayers layer, int type, NodeAddress subnetAddress, int numHostBits, clocktype time);
Routine GUI_AddLink
Return Value None
Parameters source This is the numeric identifier for the given source node. In the Node structure, it is the nodeId struct member. dest This is the numeric identifier for the given destination node. In the Node structure, it is the nodeId struct member. layer This is the protocol layer at which this link is relevant, e.g. GUI_NETWORK_LAYER, GUI_TRANSPORT_LAYER, GUI_APP_LAYER. subnetAddress and numHostBits These are optional fields for when the function is used to create a subnet link, and are used by the Animator to correctly assign IP numbers to nodes. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Adds a link between two nodes. In a wired topology, this could represent a point to point connection between the two nodes. In wireless, it might represent a link on a dynamic route. Or it might be used to represent on open telnet session. Only one link between two nodes will be shown (per layer). If GUI_AddLink is called when a link already exists, the "type" of the link will be updated. Example GUI_AddLink(client->nodeAddr, server->nodeAddr, GUI_APPLICATION_LAYER, GUI_DEFAULT_LINK_TYPE, getSimTime(node)); Output This example adds an application link between a pair of client and server nodes in the GUI.
9.5.13.
GUI_DeleteLink
void GUI_DeleteLink( NodeAddress source, NodeAddress dest, GuiLayers layer, clocktype time);
Routine GUI_DeleteLink
Return Value None
Parameters source This is the numeric identifier for the given source node. In the Node structure, it is the nodeId struct member. dest This is the numeric identifier for the given destination node. In the Node structure, it is the nodeId struct member. layer This is the protocol layer at which this link is relevant, e.g. GUI_NETWORK_LAYER, GUI_TRANSPORT_LAYER, GUI_APP_LAYER. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks The function will remove the link at the specified layer, no matter the type. The type doesn't matter because only one link will be shown for each layer. Example GUI_DeleteLink(client->nodeAddr, server->nodeAddr, GUI_APPLICATION_LAYER, getSimTime(node)); Output This example removes an application link between a pair of client and server nodes in the GUI.
9.5.14.
GUI_Broadcast
void GUI_Broadcast( NodeAddress source, GuiLayers layer, int type, NodeAddress interfaceAddress, clocktype time);
Routine GUI_Broadcast
Return Value None
Parameters source This is the numeric identifier for the given source node. In the Node structure, it is the nodeId struct member. layer This is the protocol layer at which this link is relevant, e.g. GUI_NETWORK_LAYER, GUI_TRANSPORT_LAYER, GUI_APP_LAYER. type This is the user-defined type of broadcast. interfaceAddress Primarily for wired nodes, this indicates on which connected network the broadcast should be displayed. A default value can be specified for wireless nodes, or those with only one interface. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Indicates a broadcast. Typically, broadcasts will occur at the routing protocol or below. Radios will always broadcast. Example GUI_Broadcast(node->nodeId, GUI_PHY_LAYER, GUI_DEFAULT_DATA_TYPE, GUI_DEFAULT_INTERFACE, node-> getSimTime(node)); Output This example executes a radio broadcast from the node identified by nodeId.
9.5.15.
GUI_EndBroadcast
void GUI_EndBroadcast( NodeAddress source, GuiLayers layer, int type, NodeAddress interfaceAddress, clocktype time);
Routine GUI_EndBroadcast
Return Value None
Parameters source This is the numeric identifier for the given source node. In the Node structure, it is the nodeId struct member. layer This is the protocol layer at which this link is relevant, e.g. GUI_NETWORK_LAYER, GUI_TRANSPORT_LAYER, GUI_APP_LAYER. type This is the user-defined type of broadcast. interfaceAddress Primarily for wired nodes, this indicates on which connected network the broadcast should be displayed. A default value can be specified for wireless nodes, or those with only one interface. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks To help the Animator with the timing of animation events, a wireless broadcast now requires an explicit matching call to EndBroadcast. Output This example erases a radio broadcast from the node identified by nodeId.
9.5.16.
GUI_Multicast
void GUI_Multicast( NodeAddress source, GuiLayers layer, int type, NodeAddress interfaceAddress, clocktype time);
Routine GUI_Multicast
Return Value None
Parameters source This is the numeric identifier for the given source node. In the Node structure, it is the nodeId struct member. layer This is the protocol layer at which this link is relevant, e.g. GUI_NETWORK_LAYER, GUI_TRANSPORT_LAYER, GUI_APP_LAYER. type This is the user-defined type of multicast. interfaceAddress Primarily for wired nodes, this indicates on which connected network the broadcast should be displayed. A default value can be specified for wireless nodes, or those with only one interface. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Indicates a multicast. I believe a multicast is only meaningful in certain routing protocols. The GUI currently supports this by treating it identically to GUI_Broadcast (Section 9.5.14). Example GUI_Multicast(node->nodeAddr, GUI_PHY_LAYER, GUI_DEFAULT_DATA_TYPE, GUI_DEFAULT_INTERFACE, getSimTime(node)); Output This example executes a multicast from the node identified by nodeId.
9.5.17.
GUI_Unicast
void GUI_Unicast( NodeAddress source, NodeAddress dest, GuiLayers layer, DataTypes type, clocktype time);
Routine GUI_Unicast
Return Value None
Parameters source This is the numeric identifier for the given source node. In the Node structure, it is the nodeId struct member. dest This is the numeric identifier for the given destination node. In the Node structure, it is the nodeId struct member. layer This is the protocol layer at which this link is relevant, e.g. GUI_NETWORK_LAYER, GUI_TRANSPORT_LAYER, GUI_APP_LAYER. type This is the user-defined type of unicast. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Sends a unicast packet/frame/signal to a destination. Will probably be drawn as a temporary line between source and destination, followed by a signal (at the receiver) indicating success or failure. Example GUI_Unicast(node->nodeAddr, destAddr, GUI_PHY_LAYER, GUI_DEFAULT_DATA_TYPE, getSimTime(node)); Output This example executes a unicast from the node identified by nodeId.
9.5.18.
GUI_Receive
void GUI_Receive( NodeAddress source, NodeAddress dest, GuiLayers layer, int type, clocktype time);
Routine GUI_Receive
Return Value None
Parameters source This is the numeric identifier for the given source node. In the Node structure, it is the nodeId struct member. dest This is the numeric identifier for the given destination node. In the Node structure, it is the nodeId struct member. layer This is the protocol layer at which this link is relevant, e.g. GUI_NETWORK_LAYER, GUI_TRANSPORT_LAYER, GUI_APP_LAYER. type This is the user-defined type of unicast. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Shows a successful receipt at a destination. Typically would follow a unicast, multicast, or broadcast. Example GUI_Receive(senderAddr, node->nodeAddr, GUI_PHY_LAYER, GUI_DEFAULT_DATA_TYPE, getSimTime(node)); Output This example instructs the GUI to indicate successful reception from the node identified by nodeId.
9.5.19.
GUI_Drop
void GUI_Drop( NodeAddress source, NodeAddress dest, GuiLayers layer, int type, clocktype time);
Routine GUI_Drop
Return Value None
Parameters source This is the numeric identifier for the given source node. In the Node structure, it is the nodeId struct member. dest This is the numeric identifier for the given destination node. In the Node structure, it is the nodeId struct member. layer This is the protocol layer at which this link is relevant, e.g. GUI_NETWORK_LAYER, GUI_TRANSPORT_LAYER, GUI_APP_LAYER. type This is the user-defined type of unicast. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Shows a packet/frame/signal being dropped by a node. Typically would follow a broadcast or unicast at the same layer. Example GUI_Drop(senderId, node->nodeId, GUI_PHY_LAYER, GUI_DEFAULT_DATA_TYPE, getSimTime(node)); Output This example instructs the GUI to indicate a drop reception from the node identified by senderId to node->nodeId.
9.5.20.
GUI_Collision
Routine GUI_Collision
Return Value None
Parameters dest This is the numeric identifier for the given destination node. In the Node structure, it is the nodeId struct member. layer This is the protocol layer at which this link is relevant, e.g. GUI_NETWORK_LAYER, GUI_TRANSPORT_LAYER, GUI_APP_LAYER. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Shows a node detecting a collision. Collisions are strictly a wireless animation issue for the GUI. Example GUI_Receive(senderId, node->nodeId, CHANNEL_LAYER, GUI_DEFAULT_DATA_TYPE, getSimTime(node)); Output This example instructs the GUI to indicate a successful reception from the node identified by senderId to node->nodeId.
9.5.21.
GUI_CreateSubnet
void GUI_CreateSubnet( int type, NodeAddress subnetAddress, int numHostBits, char* nodeList, clocktype time);
Routine GUI_CreateSubnet
Return Value None
Parameters type This is the type, wired or wireless, of the subnet. subnetAddress This is the base IP address of the subnet. numHostBits This is the size of the subnet. nodeList This is the list of node identifiers of the nodes in the subnet. It uses the same formatting conventions as the SUBNET variable, including the thru clause. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks The GUI does not yet fully support this function. Creates either a wired or wireless subnet. Wired subnets are drawn by connecting the nodes to a hub/switch object. Wireless subnets are typically color coded. This function must be called after GUI_InitNode is called for all nodes in the subnet, and is typically called during MAC layer initialization in the kernel code. Output A subnet is drawn.
9.5.22.
GUI_CreateHierarchy
Routine GUI_CreateHierarchy
Return Value None
Parameters componentId This is an identifier assigned to a hierachical component by the GUI. nodeList This is a duplicate of the string printed by the GUI to identify the contents of this hierarchical component. Remarks This function is used to reconstruct a hierarchically designed experiment in the GUI. Users should not attempt to create hierarchies by hand. Output Draws the nodes in a hierarchical fashion.
9.5.23.
GUI_AddApplication
void GUI_AddApplication( NodeAddress source, NodeAddress dest, char* appName, int uniqueId, clocktype time);
Routine GUI_AddApplication
Return Value None
Parameters source This is the node ID of the application client. dest This is the node ID of the application server. appName This is the name of the type of application, e.g. CBR or FTP. uniqueId This is a unique identifier assigned to the application, for the purpose of distinction. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function adds a label to the client and server nodes to indicate that an application connection is set up between the two nodes. Need only be called by the client. Output A node label.
9.5.24.
GUI_DeleteApplication
void GUI_DeleteApplication( NodeAddress source, NodeAddress dest, char* appName, int uniqueId, clocktype time);
Routine GUI_DeleteApplication
Return Value None
Parameters source This is the node ID of the application client. dest This is the node ID of the application server. appName This is the name of the type of application, e.g. CBR or FTP. uniqueId This is a unique identifier assigned to the application, for the purpose of distinction. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function removes a label from the client and server nodes indicating that an application connection is set up between the two nodes. Need only be called by the client. Output Removes a node label.
9.5.25.
GUI_AddInterfaceQueue
void GUI_AddInterfaceQueue( NodeAddress node, GuiLayers layer, int interfaceId, unsigned int priority, int queuesize, clocktype time);
Routine GUI_AddInterfaceQueue
Return Value None
Parameters node This is the identifier of the node adding the queue. layer This is protocol layer where the queue is implemented. interfaceId This is the interface on which the queue is located, if the node has more than one interface. priority This is the priority associated with the queue. queuesize This is the queue size in bytes. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function is not yet implemented in the GUI. This function will display a queue, or set of queues, next to the node during animation of the simulation. Output A queue outline.
9.5.26.
GUI_QueueInsertPacket
void GUI_QueueInsertPacket( NodeAddress node, GuiLayers layer, int interfaceId, unsigned int priority, int packetSize, clocktype time);
Routine GUI_QueueInsertPacket
Return Value None
Parameters node This is the identifier of the node adding the queue. layer This is protocol layer where the queue is implemented. interfaceId This is the interface on which the queue is located, if the node has more than one interface. priority This is the priority associated with the queue. packetSize This is the size, in bytes, of the packet. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function is not yet implemented in the GUI. This function adds a packet to a queue being displayed on the GUI. Output Adds an appropriately sized packet block to a queue.
9.5.27.
GUI_QueueDequeuePacket
void GUI_QueueDequeuePacket( NodeAddress node, GuiLayers layer, int interfaceId, unsigned int priority, int packetSize, clocktype time);
Routine GUI_QueueDequeuePacket
Return Value None
Parameters node This is the identifier of the node adding the queue. layer This is protocol layer where the queue is implemented. interfaceId This is the interface on which the queue is located, if the node has more than one interface. priority This is the priority associated with the queue. packetSize This is the size, in bytes, of the packet. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function is not yet implemented in the GUI. This function removes a packet from the displayed queue. Output Reduces the displayed queue size by the size of the removed packet.
9.5.28.
GUI_QueueDropPacket
void GUI_QueueDropPacket( NodeAddress node, GuiLayers layer, int interfaceId, unsigned int priority, clocktype time);
Routine GUI_QueueDropPacket
Return Value None
Parameters node This is the identifier of the node adding the queue. layer This is protocol layer where the queue is implemented. interfaceId This is the interface on which the queue is located, if the node has more than one interface. priority This is the priority associated with the queue. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function is not yet implemented in the GUI. This function shows a packet being dropped from the queue. Output A packet of the given size is dropped from the queue.
9.5.29.
GUI_DefineMetric
int GUI_DefineMetric( char* name, NodeAddress nodeID, GuiLayers layer, int linkID, GuiDataTypes datatype, GuiMetrics metrictype);
Routine GUI_DefineMetric
Return Value An integer identifying the metric. This integer should be used in future calls to GUI_SendIntegerData and GUI_SendRealData. Parameters metricName This is a string containing the name of the metric, e.g. packets dropped. nodeID This is the identifier of the node defining the metric. layer This is layer associated with the metric. linkID This is an identifier used to associate a metric with a link, for example an application connection, rather than a node. datatype This is the type of the data, integer or floating point. metrictype This is the analytical type of the data, e.g. a cumulative total, or a running average. Remarks This function is used to register a statistical variable for generating dynamic graphs during a simulation. This function should generally be called during initialization. The integer value returned should be used in subsequent calls to the GUI_Send*Data calls described subsequently. Routing protocols should use the protocol layer where the particular protocol resides, rather than the generic GUI_ROUTING_LAYER. Output The GUI lists all the metrics, allowing the user to choose statistics to graph dynamically.
9.5.30.
GUI_SendIntegerData
void GUI_SendIntegerData( NodeAddress node, int metricID, int value, clocktype time);
Routine GUI_SendIntegerData
Return Value None
Parameters node This is the identifier of the node sending the data. metricID This is the identifier for the metric returned from GUI_DefineMetric. value This is the value. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Each protocol should implement a RunTimeStat function, and ensure that this function is called from the master RunTimeStat function for that layer. For example, the master function for the network layer, NETWORK_RunTimeStat calls the corresponding function for the IP protocol, NetworkIpRunTimeStat. All calls to GUI_Send*Data should be placed in the RunTimeStat function. This allows the Animator to control the frequency of updates. It is also possible to call this function each time a metric is updated. In this case, the Animator will not be able to control the rate of sampling. Output Dynamically generated graphs.
9.5.31.
GUI_SendRealData
void GUI_SendRealData( SubnetType type, int metricID, double value, clocktype time);
Routine GUI_SendRealData
Return Value None
Parameters node This is the identifier of the node sending the data. metricID This is the identifier for the metric returned from GUI_DefineMetric. value This is the value. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks See the remarks in Section 9.5.30. Output Dynamically generated graphs.
9.5.32.
GUI_SendUnsignedData
void GUI_SendUnsignedData( SubnetType type, int metricID, double value, clocktype time);
Routine GUI_SendUnsignedData
Return Value None
Parameters node This is the identifier of the node sending the data. metricID This is the identifier for the metric returned from GUI_DefineMetric. value This is the value. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks See the remarks in Section 9.5.30. Output Dynamically generated graphs.
9.6.
Statistics Output Functions are used to print statistics data from each protocol to the standard QualNet experiments statistical output text file. There is currently one function that falls into this category.
9.6.1. IO_PrintStat
void IO_PrintStat( Node *node, const char *layer, const char *protocol, NodeAddress interfaceAddress, int instanceId, const char *buf);
Routine GUI_PrintStat
Return Value None
Parameters node Pointer to the Node structure containing the calling nodes data space layer This is the name of the layer at which this statistic is relevant. protocol This is the name of the protocol for which this statistic is relevant. interfaceAddress This is the IP address for which this statistic is relevant, if statistics are recorded per Network Interface. If IP address is not relevant for this statistic, use the constant ANY_DEST. instanceId This is the instance of the protocol for which this statistic is relevant, if statistics are recorded for multiple instances on one interfaceAddress. If multiple instances are not relevant for this statistic, use the value -1. buf This is the statistic, in the form of a character array, usually created with sprintf to be a verbose description of the statistic being reported. Example IO_PrintStat(node, Network, MyProtocol, ANY_DEST, -1, buf);
Output The contents of buf will be printed to the QualNet Statistical Output File as a statistic reported by MyProtocol for the given node.
9.7.
Error Functions are used to report error conditions to the user, whether they are executing QualNet via the command-line, or the GUI. The ERROR_ReportError API function is provided to give the protocol modeler a single interface from which to communicate these error conditions to the user, and debug their own models. Assertion Functions are used to debug protocol models and code by inserting sanity checks (e.g., assert that there are actually packets in the queue I am attempting to dequeue from, before I reference the contents of a NULL pointer). However, these differ from Error Functions because they should ultimately be removed from the executable to reduce overhead, once it is determined that the sanity check never fails, and can be removed by defining NDEBUG at compile-time. The ERROR_Assert API function is provided to address the need for Assertion Functions. These API functions differ from their standard C counterparts in that they provide information to the GUI-initiated QualNet simulations as well as the command-line simulations.
9.7.1. ERROR_ReportError
void ERROR_ReportError( char *msg);
Routine ERROR_ReportError
Return Value None. Simulation exits and prints msg. Parameters msg This is the error message to print, either to the GUI or the standard output, if QualNet is running at the command-line. Example ERROR_ReportError( Pointer to the packet is NULL); Output The contents of msg will be printed to the screen or a GUI error window, and then the simulation will exit.
9.7.2. ERROR_Assert
void ERROR_Assert( condition, char *msg);
Routine ERROR_Assert
Return Value None. Simulation exits and prints msg if the condition evaluates to FALSE. Parameters condition This is a Boolean condition that under all sane conditions should evaluate to TRUE, but given that the programmer may not have considered all possible permutations, we wish to doublecheck. If this condition ever evaluates to FALSE, it indicates a logic or programming error that must immediately be addressed. msg This is the error message to print, either to the GUI or the standard output, if QualNet is running at the command-line. This error message provides some additional detail about the unexpected event.
Example ERROR_Assert((ptr != NULL), Pointer to the packet is NULL); Output The line number and filename of the ERROR_Assert call, and the contents of msg will be printed to the screen or a GUI error window, and then the simulation will exit, if condition evaluates to FALSE.