Ns-3-Manual.Pdf
Total Page:16
File Type:pdf, Size:1020Kb
ns-3 Manual Release ns-3-dev ns-3 project Sep 26, 2021 CONTENTS 1 Organization 3 2 Working with git as a user 5 2.1 ns-3’s Git workflow in a nutshell.....................................5 2.2 Setup of a personal repository......................................6 2.3 Add the official ns-3 repository as remote upstream...........................7 2.4 Add your forked repository as remote..................................7 2.5 Keep in sync your repository with latest ns-3-dev updates.......................8 2.6 Start a new branch to do some work...................................8 2.7 Edit and commit the modifications....................................9 2.8 Rebase your branch on top of master.................................. 10 2.9 Pushing your changes to origin..................................... 10 2.10 Submit work for review......................................... 10 2.11 Porting patches from mercurial repositories to git............................ 10 3 Working with git as a maintainer 11 3.1 Pushing your own work......................................... 11 3.2 Review and merge someone else’s work................................. 11 3.3 Making a release............................................. 11 4 Random Variables 17 4.1 Quick Overview............................................. 17 4.2 Background................................................ 17 4.3 Creating random variables........................................ 18 4.4 Seeding and independent replications.................................. 18 4.5 Class RandomVariableStream...................................... 19 4.6 Base class public API.......................................... 20 4.7 Types of RandomVariables........................................ 20 4.8 Semantics of RandomVariableStream objects.............................. 20 4.9 Using other PRNG............................................ 21 4.10 Setting the stream number........................................ 21 4.11 Publishing your results.......................................... 22 4.12 Summary................................................. 22 5 Hash Functions 23 5.1 Basic Usage............................................... 23 5.2 Incremental Hashing........................................... 23 5.3 Using an Alternative Hash Function................................... 24 5.4 Adding New Hash Function Implementations.............................. 24 5.5 Sources for Hash Functions....................................... 24 i 6 Events and Simulator 27 6.1 Event................................................... 27 6.2 Simulator................................................. 27 6.3 Time................................................... 29 6.4 Scheduler................................................. 29 7 Callbacks 31 7.1 Callbacks Motivation........................................... 31 7.2 Callbacks Background.......................................... 32 7.3 Using the Callback API......................................... 35 7.4 Bound Callbacks............................................. 38 7.5 Traced Callbacks............................................. 39 7.6 Callback locations in ns-3........................................ 39 7.7 Implementation details.......................................... 40 8 Object model 41 8.1 Object-oriented behavior......................................... 41 8.2 Object base classes............................................ 41 8.3 Memory management and class Ptr................................... 42 8.4 CreateObject and Create......................................... 42 8.5 Aggregation............................................... 43 8.6 Examples................................................. 43 8.7 Object factories.............................................. 44 8.8 Downcasting............................................... 45 9 Configuration and Attributes 47 9.1 Object Overview............................................. 47 9.2 Attributes................................................. 50 9.3 Implementation Details......................................... 56 9.4 ConfigStore................................................ 60 10 Object names 69 11 Logging 71 11.1 Overview................................................. 71 11.2 How to add logging to your code.................................... 75 11.3 Controlling timestamp precision..................................... 76 12 Tracing 79 12.1 Tracing Motivation............................................ 79 12.2 Overview................................................. 80 12.3 Using the Tracing API.......................................... 83 12.4 Using Trace Helpers........................................... 83 12.5 Tracing implementation details..................................... 95 13 Data Collection 97 13.1 Design.................................................. 97 13.2 Data Collection Helpers......................................... 99 13.3 Probes.................................................. 108 13.4 Collectors................................................. 115 13.5 Aggregators............................................... 115 13.6 Adaptors................................................. 122 13.7 Scope/Limitations............................................ 122 14 Statistical Framework 125 ii 14.1 Goals................................................... 125 14.2 Overview................................................. 125 14.3 To-Do................................................... 126 14.4 Approach................................................. 126 14.5 Example................................................. 127 15 RealTime 135 15.1 Behavior................................................. 135 15.2 Usage................................................... 135 15.3 Implementation.............................................. 136 16 Helpers 137 17 Utilities 139 17.1 Print-introspected-doxygen....................................... 139 17.2 Bench-simulator............................................. 140 18 Making Plots using the Gnuplot Class 143 18.1 Creating Plots Using the Gnuplot Class................................. 143 18.2 An Example Program that Uses the Gnuplot Class........................... 143 18.3 An Example 2-Dimensional Plot..................................... 144 18.4 An Example 2-Dimensional Plot with Error Bars............................ 146 18.5 An Example 3-Dimensional Plot..................................... 147 19 Using Python to Run ns-3 151 19.1 Introduction............................................... 151 19.2 An Example Python Script that Runs ns-3 ................................ 151 19.3 Running Python Scripts......................................... 152 19.4 Caveats.................................................. 153 19.5 Working with Python Bindings..................................... 154 19.6 Historical Information.......................................... 159 20 Tests 161 20.1 Overview................................................. 161 20.2 Background................................................ 161 20.3 Testing framework............................................ 164 20.4 How to write tests............................................ 175 21 Support 179 21.1 Creating a new ns-3 model........................................ 179 21.2 Adding a New Module to ns-3 ...................................... 187 21.3 Creating Documentation......................................... 193 21.4 Enabling Subsets of ns-3 Modules.................................... 202 21.5 Enabling/disabling ns-3 Tests and Examples.............................. 205 21.6 Troubleshooting............................................. 207 Bibliography 209 Index 211 iii iv ns-3 Manual, Release ns-3-dev This is the ns-3 Manual. Primary documentation for the ns-3 project is available in five forms: • ns-3 Doxygen: Documentation of the public APIs of the simulator • Tutorial, Manual (this document), and Model Library for the latest release and development tree • ns-3 wiki This document is written in reStructuredText for Sphinx and is maintained in the doc/manual directory of ns-3’s source code. CONTENTS 1 ns-3 Manual, Release ns-3-dev 2 CONTENTS CHAPTER ONE ORGANIZATION This chapter describes the overall ns-3 software organization and the corresponding organization of this manual. ns-3 is a discrete-event network simulator in which the simulation core and models are implemented in C++. ns-3 is built as a library which may be statically or dynamically linked to a C++ main program that defines the simulation topology and starts the simulator. ns-3 also exports nearly all of its API to Python, allowing Python programs to import an “ns3” module in much the same way as the ns-3 library is linked by executables in C++. Fig. 1: Software organization of ns-3 The source code for ns-3 is mostly organized in the src directory and can be described by the diagram in Software organization of ns-3. We will work our way from the bottom up; in general, modules only have dependencies on modules beneath them in the figure. We first describe the core of the simulator; those components that are common across all protocol, hardware, and environmental models. The simulation core is implemented in src/core. Packets are fundamental objects in a network simulator and are implemented in src/network. These two simulation modules by themselves are intended to comprise a generic simulation core that can be used by different kinds of networks, not just Internet-based networks. The above modules of ns-3 are independent of