From: Martin Quinson Date: Thu, 23 Dec 2021 21:19:54 +0000 (+0100) Subject: Small improvements to the doc X-Git-Tag: v3.30~176 X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/b760c29144c4d7d86049c079945c33c6d6a9cfc7 Small improvements to the doc --- diff --git a/MANIFEST.in b/MANIFEST.in index 4f331de485..f01752715b 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1808,9 +1808,7 @@ include doc/doxygen/inside_extending.doc include doc/doxygen/inside_release.doc include doc/doxygen/inside_tests.doc include doc/doxygen/module-index.doc -include doc/doxygen/module-sd.doc include doc/doxygen/module-surf.doc -include doc/doxygen/module-trace.doc include doc/doxygen/outcomes_vizu.doc include doc/doxygen/platform.doc include doc/doxygen/uhood.doc diff --git a/doc/doxygen/module-sd.doc b/doc/doxygen/module-sd.doc deleted file mode 100644 index 1a82ea312e..0000000000 --- a/doc/doxygen/module-sd.doc +++ /dev/null @@ -1,35 +0,0 @@ -/** -@defgroup SD_API SimDag: Legacy handling of DAG algorithms -@brief Programming environment for DAG applications - -SimDag provides functionalities to simulate parallel task scheduling -arranged in DAGs (Direct Acyclic Graphs). Only centralized algorithms -can be expressed with SimDag; consider using @ref MSG_API "MSG" for -distributed algorithms). - -SimDag is the oldest interface in SimGrid, even if it was temporarily -removed when the new superfast kernel was added in SimGrid v3.0. It -will certainly be deprecated by future releases of the S4U API, when -inter-activity dependencies are added. - - @{ - - @defgroup SD_host_api Hosts - @brief Host management - - @defgroup SD_link_api Links - @brief Link management - - @defgroup SD_task_api Tasks - @brief Task management - - @defgroup SD_task_dependency_api Tasks dependencies - @brief Functions to specify the dependencies between tasks - - @defgroup SD_storage_api Storages - @brief Storage management - - @defgroup SD_simulation Simulation - @brief Functions to create the environment and launch the simulation - @} -*/ diff --git a/doc/doxygen/module-surf.doc b/doc/doxygen/module-surf.doc index 1d4aad03fb..32d997f76b 100644 --- a/doc/doxygen/module-surf.doc +++ b/doc/doxygen/module-surf.doc @@ -1,37 +1,3 @@ -/** @addtogroup SURF_API - - @section SURF_doc Surf documentation - Surf is composed several components: - - @ref SURF_simulation - - @ref SURF_models - - @ref SURF_build_api - - @ref SURF_c_bindings - - @ref SURF_interface - - @ref SURF_cpu_interface - - @ref SURF_network_interface - - @ref SURF_storage_interface - - @ref SURF_host_interface - - @ref SURF_vm_interface - - @ref SURF_lmm - - @ref SURF_callbacks - - @ref plugin_energy - - -*/ - -/** @defgroup SURF_models Simulation Models - @ingroup SURF_API - @brief Functions to declare the kind of models that you want to use - */ - -/** @defgroup SURF_simulation Simulation - @ingroup SURF_API - @brief Functions for creating the environment and launching the simulation - - This section describes the functions for initializing SURF, performing - the simulation and exiting SURF. -*/ - /** @defgroup SURF_build_api Create a new API @ingroup SURF_API @brief How to build a new API on top of SURF @@ -78,62 +44,3 @@ */ -/** -@defgroup SURF_c_bindings SURF C bindings -@ingroup SURF_API -@brief Describes the c bindings of SURF -*/ - -/** -@defgroup SURF_interface SURF Interface -@ingroup SURF_API -@brief Describes the general interface for all components (Cpu, Network, Storage, Host, VM) -*/ - -/** -@defgroup SURF_cpu_interface SURF Cpu Interface -@ingroup SURF_API -@brief Describes the general Cpu interface for all Cpu implementations -*/ - -/** -@defgroup SURF_network_interface SURF Network Interface -@ingroup SURF_API -@brief Describes the general Network interface for all Network implementations -*/ - -/** -@defgroup SURF_storage_interface SURF Storage Interface -@ingroup SURF_API -@brief Describes the general interface for all Storage implementations -*/ - -/** -@defgroup SURF_host_interface SURF Host Interface -@ingroup SURF_API -@brief Describes the general interface for all Host implementations -*/ - -/** -@defgroup SURF_vm_interface SURF VM Interface -@ingroup SURF_API -@brief Describes the general interface for all VM implementations -*/ - -/** -@defgroup SURF_lmm SURF Linear MaxMin -@ingroup SURF_API -@brief Describes how the linear MaxMin system work -*/ - -/** -@defgroup SURF_callbacks SURF callbacks -@ingroup SURF_API -@brief Describes how to use the SURF callbacks -*/ - -/** -@defgroup plugin_energy Energy Plugin -@ingroup SURF_API -@brief Describes how to use the energy plugin. -*/ diff --git a/doc/doxygen/module-trace.doc b/doc/doxygen/module-trace.doc deleted file mode 100644 index b0e40e5d31..0000000000 --- a/doc/doxygen/module-trace.doc +++ /dev/null @@ -1,21 +0,0 @@ -/** -@addtogroup TRACE_API - -@section TRACE_doc TRACE documentation -- @ref TRACE_category -- @ref TRACE_mark -- @ref TRACE_user_variables - -@{ - - @defgroup TRACE_category Tracing categories - @brief Functions to declare tracing categories. - - @defgroup TRACE_mark Tracing marks - @brief Functions to declare and create tracing marks. - - @defgroup TRACE_user_variables Tracing user variables - @brief Functions to declare and define user variables associated to resources. - -@} -*/ \ No newline at end of file diff --git a/doc/doxygen/platform.doc b/doc/doxygen/platform.doc index 9a88bde196..c116d146a6 100644 --- a/doc/doxygen/platform.doc +++ b/doc/doxygen/platform.doc @@ -163,14 +163,7 @@ etc. There are two tags at all times available to represent network entities and several other tags that are available only in certain contexts. -1. ````: Represents an entity that has a limited bandwidth, a - latency, and that can be shared according to TCP way to share this - bandwidth. -@remark - The concept of links in SimGrid may not be intuitive, as links are not - limited to connecting (exactly) two entities; in fact, you can have more than - two equipments connected to it. (In graph theoretical terms: A link in - SimGrid is not an edge, but a hyperedge) +1. ````: 2. ````: Represents an entity that a message can be routed to, but that is unable to execute any code. In SimGrid, routers have also @@ -478,130 +471,6 @@ 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? @ref pf_tag_route "Route" and -@ref pf_tag_zoneroute "zoneroute" have an optional attribute @c symmetrical, that can -be either @c YES or @c NO. @c YES means that the reverse route is the same -route in the inverse order, and is set to @c 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 @ref pf_tag_zoneroute "zoneroute", things are just slightly more complicated, as you have -to give the id of the gateway which is inside the zone you want to access ... -So it looks like this: - -@verbatim - - - -@endverbatim - -gw == gateway, so when any message are trying to go from zone1 to zone2, -it means that it must pass through router1 to get out of the zone, then -pass through link1, and get into zone2 by being received by router2. -router1 must belong to zone1 and router2 must belong to zone2. - -@subsubsection pf_tag_zoneroute <zoneRoute> - -The purpose of this entity is to define a route between two -NetZones. Recall that all zones form a tree, so to connect two -sibling zones, you must give such a zoneRoute specifying the source -and destination zones, along with the gateway in each zone (ie, the -point to reach within that zone to reach the netzone), and the list of -links in the ancestor zone to go from one zone to another. - -So, to go from a host @c src_host that is within zone @c src, to a -host @c dst_host that is within @c dst, you need to: - - - move within zone @c src, from @c src_host to the specified @c gw_src; - - traverse all links specified by the zoneRoute (they are supposed to be within the common ancestor); - - move within zone @c dst, from @c gw_dst to @c dst_host. - -#### Attributes #### - -| Attribute name | Mandatory | Values | Description | -| --------------- | --------- | ------ | ----------- | -| src | yes | String | The identifier of the source zone | -| dst | yes | String | See the @c src attribute | -| gw_src | yes | String | The gateway that will be used within the src zone; this can be any @ref pf_tag_host "Host" or @ref pf_router "Router" defined within the src zone. | -| gw_dst | yes | String | Same as @c gw_src, but with the dst zone instead. | -| symmetrical | no | YES@|NO (Default: YES) | If this route is symmetric, the opposite route (from dst to src) will also be declared implicitly. | - -#### Example #### - -@verbatim - - - - - - - - - - - - - - -@endverbatim - -@subsubsection pf_tag_route <route> - -The principle is the same as for -@ref pf_tag_zoneroute "ZoneRoute": The route contains a list of links that -provide a path from @c src to @c dst. Here, @c src and @c dst can both be either a -@ref pf_tag_host "host" or @ref pf_router "router". This is mostly useful for the -@ref pf_routing_model_full "Full routing model" as well as for the -@ref pf_routing_model_shortest_path "shortest-paths" based models (as they require -topological information). - - -| Attribute name | Mandatory | Values | Description | -| --------------- | --------- | ---------------------- | ----------- | -| src | yes | String | The value given to the source's "id" attribute | -| dst | yes | String | The value given to the destination's "id" attribute. | -| symmetrical | no | YES@| NO (Default: YES) | If this route is symmetric, the opposite route (from dst to src) will also be declared implicitly. | - - -#### Examples #### - -A route in the @ref pf_routing_model_full "Full routing model" could look like this: -@verbatim - - - -@endverbatim - -A route in the @ref pf_routing_model_shortest_path "Shortest-Path routing model" could look like this: -@verbatim - - - -@endverbatim -@note - You must only have one link in your routes when you're using them to provide - topological information, as the routes here are simply the edges of the - (network-)graph and the employed algorithms need to know which edge connects - which pair of entities. - @subsubsection pf_tag_bypassasroute bypasszoneroute As said before, once you choose diff --git a/docs/source/XML_reference.rst b/docs/source/XML_reference.rst index 0e9fa33ce2..e5b1ba4116 100644 --- a/docs/source/XML_reference.rst +++ b/docs/source/XML_reference.rst @@ -170,7 +170,9 @@ A host is the computing resource on which an actor can run. See :cpp:class:`simg SimGrid links usually represent one-hop network connections (see :cpp:class:`simgrid::s4u::Link`), i.e., a single wire. They can also be used to abstract a larger network interconnect, e.g., the entire transcontinental network, into a -single element. +single element. Links are characterized by their bandwidth and latency, and their sharing is realistic wrt TCP connexions. +Another unusual point is that SimGrid links can be used to connect more than two elements, just like +hyperlinks in an `hypergraph `_. **Parent tags:** :ref:`pf_tag_zone` (both leaf zones and inner zones) |br| **Children tags:** :ref:`pf_tag_prop` |br| @@ -394,20 +396,22 @@ of :ref:`pf_tag_link` . **Parent tags:** :ref:`pf_tag_zone` |br| **Children tags:** :ref:`pf_tag_link_ctn` |br| +**See also:** :ref:`pf_tag_zoneRoute` |br| **Attributes:** -:``src``: Host from which this route starts. Must be an existing host. -:``dst``: Host to which this route leads. Must be an existing host. +:``src``: Host from which this route starts. Must be the name of an existing host. +:``dst``: Host to which this route leads. Must be the name of an existing host. :``symmetrical``: Whether this route is symmetrical, ie, whether we are defining the route ``dst -> src`` at the same - time. Valid values: ``yes``, ``no``, ``YES``, ``NO``. + time. Valid values: ``yes``, ``no``, ``YES``, ``NO`` + (default: YES). ------------------------------------------------------------------------------- .. _pf_tag_router: ------------------------------------------------------------------- +-------- A router is similar to a :ref:`pf_tag_host`, but it cannot contain any actor. It is only useful to some routing algorithms. In @@ -456,6 +460,7 @@ and the list of links to go from one zone to another. **Parent tags:** :ref:`pf_tag_zone` |br| **Children tags:** :ref:`pf_tag_link_ctn` |br| +**See also:** :ref:`pf_tag_route` |br| **Attributes:** :``src``: Zone from which this route starts. Must be an existing zone. @@ -466,6 +471,14 @@ and the list of links to go from one zone to another. are defining the route ``dst -> src`` at the same time. Valid values: ``yes``, ``no``, ``YES``, ``NO``. +Afterward, the path from `src_host` in zone `src`, to `dst_host` in +zone `dst`, is composed of 3 segments. First, move within zone `src` +from `src_host` to the specified gateway `gw_src`. Then, traverse all +links specified by the zoneRoute (purportedly within the common +ancestor) and finally, move within zone `dst` from `gw_dst` to +`dst_host`. + + ------------------------------------------------------------------------------- .. _pf_tag_cluster: diff --git a/tools/cmake/DefinePackages.cmake b/tools/cmake/DefinePackages.cmake index 667716d753..1c031749f5 100644 --- a/tools/cmake/DefinePackages.cmake +++ b/tools/cmake/DefinePackages.cmake @@ -853,9 +853,7 @@ set(DOC_SOURCES doc/doxygen/inside_cmake.doc doc/doxygen/inside_extending.doc doc/doxygen/inside_release.doc - doc/doxygen/module-sd.doc doc/doxygen/module-surf.doc - doc/doxygen/module-trace.doc doc/doxygen/module-index.doc doc/doxygen/outcomes_vizu.doc doc/doxygen/platform.doc