Ns-3 Design Overview
Total Page:16
File Type:pdf, Size:1020Kb
ns-3 Design Overview ns-3 project http://www.nsnam.org/ feedback: [email protected] September 17, 2006 Introduction This ns-3 design document is intended to document the technical goals, software architecture, implementation choices, and interfaces of the simulator. It provides a place to record design agreements or archive design decisions for future reference. It is expected that this document can evolve or fork to become an “ns-3 Developers Guide” at some point in the future. This documentis written in Latex and is to be maintainedin revision control on the ns-3 code server. Changes to the document should be discussed on the [email protected] mailing list. Contents 1 Functional Overview 3 1.1 Goals ........................................... ............ 3 1.2 Userexperience.................................. ................ 3 1.2.1 Installation .................................. .............. 3 1.2.2 Userinterface................................. .............. 3 1.2.3 Scenariodefinition .... .... .... ... .... .... .... .. ............... 4 1.2.4 Capabilities.................................. .............. 4 1.3 Documentation ................................... ............... 4 1.4 RequirementsfromCollaborators. ...................... 4 1.4.1 VINI .......................................... ......... 5 1.4.2 Emulab........................................ .......... 5 1.4.3 NetworkSimulationCradle . ................ 5 1.4.4 Largescalesimulations. ................. 5 2 Technical Overview 6 2.1 Basics.......................................... ............. 6 2.2 High-levelarchitecture . .................... 7 2.3 Sourcecodeorganization . ................... 8 2.4 Buildenvironment ................................ ................ 8 2.4.1 SConsoverview ................................. ............ 9 2.4.2 Options....................................... ........... 9 2.4.3 Buildtargets .................................. ............. 9 2.4.4 Buildoutput ................................... ............ 10 3 ns-3 Coding Standard 11 3.1 Introduction.................................... ................ 11 3.2 Recommendations................................. ................ 11 3.2.1 naming ........................................ .......... 11 3.2.2 Memorymanagement .............................. ............ 12 3.2.3 Templates..................................... ............ 12 3.3 Standards ....................................... .............. 12 3.3.1 General....................................... ........... 12 3.3.2 Commenting .................................... ........... 13 3.3.3 NamingConventions. .............. 14 3.3.4 StatementFormatting. ................ 15 3.3.5 HeaderFiles ................................... ............ 17 3.3.6 SourceCodeFiles ............................... ............. 18 3.3.7 Backwardcompatibilityofbugfixes . ................... 19 1 4 ns-3 core 20 4.1 Simulator,Scheduler,andEvents . ...................... 21 4.1.1 Simulator..................................... ............ 21 4.1.2 Scheduler..................................... ............ 21 4.1.3 Events........................................ ........... 22 4.2 Timers.......................................... ............. 23 4.3 Time............................................ ............ 23 4.4 Callbacks ....................................... .............. 23 4.5 Referencelistimplementation . ..................... 24 4.6 FileI/Oandsystemtime . .... .... .... ... .... .... .... ................. 24 5 Running ns-3 simulations 25 5.1 Executingsimulations. ................... 25 5.1.1 main()program................................. ............. 25 5.1.2 Scriptinginterface . ................ 27 6 Packets 28 7 Tracing and Logging 29 7.1 Requirements .................................... ............... 29 7.1.1 traceformatforTraceGraphsupport . .................... 30 8 Acknowledgments 32 2 Chapter 1 Functional Overview This chapter describes the ns-3 simulator from a functional or user’s perspective; i.e., without as much regard to internal implementation. 1.1 Goals This section describes the broad goals for ns-3. • ns-3 is a discrete-event networking simulator, written in C++, with an emphasis on layers 2-4 of the OSI stack, including IPv4, IPv6, and future next-generation (non-IP) networks. • ns-3 is oriented towards supporting networking research and education via simulation. • ns-3 is free software developed using a community-oriented, open source development process, under GNU GPLv2 compatible licensing. 1.2 User experience 1.2.1 Installation ns-3 should be buildable from source or binary formats on popular desktop and server platforms, including x86, x86-64, and ppc, and the Linux, OS X (Darwin), Windows (32-bit, build environment TBD), Solaris, and BSD (FreeBSD and others) operating systems. 1.2.2 User interface • ns-3 should continue to offer text/script-based (non-GUI) configuration. It should be possible to create GUI-based configurators, but such configurators are outside the scope of the ns-3 project. • ns-3 should output trace (including pcap), log, statistics, and animation files 3 – trace and log files should be convertible to the existing nam format, via some external scripting technique, for backward compatibility. • Open issue: should ns-3 be directly integrated with an animator or should the animator just run on output files (post-process)? 1.2.3 Scenario definition Users use the simulator by first defining a simulation scenario, compiling the scenario if necessary, executing the simulation scenario, and processing the simulation output, either visually through an animator, or through other handling of the output files generated. Often, users of the simulator will directly modify the simulator source code as a starting point. • ns-3 scenarios can be written in C++ (as a main() function), with selected configuration options exposed as command- line arguments • ns-3 should provide a scripting environment or interface – full backward compatibility with ns-2 scripts is a non-goal – Open issue: Selection of scripting language(s) is TBD. Preferred option presently is python and possibly SWIG bindings. • scenario execution is visible on a console standard output, or written to a log file. • support for some stock topology constructs should be provided 1.2.4 Capabilities • ns-3 shall provide an emulation capability– ability to source/sink real packets and execute in real-time • ns-3 shall be designed to scale for parallel processor support and distributed simulations, in a manner mostly transparent to users. • ns-3 shall provide interfaces that facilitate the porting of implementation code (user space and kernel TCP/IP stacks) 1.3 Documentation • Source code APIs shall be documented using Doxygen and available on the web as HTML and Latex-generated PDF. • the various project documents use Latex. The documentation should be checked out nightly, built into PDF and HTML, and posted on the web. Documentation should be stored in the source code repository in source form, with figures stored in eps or image format. Vector graphics should be drawn in a commonly available vector graphics program such as dia, tgif, or xfig, and the sources stored with the eps. 1.4 Requirements from Collaborators This project is collaborating with several other networking research projects. This section is used to document the goals and/or requirements that have been suggested from these other projects. 4 1.4.1 VINI Nick Feamster and George Riley met in September 2006 and agreed that the ns-3 team would strive to support VINI on two basic fronts: • ns-3 simulations will provide some mechanism to "dump" the topology in a format compatible with VINI’s topology description. VINI would then re-create the same topology on the VINI/Planetlab systems and re-create the same experiment. • The ns-3 design will facilitate "easy" (definition of easy TBD) migration of application code to and from VINI. This is harder, but is consistent with our design goals of "easy" integration of existing code (eg. the XORP OSPF implemen- tation). The issues are still evolving, but we expect that whatever solution we converge on for the general case will be sufficient for the VINI case. 1.4.2 Emulab 1.4.3 Network Simulation Cradle 1.4.4 Large scale simulations (include Nick Weaver comments here) 5 Chapter 2 Technical Overview 2.1 Basics ns-3 is a user-space program that runs on Unix- and Linux-based systems and on Windows (build process, via Cygwin or via native win32 APIs, is to be determined). It contains support for the following: • construction of virtual networks (nodes, channels, applications) and supportfor items such as eventschedulers, topology generators, timers, and the like to support discrete-event network simulation focused on Internet-based and possibly other packet network systems. • support for network emulation; the ability for simulator processes to emit and consume real network packets • distributed simulation support; the ability for simulations to be distributed across multiple processors or machines • support for animation of network simulations • support for tracing, logging, and computing statistics on the simulation output ns-3 is written in C++, with a planned Python scripting interface(s) for users. Contributors are expected to conform to the project coding style, licensing, and copyright requirements (licensing and copy- right requirements described in the project plan document). 6 Node App ... App Unix-like APIs (sockets, netfilter, pfkey, etc.) Stack