DTD Reference
*************
-Your platform description should follow the specification presented in
-the `simgrid.dtd <https://simgrid.org/simgrid.dtd>`_
-DTD file. The same DTD is used for both the platform and deployment
-files.
+Your platform description should follow the specification presented in the
+`simgrid.dtd <https://simgrid.org/simgrid.dtd>`_ DTD file. The same DTD is used for both platform and deployment files.
.. _pf_tag_config:
<config>
------------------------------------------------------------------
-Adding configuration flags into the platform file is particularly
-useful when the described platform is best used with specific
-flags. For example, you could finely tune SMPI in your platform file
-directly. Almost all :ref:`command-line configuration items <options_list>`
-can be configured this way.
+Adding configuration flags directly into the platform file becomes particularly useful when the realism of the described
+platform depends on some specific flags. For example, this could help you to finely tune SMPI. Almost all
+:ref:`command-line configuration items <options_list>` can be configured this way.
+
+Each configuration flag is described as a :ref:`pf_tag_prop` whose 'id' is the name of the flag and 'value' is what it
+has to be set to.
**Parent tags:** :ref:`pf_tag_platform` (must appear before any other tags) |br|
**Children tags:** :ref:`pf_tag_prop` |br|
.. code-block:: xml
- <?xml version='1.0'?>
+ <?xml version = '1.0'?>
<!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
- <platform version="4.1">
- <config>
- <prop id="maxmin/precision" value="0.000010" />
- <prop id="cpu/optim" value="TI" />
- <prop id="network/model" value="SMPI" />
- <prop id="smpi/bw-factor" value="65472:0.940694;15424:0.697866;9376:0.58729" />
- </config>
-
- <!-- The rest of your platform -->
+ <platform version = "4.1">
+ <config>
+ <prop id = "maxmin/precision" value = "0.000010" />
+ <prop id = "cpu/optim" value = "TI" />
+ <prop id = "network/model" value = "SMPI" />
+ <prop id = "smpi/bw-factor" value = "65472:0.940694;15424:0.697866;9376:0.58729" />
+ </config>
+
+ <!-- The rest of your platform -->
</platform>
-
+|hr|
+
.. _pf_tag_host:
------------------------------------------------------------------
<host>
------------------------------------------------------------------
-An host is the computing resource on which an actor can execute. See :cpp:class:`simgrid::s4u::Host`.
+A host is the computing resource on which an actor can run. See :cpp:class:`simgrid::s4u::Host`.
-**Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e. zones containing no inner zones nor clusters) |br|
-**Children tags:** :ref:`pf_tag_prop`, :ref:`pf_tag_storage` |br|
+**Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e., zones containing neither inner zones nor clusters) |br|
+**Children tags:** :ref:`pf_tag_mount`, :ref:`pf_tag_prop`, :ref:`pf_tag_storage` |br|
**Attributes:**
:``id``: Host name.
1 0.5
2 0.2
5 1
- LOOPAFTER 8
+ LOOPAFTER 5
- - At time t=1, half of its power is taken by some background
- computations, so only 50% of its initial power remains available
- (0.5 means 50%).
- - At time t=2, the available power drops at 20% of the total.
- - At time t=5, the host computes back at full speed.
- - At time t=10, the history is reset (because that's 5 seconds after
- the last event). So the available speed will drop at t=11.
+ - At time t = 1, half of the host computational power (0.5 means 50%) is used to process some background load, hence
+ only 50% of this initial power remains available to your own simulation.
+ - At time t = 2, the available power drops at 20% of the initial value.
+ - At time t = 5, the host can compute at full speed again.
+ - At time t = 10, the profile is reset (as we are 5 seconds after the last event). Then the available speed will drop
+ again to 50% at time t = 11.
- If your trace does not contain a LOOPAFTER line, then your profile
- is only executed once and not repetitively.
+ If your profile does not contain any LOOPAFTER line, then it will be executed only once and not in a repetitive way.
- .. warning:: Don't get fooled: Bandwidth and Latency profiles of a
- :ref:`pf_tag_link` are absolute values, but Availability
- profiles of :ref:`pf_tag_host` are ratio.
+ .. warning:: Don't get fooled: Bandwidth and Latency profiles of a :ref:`pf_tag_link` contain absolute values, while
+ Availability profiles of a :ref:`pf_tag_host` contain ratios.
:``state_file``: File containing the state profile.
Almost every lines of such files describe timed events as ``date boolean``.
Example:
.. code-block:: python
-
+
1 0
2 1
LOOPAFTER 8
- - At time t=1, the host is turned off (value 0 means OFF)
- - At time t=2, it is turned back on (other values means ON)
- - At time t=10, the history is reset (because that's 8 seconds after
- the last event). So the host will be turned off again at t=11.
+ - At time t = 1, the host is turned off (a zero value means OFF)
+ - At time t = 2, the host is turned back on (any other value than zero means ON)
+ - At time t = 10, the profile is reset (as we are 8 seconds after the last event). Then the host will be turned off
+ again at time t = 11.
- If your trace does not contain a LOOPAFTER line, then your profile
- is only executed once and not repetitively.
+ If your profile does not contain any LOOPAFTER line, then it will be executed only once and not in a repetitive way.
-:``coordinates``: Vivaldi coordinates (Vivaldi zones only).
+:``coordinates``: Vivaldi coordinates (meaningful for Vivaldi zones only).
See :ref:`pf_tag_peer`.
:``pstate``: Initial pstate (default: 0, the first one).
See :ref:`howto_dvfs`.
+|hr|
+
.. _pf_tag_link:
------------------------------------------------------------------
<link>
------------------------------------------------------------------
-Network links can represent one-hop network connections. See :cpp:class:`simgrid::s4u::Link`.
+SimGrid links usually represent one-hop network connections (see :cpp:class:`simgrid::s4u::Link`), i.e., a single wire.
+They can also be used to abstract a larger network interconnect, e.g., the entire transcontinental network, into a
+single element.
**Parent tags:** :ref:`pf_tag_zone` (both leaf zones and inner zones) |br|
**Children tags:** :ref:`pf_tag_prop` |br|
**Attributes:**
:``id``: Link name. Must be unique over the whole platform.
-:``bandwidth``: Maximum bandwidth for this link. You must specify the
- unit as follows.
+:``bandwidth``: Maximum bandwidth for this link. You must specify a unit as follows.
- **Units in bytes and powers of 2** (1 KiBps = 1024 Bps):
- Bps, KiBps, MiBps, GiBps, TiBps, PiBps, EiBps |br|
+ **Units in bytes and powers of 2** (1 KiBps = 1,024 Bps):
+ Bps, KiBps, MiBps, GiBps, TiBps, PiBps, or EiBps. |br|
**Units in bits and powers of 2** (1 Bps = 8 bps):
- bps, Kibps, Mibps, Gibps, Tibps, Pibps, Eibps |br|
- **Units in bytes and powers of 10:** (1 KBps = 1000 Bps)
- Bps, KBps, MBps, GBps, TBps, PBps, EBps |br|
+ bps, Kibps, Mibps, Gibps, Tibps, Pibps, or Eibps. |br|
+ **Units in bytes and powers of 10** (1 KBps = 1,000 Bps):
+ Bps, KBps, MBps, GBps, TBps, PBps, or EBps. |br|
**Units in bits and powers of 10:**
- 'Ebps', 'Pbps', 'Tbps', 'Gbps', 'Mbps', 'kbps', 'bps'
+ bps, Kbps, Mbps, Gbps, Tbps, Pbps, or Ebps.
-:``latency``: Latency for this link (default: 0.0). You must specify
- the unit as follows.
+:``latency``: Latency for this link (default: 0.0). You must specify a unit as follows.
==== =========== ======================
Unit Meaning Duration in seconds
d day 60 * 60 * 24
w week 60 * 60 * 24 * 7
==== =========== ======================
-
-
-:``sharing_policy``: Sharing policy for the link.
- Either ``SHARED``, ``FATPIPE`` or ``SPLITDUPLEX`` (default: ``SHARED``).
- If set to ``SHARED``, the available bandwidth is shared fairly
- between all flows traversing this link. This tend to model the
- sharing behavior of UDP or TCP.
+:``sharing_policy``: Sharing policy for the link. Possible values are ``SHARED``, ``FATPIPE`` or ``SPLITDUPLEX``
+ (default: ``SHARED``).
+
+ If set to ``SHARED``, the available bandwidth is fairly shared among all the flows traversing this link. This tend to
+ model the bandwidth sharing behavior of the UDP or TCP protocols.
- If set to ``FATPIPE``, the flows have no mutual impact, and each
- flow can obtain the full bandwidth of this link. This is intended
- to model the internet backbones that cannot get saturated by your
- application: you mostly experience their latency.
+ If set to ``FATPIPE``, flows have no impact on each other, hence each flow can exploit the full bandwidth of this
+ link. This aims at modeling the behavior of the Internet backbones that cannot get saturated by your application.
+ What you experience of such networks usually is their latency only.
If set to ``SPLITDUPLEX``, the link models cross-traffic
effects. Under the ``SHARED`` policy, two flows of reverse
direction share the same resource, and can only get half of the
bandwidth each. But TCP connections are full duplex, meaning that
- all both directions can get the full bandwidth. To model this, any
- link under the ``SPLITDUPLEX`` policy is split in two links (their
- names are suffixed with "_UP" and "_DOWN"). You must then specify
+ both directions can get the full bandwidth. To model this, any
+ link under the ``SPLITDUPLEX`` policy is split in two links (whose
+ names are suffixed with "_UP" and "_DOWN"). Then you must specify
which direction gets actually used when referring to that link in a
:ref:`pf_tag_link_ctn`.
8.0 60000000
LOOPAFTER 12.0
- - At time t=4, the bandwidth is of 40 MBps.
- - At time t=8, it raises to 60MBps.
- - At time t=24, it drops at 40 MBps again.
+ - At time t = 4, the bandwidth is of 40 MBps.
+ - At time t = 8, it raises to 60MBps.
+ - At time t = 24, it drops at 40 MBps again.
+
+ .. warning:: Don't get fooled: Bandwidth and Latency profiles of a :ref:`pf_tag_link` contain absolute values, while
+ Availability profiles of a :ref:`pf_tag_host` contain ratios.
- .. warning:: Don't get fooled: Bandwidth and Latency profiles of a
- :ref:`pf_tag_link` are absolute values, but Availability
- profiles of :ref:`pf_tag_host` are ratio.
:``latency_file``: File containing the latency profile.
Almost every lines of such files describe timed events as ``date
latency`` (in seconds).
3.0 0.1
LOOPAFTER 5.0
- - At time t=1, the latency is of 1ms (0.001 second)
- - At time t=3, the latency is of 100ms (0.1 second)
- - At time t=8 (5 seconds after the last event), the profile loops.
- - At time t=9 (1 second after the loop reset), the latency is back at 1ms.
-
- If your trace does not contain a LOOPAFTER line, then your profile
- is only executed once and not repetitively.
-
- .. warning:: Don't get fooled: Bandwidth and Latency profiles of a
- :ref:`pf_tag_link` are absolute values, but Availability
- profiles of :ref:`pf_tag_host` are ratio.
+ - At time t = 1, the latency is of 1ms (0.001 second)
+ - At time t = 3, the latency is of 100ms (0.1 second)
+ - At time t = 8 (5 seconds after the last event), the profile loops.
+ - At time t = 9 (1 second after the loop reset), the latency is back at 1ms.
+
+ If your profile does not contain any LOOPAFTER line, then it will be executed only once and not in a repetitive way.
+
+ .. warning:: Don't get fooled: Bandwidth and Latency profiles of a :ref:`pf_tag_link` contain absolute values, while
+ Availability profiles of a :ref:`pf_tag_host` contain ratios.
+
:``state_file``: File containing the state profile. See :ref:`pf_tag_host`.
-
+
+|hr|
+
+.. _pf_tag_link_ctn:
+
+------------------------------------------------------------------
+<link_ctn>
+------------------------------------------------------------------
+
+An element in a route, representing a previously defined link.
+
+**Parent tags:** :ref:`pf_tag_route` |br|
+**Children tags:** none |br|
+**Attributes:**
+
+:``id``: Link that is to be included in this route.
+:``direction``: Whether to use the uplink (with ``UP``) or downlink
+ (with ``DOWN``) of the link. This is only valid if the
+ link has ``sharing=SPLITDUPLEX``.
+
+|hr|
+
.. _pf_tag_peer:
------------------------------------------------------------------
This tag represents a peer, as in Peer-to-Peer (P2P) networks. It is
handy to model situations where hosts have an asymmetric
-connectivity. Computers connected through set-to-boxes usually have a
+connectivity. Computers connected through set-top-boxes usually have a
much better download rate than their upload rate. To model this,
<peer> creates and connects several elements: an host, an upload link
and a download link.
:``lat``: Latency of both private links. See :ref:`pf_tag_link`.
:``coordinates``: Coordinates of the gateway for this peer.
- The communication latency between an host A=(xA,yA,zA) and an host
- B=(xB,yB,zB) is computed as follows:
+ The communication latency between a host A = (xA,yA,zA) and a host B = (xB,yB,zB) is computed as follows:
latency = sqrt( (xA-xB)² + (yA-yB)² ) + zA + zB
See the documentation of
:cpp:class:`simgrid::kernel::routing::VivaldiZone` for details on
- how the latency is computed from the coordinate, and on the the up
+ how the latency is computed from the coordinates, and on how the up
and down bandwidth are used.
:``availability_file``: File containing the availability profile.
See the full description in :ref:`pf_tag_host`
:``state_file``: File containing the state profile.
See the full description in :ref:`pf_tag_host`
+|hr|
-
+.. _pf_tag_platform:
+
+------------------------------------------------------------------
+<platform>
+------------------------------------------------------------------
+
+**Parent tags:** none (this is the root tag of every file) |br|
+**Children tags:** :ref:`pf_tag_config` (must come first),
+:ref:`pf_tag_cluster`, :ref:`pf_tag_cabinet`, :ref:`pf_tag_peer`,
+:ref:`pf_tag_zone`, :ref:`pf_tag_trace`, :ref:`pf_tag_trace_connect` |br|
+**Attributes:**
+
+:``version``: Version of the DTD, describing the whole XML format.
+ This versionning allow future evolutions, even if we
+ avoid backward-incompatible changes. The current version
+ is **4.1**. The ``simgrid_update_xml`` program can
+ upgrade most of the past platform files to the most recent
+ formalism.
+
+|hr|
+
.. _pf_tag_prop:
------------------------------------------------------------------
:``id``: Name of the defined property.
:``value``: Value of the defined property.
+|hr|
+
+.. _pf_tag_route:
+
+------------------------------------------------------------------
+<route>
+------------------------------------------------------------------
+
+A path between two network locations, composed of several :ref:`pf_tag_link`s.
+
+**Parent tags:** :ref:`pf_tag_zone` |br|
+**Children tags:** :ref:`pf_tag_link_ctn` |br|
+**Attributes:**
+
+:``src``: Host from which this route starts. Must be an existing host.
+:``dst``: Host to which this route leads. Must be an existing host.
+:``symmetrical``: Whether this route is symmetrical, ie, whether we
+ are defining the route ``dst -> src`` at the same
+ time. Valid values: ``yes``, ``no``,``YES``, ``NO``.
+
+|hr|
+
.. _pf_tag_router:
------------------------------------------------------------------
<router>
------------------------------------------------------------------
-A router is similar to an :ref:`pf_tag_host`, but it cannot contain
+A router is similar to a :ref:`pf_tag_host`, but it cannot contain
any actor. It is only useful to some routing algorithms. In
particular, they are useful when you want to use the NS3 bindings to
break the routes that are longer than 1 hop.
-**Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e. zones containing no inner zones nor clusters) |br|
+**Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e., zones containing neither inner zones nor clusters) |br|
**Children tags:** :ref:`pf_tag_prop`, :ref:`pf_tag_storage` |br|
**Attributes:**
No other host or router may have the same name over the whole platform.
:``coordinates``: Vivaldi coordinates. See :ref:`pf_tag_peer`.
+|hr|
+
+.. _pf_tag_zone:
+
+------------------------------------------------------------------
+<zone>
+------------------------------------------------------------------
+
+A networking zone is an area in which elements are located. See :cpp:class:`simgrid::s4u::Zone`.
+
+**Parent tags:** :ref:`pf_tag_platform`, :ref:`pf_tag_zone` (only internal nodes, i.e., zones
+containing only inner zones or clusters but no basic
+elements such as host or peer) |br|
+**Children tags (if internal zone):** :ref:`pf_tag_cluster`, :ref:`pf_tag_link`, :ref:`pf_tag_zone` |br|
+**Children tags (if leaf zone):** :ref:`pf_tag_host`, :ref:`pf_tag_link`, :ref:`pf_tag_peer` |br|
+**Attributes:**
+
+:``id``: Zone name.
+ No other zone may have the same name over the whole platform.
+:``routing``: Routing algorithm to use.
+
+
.. |br| raw:: html
<br />
+
+.. |hr| raw:: html
+
+ <hr />
