doc/doxygen/module-surf.doc

   1 /** \addtogroup SURF_API
   2
   3   \section SURF_doc Surf documentation
   4    Surf is composed several components:
   5    - \ref SURF_simulation
   6    - \ref SURF_actions
   7    - \ref SURF_resources
   8    - \ref SURF_build_api
   9    - \ref SURF_interface
  10    - \ref SURF_routing
  11    - \ref SURF_cpu_interface
  12    - \ref SURF_network_interface
  13    - \ref SURF_storage_interface
  14    - \ref SURF_workstation_interface
  15    - \ref SURF_vm_workstation_interface
  16    - \ref SURF_callbacks
  17    - \ref SURF_plugin_energy
  18
  19
  20 */
  21
  22 /** \defgroup SURF_simulation Simulation
  23     \ingroup SURF_API
  24     \brief Functions for creating the environment and launching the simulation
  25
  26     This section describes the functions for initialising SURF, performing
  27     the simulation and exiting SURF.
  28 */
  29
  30 /** \defgroup SURF_actions SURF actions
  31     \ingroup SURF_API
  32     \brief This section describes the different datatypes and operations related to the actions in SURF.
  33
  34     \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Actions" --> \endhtmlonly
  35 */
  36
  37 /** \defgroup SURF_resources SURF resources
  38     \ingroup SURF_API
  39     \brief This section describes the different datatypes and operations related to the resources in SURF.
  40
  41     \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Resources" --> \endhtmlonly
  42 */
  43
  44 /** \defgroup SURF_build_api Create a new API
  45     \ingroup SURF_API
  46     \brief How to build a new API on top of SURF
  47
  48     SURF provides the functionnalities to simulate the platform. There are two main datatypes in SURF:
  49     the actions and the resources. Several types of resources exist:
  50         - the workstation resource,
  51         - the network resource,
  52         - the CPU resource,
  53         - the timer resource.
  54
  55     The implentation of these resources depends on the platform model you choose. There are several
  56     platform models. You can select your model by calling surf_workstation_resource_init_CLM03()
  57     or surf_workstation_resource_init_KCCFLN05(). See the documentation of these functions to have
  58     more details about the models. Remember that the model KCCFLN05 is an implementation of both the
  59     workstation resource and the network.
  60
  61     Typically, your functions should call the SURF functions provided by the structures
  62     \a surf_workstation_resource->common_public and \a surf_workstation_resource->extension_public.
  63     See surf_resource_public and surf_workstation_resource_extension_public to know the available functions.
  64
  65     To initialize SURF, call surf_init(). Then call surf_timer_resource_init() and
  66     surf_workstation_resource_init_CLM03() or surf_workstation_resource_init_KCCFLN05()
  67     to create the platform.
  68
  69     Then you can access the workstations and the network links with
  70     the global variables \ref host_lib
  71     and \ref link_lib. Some functions in \a surf_workstation_resource->extension_public can give
  72     you some information about:
  73         - a workstation: get_speed(), get_available_speed();
  74         - a network link: get_link_name(), get_link_latency(), get_link_bandwith();
  75         - a route: get_route(), get_route_size().
  76
  77     During the simulation, call \a surf_workstation_resource->extension_public->execute() to schedule a
  78     computation task on a workstation, or \a surf_workstation_resource->extension_public->communicate()
  79     to schedule a communication task between two workstations. You can also create parallel task
  80     with \a surf_workstation_resource->extension_public->execute_parallel_task(). These functions return
  81     a new action that represents the task you have just created.
  82
  83     To execute the actions created with \a execute(), \a communicate() or \a execute_parallel_task(), call
  84     surf_solve(). The function surf_solve() is where the simulation takes place. It returns the
  85     time elapsed to execute the actions. You can know what actions have changed their state thanks
  86     to the states sets. For example, if your want to know what actions are finished,
  87     extract them from \a surf_workstation_resource->common_public->states.done_action_set.
  88     Depending on these results, you can schedule other tasks and call surf_solve() again.
  89
  90     When the simulation is over, just call surf_exit() to clean the memory.
  91
  92     Have a look at the implementation of \ref MSG_API "MSG" and \ref SD_API "Simdag" to see how these module
  93     interact with SURF. But if you want to create a new API on top of SURF,
  94     we strongly recommand you to contact us before anyway.
  95
  96 */
  97
  98 /**
  99 @defgroup SURF_c_bindings   SURF C bindings
 100 @ingroup SURF_API
 101 @brief Describes the c bindings of SURF
 102
 103 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Surf C bindings" --> @endhtmlonly
 104 */
 105
 106 /**
 107 @defgroup SURF_routing_interface   SURF Routing Interface
 108 @ingroup SURF_API
 109 @brief Describes the routing interface
 110
 111 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Surf Routing" --> @endhtmlonly
 112 */
 113
 114 /**
 115 @defgroup SURF_interface   SURF Interface
 116 @ingroup SURF_API
 117 @brief Describes the general interface for all components (Cpu, Network, Storage, Workstation, WorkstationVM)
 118
 119 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Surf Interface" --> @endhtmlonly
 120 */
 121
 122 /**
 123 @defgroup SURF_cpu_interface   SURF Cpu Interface
 124 @ingroup SURF_API
 125 @brief Describes the general Cpu interface for all Cpu implementations
 126
 127 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Cpu Interface" --> @endhtmlonly
 128 */
 129
 130 /**
 131 @defgroup SURF_network_interface   SURF Network Interface
 132 @ingroup SURF_API
 133 @brief Describes the general Network interface for all Network implementations
 134
 135 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Network Interface" --> @endhtmlonly
 136 */
 137
 138 /**
 139 @defgroup SURF_storage_interface   SURF Storage Interface
 140 @ingroup SURF_API
 141 @brief Describes the general  interface for all Storage implementations
 142
 143 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Storage Interface" --> @endhtmlonly
 144 */
 145
 146 /**
 147 @defgroup SURF_workstation_interface   SURF Workstation Interface
 148 @ingroup SURF_API
 149 @brief Describes the general  interface for all Workstation implementations
 150
 151 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Workstation Interface" --> @endhtmlonly
 152 */
 153
 154 /**
 155 @defgroup SURF_vm_workstation_interface   SURF VM Workstation Interface
 156 @ingroup SURF_API
 157 @brief Describes the general  interface for all VM Workstation implementations
 158
 159 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="VM Workstation Interface" --> @endhtmlonly
 160 */
 161
 162 /**
 163 @defgroup SURF_callbacks   SURF callbacks
 164 @ingroup SURF_API
 165 @brief Describes how to use the SURF callbacks
 166
 167 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="SURF callbacks" --> @endhtmlonly
 168 */
 169
 170 /**
 171 @defgroup SURF_plugin_energy   SURF Energy Plugin
 172 @ingroup SURF_API
 173 @brief Describes how to use the energy plugin.
 174
 175 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Energy plugin" --> @endhtmlonly
 176 */