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 + +