X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/73e4fd1f87d88fd9396f626cdf5cd50692f1d5e1..e99158dd85fe789ea5e1a40c29f196fa6c715bcf:/doc/doxygen/platform.doc diff --git a/doc/doxygen/platform.doc b/doc/doxygen/platform.doc index 85d154e0d0..14910b22ce 100644 --- a/doc/doxygen/platform.doc +++ b/doc/doxygen/platform.doc @@ -9,14 +9,14 @@ process: Which process should be deployed to which processor/core? For the last two items, there are essentially two possible ways you can provide this information as an input: -\li You can program it, either by using the Lua console ( - \ref MSG_Lua_funct) or, if you're using MSG, some of MSG's platform and +\li You can program, if you're using MSG, some of MSG's platform and deployment functions (\ref msg_simulation). If you want to use this, check the particular documentation. (You can also check the section \ref pf_flexml_bypassing, however, this documentation is deprecated; there is a new, but undocumented, way to do it properly). \li You can use two XML files: one contains the platform description while - the other contains the deployment instructions. + the other contains the deployment instructions. The platform description + can also be in Lua format. For more information on SimGrid's deployment features, please refer to the \ref deployment documentation. @@ -35,10 +35,10 @@ available and very well tested. The XML checking is done based on the Document Type Definition (DTD) file, available at -http://simgrid.gforge.inria.fr/simgrid.dtd. +http://simgrid.gforge.inria.fr/simgrid/simgrid.dtd. If you read the DTD, you should notice the following: -\li The platform tags contain a version attribute; the current version is 3. +\li The platform tags contain a version attribute; the current version is 4. This property might be used in the future to provide backwards compatibility. \li The DTD contains definitions for the two files used by SimGrid (i.e., @@ -145,14 +145,14 @@ routing | yes | Full\| Floyd\| Dijkstra\| DijkstraCache\| None\| V Example: -\verbatim +\code -\endverbatim +\endcode In this example, AS0 contains two hosts (host1 and host2). The route between the hosts goes through link1. @@ -206,8 +206,8 @@ and a separate text file whose syntax is exemplified below. #### Adding a trace file #### \verbatim - - + + \endverbatim @@ -241,8 +241,8 @@ It is also possible to specify whether the host is up or down by setting the #### Example: Expliciting the default value "ON" #### \verbatim - - + + \endverbatim @@ -259,8 +259,8 @@ of such a file is presented below. #### Adding a state file #### \verbatim - - + + \endverbatim @@ -344,7 +344,7 @@ state_file | no | string | Allows you to use a file as input for sta loopback_bw | no | int | Bandwidth for loopback (if any). See link section for syntax/details. If loopback_bw and loopback_lat (see below) attributes are omitted, no loopback link is created and all intra-node communication will use the main network link of the node. Loopback link is a \ref pf_sharing_policy_fatpipe "\b FATPIPE". loopback_lat | no | int | Latency for loopback (if any). See link section for syntax/details. See loopback_bw for more info. topology | no | FLAT\|TORUS\|FAT_TREE (default: FLAT) | Network topology to use. SimGrid currently supports FLAT (with or without backbone, as described before), TORUS and FAT_TREE attributes for this tag. -topo_parameters | no | string | Specific parameters to pass for the topology defined in the topology tag. For torus networks, comma-separated list of the number of nodes in each dimension of the torus. For fat trees, refer to \ref AsClusterFatTree "AsClusterFatTree documentation". +topo_parameters | no | string | Specific parameters to pass for the topology defined in the topology tag. For torus networks, comma-separated list of the number of nodes in each dimension of the torus. For fat trees, refer to \ref simgrid::surf::AsClusterFatTree "AsClusterFatTree documentation". TODO @@ -523,7 +523,7 @@ for routing algorithms. So, it does not have any attributes except : Attribute name | Mandatory | Values | Description --------------- | --------- | ------ | ----------- id | yes | string | The identifier of the router to be used when referring to it. -coordinates | yes | string | Must be provided when choosing the Vivaldi, coordinate-based routing model for the AS the router belongs to. More details can be found in the Section \ref pf_P2P_tags. +coordinates | no | string | Must be provided when choosing the Vivaldi, coordinate-based routing model for the AS the router belongs to. More details can be found in the Section \ref pf_P2P_tags. #### Example #### @@ -683,16 +683,14 @@ kicks in. It then loops back, starting at 100µs (the initial value) for one sec #### The ```` tag #### -Similar to ``\``, the link may also contain the ```` tag; see the host +Similar to the ```` tag, a link may also contain the ```` tag; see the host documentation (Section \ref pf_host) for an example. -TODO - \subsubsection pf_backbone \note - This tag is only available when the containing AS uses the "Cluster" mode! + This tag is only available when the containing AS uses the "Cluster" routing mode! Using this tag, you can designate an already existing link to be a backbone. @@ -703,22 +701,36 @@ id | yes | string | Name of the link that is supposed to act \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 is a prototype version that should evolve quickly, hence this + is just some doc valuable only at the time of writing. 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 + msg_file_management ; access functions are organized as a POSIX-like interface. -\subsubsection pf_sto_conc Storage Main concepts -Basically there are 3 different entities available in SimGrid that -can be used to model storages: +\subsubsection pf_sto_conc Storage - Main Concepts + +The storage facilities implemented in SimGrid help to model (and account for) +storage devices, such as tapes, hard-drives, CD or DVD devices etc. +A typical situation is depicted in the figure below: + +\image html ./webcruft/storage_sample_scenario.png +\image latex ./webcruft/storage_sample_scenario.png "storage_sample_scenario" width=\textwidth + +In this figure, two hosts called Bob and Alice are interconnected via a network +and each host is physically attached to a disk; it is not only possible for each host to +mount the disk they are attached to directly, but they can also mount disks +that are in a remote location. In this example, Bob mounts Alice's disk remotely +and accesses the storage via the network. + +SimGrid provides 3 different entities that can be used to model setups +that include storage facilities: Entity name | Description --------------- | ----------- -\ref pf_storage_entity_storage_type "storage_type" | Defines a template for a particular kind of storage (such as a hard-drive) and specifies important features of the storage, such as capacity, performance (read/write), content, ... Different models of hard-drives use different storage_types (because the difference between an SSD and an HDD does matter), as they differ in some specifications (e.g., different size or read/write performance). -\ref pf_storage_entity_storage "storage" | Defines an actual instance of a storage (disk, RAM, ...); uses a ``storage_type`` template (see line above) so that you don't need to re-specify the same details over and over again. +\ref pf_storage_entity_storage_type "storage_type" | Defines a template for a particular kind of storage (such as a hard-drive) and specifies important features of the storage, such as capacity, performance (read/write), contents, ... Different models of hard-drives use different storage_types (because the difference between an SSD and an HDD does matter), as they differ in some specifications (e.g., different sizes or read/write performance). +\ref pf_storage_entity_storage "storage" | Defines an actual instance of a storage type (disk, RAM, ...); uses a ``storage_type`` template (see line above) so that you don't need to re-specify the same details over and over again. \ref pf_storage_entity_mount "mount" | Must be wrapped by a \ref pf_host tag; declares which storage(s) this host has mounted and where (i.e., the mountpoint). @@ -726,7 +738,7 @@ Entity name | Description ### %Storage Content File ### In order to assess exactly how much time is spent reading from the storage, -SimGrid needs to know what is stored in the storage device (identified by distinct (file-)name, like in a file system) +SimGrid needs to know what is stored on the storage device (identified by distinct (file-)name, like in a file system) and what size this content has. \note @@ -735,9 +747,9 @@ and what size this content has. storage changes, only the internal SimGrid data structures change. \anchor pf_storage_content_file_structure -#### Structure of a %Storage File #### +#### Structure of a %Storage Content File #### -Here is an excerpt from two storage file; if you want to see the whole file, check +Here is an excerpt from two storage content file; if you want to see the whole file, check the file ``examples/platforms/content/storage_content.txt`` that comes with the SimGrid source code. @@ -780,7 +792,7 @@ If you want to generate a storage content file based on your own filesystem (or try running this command (works only on unix systems): \verbatim -find /path/you/want -type f -exec ls -l {} \; 2>/dev/null > ./content.txt +find . -type f -exec ls -1s --block=1 {} \; 2>/dev/null | awk '{ print $2 " " $1}' > ./content.txt \endverbatim \subsubsection pf_storage_entities The Storage Entities @@ -834,7 +846,7 @@ Attribute name | Mandatory | Values | Description -------------- | --------- | ------ | ----------- id | yes | string | Identifier of this ``storage``; used when referring to it typeId | yes | string | Here you need to refer to an already existing \ref pf_storage_entity_storage_type "\"; the storage entity defined by this tag will then inherit the properties defined there. -attach | yes | string | Name of a host (see Section \ref pf_host) that this storage is physically attached to (e.g., a harddrive in a computer) +attach | yes | string | Name of a host (see Section \ref pf_host) to which this storage is physically attached to (e.g., a hard drive in a computer) content | no | string | When specified, overwrites the content attribute of \ref pf_storage_entity_storage_type "\" content_type | no | string | When specified, overwrites the content_type attribute of \ref pf_storage_entity_storage_type "\" @@ -853,7 +865,7 @@ of type "single_HDD" (shown as an example of \ref pf_storage_entity_storage_type to a host called "bob" (the definition of this host is omitted here). The second storage is called "Disk2", is still of the same type as Disk1 but -now specifies a new content file (so the content will be different from Disk1) +now specifies a new content file (so the contents will be different from Disk1) and the filesystem uses the windows style; finally, it is attached to a second host, called alice (which is again not defined here). @@ -898,7 +910,7 @@ Here is a simple example, taken from the file ``examples/platform/storage.xml``: This example is quite interesting, as the same device, called "Disk2", is mounted by two hosts at the same time! Note, however, that the host called ``alice`` is actually attached to this storage, as can be seen in the \ref pf_storage_entity_storage "<storage>" -tag. This means that ``denise`` must access this storage via network, but SimGrid automatically takes +tag. This means that ``denise`` must access this storage through the network, but SimGrid automatically takes care of that for you. Furthermore, this example shows that ``denise`` has mounted two storages with different @@ -940,7 +952,7 @@ available in the directory ``examples/msg/io/`` useful. \subsubsection pf_storage_examples_modelling Modelling different situations The storage functionality of SimGrid is type-agnostic, that is, the implementation -does not presume any type of storagei, such as HDDs/SSDs, RAM, +does not presume any type of storage, such as HDDs/SSDs, RAM, CD/DVD devices, USB sticks etc. This allows the user to apply the simulator for a wide variety of scenarios; one @@ -1292,7 +1304,7 @@ can only occur as a child of \ref pf_routing_tag_route "<route/>" #### Example Files #### -This is an automatically generated list of example files that use the \c <link_ctn/gt; +This is an automatically generated list of example files that use the \c <link_ctn/> entity (the path is given relative to SimGrid's source directory): \verbinclude example_filelist_xmltag_linkctn @@ -1548,7 +1560,7 @@ Tag name | Description | Documentation \verbatim - + @@ -1595,7 +1607,7 @@ each of them will then be usable. \verbatim - + @@ -1741,16 +1753,16 @@ complicated in using it, here is an example of it: \verbatim - + - - + + ... - + \endverbatim @@ -1764,7 +1776,7 @@ That is for example what is commonly done when using peers (see Section \ref pf_ \verbatim - + @@ -1884,7 +1896,7 @@ 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 "platform_description" with attribute version="4" - start "host" with attributes id="host1" power="1.0" - end "host" - start "host" with attributes id="host2" power="2.0"