Proper documentation pages:

- README is no longer the used documentation - Instead the README is split to different pages. For now this is basically all the documentation we have. - Added chapter on MoonGens Packet API. Once again, this is only a first draft that contains the most important stuff. - Added DoxygenLayout file: still buggy but at least somehow what i wanted TODO - Fix the DoxygenLayout (mainly the 'tabs' at the top of the site and the navtree) - Write better documentation for all the parts
emmericp · Jun 22, 2015 · 8a1b24d · 8a1b24d
1 parent b6b7c81
commit 8a1b24d
Show file tree

Hide file tree

Showing 13 changed files with 507 additions and 3 deletions.
diff --git a/Doxyfile b/Doxyfile
@@ -661,7 +661,7 @@ FILE_VERSION_FILTER    =
 # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
 # tag is left empty.
 
-LAYOUT_FILE            =
+LAYOUT_FILE            = doc/DoxygenLayout.xml
 
 # The CITE_BIB_FILES tag can be used to specify one or more bib files containing
 # the reference definitions. This must be a list of .bib files. The .bib
@@ -744,7 +744,6 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.
 
 INPUT                  = lua/include/ \
-                         README.md \
                          doc/ \
 
 # This tag can be used to specify the character encoding of the source files

diff --git a/README.md b/README.md
@@ -1,4 +1,3 @@
-\mainpage
 ### TL;DR
 LuaJIT + DPDK = fast and flexible packet generator for 10 GBit Ethernet and beyond.
 

