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
-
-
-*/