various doc improvements

[simgrid.git] / docs / source / platform.rst

diff --git a/docs/source/platform.rst b/docs/source/platform.rst
index 4a9f3f9..1909927 100644 (file)
--- a/docs/source/platform.rst
+++ b/docs/source/platform.rst
@@ -35,19 +35,77 @@ Finally, you may also describe an **experimental scenario**, with qualitative (e
 an external load) and qualitative (e.g., representing how some elements fail and restart over time) changes.
 
 
 an external load) and qualitative (e.g., representing how some elements fail and restart over time) changes.
 
 

-Defining Basic Elements
-***********************
+First Example
+*************

 
 

-These are the components of your platform.
+Imagine you want to describe a little platform with three hosts,
+interconnected as follows:

 
 

+.. image:: /tuto_smpi/3hosts.png
+   :align: center
+
+This can be done with the following platform file, that considers the
+simulated platform as a graph of hosts and network links.
+          
+.. literalinclude:: /tuto_smpi/3hosts.xml
+   :language: xml
+
+The most important elements are the basic ones: :ref:`pf_tag_host`,
+:ref:`pf_tag_link`, and similar. Then come the routes between any pair
+of hosts, that are given explicitely with :ref:`pf_tag_route` (routes
+are symmetrical by default). Any host must be given a computational
+speed (in flops) while links must be given a latency (in seconds) and
+a bandwidth (in bytes per second). Note that you can write 1Gflops
+instead of 1000000000flops, and similar.
+
+Every platform element must be located within a given **networking
+zone** .  Zones are in
+charge of the routing, see below.
+
+The last thing you must know on SimGrid platform files is that the
+root tag must be :ref:`pf_tag_platform`. If the ``version`` attribute
+does not match what SimGrid expects, you will be hinted to use to the
+``simgrid_update_xml`` utility to update your file.

 
 

-There is not much to say about the definition of basic elements. Just
-use the appropriate tags: :ref:`pf_tag_host`, :ref:`pf_tag_link` and
-:ref:`pf_tag_storage`.

 
 Defining a Routing
 ******************
 
 
 Defining a Routing
 ******************
 

+Networking zones (:ref:`pf_tag_zone`) are used to factorize the description
+to reduce the size of your platform on disk and in memory. Then, when
+a host wants to communicate with another host belonging to the same
+zone, it is the zone's duty to find the list of links that are
+involved in the communication. In the above example, since we use
+``routing="Full"``, all routes must be explicitly given using the
+:ref:`pf_tag_route` and :ref:`pf_tag_link_ctn` tags (this :ref:`routing
+model <pf_rm>` is both simple and inefficient :) It is OK to not
+specify each and every route between hosts, as long as you do not try
+to start a communication on any of the missing routes during your
+simulation.
+
+Any zone may contain sub-zones, allowing for a hierarchical
+decomposition of the platform. Routing can be made more efficient (as the
+inter-zone routing gets factored with :ref:`pf_tag_zoneroute`), and
+allows you to have more than one routing model in your platform. For
+example, you can have a coordinate-based routing for the WAN parts
+of your platforms, a full routing within each datacenter, and a highly
+optimized routing within each cluster of the datacenter.  In this
+case, determining the route between two given hosts gets :ref:`routing_basics`
+"somewhat more complex" but SimGrid still computes
+these routes for you in a time- and space-efficient manner.
+Here is an illustration of these concepts:
+
+.. image:: img/zone_hierarchy.png
+
+Circles represent processing units and squares represent network
+routers. Bold lines represent communication links. The zone "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).
+
+.. todo:: Add more examples, such as the cloud example described in
+          previous paragraph
+

 Performance Profiles and Churn
 ******************************
 
 Performance Profiles and Churn
 ******************************