X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/0a21b9f790a054594bc96362331582333216a8c7..478e0a8f646095dcdf8869d6f5dbfb23964eb134:/doc/doxygen/platform.doc?ds=sidebyside diff --git a/doc/doxygen/platform.doc b/doc/doxygen/platform.doc index 021adbe2bb..7f7d0123c4 100644 --- a/doc/doxygen/platform.doc +++ b/doc/doxygen/platform.doc @@ -76,9 +76,8 @@ selected by specifying the routing attribute in the AS tag: \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 ```` tag; this tag takes two attributes, ``src`` (source) and ``dst`` (destination). Both source and destination must be valid identifiers @@ -88,29 +87,29 @@ to the destination specified in the tag. Hence, a route merely describes 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 host: a hostmachine; contains processors/cores etc. -\li router: a router or a gateway. -\li link: a link that defines a connection between two (or - more) resources. Every link has a bandwidth and a latency. -\li cluster: 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 (host/router and -AS); 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 (host/router +and AS). 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 ASroute: to define routes between two AS @@ -342,7 +341,7 @@ bb_lat | no | int | Latency for backbone (if any). See lin bb_sharing_policy | no | string | Sharing policy for the backbone (if any). See link section for syntax/details. availability_file | no | string | Allows you to use a file as input for availability. Similar to hosts attribute. state_file | no | string | Allows you to use a file as input for states. Similar to hosts attribute. -loopback_bw | no | int | Bandwidth for loopback (if any). See link 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 FATPIPE. +loopback_bw | no | int | Bandwidth for loopback (if any). See link 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 link 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), TORUS 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". @@ -434,16 +433,16 @@ is completely equivalent to the following declaration: \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. ````: 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. ````: Represents an entity that a message can be routed to, but that is unable to execute any code. In SimGrid, routers have also @@ -451,10 +450,12 @@ but a hyperedge) do they increase latency. As a matter of fact, routers are (almost) ignored by the simulator when the simulation has begun. +3. ````: 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 ```` (see section). Routers are used to run some routing algorithm and determine routes (see Section \ref pf_routing for details). -\endremark \subsubsection pf_router @@ -487,7 +488,7 @@ 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. +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. @@ -522,35 +523,40 @@ Picosecond | ps | 0.000000000001 = 10^(-12) #### 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 ```` 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 #### @@ -573,14 +579,13 @@ file. The structure of the files "link1.bw" and "link1.lat" is shown below. \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 ##### @@ -628,17 +633,30 @@ documentation (Section \ref pf_host) for an example. TODO +\subsubsection pf_backbone + +\note + This tag is only available 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 -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 :