X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/065494aeeb869a5a43a44b51c7bcec99ec599372..1aea752735b30aae28c3583db62ee21079380ca8:/docs/source/XML_reference.rst diff --git a/docs/source/XML_reference.rst b/docs/source/XML_reference.rst index 23c06c801f..dad879d7bb 100644 --- a/docs/source/XML_reference.rst +++ b/docs/source/XML_reference.rst @@ -18,47 +18,28 @@ 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_bypassRoute: - - -------------- - -This tag can be used to completely bypass the classical :ref:`routing algorithm ` for a pair of hosts. The -provided list of links will be used directly, with no further routing computation. This is an advanced tag that is rarely -used in practice. - -**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 the name of an existing host. -:``dst``: Host to which this route leads. Must be the name of 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`` (default: YES). - -------------------------------------------------------------------------------- - -.. _pf_tag_bypassZoneRoute: - - ------------------ - -This tag can be used to completely bypass the classical :ref:`routing algorithm ` between two zones. When -provided, it breaks the recursive search and the provided links will be used instead. This tag should probably be reserved -to experts. - -**Parent tags:** :ref:`pf_tag_zone` |br| -**Children tags:** :ref:`pf_tag_link_ctn` |br| -**Attributes:** - -:``src``: Zone from which this route starts. Must be an existing zone. -:``dst``: Zone to which this route leads. Must be an existing zone. -:``gw_src``: Netpoint (within src zone) from which this route starts. Must be an existing host/router. -:``gw_dst``: Netpoint (within dst zone) to which this route leads. Must be an existing host/router. -:``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``. +Here is the complete list of all existing tags in the DTD: + +:ref:`pf_tag_actor`: request the creation of an actor (deployment file, not in the platform). |br| +:ref:`pf_tag_argument`: pass parameters to the created actors (deployment file, not in the platform). |br| +:ref:`pf_tag_backbone`: building clusters manually from the XML (deprecated, please use the C++ API). |br| +:ref:`pf_tag_bypassRoute`: tweeking the routing (advanced tag). |br| +:ref:`pf_tag_bypassZoneRoute`: tweeking the routing (expert-only tag). |br| +:ref:`pf_tag_cabinet`: building clusters manually from the XML (deprecated, please use the C++ API). |br| +:ref:`pf_tag_cluster`: building a cluster (aka, a full zone in one tag only). |br| +:ref:`pf_tag_config`: pass simulation parameters from the XML file. |br| +:ref:`pf_tag_disk`: storage resource. |br| +:ref:`pf_tag_host`: computing resource. |br| +:ref:`pf_tag_host_link`: building clusters manually from the XML (deprecated, please use the C++ API). |br| +:ref:`pf_tag_link`: communication resource. |br| +:ref:`pf_tag_link_ctn`: name of a link to be included in a route. |br| +:ref:`pf_tag_peer`: host located in a :ref:`pf_rm_vivaldi` zone. |br| +:ref:`pf_tag_platform`: root tag of any platform description. |br| +:ref:`pf_tag_prop`: attach used-defined properties to your :ref:`pf_tag_actor`, :ref:`pf_tag_disk`, :ref:`pf_tag_host`, :ref:`pf_tag_link` or :ref:`pf_tag_zone`. |br| +:ref:`pf_tag_route`: intra-zone network path. |br| +:ref:`pf_tag_router`: like an :ref:`pf_tag_host` that cannot host actors (for network routing algorithms). |br| +:ref:`pf_tag_zone`: area of the network containing elements (:ref:`pf_tag_disk`, :ref:`pf_tag_host`, :ref:`pf_tag_link` and sub-:ref:`pf_tag_zone`). |br| +:ref:`pf_tag_zoneRoute`: inter-zone network path. ------------------------------------------------------------------------------- @@ -126,6 +107,7 @@ as ``${prefix}${clusterId}_router${suffix}``. Please refer to :ref:`platform_examples`. ------------------------------------------------------------------------------- + .. _pf_tag_config: @@ -150,10 +132,10 @@ name of the flag and ``value`` is what it has to be set to. - + - + @@ -211,13 +193,13 @@ We provide an example model of file system as a plugin, (sparsely) documented in 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_disk` |br| +**Children tags:** :ref:`pf_tag_prop`, :ref:`pf_tag_disk` |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`). + If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`API_s4u_Host_dvfs`). :``core``: Amount of cores (default: 1). See :ref:`howto_multicore`. :``availability_file``: @@ -265,7 +247,7 @@ A host is the computing resource on which an actor can run. See :cpp:class:`simg :``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`. + See :ref:`API_s4u_Host_dvfs`. ------------------------------------------------------------------------------- @@ -343,8 +325,8 @@ hyperlinks in an `hypergraph `_. 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 = 4, the bandwidth is of 40 Mb/s. + - At time t = 8, it raises to 60 Mb/s. - At time t = 24, it drops at 40 MBps again. If your profile does not contain any LOOPAFTER line, then it will @@ -418,7 +400,7 @@ and a download link. :``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`). + If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`API_s4u_Host_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 @@ -475,12 +457,12 @@ 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` +- Actor: :cpp:func:`simgrid::s4u::Actor::get_property` - 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` - Disk: :cpp:func:`simgrid::s4u::Disk::get_property` -- Zone: :cpp:func:`simgrid::s4u::NetZone::get_property` of :cpp:func:`MSG_zone_get_property_value` +- Host: :cpp:func:`simgrid::s4u::Host::get_property` +- Link: :cpp:func:`simgrid::s4u::Link::get_property` +- Zone: :cpp:func:`simgrid::s4u::NetZone::get_property` **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_disk`,:ref:`pf_tag_zone` |br| @@ -573,27 +555,92 @@ More detail can be found in the following sections :ref:`pf_routes` and :ref:`pf :``gw_src``: Netpoint (within src zone) from which this route starts. Must be an existing host/router. :``gw_dst``: Netpoint (within dst zone) to which this route leads. Must be an existing host/router. :``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``. + time. Valid values: ``yes``, ``no``, ``YES``, ``NO``. ------------------------------------------------------------------------------- +Advanced tags +------------- + +The following list contains some tags that are less often used. They are still valid, but unless you know what you are +doing, there is a good chance that you don't really want to use them. + + +------------------------------------------------------------------------------- + +.. _pf_tag_bypassRoute: + + +^^^^^^^^^^^^^ + +This tag can be used to completely bypass the classical :ref:`routing algorithm ` for a pair of hosts. The +provided list of links will be used directly, with no further routing computation. This is an advanced tag that is rarely +used in practice. + +**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 the name of an existing host. +:``dst``: Host to which this route leads. Must be the name of 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`` (default: YES). + +------------------------------------------------------------------------------- + +.. _pf_tag_bypassZoneRoute: + + +^^^^^^^^^^^^^^^^^ + +This tag can be used to completely bypass the classical :ref:`routing algorithm ` between two zones. When +provided, it breaks the recursive search and the provided links will be used instead. This tag should probably be reserved +to experts. + +**Parent tags:** :ref:`pf_tag_zone` |br| +**Children tags:** :ref:`pf_tag_link_ctn` |br| +**Attributes:** + +:``src``: Zone from which this route starts. Must be an existing zone. +:``dst``: Zone to which this route leads. Must be an existing zone. +:``gw_src``: Netpoint (within src zone) from which this route starts. Must be an existing host/router. +:``gw_dst``: Netpoint (within dst zone) to which this route leads. Must be an existing host/router. +:``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_backbone: + + +^^^^^^^^^^ + +Within a manually-built cluster, specify the backbone to use. See the documentation of :ref:`pf_tag_cabinet` for all +details, even if you should probably stop using this tag and switch to the C++ interface. + +**Parent tags:** :ref:`pf_tag_zone` with ``routing="Cluster"`` attribute |br| +**Children tags:** none |br| +**Attributes:** + +:``id``: No other link in the platform shall have the same identifier. +:``bw``: Bandwidth, see the :ref:`pf_tag_link` for syntax/details. +:``lat``: Latency, see the :ref:`pf_tag_link` for syntax/details. + +------------------------------------------------------------------------------- .. _pf_tag_cabinet: ---------- +^^^^^^^^^ -.. note:: - This tag is only available when the routing mode of the network zone - is set to ``Cluster``. +The cabinet tag is a shortcut for creating a set of (homogenous) hosts and links quickly, as in cabinets of data centers. +This is mostly useful when manually describing a cluster, i.e. a ```` where you manually specify +the content with :ref:`pf_tag_cabinet`, :ref:`pf_tag_backbone` and maybe :ref:`pf_tag_host_link`. -The cabinet tag is, like the :ref:`pf_tag_cluster` tag, -a meta-tag. This means that it is simply a shortcut for creating a set of (homogenous) hosts and links quickly; -unsurprisingly, this tag was introduced to setup cabinets in data centers. Unlike -:ref:`pf_tag_cluster`, however, the :ref:`pf_tag_cabinet` assumes that you create the backbone -and routers yourself; see our examples below. +But this approach is somewhat deprecated now, as the C++ interface is both more convinient and more powerful. For example, +the core amount or link characteristics cannot be changed with this tag. -**Parent tags:** :ref:`pf_tag_zone` |br| +**Parent tags:** :ref:`pf_tag_zone` with ``routing="Cluster"`` attribute |br| **Children tags:** none |br| **Attributes:** @@ -608,30 +655,31 @@ and routers yourself; see our examples below. :``bw``: Bandwidth for the links between nodes and backbone (if any). See the :ref:`pf_tag_link` for syntax/details. :``lat``: Latency for the links between nodes and backbone (if any). See the :ref:`pf_tag_link` for syntax/details. -.. note:: - Please note that as of now, it is impossible to change attributes such as, - amount of cores (always set to 1), the initial state of hosts/links - (always set to ON), the sharing policy of the links (always set to **SPLITDUPLEX** :ref:`pf_tag_link` ). - - -Cabinet example -^^^^^^^^^^^^^^^ -The following example shows how to use the cabinet tag. +**Example** .. literalinclude:: ../../examples/platforms/meta_cluster.xml -\note - Please note that you must specify the :ref:`pf_backbone` tag by yourself; - this is not done automatically and there are no checks - that ensure this backbone was defined. - The hosts generated in the above example are named host-1.cluster, host-2.cluster1 etc. -.. TODO:: +------------------------------------------------------------------------------- + +.. _pf_tag_host_link: + + +^^^^^^^^^^^ + +Specify the up and down private links of a given host, which must be in a Cluster zone. + +**Parent tags:** :ref:`pf_tag_zone` with ``routing="Cluster"`` attribute |br| +**Children tags:** none |br| +**Attributes:** + +:``id``: Identifier of the host to be connected. +:``up``: Link id to be used for the outgoing communications. +:``down``: Link id to be used for the incoming communications. - Missing tags: .. |br| raw:: html - +