From 362f3fb4fd2addde094a214296eb2651e4eba5e6 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Fri, 24 Jul 2015 22:28:59 +0200 Subject: [PATCH] various fixups to the surf documentation Much more would be needed, as usual :-( --- doc/doxygen/module-surf.doc | 60 +++++++++++------------ examples/java/surfPlugin/surf_plugin.tesh | 5 +- src/include/surf/surf.h | 23 +-------- src/simix/libsmx.c | 2 - src/xbt/log.c | 2 + 5 files changed, 38 insertions(+), 54 deletions(-) diff --git a/doc/doxygen/module-surf.doc b/doc/doxygen/module-surf.doc index d7e025fcec..1cfcdc4851 100644 --- a/doc/doxygen/module-surf.doc +++ b/doc/doxygen/module-surf.doc @@ -3,6 +3,7 @@ \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 @@ -10,8 +11,8 @@ - \ref SURF_cpu_interface - \ref SURF_network_interface - \ref SURF_storage_interface - - \ref SURF_workstation_interface - - \ref SURF_vm_workstation_interface + - \ref SURF_host_interface + - \ref SURF_vm_interface - \ref SURF_lmm - \ref SURF_callbacks - \ref SURF_plugin_energy @@ -19,6 +20,11 @@ */ +/** \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 @@ -33,44 +39,38 @@ SURF provides the functionalities to simulate the platform. There are two main data types in SURF: the actions and the resources. Several types of resources exist: - - the workstation resource, + - the host resource, - the network resource, - the CPU resource, - the timer resource. - The implementation of these resources depends on the platform model you choose. There are several - platform models. You can select your model by calling surf_workstation_resource_init_CLM03() - or surf_workstation_resource_init_KCCFLN05(). See the documentation of these functions to have - more details about the models. Remember that the model KCCFLN05 is an implementation of both the - workstation resource and the network. - - Typically, your functions should call the SURF functions provided by the structures - \a surf_workstation_resource->common_public and \a surf_workstation_resource->extension_public. - See surf_resource_public and surf_workstation_resource_extension_public to know the available functions. + The implementation of these resources depends on the platform + models you choose. You can select your model by calling + #surf_host_model_init_current_default() (which will give you a + CLM03 model), or similar (see \ref SURF_models). - To initialize SURF, call surf_init(). Then call surf_timer_resource_init() and - surf_workstation_resource_init_CLM03() or surf_workstation_resource_init_KCCFLN05() + To initialize SURF, call #surf_init(). Then + #surf_host_model_init_current_default() or #surf_host_model_init_ptask_L07() to create the platform. - Then you can access the workstations and the network links with - the global variables \ref host_lib - and \ref link_lib. Some functions in \a surf_workstation_resource->extension_public can give + Then you can access the hosts with the global variables \ref host_lib. + Some functions of the \ref SURF_host_interface and similar can give you some information about: - - a workstation: get_speed(), get_available_speed(); + - a host: get_speed(), get_available_speed(); - a network link: get_link_name(), get_link_latency(), get_link_bandwith(); - a route: get_route(), get_route_size(). - During the simulation, call \a surf_workstation_resource->extension_public->execute() to schedule a - computation task on a workstation, or \a surf_workstation_resource->extension_public->communicate() - to schedule a communication task between two workstations. You can also create parallel task - with \a surf_workstation_resource->extension_public->execute_parallel_task(). These functions return + During the simulation, call \a surf_host_model->execute() to schedule a + computation task on a host, or \a surf_host_model->communicate() + to schedule a communication task between two hosts. You can also create parallel task + with \a surf_host_model->extension_public->execute_parallel_task(). These functions return a new action that represents the task you have just created. To execute the actions created with \a execute(), \a communicate() or \a execute_parallel_task(), call surf_solve(). The function surf_solve() is where the simulation takes place. It returns the time elapsed to execute the actions. You can know what actions have changed their state thanks to the states sets. For example, if your want to know what actions are finished, - extract them from \a surf_workstation_resource->common_public->states.done_action_set. + extract them from \a surf_host_model->common_public->states.done_action_set. Depending on these results, you can schedule other tasks and call surf_solve() again. When the simulation is over, just call surf_exit() to clean the memory. @@ -92,7 +92,7 @@ /** @defgroup SURF_interface SURF Interface @ingroup SURF_API -@brief Describes the general interface for all components (Cpu, Network, Storage, Workstation, WorkstationVM) +@brief Describes the general interface for all components (Cpu, Network, Storage, Host, VM) @htmlonly @endhtmlonly */ @@ -130,19 +130,19 @@ */ /** -@defgroup SURF_workstation_interface SURF Workstation Interface +@defgroup SURF_host_interface SURF Host Interface @ingroup SURF_API -@brief Describes the general interface for all Workstation implementations +@brief Describes the general interface for all Host implementations -@htmlonly @endhtmlonly +@htmlonly @endhtmlonly */ /** -@defgroup SURF_vm_workstation_interface SURF VM Workstation Interface +@defgroup SURF_vm_interface SURF VM Interface @ingroup SURF_API -@brief Describes the general interface for all VM Workstation implementations +@brief Describes the general interface for all VM implementations -@htmlonly @endhtmlonly +@htmlonly @endhtmlonly */ /** diff --git a/examples/java/surfPlugin/surf_plugin.tesh b/examples/java/surfPlugin/surf_plugin.tesh index c28f77af9d..c425c63294 100644 --- a/examples/java/surfPlugin/surf_plugin.tesh +++ b/examples/java/surfPlugin/surf_plugin.tesh @@ -1,6 +1,9 @@ #! tesh -! output sort +# we have to sort the output as events are delivered in the order of +# map traversal, which is not portable + +! output sort $ java -classpath ${classpath:=.} surfPlugin/TestPlugin ${srcdir:=.}/../platforms/small_platform.xml ${srcdir:=.}/surfPlugin/surfPluginDeployment.xml > [0.000000] [jmsg/INFO] Using regular java threads. Coroutines could speed your simulation up. > [0.000000] [jmsg/INFO] Trace: Link created __loopback__ diff --git a/src/include/surf/surf.h b/src/include/surf/surf.h index c081bcbbab..f53f48c023 100644 --- a/src/include/surf/surf.h +++ b/src/include/surf/surf.h @@ -148,8 +148,6 @@ XBT_PUBLIC(void) model_help(const char *category, /** @ingroup SURF_interface * @brief Action states * - * Action states. - * * @see Action */ typedef enum { @@ -312,22 +310,10 @@ static inline void surf_host_set_state(surf_host_t host, e_surf_resource_state_t surf_resource_set_state((surf_cpp_resource_t)host, state); } -/** - * @brief Get the speed of the cpu associated to a host - * - * @param resource The surf host - * @param load [description] - * - * @return [description] - */ +/** @brief Get the speed of the cpu associated to a host */ XBT_PUBLIC(double) surf_host_get_speed(surf_resource_t resource, double load); -/** - * @brief Get the available speed of cpu associated to a host - * - * @param resource The surf host - * @return [description] - */ +/** @brief Get the available speed of cpu associated to a host */ XBT_PUBLIC(double) surf_host_get_available_speed(surf_resource_t host); /** @brief Get the number of cores of the cpu associated to a host */ @@ -912,7 +898,6 @@ XBT_PUBLIC(void) surf_network_model_init_CM02(void); #ifdef HAVE_GTNETS /** \ingroup SURF_models * \brief Initializes the platform with the network model GTNETS - * \param filename XML platform file name * * This function is called by surf_host_model_init_GTNETS * or by yourself only if you plan using surf_host_model_init_compound @@ -925,7 +910,6 @@ XBT_PUBLIC(void) surf_network_model_init_GTNETS(void); #ifdef HAVE_NS3 /** \ingroup SURF_models * \brief Initializes the platform with the network model NS3 - * \param filename XML platform file name * * This function is called by surf_host_model_init_NS3 * or by yourself only if you plan using surf_host_model_init_compound @@ -937,7 +921,6 @@ XBT_PUBLIC(void) surf_network_model_init_NS3(void); /** \ingroup SURF_models * \brief Initializes the platform with the network model Reno - * \param filename XML platform file name * * The problem is related to max( sum( arctan(C * Df * xi) ) ). * @@ -952,7 +935,6 @@ XBT_PUBLIC(void) surf_network_model_init_Reno(void); /** \ingroup SURF_models * \brief Initializes the platform with the network model Reno2 - * \param filename XML platform file name * * The problem is related to max( sum( arctan(C * Df * xi) ) ). * @@ -967,7 +949,6 @@ XBT_PUBLIC(void) surf_network_model_init_Reno2(void); /** \ingroup SURF_models * \brief Initializes the platform with the network model Vegas - * \param filename XML platform file name * * This problem is related to max( sum( a * Df * ln(xi) ) ) which is equivalent * to the proportional fairness. diff --git a/src/simix/libsmx.c b/src/simix/libsmx.c index 9dbb56f375..acd28e0ebe 100644 --- a/src/simix/libsmx.c +++ b/src/simix/libsmx.c @@ -235,7 +235,6 @@ double simcall_host_get_wattmax_at(msg_host_t host, int pstate){ * to create the SIMIX synchro. It can raise a host_error exception if the host crashed. * * \param name Name of the execution synchro to create - * \param host SIMIX host where the synchro will be executed * \param flops_amount amount Computation amount (in flops) * \param priority computation priority * \param bound @@ -570,7 +569,6 @@ void simcall_vm_migratefrom_resumeto(sg_host_t vm, sg_host_t src_pm, sg_host_t d * * The structure and the corresponding thread are created and put in the list of ready processes. * - * \param process the process created will be stored in this pointer * \param name a name for the process. It is for user-level information and can be NULL. * \param code the main function of the process * \param data a pointer to any data one may want to attach to the new object. It is for user-level information and can be NULL. diff --git a/src/xbt/log.c b/src/xbt/log.c index c690e8ba2a..d65a9f378a 100644 --- a/src/xbt/log.c +++ b/src/xbt/log.c @@ -643,6 +643,7 @@ static void xbt_log_connect_categories(void) XBT_LOG_CONNECT(mc_ignore); XBT_LOG_CONNECT(mcer_ignore); XBT_LOG_CONNECT(mc_liveness); + XBT_LOG_CONNECT(mc_main); XBT_LOG_CONNECT(mc_memory); XBT_LOG_CONNECT(mc_memory_map); XBT_LOG_CONNECT(mc_page_snapshot); @@ -654,6 +655,7 @@ static void xbt_log_connect_categories(void) XBT_LOG_CONNECT(mc_comm_pattern); XBT_LOG_CONNECT(mc_process); XBT_LOG_CONNECT(mc_protocol); + XBT_LOG_CONNECT(mc_RegionSnaphot); XBT_LOG_CONNECT(mc_server); XBT_LOG_CONNECT(mc_state); #endif -- 2.20.1