\endverbatim
\remark
-Other supported values for the routing attribute can be found below, Section
-\ref pf_raf.
-\endremark
+ Other supported values for the routing attribute can be found below, Section
+ \ref pf_raf.
There is also the ``<route>`` tag; this tag takes two attributes, ``src`` (source)
and ``dst`` (destination). Both source and destination must be valid identifiers
how to reach a router from another router.
\remark
-More information and (code-)examples can be found in the Section \ref pf_rm.
-\endremark
-
-An AS can also contain one or more AS; this allows you to
-define the hierarchy of your platform.
-
-Within each AS, the following types of resources exist:
-\li <b>host</b>: a hostmachine; contains processors/cores etc.
-\li <b>router</b>: a router or a gateway.
-\li <b>link</b>: a link that defines a connection between two (or
- more) resources. Every link has a bandwidth and a latency.
-\li <b>cluster</b>: like a real cluster, contains many hosts
- interconnected by some dedicated network.
-
-Between these elements, a routing has to be defined. The AS is
-supposed to be Autonomous, hence this has to be done at the AS level. The AS
-handles two different types of entities (<b>host/router</b> and
-<b>AS</b>); you are responsible to define routes between those elements,
+ More information and (code-)examples can be found in Section \ref pf_rm.
+
+An AS can also contain itself one or more AS; this allows you to
+model the hierarchy of your platform.
+
+### Within each AS, the following types of resources exist:
+
+%Resource | Documented in Section | Description
+--------------- | --------------------- | -----------
+AS | | Every Autonomous System (AS) may contain one or more AS.
+host | \ref pf_host | This entity carries out the actual computation. For this reason, it contains processors (with potentially multiple cores).
+router | \ref pf_router | In SimGrid, routers are used to provide helpful information to routing algorithms. Routers may also act as gateways, connecting several autonomous systems with each other.
+link | \ref pf_link | In SimGrid, (network)links define a connection between two or potentially even more resources. Every link has a bandwidth and a latency and may potentially experience congestion.
+cluster | \ref pf_cluster | In SimGrid, clusters were introduced to model large and homogenous environments. They are not really a resource by themselves - technically, they are only a shortcut, as they will internally set up all the hosts, network and routing for you, i.e., using this resource, one can easily setup thousands of hosts and links in a few lines of code. Each cluster is itself an AS.
+
+%As it is desirable to interconnect these resources, a routing has to be
+defined. The AS is supposed to be Autonomous, hence this has to be done at the
+AS level. The AS handles two different types of entities (<b>host/router</b>
+and <b>AS</b>). However, the user is responsible to define routes between those resources,
otherwise entities will be unconnected and therefore unreachable from other
-entities. Although several algorithms for routing are built into SimGrid (see
-\ref pf_rm), you might encounter a case where you want to define
-routes manually (for instance, due to specific requirements of your
-platform).
+entities. Although several routing algorithms are built into SimGrid (see
+\ref pf_rm), you might encounter a case where you want to define routes
+manually (for instance, due to specific requirements of your platform).
There are three tags to use:
\li <b>ASroute</b>: to define routes between two <b>AS</b>
\section pf_pftags Resource description
-\subsection pf_As Platform: The \<AS\> tag
+\subsection pf_As Platform: The <AS> tag
The concept of an AS was already outlined above (Section \ref pf_basics);
recall that the AS is so important because it groups other resources (such
\subsection pf_Cr Computing resources: hosts, clusters and peers.
-\subsubsection pf_host The tag <host/>
+\subsubsection pf_host <host/>
A <b>host</b> represents a computer/node card. Every host is able to execute
code and it can send and receive data to/from other hosts. Most importantly,
--------------- | --------- | ------ | -----------
id | yes | String | The identifier of the host. facilitates referring to this AS.
power | yes | double (must be > 0.0) | Computational power of every core of this host in FLOPS. Must be larger than 0.0.
-core | no | int (Default: 1) | The number of cores of this host. If more than one core is specified, the "power" parameter refers to every core, i.e., the total computational power is #cores*power.<br /> If 6 cores are specified, up to 6 tasks can be executed without sharing the computational power; if more than 6 tasks are executed, computational power will be shared among these tasks. <br /> <b>Warning:</b> Although functional, this model was never scientifically assessed.
+core | no | int (Default: 1) | The number of cores of this host. If more than one core is specified, the "power" parameter refers to every core, i.e., the total computational power is no_of_cores*power.<br /> If 6 cores are specified, up to 6 tasks can be executed without sharing the computational power; if more than 6 tasks are executed, computational power will be shared among these tasks. <br /> <b>Warning:</b> Although functional, this model was never scientifically assessed.
availability | no | int | <b>Specify if the percentage of power available.</b> (What? TODO)
availability_file| no | string | (Relative or absolute) filename to use as input; must contain availability traces for this host. The syntax of this file is defined below. <br /> <b>Note:</b> The filename must be specified with your system's format.
state | no | ON\|OFF<br/> (Default: ON) | Is this host running or not?
Tag name | Description | Documentation
------------ | ----------- | -------------
-<mount/> | Defines mounting points between some storage resource and the host. | \ref pf_sto_mo
-<prop/> | The prop tag allows you to define additional information on this host following the attribute/value schema. You may want to use it to give information to the tool you use for rendering your simulation, for example. | N/A
+\<mount/\> | Defines mounting points between some storage resource and the host. | \ref pf_storage_entity_mount
+\<prop/\> | The prop tag allows you to define additional information on this host following the attribute/value schema. You may want to use it to give information to the tool you use for rendering your simulation, for example. | N/A
### Example ###
### Expressing dynamism ###
SimGrid provides mechanisms to change a hosts' availability over
-time, using the ``availability_file`` attribute to the ``<host>`` tag
+time, using the ``availability_file`` attribute to the ``\<host\>`` tag
and a separate text file whose syntax is exemplified below.
#### Adding a trace file ####
Let us begin to explain this example by looking at line 2. (Line 1 will become clear soon).
The first column describes points in time, in this case, time 0. The second column
describes the relative amount of power this host is able to deliver (relative
-to the maximum performance specified in the ``<host>`` tag). (Clearly, the
+to the maximum performance specified in the ``\<host\>`` tag). (Clearly, the
second column needs to contain values that are not smaller than 0 and not larger than 1).
In this example, our host will deliver 500 Mflop/s at time 0, as 500 Mflop/s is the
maximum performance of this host. At time 11.0, it will
so on.
+\subsubsection pf_cluster <cluster>
-\subsubsection pf_cluster <cluster>
-
-A <b>cluster</b> represents a cluster. It is most of the time used
-when you want to have a bunch of machine defined quickly. It must be
-noted that cluster is meta-tag : <b>from the inner SimGrid point of
+``<cluster />`` represents a machine-cluster. It is most commonly used
+when one wants to define many hosts and a network quickly. Technically,
+``cluster`` is a meta-tag: <b>from the inner SimGrid point of
view, a cluster is an AS where some optimized routing is defined</b>.
The default inner organization of the cluster is as follow:
\verbatim
- _________
+ __________
| |
| router |
____________|__________|_____________ backbone
c-0.me c-99.me
\endverbatim
-You have a set of <b>host</b> defined. Each of them has a <b>link</b>
-to a central backbone (backbone is a <b>link</b> itself, as a link can
-be used to represent a switch, see the switch or <b>link</b> section
-below for more details about it). A <b>router</b> gives a way to the
-<b>cluster</b> to be connected to the outside world. Internally,
-cluster is then an AS containing all hosts : the router is the default
+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
+<b>cluster</b> to the outside world. Internally,
+SimGrid treats a cluster as an AS containing all hosts: the router is the default
gateway for the cluster.
-There is an alternative organization, which is as follow :
+There is an alternative organization, which is as follows:
\verbatim
- _________
+ __________
| |
| router |
|__________|
host0 host1 host2
\endverbatim
-The principle is the same, except we don't have the backbone. The way
-to obtain it is simple : you just have to let bb_* attributes
-unset.
+The principle is the same, except that there is no backbone. This representation
+can be obtained easily: just do not set the bb_* attributes.
Attribute name | Mandatory | Values | Description
prefix | yes | string | Each node of the cluster has to have a name. This name will be prefixed with this prefix.
suffix | yes | string | Each node of the cluster will be suffixed with this suffix
radical | yes | string | 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.
-power | yes | int | Same as the ``power`` attribute of the ``<host>`` tag.
-core | no | int (default: 1) | Same as the ``core`` attribute of the ``<host>`` tag.
-bw | yes | int | Bandwidth for the links between nodes and backbone (if any). <b>See <b>link</b> section for syntax/details.</b>
+power | yes | int | Same as the ``power`` attribute of the ``\<host\>`` tag.
+core | no | int (default: 1) | Same as the ``core`` attribute of the ``\<host\>`` tag.
+bw | yes | int | Bandwidth for the links between nodes and backbone (if any). See the \ref pf_link "link section" for syntax/details.
lat | yes | int | Latency for the links between nodes and backbone (if any). See <b>link</b> section for syntax/details.
sharing_policy | no | string | Sharing policy for the links between nodes and backbone (if any). See <b>link</b> section for syntax/details.
bb_bw | no | int | Bandwidth for backbone (if any). See <b>link</b> section for syntax/details. If bb_bw and bb_lat (see below) attributes are omitted, no backbone is created (alternative cluster architecture <b>described before</b>).
bb_sharing_policy | no | string | Sharing policy for the backbone (if any). See <b>link</b> section for syntax/details.
availability_file | no | string | Allows you to use a file as input for availability. Similar to <b>hosts</b> attribute.
state_file | no | string | Allows you to use a file as input for states. Similar to <b>hosts</b> attribute.
-loopback_bw | no | int | Bandwidth for loopback (if any). See <b>link</b> section for syntax/details. If loopback_bw and loopback_lat (see below) attributes are omitted, no loopback link is created and all intra-node communication will use the main network link of the node. Loopback link is a <b>FATPIPE</b>.
+loopback_bw | no | int | Bandwidth for loopback (if any). See <b>link</b> section for syntax/details. If loopback_bw and loopback_lat (see below) attributes are omitted, no loopback link is created and all intra-node communication will use the main network link of the node. Loopback link is a \ref sharing_policy_fatpipe "\b FATPIPE".
loopback_lat | no | int | Latency for loopback (if any). See <b>link</b> section for syntax/details. See loopback_bw for more info.
topology | no | FLAT\|TORUS\|FAT_TREE (default: FLAT) | Network topology to use. SimGrid currently supports FLAT (with or without backbone, as described before), <a href="http://en.wikipedia.org/wiki/Torus_interconnect">TORUS </a> and FAT_TREE attributes for this tag.
topo_parameters | no | string | 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. For fat trees, refer to \ref AsClusterFatTree "AsClusterFatTree documentation".
c-99.me
\endverbatim
-\subsubsection pf_peer <peer/>
+\subsubsection pf_cabinet <cabinet>
+
+\note
+ This tag is only available when the routing mode of the AS
+ is set to ``Cluster``.
+
+The ``<cabinet />`` tag is, like the \ref pf_cluster "<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 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.
+power | yes | int | Same as the ``power`` attribute of the \ref pf_host "<host>" tag.
+bw | yes | int | Bandwidth for the links between nodes and backbone (if any). See the \ref pf_link "link section" for syntax/details.
+lat | yes | int | Latency for the links between nodes and backbone (if any). See the \ref pf_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 initial state of hosts/links
+ (always set to ON), the sharing policy of the links (always set to \ref sharing_policy_fullduplex "FULLDUPLEX").
+
+#### Example ####
+
+The following example was taken from ``examples/platforms/meta_cluster.xml`` and
+shows how to use the cabinet tag.
+
+\verbatim
+ <AS id="my_cluster1" routing="Cluster">
+ <cabinet id="cabinet1" prefix="host-" suffix=".cluster1"
+ power="1Gf" bw="125MBps" lat="100us" radical="1-10"/>
+ <cabinet id="cabinet2" prefix="host-" suffix=".cluster1"
+ power="1Gf" bw="125MBps" lat="100us" radical="11-20"/>
+ <cabinet id="cabinet3" prefix="host-" suffix=".cluster1"
+ power="1Gf" bw="125MBps" lat="100us" radical="21-30"/>
+
+ <backbone id="backbone1" bandwidth="2.25GBps" latency="500us"/>
+ </AS>
+\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.
+
+
+\subsubsection pf_peer The <peer> tag
This tag represents a peer, as in Peer-to-Peer (P2P) networks. However, internally,
SimGrid transforms a peer into an AS (similar to Cluster). Hence, this tag
availability_file| no | string | Availability file for the peer. Same as host availability file. See <b>host</b> description for details.
state_file | no | string | State file for the peer. Same as host state file. See <b>host</b> description for details.
-Internally, SimGrid transforms any ``<peer/>`` construct such as
+Internally, SimGrid transforms any ``\<peer/\>`` construct such as
\verbatim
<peer id="FOO"
coordinates="12.8 14.4 6.4"
bw_out="2.25GBps"
lat="500us" />
\endverbatim
-into an ``<AS>`` (see Sections \ref pf_basics and \ref pf_As). In fact, this example of the ``<peer/>`` tag
+into an ``\<AS\>`` (see Sections \ref pf_basics and \ref pf_As). In fact, this example of the ``\<peer/\>`` tag
is completely equivalent to the following declaration:
\verbatim
\subsection pf_ne Network equipments: links and routers
-There are two tags available to represent network entities:
+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>``: Represents a entity that has a limited bandwidth, a
latency, and that can be shared according to TCP way to share this
bandwidth.
\remark
-The concept of links in SimGrid may not be intuitive, as links are not limited
-to connecting (exactly) two entities; in fact, you can have more than two equipments
-connected to it. (In graph theoretical terms: A link in SimGrid is not an edge,
-but a hyperedge)
-\endremark
+ The concept of links in SimGrid may not be intuitive, as links are not limited
+ to connecting (exactly) two entities; in fact, you can have more than two equipments
+ connected to it. (In graph theoretical terms: A link in SimGrid is not an edge,
+ but a hyperedge)
2. ``<router/>``: Represents an entity that a message can be routed
to, but that is unable to execute any code. In SimGrid, routers have also
do they increase latency. As a matter of fact, routers are (almost) ignored
by the simulator when the simulation has begun.
+3. ``<backbone/>``: This tag is only available when the containing AS 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).
-\endremark
-\subsubsection pf_router <router/>
+\subsubsection pf_router <router/>
%As said before, <b>router</b> is used only to give some information
for routing algorithms. So, it does not have any attributes except :
<router id="gw_dc1_horizdist"/>
\endverbatim
-\subsubsection pf_link <link>
+\subsubsection pf_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
id | yes | string | The identifier of the link to be used when referring to it.
bandwidth | yes | int | Maximum bandwidth for this link, given in bytes/s
latency | no | double (default: 0.0) | Latency for this link.
-sharing_policy | no | SHARED\|FATPIPE\|FULLDUPLEX (default: SHARED) | Sharing policy for the link.
+sharing_policy | no | \ref sharing_policy_shared "SHARED"\|\ref sharing_policy_fatpipe "FATPIPE"\|\ref sharing_policy_fullduplex "FULLDUPLEX" (default: SHARED) | Sharing policy for the link.
state | no | ON\|OFF (default: ON) | Allows you to to turn this link on or off (working / not working)
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.
#### Sharing policy ####
-By default a network link is SHARED, i.e., if two or more data flows go
-through a link, the bandwidth is shared fairly among the data flows. This
+\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.
-On the other hand, if a link is defined as a FATPIPE,
-each flow going through this link will be allocated the complete bandwidth,
-i.e., no sharing occurs and the bandwidth is only limiting single flows:
+\anchor 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 ``#flows*bandwidth``.
+is ``number_of_flows*bandwidth``, with at most ``bandwidth`` being available per flow.
-The last mode available is FULLDUPLEX. This means that SimGrid will
+Using the FATPIPE mode allows to model backbones that won't affect performance
+(except latency).
+
+\anchor sharing_policy_fullduplex
+The last mode available is \b FULLDUPLEX. 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.
-\endremark
+ 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).
-\endremark
+ Tip: By using the FATPIPE mode, you can model big backbones that
+ won't affect performance (except latency).
#### Example ####
#### 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_hosts_dynamism for details).
+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.
\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.
- \endnote
+ 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 #####
#### The ``<prop/>`` tag ####
-Similar to ``
<host>``, the link may also contain the ``<prop/>`` tag; see the host
+Similar to ``
\<host\>``, the link may also contain the ``<prop/>`` tag; see the host
documentation (Section \ref pf_host) for an example.
TODO
+\subsubsection pf_backbone <backbone/>
+
+\note
+ This tag is <b>only available</b> when the containing AS uses the "Cluster" 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.
+
\subsection pf_storage Storage
\note
-This is a prototype version that should evolve quickly, this
-is just some doc valuable only at the time of writing this doc</b>
-This section describes the storage management under SimGrid ; nowadays
-it's only usable with MSG. It relies basically on linux-like concepts.
-You also may want to have a look to its corresponding section in \ref
-msg_file_management ; functions access are organized as a POSIX-like
-interface.
-\endnote
+ This is a prototype version that should evolve quickly, this
+ is just some doc valuable only at the time of writing this doc
+ This section describes the storage management under SimGrid ; nowadays
+ it's only usable with MSG. It relies basically on linux-like concepts.
+ You also may want to have a look to its corresponding section in \ref
+ msg_file_management ; functions access are organized as a POSIX-like
+ interface.
\subsubsection pf_sto_conc Storage Main concepts
-Basically there is 3 different entities to know :
-\li the <b>storage_type</b>: here you define some kind of storage that
- you will instantiate many type on your platform. Think of it like
- a definition of throughput of a specific disk.
-\li the <b>storage</b>: instance of a <b>storage_type</b>. Defines a
- new storage of <b>storage_type</b>
-\li the <b>mount</b>: says that the storage is located into this
- specific resource.
-
-the content of a storage has to be defined in a content file that
-contains the content. The path to this file has to be passed within
-the <b>content</b> attribute . Here is a way to generate it:
+Basically there are 3 different entities available in SimGrid that
+can be used to model storages:
+
+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), content, ... 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 size or read/write performance).
+\ref pf_storage_entity_storage "storage" | Defines an actual instance of a storage (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_storage_entity_mount "mount" | Must be wrapped by a \ref pf_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 in 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 File ####
+
+Here is an excerpt from two storage 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 /path/you/want -type f -exec ls -l {} \; 2>/dev/null > ./content.txt
\endverbatim
-\subsubsection pf_sto_sttp storage_type
+\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.
-<b>storage_type</b> attributes :
-\li <b>id (mandatory)</b>: the identifier of the storage_type to be
- used when referring to it.
-\li <b>model (mandatory)</b>: Unused for now by the simulator (but
- mandatory, ok)
-\li <b>content</b>: default value 0. The file containing the disk
- content. (may be moved soon or later to <b>storage</b> tag.
+\anchor pf_storage_entity_storage_type
+#### \<storage_type\> ####
-The tag must contains some predefined model prop, as may do some other
-resources tags.
-<b>storage_type</b> mandatory <b>model_prop</b> :
-\li <b>Bwrite</b>: value in B/s. Write throughput
-\li <b>Bread</b>: value in B/s. Read throughput
-\li <b>Bconnexion</b>: value in B/s. Connection throughput (i.e. the
- throughput of the storage connector).
+Attribute name | Mandatory | Values | Description
+--------------- | --------- | ------ | -----------
+id | yes | string | Identifier of this storage_type; used when referring to it
+model | yes | string | For reasons of future backwards compatibility only; specifies the name of the model for the storage that should be used
+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.
+content_type | no | ("txt_unix"\|"txt_win") | Determines which kind of filesystem you're using; make sure the filenames (stored in that file, see \ref pf_storage_content_file_structure "Storage Content File Structure"!)
-A storage_type can also contain the <b>prop</b> tag. The prop tag allows you
-to define additional information on this storage_type following the
-attribute/value schema. You may want to use it to give information to
-the tool you use for rendering your simulation, for example.
+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")
+Bconnexion | yes | string | Throughput (of the storage connector) in B/s.
+
+\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" model="linear_no_lat" size="4000" content_type="txt_unix">
<model_prop id="Bwrite" value="30MBps" />
<model_prop id="Bread" value="100MBps" />
<model_prop id="Bconnection" value="150MBps" />
- <b><prop id="Brand" value="Western Digital" /></b>
+ <prop id="Brand" value="Western Digital" />
</storage_type>
\endverbatim
-\subsubsection pf_sto_st storage
+\anchor pf_storage_entity_storage
+#### <storage> ####
-<b>storage_type</b> attributes :
-\li <b>id (mandatory)</b>: the identifier of the storage to be used
- when referring to it.
-\li <b>typeId (mandatory)</b>: the identifier of the storage_type that
- this storage belongs to.
-\li <b>attach (mandatory)</b>: the host (name) to which the storage is
- attached to.
+``storage`` attributes:
-\subsubsection pf_sto_mo mount
+Attribute name | 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_host) that this storage is <i>physically</i> attached to (e.g., a harddrive in a computer)
+content | no | string | When specified, overwrites the content attribute of \ref pf_storage_entity_storage_type "\<storage_type\>"
+content_type | no | string | When specified, overwrites the content_type attribute of \ref pf_storage_entity_storage_type "\<storage_type\>"
-<b>mount</b> attributes :
-\li <b>id (mandatory)</b>: the id of the <b>storage</b> that must be
- mounted on that computer.
-\li <b>name (mandatory)</b>: the name that will be the logical
- reference to this disk (the mount point).
+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"
+ content_type="txt_windows" attach="alice" />
+\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 content 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).
+
+\anchor pf_storage_entity_mount
+#### <mount> ####
+
+Attributes:
+| Attribute name | Mandatory | Values | Description |
+| ---------------- | ----------- | -------- | ------------- |
+| id | yes | string | Refers to a \ref pf_storage_entity_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_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" model="linear_no_lat" size="500GiB">
+ <model_prop id="Bwrite" value="60MBps" />
+ <model_prop id="Bread" value="200MBps" />
+ <model_prop id="Bconnection" value="220MBps" />
+ </storage_type>
+
+ <storage id="Disk2" typeId="single_SSD"
+ content="content/win_storage_content.txt"
+ content_type="txt_windows" attach="alice" />
+ <storage id="Disk4" typeId="single_SSD"
+ content="content/small_content.txt"
+ content_type="txt_unix" attach="denise"/>
+
+ <host id="alice" power="1Gf">
+ <mount storageId="Disk2" name="c:"/>
+ </host>
+
+ <host id="denise" power="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_storage_entity_storage "<storage>"
+tag. This means that ``denise`` must access this storage via 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.
+
+\anchor pf_storage_entity_mstorage
+#### <mstorage> ####
+\note
+ This is currently unused.
-\subsubsection pf_sto_mst mstorage
-<b>Note : unused for now</b>
<b>mstorage</b> attributes :
\li <b>typeId (mandatory)</b>: the id of the <b>storage</b> that must
be mounted on that computer.
\li <b>name (mandatory)</b>: the name that will be the logical
reference to this disk (the mount point).
+\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 storagei, 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_storage_entity_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
To achieve high performance, the routing tables used within SimGrid are
<config id="General">
<prop id="maxmin/precision" value="0.000010"></prop>
<prop id="cpu/optim" value="TI"></prop>
- <prop id="workstation/model" value="compound"></prop>
+ <prop id="host/model" value="compound"></prop>
<prop id="network/model" value="SMPI"></prop>
<prop id="path" value="~/"></prop>
<prop id="smpi/bw_factor" value="65472:0.940694;15424:0.697866;9376:0.58729"></prop>
pointer functions to some the right surf functions. Since there can be
more than one callback attached to the same event (if more than one
model is in use, for example), they are stored in a dynar. Example in
-workstation_ptask_L07.c:
+host_ptask_L07.c:
\verbatim
/* Adding callback functions */
surf_parse_reset_parser();
