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