X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/45b39212faf07b4b58f6e9c31f8aa5bd4e52427c..832290b6ad79b7a2dcbf29137578e840e000b3ad:/docs/source/XML_Reference.rst
diff --git a/docs/source/XML_Reference.rst b/docs/source/XML_Reference.rst
new file mode 100644
index 0000000000..87a71812be
--- /dev/null
+++ b/docs/source/XML_Reference.rst
@@ -0,0 +1,404 @@
+.. raw:: html
+
+
+
+
+
+
+.. _platform_reference:
+
+Complete XML Reference
+**********************
+
+Your platform description should follow the specification presented in the
+`simgrid.dtd `_ DTD file. The same DTD is used for both platform and deployment files.
+
+-------------------------------------------------------------------------------
+
+.. _pf_tag_config:
+
+
+--------
+
+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 ` 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|
+**Attributes:** none
+
+.. code-block:: xml
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+-------------------------------------------------------------------------------
+
+.. _pf_tag_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 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.
+ Must be unique over the whole platform.
+:``speed``: Computational power (per core, in flop/s).
+ If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`howto_dvfs`).
+:``core``: Amount of cores (default: 1).
+ See :ref:`howto_multicore`.
+:``availability_file``:
+ File containing the availability profile.
+ Almost every lines of such files describe timed events as ``date ratio``.
+ Example:
+
+ .. code-block:: python
+
+ 1 0.5
+ 2 0.2
+ 5 1
+ LOOPAFTER 5
+
+ - 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 profile does not contain any LOOPAFTER line, then it will
+ be executed only once and not repeated.
+
+ .. 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 (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 profile does not contain any LOOPAFTER line, then it will
+ be executed only once and not repeated.
+
+:``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`.
+
+-------------------------------------------------------------------------------
+
+.. _pf_tag_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 a unit as follows.
+
+ **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, 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:**
+ bps, Kbps, Mbps, Gbps, Tbps, Pbps, or Ebps.
+
+:``latency``: Latency for this link (default: 0.0). You must specify a unit as follows.
+
+ ==== =========== ======================
+ Unit Meaning Duration in seconds
+ ==== =========== ======================
+ ps picosecond 10â»Â¹Â² = 0.000000000001
+ ns nanosecond 10â»â¹ = 0.000000001
+ us microsecond 10â»â¶ = 0.000001
+ ms millisecond 10â»Â³ = 0.001
+ s second 1
+ m minute 60
+ h hour 60 * 60
+ d day 60 * 60 * 24
+ w week 60 * 60 * 24 * 7
+ ==== =========== ======================
+
+:``sharing_policy``: Sharing policy for the link. Possible values are ``SHARED``, ``FATPIPE`` or ``SPLITDUPLEX``
+ (default: ``SPLITDUPLEX``).
+
+ If set to ``SPLITDUPLEX``, the link models the full-duplex
+ behavior, as meant in TCP or UDP. To that extend, the link is
+ actually split in two links whose names are suffixed with "_UP" and
+ "_DOWN". You should then specify the direction to use when
+ referring to that link in a :ref:`pf_tag_link_ctn`.
+
+ If set to ``FATPIPE``, flows have no impact on each other, hence
+ each flow can exploit the full bandwidth. This models Internet
+ backbones that cannot get saturated by your application. From your
+ application point of view, there is no congestion on these
+ backbones.
+
+ If set to ``SHARED``, the available bandwidth is fairly shared
+ among ALL flows traversing this link. The resulting link is not
+ full-duplex (as UDP or TCP would be): communications in both
+ directions share the same link. Prefer ``SPLITDUPLEX`` for TCP flows.
+
+:``bandwidth_file``: File containing the bandwidth profile.
+ Almost every lines of such files describe timed events as ``date
+ bandwidth`` (in bytes per second).
+ Example:
+
+ .. code-block:: python
+
+ 4.0 40000000
+ 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.
+
+ If your profile does not contain any LOOPAFTER line, then it will
+ be executed only once and not repeated.
+
+ .. 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.
+
+:``latency_file``: File containing the latency profile.
+ Almost every lines of such files describe timed events as ``date
+ latency`` (in seconds).
+ Example:
+
+ .. code-block:: python
+
+ 1.0 0.001
+ 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 profile does not contain any LOOPAFTER line, then it will
+ be executed only once and not repeated.
+
+ .. 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`.
+
+-------------------------------------------------------------------------------
+
+.. _pf_tag_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``: either ``UP`` (by default) or ``DOWN``, specifying whether to
+ use the uplink or downlink component of the link (that must
+ follow the ``SPLITDUPLEX`` sharing policy). |br|
+ Please refer to the ``sharing_policy`` attribute in
+ :ref:`pf_tag_link`.
+
+-------------------------------------------------------------------------------
+
+.. _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-top-boxes usually have a
+much better download rate than their upload rate. To model this,
+ creates and connects several elements: an host, an upload link
+and a download link.
+
+**Parent tags:** :ref:`pf_tag_zone` (only with Vivaldi routing) |br|
+**Children tags:** none |br|
+**Attributes:**
+
+:``id``: Name of the host. Must be unique on the whole platform.
+:``speed``: Computational power (in flop/s).
+ If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`howto_dvfs`).
+:``bw_in``: Bandwidth of the private downstream link, along with its
+ unit. See :ref:`pf_tag_link`.
+:``bw_out``: Bandwidth of the private upstream link, along with its
+ unit. See :ref:`pf_tag_link`.
+:``lat``: Latency of both private links. See :ref:`pf_tag_link`.
+:``coordinates``: Coordinates of the gateway for this peer.
+
+ 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 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`
+
+-------------------------------------------------------------------------------
+
+.. _pf_tag_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.
+
+-------------------------------------------------------------------------------
+
+.. _pf_tag_prop:
+
+
+------
+
+This tag can be used to attach user-defined properties to some
+platform elements. Both the name and the value can be any string of
+your wish. You can use this to pass extra parameters to your code and
+the plugins.
+
+From your code, you can interact with these properties using the
+following functions:
+
+- Actor: :cpp:func:`simgrid::s4u::Actor::get_property` or :cpp:func:`MSG_process_get_property_value`
+- Cluster: this is a zone, see below.
+- Host: :cpp:func:`simgrid::s4u::Host::get_property` or :cpp:func:`MSG_host_get_property_value`
+- Link: :cpp:func:`simgrid::s4u::Link::get_property`
+- Storage: :cpp:func:`simgrid::s4u::Storage::get_property` or :cpp:func:`MSG_storage_get_property_value`
+- Zone: :cpp:func:`simgrid::s4u::Zone::get_property` of :cpp:func:`MSG_zone_get_property_value`
+
+**Parent tags:** :ref:`pf_tag_actor`, :ref:`pf_tag_config`, :ref:`pf_tag_cluster`, :ref:`pf_tag_host`,
+:ref:`pf_tag_link`, :ref:`pf_tag_storage`, :ref:`pf_tag_zone` |br|
+**Children tags:** none |br|
+**Attributes:**
+
+:``id``: Name of the defined property.
+:``value``: Value of the defined property.
+
+-------------------------------------------------------------------------------
+
+.. _pf_tag_route:
+
+
+-------
+
+A path between two network locations, composed of several occurences
+of :ref:`pf_tag_link` .
+
+**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``.
+
+-------------------------------------------------------------------------------
+
+.. _pf_tag_router:
+
+
+------------------------------------------------------------------
+
+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 neither inner zones nor clusters) |br|
+**Children tags:** :ref:`pf_tag_prop`, :ref:`pf_tag_storage` |br|
+**Attributes:**
+
+:``id``: Router name.
+ No other host or router may have the same name over the whole platform.
+:``coordinates``: Vivaldi coordinates. See :ref:`pf_tag_peer`.
+
+-------------------------------------------------------------------------------
+
+.. _pf_tag_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
+
+