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.
+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.
+
-------------------------------------------------------------------------------
-.. _pf_tag_disk:
+.. _pf_tag_cluster:
-<disk>
-------
+<cluster>
+---------
-SimGrid can simulate the time it takes to read or write data on disk, even if the stored data is not made persistent in
-any way by SimGrid. This means that your application will correctly be slowed down when doing simulated I/O, but there
-is no way to get the data stored this way.
+This complex tag builds a full zone, with some hosts, links, a router, and the relevant routing algorithm. There is several
+kind of specifically tailored cluster types: crossbar clusters (contention-free internal network), backbone clusters
+(constrained internal network), fat-trees, DragonFly and Torus (star clusters are similar, but can only be created from the
+C++ code). The ``topology`` attribute is used to choose the type of cluster while the ``topo_parameters`` attribute is used
+to configure the topology. Please refer to the :ref:`examples in the documentation <platform_examples>` for all details.
-We decided to not model anything beyond raw access in SimGrid because we believe that there is not single way of doing so.
-We provide an example model of file system as a plugin, (sparsely) documented in :ref:`plugin_filesystem`.
+Regardless of its topology, each cluster comes with a router that can be used for inter-zone routing. Its name is defined
+as ``${prefix}${clusterId}_router${suffix}``.
-**Parent tags:** :ref:`pf_tag_host` |br|
-**Children tags:** :ref:`pf_tag_prop` |br|
+**Parent tags:** :ref:`pf_tag_platform`, :ref:`pf_tag_zone` |br|
+**Children tags:** none |br|
**Attributes:**
-:``id``: A name of your choice (must be unique on this host).
-:``read_bw``: Read bandwidth for this disk. You must specify a unit as follows.
+:``id``: The identifier of the cluster. Facilitates referring to this cluster.
+:``prefix``: Each node of the cluster has to have a name. This name will be prefixed with this prefix.
+:``suffix``: Each node of the cluster will be suffixed with this suffix
+:``radical``: Regexp used to generate cluster nodes name.
- **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.
+ Syntax: "10-20" will give you 11 machines numbered from 10 to 20, "10-20;2" will give you 12 machines, one with the number 2, others numbered as before.
-:``write_bw``: Write bandwidth for this disk. You must specify a unit as for the read bandwidth.
+ The produced number is concatenated between prefix and suffix to form machine names.
+:``speed``: Same as the ``speed`` attribute of the :ref:`pf_tag_host` tag.
+:``core``: Same as the ``core`` attribute of the :ref:`pf_tag_host` tag.
+:``bw``: Bandwidth for the links between nodes and backbone (if any). See :ref:`pf_tag_link` for syntax/details.
+:``lat``: Latency for the links between nodes and backbone (if any). See :ref:`pf_tag_link` for syntax/details.
+:``sharing_policy``: Sharing policy for the links between nodes and backbone (if any). See :ref:`pf_tag_link` for syntax/details.
+:``bb_bw``: Bandwidth for backbone (if any). See :ref:`pf_tag_link` for syntax/details.
-.. code-block:: xml
+ If bb_bw and bb_lat attributes are omitted, no backbone is created (alternative cluster architecture described earlier).
+:``bb_lat``: Latency for backbone (if any). See :ref:`pf_tag_link` section for syntax/details.
- <host id="alice" speed="1Gf">
- <disk id="Disk1" read_bw="200MBps" write_bw="80MBps">
- <!-- you can add properties for anything you want: they are not used by SimGrid -->
- <prop id="content" value="storage/content/small_content.txt"/>
- </disk>
- <prop id="ram" value="100B" />
- </host>
+ If bb_lat and bb_bw attributes are omitted, no backbone is created (alternative cluster architecture described earlier).
+:``bb_sharing_policy``: Sharing policy for the backbone (if any). See :ref:`pf_tag_link` section for syntax/details.
+:``limiter_link``: Bandwidth for limiter link (if any).
+
+ This adds a specific link for each node, to set the maximum bandwidth reached when communicating in both directions at the same time.
+
+ In theory this value should be 2*bw for splitduplex links, but in reality this might be less. This value will depend heavily on the communication model, and on the cluster's hardware, so no default value can be set, this has to be measured.
+
+ More details can be obtained in `Toward Better Simulation of MPI Applications on Ethernet/TCP Networks <https://hal.inria.fr/hal-00919507/>`_
+:``loopback_bw``: Bandwidth for loopback (if any). See :ref:`pf_tag_link` section for syntax/details.
+
+ If loopback_bw and loopback_lat attributes are omitted, no loopback link is created and all intra-node communication will use the main network link of the node.
+
+ The sharing policy of a loopback link is **FATPIPE** :ref:`pf_tag_link`.
+:``loopback_lat``: Latency for loopback (if any). See loopback_bw for more info.
+:``topology``: Network topology to use.
+
+ SimGrid currently supports FLAT (with or without backbone, as described before), TORUS, FAT_TREE and DRAGONFLY attributes for this tag.
+
+ See :ref:`platform_examples` for more details.
+
+:``topo_parameters``: Specific parameters to pass for the topology defined in the topology tag.
+
+ For torus networks, comma-separated list of the number of nodes in each dimension of the torus.
+
+ Please refer to :ref:`platform_examples`.
-------------------------------------------------------------------------------
<!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
<platform version = "4.1">
<config>
- <prop id = "maxmin/precision" value = "0.000010" />
+ <prop id = "precision/work-amount" 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" />
+ <prop id = "network/bandwidth-factor" value = "65472:0.940694;15424:0.697866;9376:0.58729" />
</config>
<!-- The rest of your platform -->
-------------------------------------------------------------------------------
+.. _pf_tag_disk:
+
+<disk>
+------
+
+SimGrid can simulate the time it takes to read or write data on disk, even if the stored data is not made persistent in
+any way by SimGrid. This means that your application will correctly be slowed down when doing simulated I/O, but there
+is no way to get the data stored this way.
+
+We decided to not model anything beyond raw access in SimGrid because we believe that there is not single way of doing so.
+We provide an example model of file system as a plugin, (sparsely) documented in :ref:`plugin_filesystem`.
+
+**Parent tags:** :ref:`pf_tag_host` |br|
+**Children tags:** :ref:`pf_tag_prop` |br|
+**Attributes:**
+
+:``id``: A name of your choice (must be unique on this host).
+:``read_bw``: Read bandwidth for this disk. 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.
+
+:``write_bw``: Write bandwidth for this disk. You must specify a unit as for the read bandwidth.
+
+.. code-block:: xml
+
+ <host id="alice" speed="1Gf">
+ <disk id="Disk1" read_bw="200MBps" write_bw="80MBps">
+ <!-- you can add properties for anything you want: they are not used by SimGrid -->
+ <prop id="content" value="storage/content/small_content.txt"/>
+ </disk>
+ <prop id="ram" value="100B" />
+ </host>
+
+-------------------------------------------------------------------------------
+
.. _pf_tag_host:
<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_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``:
:``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`.
-------------------------------------------------------------------------------
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.
+single element. Links are characterized by their bandwidth and latency, and their sharing is realistic wrt TCP connexions.
+Another unusual point is that SimGrid links can be used to connect more than two elements, just like
+hyperlinks in an `hypergraph <https://en.wikipedia.org/wiki/Hypergraph>`_.
**Parent tags:** :ref:`pf_tag_zone` (both leaf zones and inner zones) |br|
**Children tags:** :ref:`pf_tag_prop` |br|
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
:``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
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|
<route>
-------
-A path between two network locations, composed of several occurrences
-of :ref:`pf_tag_link` .
+A path between two network locations, composed of several occurrences of :ref:`pf_tag_link`. It is only relevant for
+intra-:ref:`pf_tag_zone` routes. Inter-zone routes must be declared with :ref:`pf_tag_zoneRoute`. More detail can be
+found in the following sections :ref:`pf_routes` and :ref:`pf_route_usage`.
**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.
+:``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``.
+ time. Valid values: ``yes``, ``no``, ``YES``, ``NO``
+ (default: YES).
-------------------------------------------------------------------------------
.. _pf_tag_router:
<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.
+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|
**Attributes:**
<zoneRoute>
-----------
-The purpose of this entity is to define a route between two zones.
-Recall that all zones form a tree, so to connect two sibling zones,
-you must give such a zoneRoute specifying the source and destination zones,
-along with the gateway in each zone (i.e., the point to reach within that zone to reach the zone),
-and the list of links to go from one zone to another.
+All information to factorize the routes between two zones; intra-zone paths must be declared with :ref:`pf_tag_route`.
+Since zones form a tree, :ref:`pf_tag_zoneRoute` is probably best used to connect sibling zones.
+
+When declaring a zoneRoute, you must give the source and destination zones, along with the gateway in each zone (i.e.,
+the point to reach within that zone to reach the declared route), and the list of links to go from one zone to another.
+More detail can be found in the following sections :ref:`pf_routes` and :ref:`pf_route_usage`.
**Parent tags:** :ref:`pf_tag_zone` |br|
**Children tags:** :ref:`pf_tag_link_ctn` |br|
:``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
+:``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_cluster:
+Advanced tags
+-------------
-<cluster>
----------
+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.
-This tag is commonly used when one wants to define many hosts and a network quickly.
-Technically, cluster is a meta-tag: **from the inner SimGrid point of
-view, a cluster is a network zone where some optimized routing is defined**.
-The default inner organization of the cluster is as follow:
-
-.. code-block:: text
-
- __________
- | |
- | router |
- ____________|__________|_____________ backbone
- | | | | | |
- l0| l1| l2| l97| l96 | | l99
- | | | ........ | | |
- | |
- c-0.me c-99.me
-
-
-Here, a set of **hosts** is defined. Each of them has a **link**
-to a central backbone (backbone is a link itself, as a link can
-be used to represent a switch).
-A **router** allows to connect a **cluster** to the outside world. Internally,
-SimGrid treats a cluster as a network zone containing all hosts: the router is the
-gateway for the cluster.
-
-There is an alternative organization, which is as follows:
-
-.. code-block:: text
-
- __________
- | |
- | router |
- |__________|
- / | \
- / | \
- l0 / l1| \l2
- / | \
- / | \
- host0 host1 host2
-
-The principle is the same, except that there is no backbone. This representation
-can be obtained easily: just do not set the bb_* attributes.
-**Parent tags:** :ref:`pf_tag_platform`, :ref:`pf_tag_zone` |br|
-**Children tags:** none |br|
-**Attributes:**
-
-:``id``: The identifier of the cluster. Facilitates referring to this cluster.
-:``prefix``: Each node of the cluster has to have a name. This name will be prefixed with this prefix.
-:``suffix``: Each node of the cluster will be suffixed with this suffix
-:``radical``: Regexp used to generate cluster nodes name.
-
- Syntax: "10-20" will give you 11 machines numbered from 10 to 20, "10-20;2" will give you 12 machines, one with the number 2, others numbered as before.
-
- The produced number is concatenated between prefix and suffix to form machine names.
-:``speed``: Same as the ``speed`` attribute of the :ref:`pf_tag_host` tag.
-:``core``: Same as the ``core`` attribute of the :ref:`pf_tag_host` tag.
-:``bw``: Bandwidth for the links between nodes and backbone (if any). See :ref:`pf_tag_link` for syntax/details.
-:``lat``: Latency for the links between nodes and backbone (if any). See :ref:`pf_tag_link` for syntax/details.
-:``sharing_policy``: Sharing policy for the links between nodes and backbone (if any). See :ref:`pf_tag_link` for syntax/details.
-:``bb_bw``: Bandwidth for backbone (if any). See :ref:`pf_tag_link` for syntax/details.
-
- If bb_bw and bb_lat attributes are omitted, no backbone is created (alternative cluster architecture described earlier).
-:``bb_lat``: Latency for backbone (if any). See :ref:`pf_tag_link` section for syntax/details.
-
- If bb_lat and bb_bw attributes are omitted, no backbone is created (alternative cluster architecture described earlier).
-:``bb_sharing_policy``: Sharing policy for the backbone (if any). See :ref:`pf_tag_link` section for syntax/details.
-:``limiter_link``: Bandwidth for limiter link (if any).
-
- This adds a specific link for each node, to set the maximum bandwidth reached when communicating in both directions at the same time.
-
- In theory this value should be 2*bw for splitduplex links, but in reality this might be less. This value will depend heavily on the communication model, and on the cluster's hardware, so no default value can be set, this has to be measured.
-
- More details can be obtained in `Toward Better Simulation of MPI Applications on Ethernet/TCP Networks <https://hal.inria.fr/hal-00919507/>`_
-:``loopback_bw``: Bandwidth for loopback (if any). See :ref:`pf_tag_link` section for syntax/details.
-
- If loopback_bw and loopback_lat attributes are omitted, no loopback link is created and all intra-node communication will use the main network link of the node.
-
- The sharing policy of a loopback link is **FATPIPE** :ref:`pf_tag_link`.
-:``loopback_lat``: Latency for loopback (if any). See loopback_bw for more info.
-:``topology``: Network topology to use.
+-------------------------------------------------------------------------------
- SimGrid currently supports FLAT (with or without backbone, as described before), TORUS, FAT_TREE and DRAGONFLY attributes for this tag.
+.. _pf_tag_bypassRoute:
- See :ref:`platform_examples` for more details.
+<bypassRoute>
+^^^^^^^^^^^^^
-:``topo_parameters``: Specific parameters to pass for the topology defined in the topology tag.
+This tag can be used to completely bypass the classical :ref:`routing algorithm <pf_route_usage>` 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.
- For torus networks, comma-separated list of the number of nodes in each dimension of the torus.
+**Parent tags:** :ref:`pf_tag_zone` |br|
+**Children tags:** :ref:`pf_tag_link_ctn` |br|
+**Attributes:**
- Please refer to :ref:`platform_examples`.
+:``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).
+-------------------------------------------------------------------------------
-Cluster example
-^^^^^^^^^^^^^^^
+.. _pf_tag_bypassZoneRoute:
-Consider the following two (and independent) uses of the ``cluster`` tag:
+<bypassZoneRoute>
+^^^^^^^^^^^^^^^^^
-.. code-block:: xml
+This tag can be used to completely bypass the classical :ref:`routing algorithm <pf_route_usage>` 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.
- <cluster id="my_cluster_1" prefix="" suffix="" radical="0-262144"
- speed="1e9" bw="125e6" lat="5E-5"/>
+**Parent tags:** :ref:`pf_tag_zone` |br|
+**Children tags:** :ref:`pf_tag_link_ctn` |br|
+**Attributes:**
- <cluster id="my_cluster_2" prefix="c-" suffix=".me" radical="0-99"
- speed="1e9" bw="125e6" lat="5E-5"
- bb_bw="2.25e9" bb_lat="5E-4"/>
+:``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``.
+-------------------------------------------------------------------------------
-The second example creates one router and 100 machines with the following names:
+.. _pf_tag_backbone:
-.. code-block:: text
+<backbone>
+^^^^^^^^^^
- c-my_cluster_2_router.me
- c-0.me
- c-1.me
- c-2.me
- ...
- c-99.me
+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.
-.. note::
+**Parent tags:** :ref:`pf_tag_zone` with ``routing="Cluster"`` attribute |br|
+**Children tags:** none |br|
+**Attributes:**
- The router name is defined as the resulting string: prefix + clusterId + "_router" + suffix.
- In this case: *my_cluster_1_router* and *my_cluster_2_router.me*.
+:``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:
<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 ``<zone routing="Cluster">`` 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:**
:``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.
+-------------------------------------------------------------------------------
+
+.. _pf_tag_host_link:
+
+<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.
+
+
.. |br| raw:: html
<br />