diff --git a/doc/DoxygenLayout.xml b/doc/DoxygenLayout.xml
@@ -0,0 +1,196 @@
+<doxygenlayout version="1.0">
+  <!-- Generated by doxygen 1.8.6 -->
+  <!-- Navigation index tabs for HTML output -->
+  <navindex>
+    <tab type="mainpage" visible="yes" title="Home"/>
+    <tab type="user" url="@ref download" visible="yes" title="Download"/>
+    <tab type="user" url="@ref documentation" visible="yes" title="Documentation"/>
+    <tab type="pages" visible="no" title="" intro=""/>
+    <tab type="modules" visible="yes" title="" intro=""/>
+    <tab type="namespaces" visible="yes" title="">
+      <tab type="namespacelist" visible="yes" title="" intro=""/>
+      <tab type="namespacemembers" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="classes" visible="yes" title="">
+      <tab type="classlist" visible="yes" title="" intro=""/>
+      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> 
+      <tab type="hierarchy" visible="yes" title="" intro=""/>
+      <tab type="classmembers" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="files" visible="yes" title="Filebrowser">
+      <tab type="filelist" visible="no" title="" intro=""/>
+      <tab type="globals" visible="no" title="" intro=""/>
+    </tab>
+    <tab type="examples" visible="yes" title="" intro=""/>  
+  </navindex>
+
+  <!-- Layout definition for a class page -->
+  <class>
+    <briefdescription visible="yes"/>
+    <includes visible="$SHOW_INCLUDE_FILES"/>
+    <inheritancegraph visible="$CLASS_GRAPH"/>
+    <collaborationgraph visible="$COLLABORATION_GRAPH"/>
+    <memberdecl>
+      <nestedclasses visible="yes" title=""/>
+      <publictypes title=""/>
+      <services title=""/>
+      <interfaces title=""/>
+      <publicslots title=""/>
+      <signals title=""/>
+      <publicmethods title=""/>
+      <publicstaticmethods title=""/>
+      <publicattributes title=""/>
+      <publicstaticattributes title=""/>
+      <protectedtypes title=""/>
+      <protectedslots title=""/>
+      <protectedmethods title=""/>
+      <protectedstaticmethods title=""/>
+      <protectedattributes title=""/>
+      <protectedstaticattributes title=""/>
+      <packagetypes title=""/>
+      <packagemethods title=""/>
+      <packagestaticmethods title=""/>
+      <packageattributes title=""/>
+      <packagestaticattributes title=""/>
+      <properties title=""/>
+      <events title=""/>
+      <privatetypes title=""/>
+      <privateslots title=""/>
+      <privatemethods title=""/>
+      <privatestaticmethods title=""/>
+      <privateattributes title=""/>
+      <privatestaticattributes title=""/>
+      <friends title=""/>
+      <related title="" subtitle=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <inlineclasses title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <services title=""/>
+      <interfaces title=""/>
+      <constructors title=""/>
+      <functions title=""/>
+      <related title=""/>
+      <variables title=""/>
+      <properties title=""/>
+      <events title=""/>
+    </memberdef>
+    <allmemberslink visible="yes"/>
+    <usedfiles visible="$SHOW_USED_FILES"/>
+    <authorsection visible="yes"/>
+  </class>
+
+  <!-- Layout definition for a namespace page -->
+  <namespace>
+    <briefdescription visible="yes"/>
+    <memberdecl>
+      <nestednamespaces visible="yes" title=""/>
+      <constantgroups visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <inlineclasses title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+    </memberdef>
+    <authorsection visible="yes"/>
+  </namespace>
+
+  <!-- Layout definition for a file page -->
+  <file>
+    <briefdescription visible="yes"/>
+    <includes visible="$SHOW_INCLUDE_FILES"/>
+    <includegraph visible="$INCLUDE_GRAPH"/>
+    <includedbygraph visible="$INCLUDED_BY_GRAPH"/>
+    <sourcelink visible="yes"/>
+    <memberdecl>
+      <classes visible="yes" title=""/>
+      <namespaces visible="yes" title=""/>
+      <constantgroups visible="yes" title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <inlineclasses title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+    </memberdef>
+    <authorsection/>
+  </file>
+
+  <!-- Layout definition for a group page -->
+  <group>
+    <briefdescription visible="yes"/>
+    <groupgraph visible="$GROUP_GRAPHS"/>
+    <memberdecl>
+      <nestedgroups visible="yes" title=""/>
+      <dirs visible="yes" title=""/>
+      <files visible="yes" title=""/>
+      <namespaces visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <enumvalues title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <signals title=""/>
+      <publicslots title=""/>
+      <protectedslots title=""/>
+      <privateslots title=""/>
+      <events title=""/>
+      <properties title=""/>
+      <friends title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <pagedocs/>
+      <inlineclasses title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <enumvalues title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <signals title=""/>
+      <publicslots title=""/>
+      <protectedslots title=""/>
+      <privateslots title=""/>
+      <events title=""/>
+      <properties title=""/>
+      <friends title=""/>
+    </memberdef>
+    <authorsection visible="yes"/>
+  </group>
+
+  <!-- Layout definition for a directory page -->
+  <directory>
+    <briefdescription visible="yes"/>
+    <directorygraph visible="yes"/>
+    <memberdecl>
+      <dirs visible="yes"/>
+      <files visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+  </directory>
+</doxygenlayout>
diff --git a/doc/architecture.md b/doc/architecture.md
@@ -0,0 +1,17 @@
+\page architecture Architecture
+\tableofcontents
+
+
+MoonGen is basically a Lua wrapper around DPDK with utility functions for packet generation. Users write custom scripts for their experiments. It is recommended to make use of hard-coded setup-specific constants in your scripts. The script is the configuration, it is beside the point to write a complicated configuration interface for a script.
+
+The following diagram shows the architecture and how multi-core support is handled.
+
+<p align="center">
+<img alt="Architecture" src="https://raw.githubusercontent.com/emmericp/MoonGen/master/doc/img/moongen-architecture.png" srcset="https://raw.githubusercontent.com/emmericp/MoonGen/master/doc/img/moongen-architecture.png 1x, https://raw.githubusercontent.com/emmericp/MoonGen/master/doc/img/moongen-architecture@2x.png 2x"/>
+</p>
+
+Execution begins in the master task that must be defined in the user's script. This task configures queues and filters on the used NICs and then starts one or more slave tasks.
+
+Note that Lua does not have any native support for multi threading. MoonGen therefore starts a new and completely independent LuaJIT VM for each thread. The new VMs receive serialized arguments: the function to execute and arguments like the queue to send packets from. Threads only share state through the underlying library.
+
+The example script quality-of-service-test.lua shows how this threading model can be used to implement a typical load generation task. It implements a QoS test by sending two different types of packets and measures their throughput and latency. It does so by starting two packet generation tasks: one for the background traffic and one for the prioritized traffic. A third task is used to categorize and count the incoming packets.
diff --git a/doc/documentation.md b/doc/documentation.md
@@ -0,0 +1,21 @@
+\page documentation MoonGen Manual
+Overview
+========
+
+Manual
+------
+- Section \subpage install explains how to download, compile and install MoonGen. 
+- Section \subpage architecture 
+- Section \subpage packet_api explains how to work with packets in MoonGen.
+- Section \subpage timestamping
+- Section \subpage rate_control
+- Section \subpage faq
+
+
+
+References
+----------
+- Section Filebrowser. You can find the filebrowser containing all autogenerated documentation from source files as tab "Filebrowser" at the top of this page. <!--- obviously this should be a link to files.html, but i was not able to get it to work yet-->
+- Section \subpage todo 
+- Section \subpage deprecated
+- Section \subpage examples
diff --git a/doc/download.md b/doc/download.md
@@ -0,0 +1,15 @@
+\page download Downloads
+\tableofcontents
+GIT repository
+==============
+Currently the source files of MoonGen are only available on [GIT](https://github.com/emmericp/MoonGen):
+
+        git clone https://github.com/emmericp/MoonGen.git
+
+Installation
+------------
+See \ref install for instructions on how to install MoonGen.
+
+Download Manual
+==============
+The manual is not yet available as standalone document.
diff --git a/doc/examples.md b/doc/examples.md
@@ -0,0 +1,8 @@
+\page examples Example User-Scripts
+\tableofcontents
+
+Following is a list of example scripts:
+\example quality-of-service-test.lua
+\example l3-tcp-syn-flood.lua
+\example l2-poisson-load-latency.lua
+\example timestamps.lua
diff --git a/doc/faq.md b/doc/faq.md
@@ -0,0 +1,29 @@
+\page faq Frequently Asked Questions
+\tableofcontents
+
+### Which NICs do you support?
+Basic functionality is available on all [NICs supported by DPDK](http://dpdk.org/doc/nics).
+Hardware timestamping is currently supported and tested on Intel 82599, X540 and 82580 chips.
+Hardware rate control is supported and tested on Intel 82599 and X540 chips.
+
+
+### How is MoonGen different from SnabbSwitch?
+[SnabbSwitch](https://github.com/SnabbCo/snabbswitch) is a framework for packet-processing in Lua. 
+There are a few important differences:
+
+* MoonGen comes with explicit multi-core support in its API, SnabbSwitch does not
+* MoonGen focuses on efficient packet generation, SnabbSwitch is a more generic framework
+* Our API is designed for packet-generation tasks, i.e. writing a packet generator script for MoonGen is a lot easier than writing one for SnabbSwitch
+* We implement driver-like functionality for hardware functions required by packet generators: timestamping, rate control, and packet filtering
+* SnabbSwitch reimplements the NIC driver in Lua, we rely on the DPDK driver for most parts
+
+
+### Why does MoonGen use DPDK instead of SnabbSwitch as driver?
+We decided for DPDK as back end for the following reasons:
+
+* DPDK is faster for raw packet IO. This is not really a drawback for the use cases SnabbSwitch is designed for where IO is only a small part of the processing. However, for packet generation, especially with small packets, the share of packet IO is significant and the performance of SnabbSwitch is not sufficient here.
+* DPDK provides a stable and mature code base whereas SnabbSwitch is a relatively young project.
+* DPDK currently supports more NICs (with stable and mature drivers) than SnabbSwitch. (We do not want to write our own drivers or debug existing ones.)
+* Lack of multi-core support. (Only possible by starting SnabbSwitch more than once.)
+
+Note that this might change. Using DPDK also comes with disadvantages like its bloated build system and configuration.
diff --git a/doc/index.md b/doc/index.md
@@ -0,0 +1,28 @@
+\mainpage
+\tableofcontents
+# MoonGen Packet Generator
+
+MoonGen is a high-speed scriptable packet generator.
+The whole load generator is controlled by a Lua script: all packets that are sent are crafted by a user-provided script.
+Thanks to the incredibly fast LuaJIT VM and the packet processing library DPDK, it can saturate a 10 GBit Ethernet link with 64 Byte packets while using only a single CPU core.
+MoonGen can achieve this rate even if each packet is modified by a Lua script. It does not rely on tricks like replaying the same buffer.
+
+MoonGen can also receive packets, e.g. to check which packets are dropped by a
+system under test. As the reception is also fully under control of the user's
+Lua script, it can be used to implement advanced test scripts. E.g. one can use
+two instances of MoonGen that establish a connection with each other. This
+setup can be used to benchmark middle-boxes like firewalls.
+
+Reading the example script [quality-of-service-test.lua](https://github.com/emmericp/MoonGen/blob/master/examples/quality-of-service-test.lua) is a good way to learn more about our scripting API as this script uses most features of MoonGen.
+
+MoonGen focuses on four main points:
+
+* High performance and multi-core scaling: > 15 million packets per second per CPU core
+* Flexibility: Each packet is crafted in real time by a user-provided Lua script
+* Precise and accurate timestamping: Timestamping with sub-microsecond precision on commodity hardware
+* Precise and accurate rate control: Reliable generation of arbitrary traffic patterns on commodity hardware
+
+You can have a look at [our slides from a recent talk](https://raw.githubusercontent.com/emmericp/MoonGen/master/doc/Slides.pdf) or read a draft of [our paper](http://arxiv.org/ftp/arxiv/papers/1410/1410.3322.pdf) [1] for a more detailed discussion of MoonGen's internals.
+
+
+
diff --git a/doc/install.md b/doc/install.md
@@ -0,0 +1,20 @@
+\page install Installation
+\tableofcontents
+
+Download MoonGen as instructed on the \ref download page.
+
+\section installation Installation
+1. Install the dependencies (see \ref dependencies)
+2. git submodule update --init
+3. ./build.sh
+4. ./setup-hugetlbfs.sh
+5. Run MoonGen from the build directory
+
+Note: You can also use the script bind-interfaces.sh to bind all currently unused NICs (no routing table entry in the system) to DPDK/MoonGen. build.sh calls this script automatically. Use deps/dpdk/tools/dpdk_nic_bind.py to unbind NICs from the DPDK driver.
+
+\section dependencies Dependencies
+
+- gcc
+- make
+- cmake
+- kernel headers (for the DPDK igb-uio driver)