\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. Each cluster is itself an AS.
-
-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>
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".
\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/>
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 ``#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).
-The last mode available is FULLDUPLEX. This means that SimGrid will
+\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 ####
\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 #####
TODO
+\subsubsection pf_backbone <backbone/>
+
+\note
+ This tag is <b>only available</b> when the containing AS uses the "Cluster" mode!
+
+TODO: Is default=shared correct?
+
+Attribute name | Mandatory | Values | Description
+--------------- | --------- | ------ | -----------
+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.
+
\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 :
