From 35396134941edb726769112d256609358ca00486 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Sat, 26 Sep 2020 23:43:37 +0200 Subject: [PATCH] improve the wifi ns-3 documentation a bit --- docs/source/ns3.rst | 191 +++++++++++++++++++------------------------- 1 file changed, 81 insertions(+), 110 deletions(-) diff --git a/docs/source/ns3.rst b/docs/source/ns3.rst index 3a20e28aaa..e99ff475b5 100644 --- a/docs/source/ns3.rst +++ b/docs/source/ns3.rst @@ -8,6 +8,13 @@ You can use the well-known `ns-3 packet-level network simulator validity of your simulation. Just install ns-3 and recompile SimGrid accordingly. +The SimGrid/ns-3 binding only contains features that are common to both systems. +Not all ns-3 models are available from SimGrid (only the TCP and WiFi ones are), +while not all SimGrid platform files can be used in conjunction ns-3 (routes +must be of length 1). Also, the platform built in ns-3 from the SimGrid +description is very basic. + + Compiling the ns-3/SimGrid binding ********************************** @@ -37,7 +44,9 @@ If your local copy defines the variable ``SIMGRID_HAVE_NS3`` to 1, then ns-3 was correctly detected. Otherwise, explore ``CMakeFiles/CMakeOutput.log`` and ``CMakeFiles/CMakeError.log`` to diagnose the problem. -Test your installation after compilation as follows: +Test that ns-3 was successfully integrated with the following (from your SimGrid +build directory). It will run all SimGrid tests that are related to the ns-3 +integration. If no test is run at all, you probably forgot to enable ns-3 in cmake. .. code-block:: shell @@ -56,12 +65,6 @@ version of either SimGrid or ns-3, try upgrading everything. Using ns-3 from SimGrid *********************** -The SimGrid/ns-3 binding only contains features that are common to -both systems. Not all ns-3 models are available (only the TCP and wifi -ones are), while not all SimGrid platform file can be used with ns-3 -(routes must be of length 1). Also, the platform built in ns-3 from -the SimGrid description is very basic. - Platform files compatibility ============================ @@ -70,7 +73,7 @@ harmless, but you still need to connect your hosts using one-hop routes. The best solution is to add routers to split your route. Here is an example of an invalid platform: -.. code-block:: shell +.. code-block:: xml @@ -83,17 +86,18 @@ example of an invalid platform: - - + + This can be reformulated as follows to make it usable with the ns-3 binding. -There is no direct connection from alice to bob, but that's OK because -ns-3 automatically routes from point to point. +There is no direct connection from alice to bob, but that's OK because ns-3 +automatically routes from point to point (using +``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``). -.. code-block:: shell +.. code-block:: xml @@ -118,8 +122,8 @@ ns-3 automatically routes from point to point. Once your platform is OK, just change the :ref:`network/model -`_ configuration option to "ns-3" as follows. The rest -is unchanged. +` configuration option to `ns-3` as follows. The other +options can be used as usual. .. code-block:: shell @@ -130,112 +134,77 @@ ns-3 model, such as `examples/platforms/dogbone.xml `_ to see which ones are used in our regression tests. -Build a wifi-compatible platform -=================================== - -We describe here a simple platform allowing ns3 wifi communication -between two SimGrid hosts. - -First, here are the mandatory information necessary to create a -simgrid platform: - -.. code-block:: shell - - - - - +WiFi platforms +-------------- -Then, we create our access point and station hosts: +In SimGrid, WiFi networks are modeled as regular links with a specific +attribute, and these links are then added to routes between hosts. The main +difference When using ns-3 WiFi networks is that the network performance is not +given by the link bandwidth and latency but by the access point WiFi +characteristics, and the distance between the access point and the hosts (called +station in the WiFi world). -.. code-block:: shell +So, to declare a new WiFi network, simply declare a link with the ``WiFi`` +sharing policy as you would do in a pure SimGrid simulation (you must still +provide the ``bandwidth`` and ``latency`` attributes even if they are ignored, +because they are mandatory to the SimGrid XML parser). - - +.. code-block:: xml -We must specify that alice will be our access point. To do that we -simply add the property ``wifi_link`` to the host ``alice``: + -.. code-block:: shell +To declare that a given host is connected to this WiFi zone, use the +``wifi_link`` property of that host. The property value must be the link id that +you want to use as a WiFi zone. This is not needed when using pure SimGrid wifi, +only when using ns-3 wifi, because the wifi performance is :ref:`configured `. - - - +.. code-block:: xml - + + + -The value ``net0`` of this property defines the name of the wifi network -generated. To generate this wifi network we create a wifi link: +To connect the station node to the access point node, simply create a route +between them: -.. code-block:: shell +.. code-block:: xml - + + + -The important information here are: - * The id of the link, ``net0``, must match the network name defined by the property ``wifi_link`` of the access point node - * The sharing policy must be set to ``WIFI`` +.. _ns3_wifi_perf: -Note: bandwidth and latency are mandatory by simgrid to create a link but are NOT used to create a wifi network. Instead the -wifi network capabilities are defined by its MCS, NSS and distance from access point to station. Those properties are described in section :ref:`Optional access point node properties `_ +WiFi network performance +^^^^^^^^^^^^^^^^^^^^^^^^ -To connect the station node to the access point node, we -create a route between the hosts: -.. code-block:: shell - - - - - -Finally, we end the xml file with the missing closing tags: - -.. code-block:: shell +The performance of a wifi network is controlled by 3 property that can be added +to the an host connected to the wifi zone: - - + * ``wifi_mcs`` (`Modulation and Coding Scheme `_) + Roughly speaking, it defines the speed at which the access point is + exchanging data with all stations. It depends on its model and configuration, + and the possible values are listed for example on Wikipedia. + |br| By default, ``wifi_mcs=3``. + * ``wifi_nss`` (Number of Spatial Streams, or `number of antennas `_) + defines the amount of simultaneous data streams that the AP can sustain. + Not all value of MCS and NSS are valid nor compatible (cf. `802.11n standard `_). + |br| By default, ``wifi_nss=1``. + * ``wifi_distance`` is the distance from the station to the access point. Each + station can have a specific value. + |br| By default, ``wifi_distance=10``. -.. _optional_prop: +Here is an example of host changing all these values: -Optional access point node properties --------------------------------------- +.. code-block:: xml -The MCS (`Modulation and Coding Scheme `_) can be set with the property ``wifi_mcs``: - -.. code-block:: shell - - - - - - -Its default value is 3. - -The NSS (Number of Spatial Streams, also known as the `number of antennas `_) can be set with the property ``wifi_nss``: - -.. code-block:: shell - - - - - - -Its default value is 1. - -Note: not all value of MCS and NSS are valid nor compatible. Check `802.11n standard `_ for more information. - -Optional station node properties ---------------------------------- - -The distance in meter at which the station is placed from the access point can -be set with the property ``wifi_distance``. - -.. code-block:: shell - - - - - -Its default value is 10. + + + + + + Limitations =========== @@ -243,13 +212,11 @@ Limitations A ns-3 platform is automatically created from the provided SimGrid platform. However, there are some known caveats: - * The default values (e.g., TCP parameters) are the ns-3 default values. - * ns-3 networks are routed using the shortest path algorithm, using - ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``. - * End hosts cannot have more than one interface card. So, your - SimGrid hosts should be connected to the platform through only - one link. Otherwise, your SimGrid host will be considered as a - router (FIXME: is it still true?). + * The default values (e.g., TCP parameters) are the ns-3 default values. + * ns-3 networks are routed using the shortest path algorithm, using ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``. + * End hosts cannot have more than one interface card. So, your SimGrid hosts + should be connected to the platform through only one link. Otherwise, your + SimGrid host will be considered as a router (FIXME: is it still true?). Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully readable) as possible. If the current state does not fit your needs, you should modify @@ -264,3 +231,7 @@ is sending data that is not routable in your platform. Make sure that you only use routes of length 1, and that any host is connected to the platform. Arguably, SimGrid could detect this situation and report it, but unfortunately, this is still to be done. + +.. |br| raw:: html + +
-- 2.20.1