doc/module-surf.doc

   1 /** \addtogroup SURF_API
   2
   3   \section SURF_doc Surf documentation
   4    - \ref SURF_simulation
   5    - \ref SURF_actions
   6    - \ref SURF_resources
   7    - \ref SURF_build_api
   8
   9 */
  10
  11 /**     \addtogroup SURF_simulation
  12         \ingroup SURF_API  */
  13 /**     \addtogroup SURF_actions
  14         \ingroup SURF_API  */
  15 /**     \addtogroup SURF_resources
  16         \ingroup SURF_API  */
  17 /**     \addtogroup SURF_build_api
  18         \ingroup SURF_API  */
  19
  20 /** \defgroup SURF_simulation Simulation
  21     \ingroup SURF_API
  22     \brief Functions for creating the environment and launching the simulation
  23
  24     This section describes the functions for initialising SURF, performing
  25     the simulation and exiting SURF.
  26 */
  27
  28 /** \defgroup SURF_actions SURF actions
  29     \ingroup SURF_API
  30     \brief This section describes the different datatypes and operations related to the actions in SURF.
  31
  32     \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Actions" --> \endhtmlonly
  33 */
  34
  35 /** \defgroup SURF_resources SURF resources
  36     \ingroup SURF_API
  37     \brief This section describes the different datatypes and operations related to the resources in SURF.
  38
  39     \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Resources" --> \endhtmlonly
  40 */
  41
  42 /** \defgroup SURF_build_api Create a new API
  43     \ingroup SURF_API
  44     \brief How to build a new API on top of SURF
  45
  46     SURF provides the functionnalities to simulate the platform. There are two main datatypes in SURF:
  47     the actions and the resources. Several types of resources exist:
  48         - the workstation resource,
  49         - the network resource,
  50         - the CPU resource,
  51         - the timer resource.
  52
  53     The implentation of these resources depends on the platform model you choose. There are several
  54     platform models. You can select your model by calling surf_workstation_resource_init_CLM03()
  55     or surf_workstation_resource_init_KCCFLN05(). See the documentation of these functions to have
  56     more details about the models. Remember that the model KCCFLN05 is an implementation of both the
  57     workstation resource and the network.
  58
  59     Typically, your functions should call the SURF functions provided by the structures
  60     \a surf_workstation_resource->common_public and \a surf_workstation_resource->extension_public.
  61     See surf_resource_public and surf_workstation_resource_extension_public to know the available functions.
  62
  63     To initialize SURF, call surf_init(). Then call surf_timer_resource_init() and
  64     surf_workstation_resource_init_CLM03() or surf_workstation_resource_init_KCCFLN05()
  65     to create the platform.
  66
  67     Then you can access the workstations and the network links with the global variables \ref workstation_set
  68     and \ref network_link_set. Some functions in \a surf_workstation_resource->extension_public can give
  69     you some information about:
  70         - a workstation: get_speed(), get_available_speed();
  71         - a network link: get_link_name(), get_link_latency(), get_link_bandwith();
  72         - a route: get_route(), get_route_size().
  73
  74     During the simulation, call \a surf_workstation_resource->extension_public->execute() to schedule a
  75     computation task on a workstation, or \a surf_workstation_resource->extension_public->communicate()
  76     to schedule a communication task between two workstations. You can also create parallel task
  77     with \a surf_workstation_resource->extension_public->execute_parallel_task(). These functions return
  78     a new action that represents the task you have just created.
  79
  80     To execute the actions created with \a execute(), \a communicate() or \a execute_parallel_task(), call
  81     surf_solve(). The function surf_solve() is where the simulation takes place. It returns the
  82     time elapsed to execute the actions. You can know what actions have changed their state thanks
  83     to the states sets. For example, if your want to know what actions are finished,
  84     extract them from \a surf_workstation_resource->common_public->states.done_action_set.
  85     Depending on these results, you can schedule other tasks and call surf_solve() again.
  86
  87     When the simulation is over, just call surf_exit() to clean the memory.
  88
  89     Have a look at the implementation of \ref MSG_API "MSG" and \ref SD_API "Simdag" to see how these module
  90     interact with SURF. But if you want to create a new API on top of SURF,
  91     we strongly recommand you to contact us before anyway.
  92
  93 */