X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/7897fb8815dbff65907f646efb6f3ccf024e5481..HEAD:/doc/doxygen/platform.doc diff --git a/doc/doxygen/platform.doc b/doc/doxygen/platform.doc deleted file mode 100644 index a4902d63dc..0000000000 --- a/doc/doxygen/platform.doc +++ /dev/null @@ -1,1516 +0,0 @@ -/*! \page platform Platform Description - -@tableofcontents - -In order to run any simulation, SimGrid needs 3 things: something to run -(so, your code), a description of the platform on which you want to run your -application, and finally it needs something to know where to deploy what. - -For the latest 2 entries, you have basically 2 ways to give it as an input : -\li You can program it, either using the Lua console (\ref - MSG_Lua_funct) or if you're using MSG some of its platform and - deployments functions(\ref msg_simulation). If you want to use it, - please refer to its doc. (you can also check the section \ref - pf_flexml_bypassing but this is strongly deprecated, as there is a - new way to do it properly, but not yet documented). -\li You can use two XML files: a platform description file and a - deployment description one. - -For the deployment stuff, please take a look at \ref deployment - -The platform description may be complicated. This documentation is all -about how to write this file: what are the basic concept it relies on, -what possibilities are offered, and some hints and tips on how to -write a good platform description. - -\section pf_overview Some words about XML and DTD - -We choose to use XML because of some of its possibilities: if you're -using an accurate XML editor, or simply using any XML plug-in for -eclipse, it will allow you to have cool stuff like auto-completion, -validation and checking, so all syntax errors may be avoided this -way. - -the XML checking is done based on the dtd which is nowadays online at -http://simgrid.gforge.inria.fr/simgrid.dtd -while you might be tempted to read it, it will not help you that much. - -If you read it, you should notice two or three important things : -\li The platform tags contains a version attributes. At the time of - writing this doc the current version is 3. -\li The DTD contains definitions for the 2 files used by SimGrid (platform - description and deployment). -\li There is a bunch of possibilities ! Let's see what's in it - - -\section pf_basics Basic concepts - -Nowadays, the Internet is composed of a bunch of independently managed -networks. Within each of those networks, there are entry and exit -points (most of the time, you can both enter and exit through the same -point) that allows to go out of the current network and reach other -networks. At the upper level, these networks are known as -Autonomous System (AS), while at the lower level they are named -sub-networks, or LAN. Indeed they are autonomous: routing is defined -within the limits of his network by the administrator, and so, those -networks can continue to operate without the existence of other -networks. There are some rules to get out of networks by the entry -points (or gateways). Those gateways allow you to go from a network to -another one. Inside of each autonomous system, there is a bunch of -equipments (cables, routers, switches, computers) that belong to the -autonomous system owner. - -SimGrid platform description file relies exactly on the same concepts -as real life platform. Every resource (computers, network equipments, -and so on) belongs to an AS. Within this AS, you can define the -routing you want between its elements (that's done with the routing -model attribute and eventually with some \ tag). You define AS -by using ... well ... the \ tag. An AS can also contain some AS : -AS allows you to define the hierarchy of your platform. - -Within each AS, you basically have the following type of resources: -\li host: an host, with cores in it, and so on -\li router: a router or a gateway. -\li link: a link, that defines a connection between two (or - more) resources (and have a bandwidth and a latency) -\li cluster: like a real cluster, contains many hosts - interconnected by some dedicated network. - -Between those elements, a routing has to be defined. As the AS is -supposed to be Autonomous, this has to be done at the AS level. As AS -handles two different types of entities (host/router and -AS) you will have to define routes between those elements. A -network model have to be provided for AS, but you may/will need, -depending of the network model, or because you want to bypass the -default behavior to defines routes manually. There are 3 tags to use: -\li ASroute: to define routes between two AS -\li route: to define routes between two host/router -\li bypassRoute: to define routes between two AS that - will bypass default routing. - -Here is an illustration of the overall concepts: - -\htmlonly - -
-\endhtmlonly - Circles represent processing units and squares represent network routers. Bold - lines represent communication links. AS2 models the core of a national - network interconnecting a small flat cluster (AS4) and a larger - hierarchical cluster (AS5), a subset of a LAN (AS6), and a set of peers - scattered around the world (AS7). - - -This is all for the concepts ! To make a long story short, a SimGrid -platform is made of a hierarchy of AS, each of them containing -resources, and routing is defined at AS level. Let's have a deeper -look in the tags. - - - -\section pf_pftags Describing resources and their organization - -\subsection pf_As Platform organization tag : AS - -AS (or Autonomous System) is an organizational unit that contains -resources and defines routing between them, and eventually some other -AS. So it allows you to define a hierarchy into your platform. -*ANY* resource *MUST* belong to an AS. There are a few -attributes. - -AS attributes : -\li id (mandatory): the identifier of AS to be used when - referring to it. -\li routing (mandatory): the routing model used into it. By - model we mean the internal way the simulator will manage routing. - That also have a big impact on how many information you'll have to - provide to help the simulator to route between the AS elements. - routing possible values are Full, Floyd, Dijkstra, - DijkstraCache, none, Vivaldi, Cluster. For more - explanation about what to choose, take a look at the section - devoted to it below. - -Elements into an AS are basically resources (computers, network -equipments) and some routing information if necessary (see below for -more explanation). - -AS example -\verbatim - - - - - - -\endverbatim - -In this example, AS0 contains two hosts (host1 and host2). The route -between the hosts goes through link1. - - -\subsection pf_Cr Computing resources: hosts, clusters and peers. - -\subsubsection pf_host host - -A host represents a computer, where you will be able to execute -code and from which you can send and receive information. A host can -contain more than 1 core. Here are the attributes of a host : - - -host attributes : -\li id (mandatory): the identifier of the host to be used when - referring to it. -\li power (mandatory):the peak number FLOPS the CPU can manage. - Expressed in flop/s. -\li core: The number of core of this host (by default, 1). If - you specify the amount of cores, the 'power' parameter is the power - of each core. - For example, if you specify that your host has 6 cores, it will be - available to up to 6 sequential tasks without sharing. If more - tasks are placed on this host, the resource will be shared - accordingly. For example, if you schedule 12 tasks on that host, - each will get half of the specified computing power. Please note - that although sound, this model were never scientifically assessed. - Please keep this fact in mind when using it. -\li availability: specify if the percentage of power available. -\li availability_file: Allow you to use a file as input. This - file will contain availability traces for this computer. The - syntax of this file is defined below. Possible values : absolute - or relative path, syntax similar to the one in use on your system. -\li state: the computer state, as in : is that computer ON or - OFF. Possible values : "ON" or "OFF". -\li state_file: Same mechanism as availability_file, similar - syntax for value. -\li coordinates: you'll have to give it if you choose the - vivaldi, coordinate-based routing model for the AS the host - belongs to. More details about it in the P2P coordinate based - section. - -An host can contain some mount that defines mounting points -between some storage resource and the host. Please refer to the -storage doc for more information. - -An host can also contain the prop tag. 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. - -host example -\verbatim - - - - - -\endverbatim - - -Expressing dynamicity. -It is also possible to seamlessly declare a host whose -availability changes over time using the availability_file -attribute and a separate text file whose syntax is exemplified below. - -Adding a trace file -\verbatim - - - -\endverbatim -Example of "bob.trace" file -\verbatim -PERIODICITY 1.0 - 0.0 1.0 - 11.0 0.5 - 20.0 0.8 -\endverbatim - -At time 0, our host will deliver 500~Mflop/s. At time 11.0, it will -deliver half, that is 250~Mflop/s until time 20.0 where it will -will start delivering 80\% of its power, that is 400~Mflop/s. Last, at -time 21.0 (20.0 plus the periodicity 1.0), we loop back to the -beginning and the host will deliver again 500~Mflop/s. - -Changing initial state - -It is also possible to specify whether the host -is up or down by setting the state attribute to either ON -(default value) or OFF. - -Expliciting the default value "ON" -\verbatim - - - -\endverbatim -Host switched off -\verbatim - - - -\endverbatim -Expressing churn -To express the fact that a host can change state over time (as in P2P -systems, for instance), it is possible to use a file describing the time -at which the host is turned on or off. An example of the content -of such a file is presented below. -Adding a state file - \verbatim - - - - \endverbatim -Example of "bob.fail" file -\verbatim - PERIODICITY 10.0 - 1.0 -1.0 - 2.0 1.0 -\endverbatim - -A negative value means down while a positive one means up and - running. From time 0.0 to time 1.0, the host is on. At time 1.0, it is -turned off and at time 2.0, it is turned on again until time 12 (2.0 plus the -periodicity 10.0). It will be turned on again at time 13.0 until time 23.0, and -so on. - - - -\subsubsection pf_cluster cluster - -A cluster 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 : from the inner SimGrid point of -view, a cluster is an AS where some optimized routing is defined. -The default inner organization of the cluster is as follow: - -\verbatim - _________ - | | - | router | - ____________|__________|_____________ backbone - | | | | | | - l0| l1| l2| l97| l96 | | l99 - | | | ........ | | | - | | - c-0.me c-99.me -\endverbatim - -You have a set of host defined. Each of them has a link -to a central backbone (backbone is a link itself, as a link can -be used to represent a switch, see the switch or link section -below for more details about it). A router gives a way to the -cluster to be connected to the outside world. Internally, -cluster is then an AS containing all hosts : the router is the default -gateway for the cluster. - -There is an alternative organization, which is as follow : -\verbatim - _________ - | | - | router | - |__________| - / | \ - / | \ - l0 / l1| \l2 - / | \ - / | \ - 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. - - - -cluster attributes : -\li id (mandatory): the identifier of the cluster to be used - when referring to it. -\li prefix (mandatory): each node of the cluster has to have a - name. This is its prefix. -\li suffix (mandatory): node suffix name. -\li radical (mandatory): regexp used to generate cluster nodes - name. Syntax is quite common, "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. -\li power (mandatory): same as host power. -\li core: same as host core. -\li bw (mandatory): bandwidth for the links between nodes and - backbone (if any). See link section for syntax/details. -\li lat (mandatory): latency for the links between nodes and - backbone (if any). See link section for syntax/details. -\li sharing_policy: sharing policy for the links between nodes - and backbone (if any). See link section for syntax/details. -\li bb_bw : bandwidth for backbone (if any). See link - section for syntax/details. If both bb_* attributes are omitted, - no backbone is created (alternative cluster architecture described - before). -\li bb_lat : latency for backbone (if any). See link - section for syntax/details. If both bb_* attributes are omitted, - no backbone is created (alternative cluster architecture described - before). -\li bb_sharing_policy: sharing policy for the backbone (if - any). See link section for syntax/details. -\li availability_file: Allow you to use a file as input for - availability. Similar to hosts attribute. -\li state_file: Allow you to use a file as input for states. - Similar to hosts attribute. -\li loopback_bw : bandwidth for loopback (if any). See link - section for syntax/details. If both loopback_* 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. -\li loopback_lat : latency for loopback (if any). See link - section for syntax/details. See loopback_bw for more info. -\li topology : network topology to use. For now SimGrid supports FLAT - (default, with or without backbone, as described before) or - TORUS - attributes for this tag. -\li topo_parameters : 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. - - -the router name is defined as the resulting String in the following -java line of code: - -@verbatim -router_name = prefix + clusterId + _router + suffix; -@endverbatim - - -cluster example -\verbatim - - - -\endverbatim -The second examples creates one router and 100 machines, which names -are the following: -\verbatim -c-my_cluster_1_router.me -c-0.me -c-1.me -c-2.me -... -c-99.me -\endverbatim - -\subsubsection pf_peer peer -A peer represents a peer, as in Peer-to-Peer (P2P). Basically, -as cluster, A PEER IS INTERNALLY INTERPRETED AS AN \. It's -just a kind of shortcut that does the following : - -\li It creates a tiny AS whose routing type is cluster -\li It creates an host -\li Two links : one for download and one for upload. This is - convenient to use and simulate stuff under the last mile model (as - ADSL peers). -\li It connects the two links to the host -\li It creates a router (a gateway) that serve as entry point for this peer zone. - This router has coordinates. - -peer attributes : -\li id (mandatory): the identifier of the peer to be used when - referring to it. -\li power CDATA (mandatory): as in host -\li bw_in CDATA (mandatory): bandwidth in. -\li bw_out CDATA (mandatory):bandwidth out. -\li lat CDATA (mandatory): Latency for in and out links. -\li coordinates: coordinates of the gateway for this peer. -\li sharing_policy: sharing policy for links. Can be SHARED or - FULLDUPLEX, FULLDUPLEX is the default. See link description - for details. -\li availability_file: availability file for the peer. Same as - host availability file. See host description for details. -\li state_file : state file for the peer. Same as host state - file. See host description for details. - -In term of XML, the peer construct can be explained as follows: it transforms -\verbatim - -\endverbatim -into -\verbatim - - - - - - - -\endverbatim - - -\subsection pf_ne Network equipments: links and routers - -You have basically two entities available to represent network entities: -\li link: represents something that has a limited bandwidth, a - latency, and that can be shared according to TCP way to share this - bandwidth. LINKS ARE NOT EDGES BUT HYPEREDGES: it means - that you can have more than 2 equipments connected to it. -\li router: represents something that one message can be routed - to, but does not accept any code, nor have any influence on the - performances (no bandwidth, no latency, not anything).ROUTERS - ARE ENTITIES (ALMOST) IGNORED BY THE SIMULATOR WHEN THE SIMULATION - HAS BEGUN. If you want to represent something like a switch, - you must use link (see section below). Routers are used in - order to run some routing algorithm and determine routes (see - routing section for details). - -let's see deeper what those entities hide. - -\subsubsection pf_router router -As said before, router is used only to give some information -for routing algorithms. So, it does not have any attributes except : - -router attributes : -\li id (mandatory): the identifier of the router to be used - when referring to it. - \li coordinates: you'll have to give it if you choose the - vivaldi, coordinate-based routing model for the AS the host - belongs to. More details about it in the P2P coordinates based - section. - -router example -\verbatim - -\endverbatim - -\subsubsection pf_link link - -Network links can represent one-hop network connections. They are -characterized by their id and their bandwidth. The latency is optional -with a default value of 0.0. For instance, we can declare a network -link named link1 having bandwidth of 1Gb/s and a latency of 50µs. -Example link: - -\verbatim - -\endverbatim -Expressing sharing policy - -By default a network link is SHARED, that is if more than one flow go -through a link, each gets a share of the available bandwidth similar -to the share TCP connections offers. - -Conversely if a link is defined as a FATPIPE, each flow going through -this link will get all the available bandwidth, whatever the number of -flows. The FATPIPE behavior allows to describe big backbones that -won't affect performances (except latency). Finally a link can be -considered as FULLDUPLEX, that means that in the simulator, 2 links -(one named UP and the other DOWN) will be created for each link, so as -the 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 link_ctn description. - -\verbatim - -\endverbatim - -Expressing dynamicity and failures - -As for hosts, it is possible to declare links whose state, bandwidth -or latency change over the time. In this case, the bandwidth and -latency attributes are respectively replaced by the bandwidth file and -latency file attributes and the corresponding text files. - -\verbatim - -\endverbatim - -It has to be noted that even if the syntax is the same, the semantic -of bandwidth and latency trace files differs from that of host -availability files. Those 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 -\verbatim - -1 PERIODICITY 12.0 -2 4.0 40000000 -3 8.0 60000000 -\endverbatim -Example of "link1.lat" file -\verbatim - 1 PERIODICITY 5.0 -2 1.0 0.001 -3 2.0 0.01 -4 3.0 0.001 -\endverbatim - -In this example, the bandwidth varies with a period of 12 seconds -while the latency varies with a period of 5 seconds. At the beginning -of simulation, the link’s bandwidth is of 80,000,000 B/s (i.e., 80 -Mb/s). After four seconds, it drops at 40 Mb/s, and climbs back to 60 -Mb/s after eight seconds. It keeps that way until second 12 (ie, until -the end of the period), point at which it loops its behavior (seconds -12-16 will experience 80 Mb/s, 16-20 40 Mb/s and so on). In the same -time, the latency values are 100µs (initial value) on the [0, 1[ time -interval, 1ms on [1, 2[, 10ms on [2, 3[, 1ms on [3,5[ (i.e., until the -end of period). It then loops back, starting at 100µs for one second. - -link attributes : -\li id (mandatory): the identifier of the link to be used when referring to it. -\li bandwidth (mandatory): bandwidth for the link. -\li lat : latency for the link. Default is 0.0. -\li sharing_policy: sharing policy for the link. -\li state: Allow you to to set link as ON or OFF. Default is ON. -\li bandwidth_file: Allow you to use a file as input for bandwidth. -\li latency_file: Allow you to use a file as input for latency. -\li state_file: Allow you to use a file as input for states. - -As an host, a link tag can also contain the prop tag. - -link example -\verbatim - -\endverbatim - - -\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. - -\subsubsection pf_sto_conc Storage Main concepts -Basically there is 3 different entities to know : -\li the storage_type: 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 storage: instance of a storage_type. Defines a - new storage of storage_type -\li the mount: 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 content attribute . Here is a way to generate it: - -\verbatim -find /path/you/want -type f -exec ls -l {} \; 2>/dev/null > ./content.txt -\endverbatim - -\subsubsection pf_sto_sttp storage_type - - -storage_type attributes : -\li id (mandatory): the identifier of the storage_type to be - used when referring to it. -\li model (mandatory): Unused for now by the simulator (but - mandatory, ok) -\li content: default value 0. The file containing the disk - content. (may be moved soon or later to storage tag. - -The tag must contains some predefined model prop, as may do some other -resources tags. -storage_type mandatory model_prop : -\li Bwrite: value in B/s. Write throughput -\li Bread: value in B/s. Read throughput -\li Bconnexion: value in B/s. Connection throughput (i.e. the - throughput of the storage connector). - -A storage_type can also contain the prop 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. - -\verbatim - - - - - - -\endverbatim - -\subsubsection pf_sto_st storage - -storage_type attributes : -\li id (mandatory): the identifier of the storage to be used - when referring to it. -\li typeId (mandatory): the identifier of the storage_type that - this storage belongs to. -\li attach (mandatory): the host (name) to which the storage is - attached to. - -\subsubsection pf_sto_mo mount - -mount attributes : -\li id (mandatory): the id of the storage that must be - mounted on that computer. -\li name (mandatory): the name that will be the logical - reference to this disk (the mount point). - -\subsubsection pf_sto_mst mstorage -Note : unused for now -mstorage attributes : -\li typeId (mandatory): the id of the storage that must - be mounted on that computer. -\li name (mandatory): the name that will be the logical - reference to this disk (the mount point). - -\section pf_routing Routing - -In order to run fast, it has been chosen to use static routing within -SimGrid. By static, it means that it is calculated once (or almost), -and will not change during execution. We chose to do that because it -is rare to have a real deficiency of a resource ; most of the time, a -communication fails because the links are too overloaded, and so your -connection stops before the time out, or because the computer at the -other end is not answering. - -We also chose to use shortest paths algorithms in order to emulate -routing. Doing so is consistent with the reality: RIP, OSPF, BGP are -all calculating shortest paths. They have some convergence time, but -at the end, so when the platform is stable (and this should be the -moment you want to simulate something using SimGrid) your packets will -follow the shortest paths. - -\subsection pf_rm Routing models - -Within each AS, you have to define a routing model to use. You have -basically 3 main kind of routing models : - -\li Shortest-path based models: you let SimGrid calculates shortest - paths and manage it. Behaves more or less as most real life - routing. -\li Manually-entered route models: you'll have to define all routes - manually by yourself into the platform description file. - Consistent with some manually managed real life routing. -\li Simple/fast models: those models offers fast, low memory routing - algorithms. You should consider to use it if you can make some - assumptions about your AS. Routing in this case is more or less - ignored - -\subsubsection pf_raf The router affair - -Expressing routers becomes mandatory when using shortest-path based -models or when using ns-3 or the bindings to the GTNetS packet-level -simulator instead of the native analytical network model implemented -in SimGrid. - -For graph-based shortest path algorithms, routers are mandatory, -because both algorithms need a graph, and so we need to have source -and destination for each edge. - -Routers are naturally an important concept in GTNetS or ns-3 since the -way they run the packet routing algorithms is actually simulated. -Instead, the SimGrid’s analytical models aggregate the routing time -with the transfer time. Rebuilding a graph representation only from -the route information turns to be a very difficult task, because of -the missing information about how routes intersect. That is why we -introduced a \ tag, which is simply used to express these -intersection points. The only attribute accepted by this tag an id. It -is important to understand that the \ tag is only used to -provide topological information. - -To express those topological information, some route have to be -defined saying which link is between which routers. Description or the -route syntax is given below, as well as example for the different -models. - -\subsubsection pf_rm_sh Shortest-path based models - -Here is the complete list of such models, that computes routes using -classic shortest-paths algorithms. How to choose the best suited -algorithm is discussed later in the section devoted to it. - -\li Floyd: Floyd routing data. Pre-calculates all routes once. -\li Dijkstra: Dijkstra routing data ,calculating routes when - necessary. -\li DijkstraCache: Dijkstra routing data. Handle some cache for - already calculated routes. - -All those shortest-path models are instanciated the same way. Here are -some example of it: - -Floyd example : -\verbatim - - - - - - - - - - - - - - - -\endverbatim - -ASroute given at the end gives a topological information: link1 is -between router1 and host1. - -Dijsktra example : -\verbatim - - - - - - - - - - - - - - - - -\endverbatim - -DijsktraCache example : -\verbatim - - - ... -(platform unchanged compared to upper example) -\endverbatim - -\subsubsection pf_rm_me Manually-entered route models - -\li Full: You have to enter all necessary routes manually - -Full example : -\verbatim - - - - - - -\endverbatim - -\subsubsection pf_rm_sf Simple/fast models - -\li none: No routing (Unless you know what you are doing, avoid -using this mode in combination with a non Constant network model). -None Example : -\verbatim - - -\endverbatim - -\li Vivaldi: Vivaldi routing, so when you want to use - coordinates. See the corresponding section P2P below for details. -\li Cluster: Cluster routing, specific to cluster tag, should - not be used, except internally. - -\subsection ps_dec Defining routes - -The principle of route definition is the same for the 4 available tags -for doing it. Those for tags are: - -\li route: to define route between host/router -\li ASroute: to define route between AS -\li bypassRoute: to bypass normal routes as calculated by the - network model between host/router -\li bypassASroute: same as bypassRoute, but for AS - -Basically all those tags will contain an (ordered) list of references -to link that compose the route you want to define. - -Consider the example below: - -\verbatim - - - - - -\endverbatim - -The route here from host Alice to Bob will be first link1, then link2, -and finally link3. What about the reverse route ? route and -ASroute have an optional attribute symmetrical, that can -be either YES or NO. YES means that the reverse route is the same -route in the inverse order, and is set to YES by default. Note that -this is not the case for bypass*Route, as it is more probable that you -want to bypass only one default route. - -For an ASroute, things are just slightly more complicated, as you have -to give the id of the gateway which is inside the AS you're talking -about you want to access ... So it looks like this : - - -\verbatim - - - -\endverbatim - -gw == gateway, so when any message are trying to go from AS1 to AS2, -it means that it must pass through router1 to get out of the AS, then -pass through link1, and get into AS2 by being received by router2. -router1 must belong to AS1 and router2 must belong to AS2. - -\subsubsection pf_linkctn link_ctn - -a link_ctn is the tag that is used in order to reference a -link in a route. Its id is the link id it refers to. - -link_ctn attributes : -\li id (mandatory): Id of the link this tag refers to -\li direction: if the link referenced by id has been - declared as FULLDUPLEX, this is used to indicate in which - direction the route you're defining is going through this link. - Possible values "UP" or "DOWN". - -\subsubsection pf_asro ASroute - -ASroute tag purpose is to let people write manually their routes -between AS. It's useful when you're in Full model. - -ASroute attributes : -\li src (mandatory): the source AS id. -\li dst (mandatory): the destination AS id. -\li gw_src (mandatory): the gateway to be used within the AS. - Can be any host or \b router defined into the \b src AS or - into one of the AS it includes. -\li gw_dst (mandatory): the gateway to be used within the AS. - Can be any host or \b router defined into the \b dst AS or - into one of the AS it includes. -\li symmetrical: if the route is symmetric, the reverse route - will be the opposite of the one defined. Can be either YES or NO, - default is YES. - -Example of ASroute with Full -\verbatim - - - - - - - - - - - - - - -\endverbatim - -\subsubsection pf_ro route -The principle is the same as ASroute : route contains list of -links that are in the path between src and dst, except that it is for -routes between a src that can be either host or \b router and a -dst that can be either host or \b router. Useful for Full -as well as for the shortest-paths based models, where you -have to give topological information. - - -route attributes : -\li src (mandatory): the source id. -\li dst (mandatory): the destination id. -\li symmetrical: if the route is symmetric, the reverse route - will be the opposite of the one defined. Can be either YES or NO, - default is YES. - -route example in Full -\verbatim - - - -\endverbatim - -route example in a shortest-path model -\verbatim - - - -\endverbatim -Note that when using route to give topological information, you have -to give routes with one link only in it, as SimGrid needs to know -which host are at the end of the link. - -\subsubsection pf_byro bypassASroute - -Note : bypassASroute and bypassRoute are under rewriting to perform -better ; so you may not use it yet As said before, once you choose -a model, it (if so) 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 AS at an upper stage : -bypassASroute is the tag you're looking for. It allows to -bypass routes defined between already defined between AS (if you want -to bypass route for a specific host, you should just use byPassRoute). -The principle is the same as ASroute : bypassASroute contains -list of links that are in the path between src and dst. - -bypassASroute attributes : -\li src (mandatory): the source AS id. -\li dst (mandatory): the destination AS id. -\li gw_src (mandatory): the gateway to be used within the AS. - Can be any host or \b router defined into the \b src AS or - into one of the AS it includes. -\li gw_dst (mandatory): the gateway to be used within the AS. - Can be any host or \b router defined into the \b dst AS or - into one of the AS it includes. -\li symmetrical: if the route is symmetric, the reverse route - will be the opposite of the one defined. Can be either YES or NO, - default is YES. - -bypassASroute Example -\verbatim - - - -\endverbatim - -\subsubsection pf_byro bypassRoute -Note : bypassASRoute and bypassRoute are under rewriting to perform -better ; so you may not use it yet As said before, once you choose -a model, it (if so) 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 AS at an upper stage : -bypassRoute is the tag you're looking for. It allows to bypass -routes defined between host/router. The principle is the same -as route : bypassRoute contains list of links references of -links that are in the path between src and dst. - -bypassRoute attributes : -\li src (mandatory): the source AS id. -\li dst (mandatory): the destination AS id. -\li symmetrical: if the route is symmetric, the reverse route - will be the opposite of the one defined. Can be either YES or NO, - default is YES. - -bypassRoute Example -\verbatim -bypassRoute Example -\verbatim - - - -\endverbatim - - -\subsection pb_baroex Basic Routing Example - -Let's say you have an AS named AS_Big that contains two other AS, AS_1 -and AS_2. If you want to make an host (h1) from AS_1 with another one -(h2) from AS_2 then you'll have to proceed as follow: -\li First, you have to ensure that a route is defined from h1 to the - AS_1's exit gateway and from h2 to AS_2's exit gateway. -\li Then, you'll have to define a route between AS_1 to AS_2. As those - AS are both resources belonging to AS_Big, then it has to be done - at AS_big level. To define such a route, you have to give the - source AS (AS_1), the destination AS (AS_2), and their respective - gateway (as the route is effectively defined between those two - entry/exit points). Elements of this route can only be elements - belonging to AS_Big, so links and routers in this route should be - defined inside AS_Big. If you choose some shortest-path model, - this route will be computed automatically. - -As said before, there are mainly 2 tags for routing : -\li ASroute: to define routes between two AS -\li route: to define routes between two host/router - -As we are dealing with routes between AS, it means that those we'll -have some definition at AS_Big level. Let consider AS_1 contains 1 -host, 1 link and one router and AS_2 3 hosts, 4 links and one router. -There will be a central router, and a cross-like topology. At the end -of the crosses arms, you'll find the 3 hosts and the router that will -act as a gateway. We have to define routes inside those two AS. Let -say that AS_1 contains full routes, and AS_2 contains some Floyd -routing (as we don't want to bother with defining all routes). As -we're using some shortest path algorithms to route into AS_2, we'll -then have to define some route to gives some topological -information to SimGrid. Here is a file doing it all : - -\verbatim - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\endverbatim - -\section pf_other_tags Tags not (directly) describing the platform - -There are 3 tags, that you can use inside a \ tag that are -not describing the platform: -\li random: it allows you to define random generators you want to use - for your simulation. -\li config: it allows you to pass some configuration stuff like, for - example, the network model and so on. It follows the -\li include: simply allows you to include another file into the - current one. - -\subsection pf_conf config -config attributes : -\li id (mandatory): the identifier of the config to be used - when referring to it. - - -config tag only purpose is to include prop tags. Valid -id are basically the same as the list of possible parameters you can -use by command line, except that "/" are used for namespace -definition. See the \ref options config and options page for more -information. - - -config example -\verbatim - - - - - - - - - - - - - -... -\endverbatim - - -\subsection pf_rand random -Not yet in use, and possibly subject to huge modifications. - -\subsection pf_incl include -include tag allows to import into a file platform parts located -in another file. This is done with the intention to help people -combine their different AS and provide new platforms. Those files -should contains XML part that contains either -include,cluster,peer,AS,trace,trace_connect tags. - -include attributes : -\li file (mandatory): filename of the file to include. Possible - values: absolute or relative path, syntax similar to the one in - use on your system. - -Note: due to some obscure technical reasons, you have to open -and close tag in order to let it work. -include Example -\verbatim - - - - - - - - -\endverbatim - -\subsection pf_tra trace and trace_connect -Both tags are an alternate way to passe availability, state, and so on -files to entity. Instead of referring to the file directly in the host, -link, or cluster tag, you proceed by defining a trace with an id -corresponding to a file, later an host/link/cluster, and finally using -trace_connect you say that the file trace must be used by the entity. -Get it ? Let's have a look at an example : - -\verbatim - - - - - -\endverbatim - -All constraints you have is that trace_connect is after -trace and host definitions. - - -trace attributes : -\li id (mandatory): the identifier of the trace to be used when - referring to it. -\li file: filename of the file to include. Possible values : - absolute or relative path, syntax similar to the one in use on - your system. If omitted, the system expects that you provide the - trace values inside the trace tags (see below). -\li trace periodicity (mandatory): trace periodicity, same - definition as in hosts (see upper for details). - -Here is an example of trace when no file name is provided: - -\verbatim - - 0.0 1.0 - 11.0 0.5 - 20.0 0.8 - -\endverbatim - -trace_connect attributes : -\li kind: the type of trace, possible values - HOST_AVAIL|POWER|LINK_AVAIL|BANDWIDTH|LATENCY, default: - HOST_AVAIL -\li trace (mandatory): the identifier of the trace referenced. -\li element (mandatory): the identifier of the entity referenced. - - - -\section pf_hints Hints and tips, or how to write a platform efficiently - -Now you should know at least the syntax and be able to create a -platform by your own. However, after having ourselves wrote some platforms, there -are some best practices you should pay attention to in order to -produce good platform and some choices you can make in order to have -faster simulations. Here's some hints and tips, then. - -\subsection pf_as_h AS Hierarchy -The AS design allows SimGrid to go fast, because computing route is -done only for the set of resources defined in this AS. If you're using -only a big AS containing all resource with no AS into it and you're -using Full model, then ... you'll loose all interest into it. On the -other hand, designing a binary tree of AS with, at the lower level, -only one host, then you'll also loose all the good AS hierarchy can -give you. Remind you should always be "reasonable" in your platform -definition when choosing the hierarchy. A good choice if you try to -describe a real life platform is to follow the AS described in -reality, since this kind of trade-off works well for real life -platforms. - -\subsection pf_exit_as Exit AS: why and how -Users that have looked at some of our platforms may have notice a -non-intuitive schema ... Something like that : - - -\verbatim - - - - - - - - - - - - - - - - - - - - - - - -\endverbatim - -In the AS_4, you have an exitAS_4 defined, containing only one router, -and routes defined to that AS from all other AS (as cluster is only a -shortcut for an AS, see cluster description for details). If there was -an upper AS, it would define routes to and from AS_4 with the gateway -router_4. It's just because, as we did not allowed (for performances -issues) to have routes from an AS to a single host/router, you have to -enclose your gateway, when you have AS included in your AS, within an -AS to define routes to it. - -\subsection pf_P2P_tags P2P or how to use coordinates -SimGrid allows you to use some coordinated-based system, like vivaldi, -to describe a platform. The main concept is that you have some peers -that are located somewhere: this is the function of the -coordinates of the \ or \ tag. There's nothing -complicated in using it, here is an example of it: - -\verbatim - - - - - - - - - - - ... - - - -\endverbatim - -Coordinates are then used to calculate latency between two hosts by -calculating the euclidean distance between the two hosts coordinates. -The results express the latency in ms. - -Note that the previous example defines a routing directly between hosts but it could be also used to define a routing between AS. -That is for example what is commonly done when using peers (see Section \ref pf_peer). -\verbatim - - - - - - - - - - - - - -\endverbatim -In such a case though, we connect the AS created by the peer tag with the Vivaldi routing mechanism. -This means that to route between AS1 and AS2, it will use the coordinates of router_AS1 and router_AS2. -This is currently a convention and we may offer to change this convention in the DTD later if needed. -You may have noted that conveniently, a peer named FOO defines an AS named FOO and a router named router_FOO, which is why it works seamlessly with the peer tag. - - -\subsection pf_wisely Choosing wisely the routing model to use - - -Choosing wisely the routing model to use can significantly fasten your -simulation/save your time when writing the platform/save tremendous -disk space. Here is the list of available model and their -characteristics (lookup : time to resolve a route): - -\li Full: Full routing data (fast, large memory requirements, - fully expressive) -\li Floyd: Floyd routing data (slow initialization, fast - lookup, lesser memory requirements, shortest path routing only). - Calculates all routes at once at the beginning. -\li Dijkstra: Dijkstra routing data (fast initialization, slow - lookup, small memory requirements, shortest path routing only). - Calculates a route when necessary. -\li DijkstraCache: Dijkstra routing data (fast initialization, - fast lookup, small memory requirements, shortest path routing - only). Same as Dijkstra, except it handles a cache for latest used - routes. -\li none: No routing (usable with Constant network only). - Defines that there is no routes, so if you try to determine a - route without constant network within this AS, SimGrid will raise - an exception. -\li Vivaldi: Vivaldi routing, so when you want to use coordinates -\li Cluster: Cluster routing, specific to cluster tag, should - not be used. - -\subsection pf_switch Hey, I want to describe a switch but there is no switch tag ! - -Actually we did not include switch tag, ok. But when you're trying to -simulate a switch, the only major impact it has when you're using -fluid model (and SimGrid uses fluid model unless you activate GTNetS, -ns-3, or constant network mode) is the impact of the upper limit of -the switch motherboard speed that will eventually be reached if you're -using intensively your switch. So, the switch impact is similar to a -link one. That's why we are used to describe a switch using a link tag -(as a link is not an edge by a hyperedge, you can connect more than 2 -other links to it). - -\subsection pf_platform_multipath How to express multipath routing in platform files? - -It is unfortunately impossible to express the fact that there is more -than one routing path between two given hosts. Let's consider the -following platform file: - -\verbatim - - - - - - - - - -\endverbatim - -Although it is perfectly valid, it does not mean that data traveling -from A to C can either go directly (using link 3) or through B (using -links 1 and 2). It simply means that the routing on the graph is not -trivial, and that data do not following the shortest path in number of -hops on this graph. Another way to say it is that there is no implicit -in these routing descriptions. The system will only use the routes you -declare (such as <route src="A" dst="C"><link_ctn -id="3"/></route>), without trying to build new routes by aggregating -the provided ones. - -You are also free to declare platform where the routing is not -symmetric. For example, add the following to the previous file: - -\verbatim - - - - -\endverbatim - -This makes sure that data from C to A go through B where data from A -to C go directly. Don't worry about realism of such settings since -we've seen ways more weird situation in real settings (in fact, that's -the realism of very regular platforms which is questionable, but -that's another story). - -\section pf_flexml_bypassing Bypassing the XML parser with your own C functions -NOTE THAT THIS DOCUMENTATION, WHILE STILL WORKING, IS STRONGLY DEPRECATED - -So you want to bypass the XML files parser, uh? Maybe doing some parameter -sweep experiments on your simulations or so? This is possible, and -it's not even really difficult (well. Such a brutal idea could be -harder to implement). Here is how it goes. - -For this, you have to first remember that the XML parsing in SimGrid is done -using a tool called FleXML. Given a DTD, this gives a flex-based parser. If -you want to bypass the parser, you need to provide some code mimicking what -it does and replacing it in its interactions with the SURF code. So, let's -have a look at these interactions. - -FleXML parser are close to classical SAX parsers. It means that a -well-formed SimGrid platform XML file might result in the following -"events": - - - start "platform_description" with attribute version="2" - - start "host" with attributes id="host1" power="1.0" - - end "host" - - start "host" with attributes id="host2" power="2.0" - - end "host" - - start "link" with ... - - end "link" - - start "route" with ... - - start "link_ctn" with ... - - end "link_ctn" - - end "route" - - end "platform_description" - -The communication from the parser to the SURF code uses two means: -Attributes get copied into some global variables, and a surf-provided -function gets called by the parser for each event. For example, the event - - start "host" with attributes id="host1" power="1.0" - -let the parser do something roughly equivalent to: -\verbatim - strcpy(A_host_id,"host1"); - A_host_power = 1.0; - STag_host(); -\endverbatim - -In SURF, we attach callbacks to the different events by initializing the -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: -\verbatim - /* Adding callback functions */ - surf_parse_reset_parser(); - surfxml_add_callback(STag_surfxml_host_cb_list, &parse_cpu_init); - surfxml_add_callback(STag_surfxml_prop_cb_list, &parse_properties); - surfxml_add_callback(STag_surfxml_link_cb_list, &parse_link_init); - surfxml_add_callback(STag_surfxml_route_cb_list, &parse_route_set_endpoints); - surfxml_add_callback(ETag_surfxml_link_c_ctn_cb_list, &parse_route_elem); - surfxml_add_callback(ETag_surfxml_route_cb_list, &parse_route_set_route); - - /* Parse the file */ - surf_parse_open(file); - xbt_assert(!surf_parse(), "Parse error in %s", file); - surf_parse_close(); -\endverbatim - -So, to bypass the FleXML parser, you need to write your own version of the -surf_parse function, which should do the following: - - Fill the A__ variables with the wanted values - - Call the corresponding STag__fun function to simulate tag start - - Call the corresponding ETag__fun function to simulate tag end - - (do the same for the next set of values, and loop) - -Then, tell SimGrid that you want to use your own "parser" instead of the stock one: -\verbatim - surf_parse = surf_parse_bypass_environment; - MSG_create_environment(NULL); - surf_parse = surf_parse_bypass_application; - MSG_launch_application(NULL); -\endverbatim - -A set of macros are provided at the end of -include/surf/surfxml_parse.h to ease the writing of the bypass -functions. An example of this trick is distributed in the file -examples/msg/masterslave/masterslave_bypass.c - - -*/