X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/45b39212faf07b4b58f6e9c31f8aa5bd4e52427c..832290b6ad79b7a2dcbf29137578e840e000b3ad:/docs/source/platform_reference.rst diff --git a/docs/source/platform_reference.rst b/docs/source/platform_reference.rst deleted file mode 100644 index 8fd08925ad..0000000000 --- a/docs/source/platform_reference.rst +++ /dev/null @@ -1,404 +0,0 @@ -.. raw:: html - - - -
-
- -.. _platform_reference: - -DTD 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 - -