-/*! \page platform Platform Description
+/*! \page platform Step 1: %Model the underlying platform
@tableofcontents
If you want this host to be unavailable, simply substitute ON with OFF.
+\anchor pf_host_churn
### Expressing churn ###
To express the fact that a host can change state over time (as in P2P
\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:
+can be used to model storage:
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).
### %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
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.
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
-------------- | --------- | ------ | -----------
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 "\<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 <i>physically</i> 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 <i>physically</i> 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 "\<storage_type\>"
content_type | no | string | When specified, overwrites the content_type attribute of \ref pf_storage_entity_storage_type "\<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).
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
\subsubsection pf_routing_tag_bypassasroute bypassASroute
-<b>Note : bypassASroute and bypassRoute are under rewriting to perform
-better ; so you may not use it yet</b> %As said before, once you choose
-a model, it (if so) calculates routes for you. But maybe you want to
+%As said before, once you choose
+a model, it (most likely; the constant network model, for example, doesn't) 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 :
+to bypass some routes defined in lower level AS at an upper stage:
<b>bypassASroute</b> 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).
\subsubsection pf_routing_tag_bypassroute bypassRoute
-<b>Note : bypassASRoute and bypassRoute are under rewriting to perform
-better ; so you may not use it yet</b> %As said before, once you choose
-a model, it (if so) calculates routes for you. But maybe you want to
+%As said before, once you choose
+a model, it (most likely; the constant network model, for example, doesn't) 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 :
<b>bypassRoute</b> is the tag you're looking for. It allows to bypass
\subsection pf_trace 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 a 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 :
+Both tags are an alternate way to pass files containing information on
+availability, state etc. to an entity. (See also, for instance, Section \ref
+pf_host_churn "Churn", as described for the host 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 a host/link/cluster, and
+finally using trace_connect you say that the file trace must be used by the
+entity.
+
+
+#### Example ####
\verbatim
<AS id="AS0" routing="Full">
<host id="bob" power="1000000000"/>
</AS>
- <trace id="myTrace" file="bob.trace" periodicity="1.0"/>
- <trace_connect trace="myTrace" element="bob" kind="POWER"/>
+<trace id="myTrace" file="bob.trace" periodicity="1.0"/>
+<trace_connect trace="myTrace" element="bob" kind="POWER"/>
\endverbatim
-All constraints you have is that <b>trace_connect</b> is after
-<b>trace</b> and <b>host</b> definitions.
+\note
+ The order here is important. \c trace_connect must come
+ after the elements \c trace and \c host, as both the host
+ and the trace definition must be known when \c trace_connect
+ is parsed; the order of \c trace and \c host is arbitrary.
-<b>trace</b> attributes :
-\li <b>id (mandatory)</b>: the identifier of the trace to be used when
- referring to it.
-\li <b>file</b>: 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 <b>trace periodicity (mandatory)</b>: trace periodicity, same
- definition as in hosts (see upper for details).
+#### \c trace attributes ####
+
+
+| Attribute name | Mandatory | Values | Description |
+| --------------- | --------- | ---------------------- | ----------- |
+| id | yes | String | Identifier of this trace; this is the name you pass on to \c trace_connect. |
+| file | no | String | Filename of the file that contains the information - the path must follow the style of your OS. You can omit this, but then you must specifiy the values inside of <trace> and </trace> - see the example below. |
+| trace_periodicity | yes | String | This is the same as for \ref pf_host "hosts" (see there for details) |
Here is an example of trace when no file name is provided:
0.0 1.0
11.0 0.5
20.0 0.8
- </trace>
+ </trace>
\endverbatim
-<b>trace_connect</b> attributes :
-\li <b>kind</b>: the type of trace, possible values
- <b>HOST_AVAIL|POWER|LINK_AVAIL|BANDWIDTH|LATENCY,</b> default:
- <b>HOST_AVAIL</b>
-\li <b>trace (mandatory)</b>: the identifier of the trace referenced.
-\li <b>element (mandatory)</b>: the identifier of the entity referenced.
-
+#### \c trace_connect attributes ####
+| Attribute name | Mandatory | Values | Description |
+| --------------- | --------- | ---------------------- | ----------- |
+| kind | no | HOST_AVAIL\|POWER\|<br/>LINK_AVAIL\|BANDWIDTH\|LATENCY (Default: HOST_AVAIL) | Describes the kind of trace. |
+| trace | yes | String | Identifier of the referenced trace (specified of the trace's \c id attribute) |
+| element | yes | String | The identifier of the referenced entity as given by its \c id attribute |
\section pf_hints Hints and tips, or how to write a platform efficiently
