Here, a set of <b>host</b>s is defined. Each of them has a <b>link</b>
to a central backbone (backbone is a link itself, as a link can
be used to represent a switch, see the switch / link section
-below for more details about it). A <b>router</b> allows to connect a
+below for more details about it). A <b>router</b> allows one to connect a
<b>cluster</b> to the outside world. Internally,
SimGrid treats a cluster as a network zone containing all hosts: the router is the default
gateway for the cluster.
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_tag_link <link>
-
-Network links can represent one-hop network connections. They are
-characterized by their id and their bandwidth; links can (but may not) be subject
-to latency.
-
-#### Attributes ####
-
-Attribute name | Mandatory | Values | Description
---------------- | --------- | ------ | -----------
-id | yes | string | The identifier of the link to be used when referring to it.
-bandwidth | yes | string | Maximum bandwidth for this link, along with its unit.
-latency | no | double (default: 0.0) | Latency for this link.
-sharing_policy | no | @ref sharing_policy_shared "SHARED"@|@ref pf_sharing_policy_fatpipe "FATPIPE"@|@ref pf_sharing_policy_splitduplex "SPLITDUPLEX" (default: SHARED) | Sharing policy for the link.
-bandwidth_file | no | string | Allows you to use a file as input for bandwidth.
-latency_file | no | string | Allows you to use a file as input for latency.
-state_file | no | string | Allows you to use a file as input for states.
-
-
-#### Possible shortcuts for ``latency`` ####
-
-When using the latency attribute, you can specify the latency by using the scientific
-notation or by using common abbreviations. For instance, the following three tags
-are equivalent:
-
-@verbatim
- <link id="LINK1" bandwidth="125000000" latency="5E-6"/>
- <link id="LINK1" bandwidth="125000000" latency="5us"/>
- <link id="LINK1" bandwidth="125000000" latency="0.000005"/>
-@endverbatim
-
-Here, the second tag uses "us", meaning "microseconds". Other shortcuts are:
-
-Name | Abbreviation | Time (in seconds)
----- | ------------ | -----------------
-Week | w | 7 * 24 * 60 * 60
-Day | d | 24 * 60 * 60
-Hour | h | 60 * 60
-Minute | m | 60
-Second | s | 1
-Millisecond | ms | 0.001 = 10^(-3)
-Microsecond | us | 0.000001 = 10^(-6)
-Nanosecond | ns | 0.000000001 = 10^(-9)
-Picosecond | ps | 0.000000000001 = 10^(-12)
-
-#### Sharing policy ####
-
-@anchor sharing_policy_shared
-By default a network link is @b SHARED, i.e., if two or more data flows go
-through a link, the bandwidth is shared fairly among all data flows. This
-is similar to the sharing policy TCP uses.
-
-@anchor pf_sharing_policy_fatpipe
-On the other hand, if a link is defined as a @b FATPIPE,
-each flow going through this link will be provided with the complete bandwidth,
-i.e., no sharing occurs and the bandwidth is only limiting each flow individually.
-Please note that this is really on a per-flow basis, not only on a per-host basis!
-The complete bandwidth provided by this link in this mode
-is ``number_of_flows*bandwidth``, with at most ``bandwidth`` being available per flow.
-
-Using the FATPIPE mode allows to model backbones that won't affect performance
-(except latency).
-
-@anchor pf_sharing_policy_splitduplex
-The last mode available is @b SPLITDUPLEX. This means that SimGrid will
-automatically generate two links (one carrying the suffix _UP and the other the
-suffix _DOWN) for each ``<link>`` tag. This models situations when the direction
-of traffic is important.
-
-@remark
- Transfers from one side to the other will interact similarly as
- TCP when ACK returning packets circulate on the other direction. More
- discussion about it is available in the description of link_ctn description.
-
-In other words: The SHARED policy defines a physical limit for the bandwidth.
-The FATPIPE mode defines a limit for each application,
-with no upper total limit.
-
-@remark
- Tip: By using the FATPIPE mode, you can model big backbones that
- won't affect performance (except latency).
-
-#### Example ####
-
-@verbatim
- <link id="SWITCH" bandwidth="125000000" latency="5E-5" sharing_policy="FATPIPE" />
-@endverbatim
-
-#### Expressing dynamism and failures ####
-
-Similar to hosts, it is possible to declare links whose state, bandwidth
-or latency changes over time (see Section @ref pf_host_dynamism for details).
-
-In the case of network links, the ``bandwidth`` and ``latency`` attributes are
-replaced by the ``bandwidth_file`` and ``latency_file`` attributes.
-The following XML snippet demonstrates how to use this feature in the platform
-file. The structure of the files "link1.bw" and "link1.lat" is shown below.
-
-@verbatim
-<link id="LINK1" state_file="link1.fail" bandwidth="80000000" latency=".0001" bandwidth_file="link1.bw" latency_file="link1.lat" />
-@endverbatim
-
-@note
- Even if the syntax is the same, the semantic of bandwidth and latency
- trace files differs from that of host availability files. For bandwidth and
- latency, the corresponding files do not
- express availability as a fraction of the available capacity but directly in
- bytes per seconds for the bandwidth and in seconds for the latency. This is
- because most tools allowing to capture traces on real platforms (such as NWS)
- express their results this way.
-
-##### Example of "link1.bw" file #####
-
-~~~{.py}
-PERIODICITY 12.0
-4.0 40000000
-8.0 60000000
-~~~
-
-In this example, the bandwidth changes repeatedly, with all changes
-being repeated every 12 seconds.
-
-At the beginning of the the simulation, the link's bandwidth is 80,000,000
-B/s (i.e., 80 Mb/s); this value was defined in the XML snippet above.
-After four seconds, it drops to 40 Mb/s (line 2), and climbs
-back to 60 Mb/s after another 4 seconds (line 3). The value does not change any
-more until the end of the period, that is, after 12 seconds have been simulated).
-At this point, periodicity kicks in and this behavior is repeated: Seconds
-12-16 will experience 80 Mb/s, 16-20 40 Mb/s etc.).
-
-##### Example of "link1.lat" file #####
-
-~~~{.py}
-PERIODICITY 5.0
-1.0 0.001
-2.0 0.01
-3.0 0.001
-~~~
-
-In this example, the latency varies with a period of 5 seconds.
-In the xml snippet above, the latency is initialized to be 0.0001s (100µs). This
-value will be kept during the first second, since the latency_file contains
-changes to this value at second one, two and three.
-At second one, the value will be 0.001, i.e., 1ms. One second later it will
-be adjusted to 0.01 (or 10ms) and one second later it will be set again to 1ms. The
-value will not change until second 5, when the periodicity defined in line 1
-kicks in. It then loops back, starting at 100µs (the initial value) for one second.
-
-#### The ``<prop/>`` tag ####
-
-Similar to the ``<host>`` tag, a link may also contain the ``<prop/>`` tag; see the host
-documentation (Section @ref pf_tag_host) for an example.
-
-
@subsubsection pf_backbone <backbone/>
@note
@ref msg_file ; access functions are organized as a POSIX-like
interface.
-@subsubsection pf_sto_conc Storage - Main Concepts
-
-The storage facilities implemented in SimGrid help to model (and account for)
-storage devices, such as tapes, hard-drives, CD or DVD devices etc.
-A typical situation is depicted in the figure below:
-
-@image html ./webcruft/storage_sample_scenario.png
-@image latex ./webcruft/storage_sample_scenario.png "storage_sample_scenario" width=@textwidth
-
-In this figure, two hosts called Bob and Alice are interconnected via a network
-and each host is physically attached to a disk; it is not only possible for each host to
-mount the disk they are attached to directly, but they can also mount disks
-that are in a remote location. In this example, Bob mounts Alice's disk remotely
-and accesses the storage via the network.
-
-SimGrid provides 3 different entities that can be used to model setups
-that include storage facilities:
-
-Entity name | Description
---------------- | -----------
-@ref pf_storage_entity_storage_type "storage_type" | Defines a template for a particular kind of storage (such as a hard-drive) and specifies important features of the storage, such as capacity, performance (read/write), contents, ... Different models of hard-drives use different storage_types (because the difference between an SSD and an HDD does matter), as they differ in some specifications (e.g., different sizes or read/write performance).
-@ref pf_tag_storage "storage" | Defines an actual instance of a storage type (disk, RAM, ...); uses a ``storage_type`` template (see line above) so that you don't need to re-specify the same details over and over again.
-@ref pf_tag_mount "mount" | Must be wrapped by a @ref pf_tag_host tag; declares which storage(s) this host has mounted and where (i.e., the mountpoint).
-
-
-@anchor pf_storage_content_file
-### %Storage Content File ###
-
-In order to assess exactly how much time is spent reading from the storage,
-SimGrid needs to know what is stored on the storage device (identified by distinct (file-)name, like in a file system)
-and what size this content has.
-
-@note
- The content file is never changed by the simulation; it is parsed once
- per simulation and kept in memory afterwards. When the content of the
- storage changes, only the internal SimGrid data structures change.
-
-@anchor pf_storage_content_file_structure
-#### Structure of a %Storage Content File ####
-
-Here is an excerpt from two storage content file; if you want to see the whole file, check
-the file ``examples/platforms/content/storage_content.txt`` that comes with the
-SimGrid source code.
-
-SimGrid essentially supports two different formats: UNIX-style filepaths should
-follow the well known format:
-
-@verbatim
-/lib/libsimgrid.so.3.6.2 12710497
-/bin/smpicc 918
-/bin/smpirun 7292
-/bin/smpif2c 1990
-/bin/simgrid_update_xml 5018
-/bin/graphicator 66986
-/bin/simgrid-colorizer 2993
-/bin/smpiff 820
-/bin/tesh 356434
-@endverbatim
-
-Windows filepaths, unsurprisingly, use the windows style:
-
-@verbatim
-@Windows@avastSS.scr 41664
-@Windows@bfsvc.exe 75264
-@Windows@bootstat.dat 67584
-@Windows@CoreSingleLanguage.xml 31497
-@Windows@csup.txt 12
-@Windows@dchcfg64.exe 335464
-@Windows@dcmdev64.exe 93288
-@endverbatim
-
-@note
- The different file formats come at a cost; in version 3.12 (and most likely
- in later versions, too), copying files from windows-style storages to unix-style
- storages (and vice versa) is not supported.
-
-@anchor pf_storage_content_file_create
-#### Generate a %Storage Content File ####
-
-If you want to generate a storage content file based on your own filesystem (or at least a filesystem you have access to),
-try running this command (works only on unix systems):
-
-@verbatim
-find . -type f -exec ls -1s --block=1 {} @; 2>/dev/null | awk '{ print $2 " " $1}' > ./content.txt
-@endverbatim
-
-@subsubsection pf_storage_entities The Storage Entities
-
-These are the entities that you can use in your platform files to include
-storage in your model. See also the list of our @ref pf_storage_example_files "example files";
-these might also help you to get started.
-
-@anchor pf_storage_entity_storage_type
-#### @<storage_type@> ####
-
-Attribute name | Mandatory | Values | Description
---------------- | --------- | ------ | -----------
-id | yes | string | Identifier of this storage_type; used when referring to it
-model | no | string | In the future, this will allow to change the performance model to use
-size | yes | string | Specifies the amount of available storage space; you can specify storage like "500GiB" or "500GB" if you want. (TODO add a link to all the available abbreviations)
-content | yes | string | Path to a @ref pf_storage_content_file "Storage Content File" on your system. This file must exist.
-
-This tag must contain some predefined model properties, specified via the <model_prop> tag. Here is a list,
-see below for an example:
-
-Property id | Mandatory | Values | Description
---------------- | --------- | ------ | -----------
-Bwrite | yes | string | Bandwidth for write access; in B/s (but you can also specify e.g. "30MBps")
-Bread | yes | string | Bandwidth for read access; in B/s (but you can also specify e.g. "30MBps")
-
-@note
- A storage_type can also contain the <b><prop></b> tag. The <prop> tag allows you
- to associate additional information to this <storage_type> and follows the
- attribute/value schema; see the example below. You may want to use it to give information to
- the tool you use for rendering your simulation, for example.
-
-Here is a complete example for the ``storage_type`` tag:
-@verbatim
-<storage_type id="single_HDD" size="4000">
- <model_prop id="Bwrite" value="30MBps" />
- <model_prop id="Bread" value="100MBps" />
- <prop id="Brand" value="Western Digital" />
-</storage_type>
-@endverbatim
-
-@subsubsection pf_tag_storage <storage>
-
-Attributes | Mandatory | Values | Description
--------------- | --------- | ------ | -----------
-id | yes | string | Identifier of this ``storage``; used when referring to it
-typeId | yes | string | Here you need to refer to an already existing @ref pf_storage_entity_storage_type "@<storage_type@>"; the storage entity defined by this tag will then inherit the properties defined there.
-attach | yes | string | Name of a host (see Section @ref pf_tag_host) to which this storage is <i>physically</i> attached to (e.g., a hard drive in a computer)
-content | no | string | When specified, overwrites the content attribute of @ref pf_storage_entity_storage_type "@<storage_type@>"
-
-Here are two examples:
-
-@verbatim
- <storage id="Disk1" typeId="single_HDD" attach="bob" />
-
- <storage id="Disk2" typeId="single_SSD"
- content="content/win_storage_content.txt" />
-@endverbatim
-
-The first example is straightforward: A disk is defined and called "Disk1"; it is
-of type "single_HDD" (shown as an example of @ref pf_storage_entity_storage_type "@<storage_type@>" above) and attached
-to a host called "bob" (the definition of this host is omitted here).
-
-The second storage is called "Disk2", is still of the same type as Disk1 but
-now specifies a new content file (so the contents will be different from Disk1)
-and the filesystem uses the windows style; finally, it is attached to a second host,
-called alice (which is again not defined here).
-
-@subsubsection pf_tag_mount <mount>
-
-| Attribute | Mandatory | Values | Description |
-| ----------- | ----------- | -------- | ------------- |
-| id | yes | string | Refers to a @ref pf_tag_storage "<storage>" entity that will be mounted on that computer |
-| name | yes | string | Path/location to/of the logical reference (mount point) of this disk
-
-This tag must be enclosed by a @ref pf_tag_host tag. It then specifies where the mountpoint of a given storage device (defined by the ``id`` attribute)
-is; this location is specified by the ``name`` attribute.
-
-Here is a simple example, taken from the file ``examples/platform/storage.xml``:
-
-@verbatim
- <storage_type id="single_SSD" size="500GiB">
- <model_prop id="Bwrite" value="60MBps" />
- <model_prop id="Bread" value="200MBps" />
- </storage_type>
-
- <storage id="Disk2" typeId="single_SSD"
- content="content/win_storage_content.txt"
- attach="alice" />
- <storage id="Disk4" typeId="single_SSD"
- content="content/small_content.txt"
- attach="denise"/>
-
- <host id="alice" speed="1Gf">
- <mount storageId="Disk2" name="c:"/>
- </host>
-
- <host id="denise" speed="1Gf">
- <mount storageId="Disk2" name="c:"/>
- <mount storageId="Disk4" name="/home"/>
- </host>
-@endverbatim
-
-This example is quite interesting, as the same device, called "Disk2", is mounted by
-two hosts at the same time! Note, however, that the host called ``alice`` is actually
-attached to this storage, as can be seen in the @ref pf_tag_storage "<storage>"
-tag. This means that ``denise`` must access this storage through the network, but SimGrid automatically takes
-care of that for you.
-
-Furthermore, this example shows that ``denise`` has mounted two storages with different
-filesystem types (unix and windows). In general, a host can mount as many storage devices as
-required.
-
-@note
- Again, the difference between ``attach`` and ``mount`` is simply that
- an attached storage is always physically inside (or connected to) that machine;
- for instance, a USB stick is attached to one and only one machine (where it's plugged-in)
- but it can only be mounted on others, as mounted storage can also be a remote location.
-
-###### Example files #####
-
-@verbinclude example_filelist_xmltag_mount
-
-@subsubsection pf_storage_example_files Example files
-
-Several examples were already discussed above; if you're interested in full examples,
-check the the following platforms:
-
-1. ``examples/platforms/storage.xml``
-2. ``examples/platforms/remote_io.xml``
-
-If you're looking for some examplary C code, you may find the source code
-available in the directory ``examples/msg/io/`` useful.
-
-@subsubsection pf_storage_examples_modelling Modelling different situations
-
-The storage functionality of SimGrid is type-agnostic, that is, the implementation
-does not presume any type of storage, such as HDDs/SSDs, RAM,
-CD/DVD devices, USB sticks etc.
-
-This allows the user to apply the simulator for a wide variety of scenarios; one
-common scenario would be the access of remote RAM.
-
-#### Modelling the access of remote RAM ####
-
-How can this be achieved in SimGrid? Let's assume we have a setup where three hosts
-(HostA, HostB, HostC) need to access remote RAM:
-
-@verbatim
- Host A
- /
-RAM -- Host B
- @
- Host C
-@endverbatim
-
-An easy way to model this scenario is to setup and define the RAM via the
-@ref pf_tag_storage "storage" and @ref pf_storage_entity_storage_type "storage type"
-entities and attach it to a remote dummy host; then, every host can have their own links
-to this host (modelling for instance certain scenarios, such as PCIe ...)
-
-@verbatim
- Host A
- /
-RAM - Dummy -- Host B
- @
- Host C
-@endverbatim
-
-Now, if read from this storage, the host that mounts this storage
-communicates to the dummy host which reads from RAM and
-sends the information back.
-
@section pf_routing Routing
| @ref pf_routing_model_dijkstra "Dijkstra" | Dijkstra routing data. Calculates routes only when needed |
| @ref pf_routing_model_dijkstracache "DijkstraCache" | Dijkstra routing data. Handles some cache for already calculated routes. |
-All those shortest-path models are instanciated in the same way and are
+All those shortest-path models are instantiated in the same way and are
completely interchangeable. Here are some examples:
@anchor pf_routing_model_floyd
pass through link1, and get into zone2 by being received by router2.
router1 must belong to zone1 and router2 must belong to zone2.
-@subsubsection pf_tag_linkctn <link_ctn>
-
-This entity has only one purpose: Refer to an already existing
-@ref pf_tag_link "<link/>" when defining a route, i.e., it
-can only occur as a child of @ref pf_tag_route "<route/>"
-
-| Attribute name | Mandatory | Values | Description |
-| --------------- | --------- | ------ | ----------- |
-| id | yes | String | The identifier of the link that should be added to the route. |
-| direction | maybe | UP@|DOWN | If the link referenced by @c id has been declared as @ref pf_sharing_policy_splitduplex "SPLITDUPLEX", this indicates which direction the route traverses through this link: UP or DOWN. If you don't use SPLITDUPLEX, do not use this attribute or SimGrid will not find the right link.
-
-#### Example Files ####
-
-This is an automatically generated list of example files that use the @c <link_ctn/>
-entity (the path is given relative to SimGrid's source directory):
-
-@verbinclude example_filelist_xmltag_linkctn
-
@subsubsection pf_tag_zoneroute <zoneRoute>
The purpose of this entity is to define a route between two
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 to
+<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
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 to bypass
+<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.
- @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_tag_config <config>
-
-Adding configuration flags into the platform file is particularly
-useful when the described platform is best used with specific
-flags. For example, you could finely tune SMPI in your platform file directly.
-
-| Attribute | Values | Description |
-| ---------- | ------------------- | ---------------------------------------------- |
-| id | String (optional) | This optional identifier is ignored by SimGrid |
-
-* **Included tags:** @ref pf_tag_prop to specify a given configuration item (see @ref options).
-
-Any such configuration must be given at the very top of the platform file.
-
-* **Example**
-
-@verbatim
-<?xml version='1.0'?>
-<!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
-<platform version="4">
-<config>
- <prop id="maxmin/precision" 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" />
-</config>
-
-<zone id="zone0" routing="Full">
-...
-@endverbatim
-
-@subsection pf_tag_prop <prop>
-
-Defines a user-defined property, identified with a name and having a
-value. You can specify such properties to most kind of resources:
-@ref pf_tag_zone, @ref pf_tag_host, @ref pf_tag_storage,
-@ref pf_tag_cluster and @ref pf_tag_link. These values can be retrieved
-at runtime with MSG_zone_property() or simgrid::s4u::NetZone::property(),
-or similar functions.
-
-| Attribute | Values | Description |
-| --------- | ---------------------- | ----------------------------------------------------------------------------------------- |
-| id | String (mandatory) | Identifier of this property. Must be unique for a given property holder, eg host or link. |
-| value | String (mandatory) | Value of this property; The semantic is completely up to you. |
-
-* **Included tags:** none.
-
-#### Example ####
-
-@code{.xml}
-<prop id="Operating System" value="Linux" />
-@endcode
-
-
@subsection pf_trace trace and trace_connect
Both tags are an alternate way to pass files containing information on
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 instan
ciation if the accuracy really matters to you (see <a
+your instan
tiation 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
