\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
+\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,
+\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.
The complete bandwidth provided by this link in this mode
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 :
