+++ /dev/null
-/*! @page platform Describing the virtual platform
-
-
-@section pf_res Resource description
-
-@subsection pf_res_computing Computing Resources
-
-@subsubsection pf_cabinet <cabinet>
-
-@note
- This tag is only available when the routing mode of the network zone
- is set to ``Cluster``.
-
-The ``<cabinet />`` tag is, like the @ref pf_tag_cluster "<cluster>" tag,
-a meta-tag. This means that it is simply a shortcut for creating a set of (homogeneous) hosts and links quickly;
-unsurprisingly, this tag was introduced to setup cabinets in data centers quickly. Unlike
-<cluster>, however, the <cabinet> assumes that you create the backbone
-and routers yourself; see our examples below.
-
-#### Attributes ####
-
-Attribute name | Mandatory | Values | Description
---------------- | --------- | ------ | -----------
-id | yes | string | The identifier of the cabinet. Facilitates referring to this cluster.
-prefix | yes | string | Each node of the cabinet has to have a name. This name will be prefixed with this prefix.
-suffix | yes | string | Each node of the cabinet will be suffixed with this suffix
-radical | yes | string | Regexp used to generate cabinet 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 | yes | int | Same as the ``speed`` attribute of the @ref pf_tag_host "<host>" tag.
-bw | yes | int | Bandwidth for the links between nodes and backbone (if any). See the @ref pf_tag_link "link section" for syntax/details.
-lat | yes | int | Latency for the links between nodes and backbone (if any). See the @ref pf_tag_link "link section" 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 sharing policy of the links (always set to @ref pf_sharing_policy_splitduplex "SPLITDUPLEX").
-
-#### Example ####
-
-The following example was taken from ``examples/platforms/meta_cluster.xml`` and
-shows how to use the cabinet tag.
-
-@verbatim
- <zone id="my_cluster1" routing="Cluster">
- <cabinet id="cabinet1" prefix="host-" suffix=".cluster1"
- speed="1Gf" bw="125MBps" lat="100us" radical="1-10"/>
- <cabinet id="cabinet2" prefix="host-" suffix=".cluster1"
- speed="1Gf" bw="125MBps" lat="100us" radical="11-20"/>
- <cabinet id="cabinet3" prefix="host-" suffix=".cluster1"
- speed="1Gf" bw="125MBps" lat="100us" radical="21-30"/>
-
- <backbone id="backbone1" bandwidth="2.25GBps" latency="500us"/>
- </zone>
-@endverbatim
-
-@note
- Please note that you must specify the @ref pf_backbone "<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.
-
-
-@subsection pf_ne Network equipment
-
-There are two tags at all times available to represent network entities and
-several other tags that are available only in certain contexts.
-1. ``<link>``:
-
-
-3. ``<backbone/>``: This tag is only available when the containing network zone is
- used as a cluster (i.e., mode="Cluster")
-
-@remark
- If you want to represent an entity like a switch, you must use ``<link>`` (see section). Routers are used
- to run some routing algorithm and determine routes (see Section @ref pf_routing for details).
-
-@subsubsection pf_backbone <backbone/>
-
-@note
- This tag is <b>only available</b> when the containing network zone uses the "Cluster" routing mode!
-
-Using this tag, you can designate an already existing link to be a backbone.
-
-Attribute name | Mandatory | Values | Description
---------------- | --------- | ------ | -----------
-id | yes | string | Name of the link that is supposed to act as a backbone.
-
-
-
-@section pf_routing Routing
-
-
-@subsubsection pf_routing_model_simple Simple/fast models
-
-| Name | Description |
-| ---------------------------------------- | ------------------------------------------------------------------------------ |
-| @ref pf_routing_model_cluster "Cluster" | This is specific to the @ref pf_tag_cluster "<cluster/>" tag and should not be used by the user, as several assumptions are made. |
-| @ref pf_routing_model_none "None" | No routing at all. Unless you know what you're doing, avoid using this mode in combination with a non-constant network model. |
-| @ref pf_routing_model_vivaldi "Vivaldi" | Perfect when you want to use coordinates. Also see the corresponding @ref pf_P2P_tags "P2P section" below. |
-
-@anchor pf_routing_model_cluster
-### Cluster ###
-
-@note
- In this mode, the @ref pf_cabinet "<cabinet/>" tag is available.
-
-#### Example platform files ####
-
-This is an automatically generated list of example files that use the Cluster
-routing model (the path is given relative to SimGrid's source directory):
-
-@verbinclude example_filelist_routing_cluster
-
-@anchor pf_routing_model_none
-
-### None ###
-
-This model does exactly what it's name advertises: Nothing. There is no routing
-available within this model and if you try to communicate within the zone that
-uses this model, SimGrid will fail unless you have explicitly activated the
-@ref options_model_select_network_constant "Constant Network Model" (this model charges
-the same for every single communication). It should
-be noted, however, that you can still attach an @ref pf_tag_zoneroute "ZoneRoute",
-as is demonstrated in the example below:
-
-@verbinclude platforms/cluster_and_one_host.xml
-
-#### Example platform files ####
-
-This is an automatically generated list of example files that use the None
-routing model (the path is given relative to SimGrid's source directory):
-
-@verbinclude example_filelist_routing_none
-
-
-
-
-@anchor pf_routing_model_vivaldi
-### Vivaldi ###
-
-For more information on how to use the [Vivaldi Coordinates](https://en.wikipedia.org/wiki/Vivaldi_coordinates),
-see also Section @ref pf_P2P_tags "P2P tags".
-
-Note that it is possible to combine the Vivaldi routing model with other routing models;
-an example can be found in the file @c examples/platforms/cloud.xml. This
-examples models a NetZone using Vivaldi that contains other NetZones that use different
-routing models.
-
-#### Example platform files ####
-
-This is an automatically generated list of example files that use the None
-routing model (the path is given relative to SimGrid's source directory):
-
-@verbinclude example_filelist_routing_vivaldi
-
-
-@subsection ps_dec Defining routes
-
-There are currently four different ways to define routes:
-
-| Name | Description |
-| ------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| @ref pf_tag_route "route" | Used to define route between host/router |
-| @ref pf_tag_zoneroute "zoneRoute" | Used to define route between different zones |
-| @ref pf_tag_bypassroute "bypassRoute" | Used to supersede normal routes as calculated by the network model between host/router; e.g., can be used to use a route that is not the shortest path for any of the shortest-path routing models. |
-| @ref pf_tag_bypassasroute "bypassZoneRoute" | Used in the same way as bypassRoute, but for zones |
-
-Basically all those tags will contain an (ordered) list of references
-to link that compose the route you want to define.
-
-Consider the example below:
-
-@subsubsection pf_tag_bypassasroute bypasszoneroute
-
-As said before, once you choose
-a model, it (most likely; the constant network model, for example, doesn't) calculates routes for you. But maybe you want to
-define some of your routes, which will be specific. You may also want
-to bypass some routes defined in lower level zone at an upper stage:
-<b>bypasszoneroute</b> is the tag you're looking for. It allows one to
-bypass routes defined between already defined between zone (if you want
-to bypass route for a specific host, you should just use byPassRoute).
-The principle is the same as zoneroute: <b>bypasszoneroute</b> contains
-list of links that are in the path between src and dst.
-
-#### Attributes ####
-
-| Attribute name | Mandatory | Values | Description |
-| --------------- | --------- | ---------------------- | ----------- |
-| src | yes | String | The value given to the source zone's "id" attribute |
-| dst | yes | String | The value given to the destination zone's "id" attribute. |
-| gw_src | yes | String | The value given to the source gateway's "id" attribute; this can be any host or router within the src zone |
-| gw_dst | yes | String | The value given to the destination gateway's "id" attribute; this can be any host or router within the dst zone|
-| symmetrical | no | YES@| NO (Default: YES) | If this route is symmetric, the opposite route (from dst to src) will also be declared implicitly. |
-
-#### Example ####
-
-@verbatim
-<bypasszoneRoute src="my_cluster_1" dst="my_cluster_2"
- gw_src="my_cluster_1_router"
- gw_dst="my_cluster_2_router">
- <link_ctn id="link_tmp"/>
-</bypasszoneroute>
-@endverbatim
-
-This example shows that link @c link_tmp (definition not displayed here) directly
-connects the router @c my_cluster_1_router in the source cluster to the router
-@c my_cluster_2_router in the destination router. Additionally, as the @c symmetrical
-attribute was not given, this route is presumed to be symmetrical.
-
-@subsubsection pf_tag_bypassroute bypassRoute
-
-As said before, once you choose
-a model, it (most likely; the constant network model, for example, doesn't) calculates routes for you. But maybe you want to
-define some of your routes, which will be specific. You may also want
-to bypass some routes defined in lower level zone at an upper stage:
-<b>bypassRoute</b> is the tag you're looking for. It allows one to bypass
-routes defined between <b>host/router</b>. The principle is the same
-as route: <b>bypassRoute</b> contains list of links references of
-links that are in the path between src and dst.
-
-#### Attributes ####
-
-| Attribute name | Mandatory | Values | Description |
-| --------------- | --------- | ---------------------- | ----------- |
-| src | yes | String | The value given to the source zone's "id" attribute |
-| dst | yes | String | The value given to the destination zone's "id" attribute. |
-| symmetrical | no | YES @| NO (Default: YES) | If this route is symmetric, the opposite route (from dst to src) will also be declared implicitly. |
-
-#### Examples ####
-
-@verbatim
-<bypassRoute src="host_1" dst="host_2">
- <link_ctn id="link_tmp"/>
-</bypassRoute>
-@endverbatim
-
-This example shows that link @c link_tmp (definition not displayed here) directly
-connects host @c host_1 to host @c host_2. Additionally, as the @c symmetrical
-attribute was not given, this route is presumed to be symmetrical.
-
-@section pf_other Other tags
-
-The following tags can be used inside a @<platform@> tag even if they are not
-directly describing the platform:
-
- - @ref pf_tag_config passes configuration options, e.g. to change the network model;
- - @ref pf_tag_prop gives user-defined properties to various elements
-
-@subsection pf_trace trace and trace_connect
-
-Both tags are an alternate way to pass files containing information on
-availability, state etc. to an entity. (See also @ref howto_churn).
-Instead of referring to the file directly in the host, link, or
-cluster tag, you proceed by defining a trace with an id corresponding
-to a file, later a host/link/cluster, and finally using trace_connect
-you say that the file trace must be used by the entity.
-
-
-#### Example ####
-
-@verbatim
-<zone id="zone0" routing="Full">
- <host id="bob" speed="1000000000"/>
-</zone>
-<trace id="myTrace" file="bob.trace" periodicity="1.0"/>
-<trace_connect trace="myTrace" element="bob" kind="POWER"/>
-@endverbatim
-
-@note
- The order here is important. @c trace_connect must come
- after the elements @c trace and @c host, as both the host
- and the trace definition must be known when @c trace_connect
- is parsed; the order of @c trace and @c host is arbitrary.
-
-
-#### @c trace attributes ####
-
-
-| Attribute name | Mandatory | Values | Description |
-| --------------- | --------- | ---------------------- | ----------- |
-| id | yes | String | Identifier of this trace; this is the name you pass on to @c trace_connect. |
-| file | no | String | Filename of the file that contains the information - the path must follow the style of your OS. You can omit this, but then you must specify the values inside of <trace> and </trace> - see the example below. |
-| trace_periodicity | yes | String | This is the same as for @ref pf_tag_host "hosts" (see there for details) |
-
-Here is an example of trace when no file name is provided:
-
-@verbatim
- <trace id="myTrace" periodicity="1.0">
- 0.0 1.0
- 11.0 0.5
- 20.0 0.8
- </trace>
-@endverbatim
-
-#### @c trace_connect attributes ####
-
-| Attribute name | Mandatory | Values | Description |
-| --------------- | --------- | ---------------------- | ----------- |
-| kind | no | HOST_AVAIL@|POWER@|<br/>LINK_AVAIL@|BANDWIDTH@|LATENCY (Default: HOST_AVAIL) | Describes the kind of trace. |
-| trace | yes | String | Identifier of the referenced trace (specified of the trace's @c id attribute) |
-| element | yes | String | The identifier of the referenced entity as given by its @c id attribute |
-
-@section pf_hints Hints, tips and frequently requested features
-
-Now you should know at least the syntax and be able to create a
-platform by your own. However, after having ourselves wrote some platforms, there
-are some best practices you should pay attention to in order to
-produce good platform and some choices you can make in order to have
-faster simulations. Here's some hints and tips, then.
-
-@subsection pf_hints_search Finding the platform example that you need
-
-Most platform files that we ship are in the @c examples/platforms
-folder. The good old @c grep tool can find the examples you need when
-wondering on a specific XML tag. Here is an example session searching
-for @ref pf_trace "trace_connect":
-
-@verbatim
-% cd examples/platforms
-% grep -R -i -n --include="*.xml" "trace_connect" .
-./two_hosts_platform_with_availability_included.xml:26:<trace_connect kind="SPEED" trace="A" element="Cpu A"/>
-./two_hosts_platform_with_availability_included.xml:27:<trace_connect kind="HOST_AVAIL" trace="A_failure" element="Cpu A"/>
-./two_hosts_platform_with_availability_included.xml:28:<trace_connect kind="SPEED" trace="B" element="Cpu B"/>
-./two_hosts.xml:17: <trace_connect trace="Tremblay_power" element="Tremblay" kind="SPEED"/>
-@endverbatim
-
-@subsection pf_hint_generating How to generate different platform files?
-
-This is actually a good idea to search for a better platform file,
-that better fit the need of your study. To be honest, the provided
-examples are not representative of anything. They exemplify our XML
-syntax, but that's all. small_platform.xml for example was generated
-without much thought beyond that.
-
-The best thing to do when possible is to write your own platform file,
-that model the platform on which you run your code. For that, you
-could use <a href="https://gitlab.inria.fr/simgrid/platform-calibration">our
-calibration scripts</a>. This leads to very good fits between the
-platform, the model and the needs. The g5k.xml example resulted of
-such an effort, which also lead to <a href="https://github.com/lpouillo/topo5k/">an
-ongoing attempt</a> to automatically extract the SimGrid platform from
-the <a href="http://grid5000.fr/">Grid'5000</a> experimental platform.
-But it's hard to come up with generic models. Don't take these files
-too seriously. Actually, you should always challenge our models and
-your instantiation if the accuracy really matters to you (see <a
-href="https://hal.inria.fr/hal-00907887">this discussion</a>).
-
-But such advices only hold if you have a real platform and a real
-application at hand. It's moot for more abstract studies working on
-ideas and algorithms instead of technical artefacts. Well, in this
-case, there unfortunately is nothing better than this old and rusty
-<a href="http://pda.gforge.inria.fr/tools/download.html">simulacrum</a>.
-This project is dormant since over 10 years (and you will have to
-update the generated platforms with <tt>bin/simgrid_update_xml</tt> to
-use them), but that's the best we have for this right now....
-
-@subsection pf_zone_h Zone Hierarchy
-The network zone design allows SimGrid to go fast, because computing route is
-done only for the set of resources defined in the current zone. If you're using
-only a big zone containing all resource with no zone into it and you're
-using Full model, then ... you'll loose all interest into it. On the
-other hand, designing a binary tree of zone with, at the lower level,
-only one host, then you'll also loose all the good zone hierarchy can
-give you. Remind you should always be "reasonable" in your platform
-definition when choosing the hierarchy. A good choice if you try to
-describe a real life platform is to follow the zone described in
-reality, since this kind of trade-off works well for real life
-platforms.
-
-@subsection pf_exit_zone Exit Zone: why and how
-Users that have looked at some of our platforms may have notice a
-non-intuitive schema ... Something like that:
-
-
-@verbatim
-<zone id="zone_4" routing="Full">
-<zone id="exitzone_4" routing="Full">
- <router id="router_4"/>
-</zone>
-<cluster id="cl_4_1" prefix="c_4_1-" suffix="" radical="1-20" speed="1000000000" bw="125000000" lat="5E-5" bb_bw="2250000000" bb_lat="5E-4"/>
-<cluster id="cl_4_2" prefix="c_4_2-" suffix="" radical="1-20" speed="1000000000" bw="125000000" lat="5E-5" bb_bw="2250000000" bb_lat="5E-4"/>
-<link id="4_1" bandwidth="2250000000" latency="5E-5"/>
-<link id="4_2" bandwidth="2250000000" latency="5E-5"/>
-<link id="bb_4" bandwidth="2250000000" latency="5E-4"/>
-<zoneroute src="cl_4_1"
- dst="cl_4_2"
- gw_src="c_4_1-cl_4_1_router"
- gw_dst="c_4_2-cl_4_2_router">
- <link_ctn id="4_1"/>
- <link_ctn id="bb_4"/>
- <link_ctn id="4_2"/>
-</zoneroute>
-<zoneroute src="cl_4_1"
- dst="exitzone_4"
- gw_src="c_4_1-cl_4_1_router"
- gw_dst="router_4">
- <link_ctn id="4_1"/>
- <link_ctn id="bb_4"/>
-</zoneroute>
-<zoneroute src="cl_4_2"
- dst="exitzone_4"
- gw_src="c_4_2-cl_4_2_router"
- gw_dst="router_4">
- <link_ctn id="4_2"/>
- <link_ctn id="bb_4"/>
-</zoneroute>
-</zone>
-@endverbatim
-
-In the zone_4, you have an exitzone_4 defined, containing only one router,
-and routes defined to that zone from all other zone (as cluster is only a
-shortcut for a zone, see cluster description for details). If there was
-an upper zone, it would define routes to and from zone_4 with the gateway
-router_4. It's just because, as we did not allowed (for performances
-issues) to have routes from a zone to a single host/router, you have to
-enclose your gateway, when you have zone included in your zone, within a
-zone to define routes to it.
-
-@subsection pf_routing_howto_choose_wisely Choosing wisely the routing model to use
-
-
-Choosing wisely the routing model to use can significantly fasten your
-simulation/save your time when writing the platform/save tremendous
-disk space. Here is the list of available model and their
-characteristics (lookup: time to resolve a route):
-
-@li <b>Full</b>: Full routing data (fast, large memory requirements,
- fully expressive)
-@li <b>Floyd</b>: Floyd routing data (slow initialization, fast
- lookup, lesser memory requirements, shortest path routing only).
- Calculates all routes at once at the beginning.
-@li <b>Dijkstra</b>: Dijkstra routing data (fast initialization, slow
- lookup, small memory requirements, shortest path routing only).
- Calculates a route when necessary.
-@li <b>DijkstraCache</b>: Dijkstra routing data (fast initialization,
- fast lookup, small memory requirements, shortest path routing
- only). Same as Dijkstra, except it handles a cache for latest used
- routes.
-@li <b>None</b>: No routing (usable with Constant network only).
- Defines that there is no routes, so if you try to determine a
- route without constant network within this zone, SimGrid will raise
- an exception.
-@li <b>Vivaldi</b>: Vivaldi routing, so when you want to use coordinates
-@li <b>Cluster</b>: Cluster routing, specific to cluster tag, should
- not be used.
-
-@subsection pf_loopback I want to specify the characteristics of the loopback link!
-
-Each routing model automatically adds a loopback link for each declared host, i.e.,
-a network route from the host to itself, if no such route is declared in the XML
-file. This default link has a bandwidth of 498 Mb/s, a latency of 15 microseconds,
-and is <b>not</b> shared among network flows.
-
-If you want to specify the characteristics of the loopback link for a given host, you
-just have to specify a route from this host to itself with the desired characteristics
-in the XML file. This will prevent the routing model to add and use the default
-loopback link.
-
-@subsection pf_switch I want to describe a switch but there is no switch tag!
-
-Actually we did not include switch tag. But when you're trying to
-simulate a switch, assuming
-fluid bandwidth models are used (which SimGrid uses by default unless
-ns-3 or constant network models are activated), the limiting factor is
-switch backplane bandwidth. So, essentially, at least from
-the simulation perspective, a switch is similar to a
-link: some device that is traversed by flows and with some latency and
-so,e maximum bandwidth. Thus, you can simply simulate a switch as a
-link. Many links
-can be connected to this "switch", which is then included in routes just
-as a normal link.
-
-
-@subsection pf_multicabinets I want to describe multi-cabinets clusters!
-
-You have several possibilities, as usual when modeling things. If your
-cabinets are homogeneous and the intercabinet network negligible for
-your study, you should just create a larger cluster with all hosts at
-the same layer.
-
-In the rare case where your hosts are not homogeneous between the
-cabinets, you can create your cluster completely manually. For that,
-create an As using the Cluster routing, and then use one
-<cabinet> for each cabinet. This cabinet tag can only be used an
-As using the Cluster routing schema, and creating
-
-Be warned that creating a cluster manually from the XML with
-<cabinet>, <backbone> and friends is rather tedious. The
-easiest way to retrieve some control of your model without diving into
-the <cluster> internals is certainly to create one separate
-<cluster> per cabinet and interconnect them together. This is
-what we did in the G5K example platform for the Graphen cluster.
-
-@subsection pf_platform_multipath I want to express multipath routing in platform files!
-
-It is unfortunately impossible to express the fact that there is more
-than one routing path between two given hosts. Let's consider the
-following platform file:
-
-@verbatim
-<route src="A" dst="B">
- <link_ctn id="1"/>
-</route>
-<route src="B" dst="C">
- <link_ctn id="2"/>
-</route>
-<route src="A" dst="C">
- <link_ctn id="3"/>
-</route>
-@endverbatim
-
-Although it is perfectly valid, it does not mean that data traveling
-from A to C can either go directly (using link 3) or through B (using
-links 1 and 2). It simply means that the routing on the graph is not
-trivial, and that data do not following the shortest path in number of
-hops on this graph. Another way to say it is that there is no implicit
-in these routing descriptions. The system will only use the routes you
-declare (such as <route src="A" dst="C"><link_ctn
-id="3"/></route>), without trying to build new routes by aggregating
-the provided ones.
-
-You are also free to declare platform where the routing is not
-symmetrical. For example, add the following to the previous file:
-
-@verbatim
-<route src="C" dst="A">
- <link_ctn id="2"/>
- <link_ctn id="1"/>
-</route>
-@endverbatim
-
-This makes sure that data from C to A go through B where data from A
-to C go directly. Don't worry about realism of such settings since
-we've seen ways more weird situation in real settings (in fact, that's
-the realism of very regular platforms which is questionable, but
-that's another story).
-
-*/
