move documentation from doxygen files into api files

doc/doxygen/Makefile.am

@@ -115,9 +115,7 @@ chapters =	\
 	chapters/api/scheduling_policy.doxy \
 	chapters/api/versioning.doxy \
 	chapters/api/workers.doxy \
-	chapters/api/threads.doxy \
-	chapters/api/sc_hypervisor/sc_hypervisor.doxy \
-	chapters/api/sc_hypervisor/sc_hypervisor_usage.doxy
+	chapters/api/threads.doxy
 
 images = 	\
 	chapters/images/data_trace.eps \

doc/doxygen/chapters/api/sc_hypervisor/sc_hypervisor.doxy

@@ -1,212 +0,0 @@
-/* StarPU --- Runtime system for heterogeneous multicore architectures.
- *
- * Copyright (C) 2011-2013                                Inria
- * Copyright (C) 2010-2013,2015-2017                      CNRS
- * Copyright (C) 2009-2011,2014                           Université de Bordeaux
- *
- * StarPU is free software; you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as published by
- * the Free Software Foundation; either version 2.1 of the License, or (at
- * your option) any later version.
- *
- * StarPU is distributed in the hope that it will be useful, but
- * WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- *
- * See the GNU Lesser General Public License in COPYING.LGPL for more details.
- */
-
-/*! \defgroup API_SC_Hypervisor Scheduling Context Hypervisor - Building a new resizing policy
-
-\struct sc_hypervisor_policy
-\ingroup API_SC_Hypervisor
-This structure contains all the methods that implement a hypervisor resizing policy.
-\var sc_hypervisor_policy::name
-        Indicates the name of the policy, if there is not a custom policy, the policy corresponding to this name will be used by the hypervisor
-\var sc_hypervisor_policy::custom
-        Indicates whether the policy is custom or not
-\var sc_hypervisor_policy::size_ctxs
-	Distribute workers to contexts even at the beginning of the program
-\var sc_hypervisor_policy::resize_ctxs
-	Require explicit resizing
-\var sc_hypervisor_policy::handle_idle_cycle
-        It is called whenever the indicated worker executes another idle cycle in sched_ctx
-\var sc_hypervisor_policy::handle_pushed_task
-        It is called whenever a task is pushed on the worker’s queue corresponding to the context sched_ctx
-\var sc_hypervisor_policy::handle_poped_task
-        It is called whenever a task is poped from the worker’s queue corresponding to the context sched_ctx
-\var sc_hypervisor_policy::handle_poped_task
-	The hypervisor takes a decision when another task was poped from this worker in this ctx
-\var sc_hypervisor_policy::handle_idle_end
-        It is called whenever a task is executed on the indicated worker and context after a long period of idle time
-\var sc_hypervisor_policy::handle_post_exec_hook
-        It is called whenever a tag task has just been executed. The table of resize requests is provided as well as the tag
-\var sc_hypervisor_policy::handle_submitted_job
-	The hypervisor takes a decision when a job was submitted in this ctx
-\var sc_hypervisor_policy::end_ctx
-	The hypervisor takes a decision when a certain ctx was deleted
-
-\struct sc_hypervisor_policy_config
-\ingroup API_SC_Hypervisor
-This structure contains all configuration information of a
-context. It contains configuration information for each context, which
-can be used to construct new resize strategies.
-\var sc_hypervisor_policy_config::min_nworkers
-        Indicates the minimum number of workers needed by the context
-\var sc_hypervisor_policy_config::max_nworkers
-        Indicates the maximum number of workers needed by the context
-\var sc_hypervisor_policy_config::granularity
-        Indicates the workers granularity of the context
-\var sc_hypervisor_policy_config::priority
-        Indicates the priority of each worker in the context
-\var sc_hypervisor_policy_config::max_idle
-        Indicates the maximum idle time accepted before a resize is triggered
-\var sc_hypervisor_policy_config::min_working
-	Indicates that underneath this limit the priority of the worker is reduced
-\var sc_hypervisor_policy_config::fixed_workers
-        Indicates which workers can be moved and which ones are fixed
-\var sc_hypervisor_policy_config:: new_workers_max_idle
-        Indicates the maximum idle time accepted before a resize is triggered for the workers that just arrived in the new context
-\var sc_hypervisor_policy_config::ispeed_w_sample
-         Indicates the sample used to compute the instant speed per worker
-\var sc_hypervisor_policy_config::ispeed_ctx_sample
-        Indicates the sample used to compute the instant speed per ctxs
-\var sc_hypervisor_policy_config::time_sample
-        todo
-
-\struct sc_hypervisor_wrapper
-\ingroup API_SC_Hypervisor
-This structure is a wrapper of the contexts available in StarPU
-and contains all information about a context obtained by incrementing
-the performance counters.
-\var sc_hypervisor_wrapper::sched_ctx
-        The context wrapped
-\var sc_hypervisor_wrapper::config
-        The corresponding resize configuration
-\var sc_hypervisor_wrapper::current_idle_time
-        The idle time counter of each worker of the context
-\var sc_hypervisor_wrapper::idle_time
-	The time the workers were idle from the last resize
-\var sc_hypervisor_wrapper::idle_start_time
-	The moment when the workers started being idle
-\var sc_hypervisor_wrapper::worker_to_be_removed
-	The list of workers that will leave this contexts (lazy resizing process)
-\var sc_hypervisor_wrapper::pushed_tasks
-        The number of pushed tasks of each worker of the context
-\var sc_hypervisor_wrapper::poped_tasks
-        The number of poped tasks of each worker of the context
-\var sc_hypervisor_wrapper::total_flops
-        The total number of flops to execute by the context
-\var sc_hypervisor_wrapper::total_elapsed_flops
-        The number of flops executed by each workers of the context
-\var sc_hypervisor_wrapper::elapsed_flops
-        The number of flops executed by each worker of the context from last resize
-\var sc_hypervisor_wrapper::elapsed_data
-	The quantity of data (in bytes) used to execute tasks on each worker in this ctx
-\var sc_hypervisor_wrapper::elapsed_tasks
-	The nr of tasks executed on each worker in this ctx
-\var sc_hypervisor_wrapper::ref_speed
-	The average speed of the workers (type of workers) when they belonged to this context
-	0 - cuda 1 - cpu
-\var sc_hypervisor_wrapper::submitted_flops
-	The number of flops submitted to this ctx
-\var sc_hypervisor_wrapper::remaining_flops
-        The number of flops that still have to be executed by the workers in the context
-\var sc_hypervisor_wrapper::ready_flops
-	The number of flops corresponding to the ready tasks in this context
-\var sc_hypervisor_wrapper::start_time
-        The time when he started executed
-\var sc_hypervisor_wrapper::real_start_time
-	The first time a task was pushed to this context
-\var sc_hypervisor_wrapper::resize_ack
-        The structure confirming the last resize finished and a new one can be done
-\var sc_hypervisor_wrapper::mutex
-	The mutex needed to synchronize the acknowledgment of the workers into 
-	the receiver context
-\var sc_hypervisor_wrapper::total_flops_available
-	A boolean indicating if the hypervisor can use the flops corresponding to 
-	the entire execution of the context
-\var sc_hypervisor_wrapper::nready_tasks
-	The number of ready tasks in a context
-
-\struct sc_hypervisor_resize_ack
-\ingroup API_SC_Hypervisor
-This structures checks if the workers moved to another context
-are actually taken into account in that context.
-\var sc_hypervisor_resize_ack::receiver_sched_ctx
-        The context receiving the new workers
-\var sc_hypervisor_resize_ack::moved_workers
-        The workers moved to the receiver context
-\var sc_hypervisor_resize_ack::nmoved_workers
-        The number of workers moved
-\var sc_hypervisor_resize_ack::acked_workers
-        If the value corresponding to a worker is 1, this one is taken
-	into account in the new context if 0 not yet
-
-\struct sc_hypervisor_policy_task_pool
-task wrapper linked list
-\ingroup API_SC_Hypervisor
-\var sc_hypervisor_policy_task_pool::cl
-Which codelet has been executed
-\var sc_hypervisor_policy_task_pool::footprint
-Task footprint key
-\var sc_hypervisor_policy_task_pool::sched_ctx_id
-Context the task belongs to
-\var sc_hypervisor_policy_task_pool::n
-Number of tasks of this kind
-\var sc_hypervisor_policy_task_pool::data_size
-The quantity of data(in bytes) needed by the task to execute
-\var sc_hypervisor_policy_task_pool::next
-Other task kinds
-
-\def STARPU_HYPERVISOR_TAG
-\ingroup API_SC_Hypervisor
-todo
-
-\fn void sc_hypervisor_post_resize_request(unsigned sched_ctx, int task_tag)
-\ingroup API_SC_Hypervisor
-Requires resizing the context \p sched_ctx whenever a task tagged with the id \p task_tag
-finished executing 
-
-\fn unsigned sc_hypervisor_get_size_req(unsigned **sched_ctxs, int* nsched_ctxs, int **workers, int *nworkers)
-\ingroup API_SC_Hypervisor
-Check if there are pending demands of resizing
-
-\fn void sc_hypervisor_save_size_req(unsigned *sched_ctxs, int nsched_ctxs, int *workers, int nworkers)
-\ingroup API_SC_Hypervisor
-Save a demand of resizing
-
-\fn void sc_hypervisor_free_size_req(void)
-\ingroup API_SC_Hypervisor
-Clear the list of pending demands of resizing
-
-\fn unsigned sc_hypervisor_can_resize(unsigned sched_ctx)
-\ingroup API_SC_Hypervisor
-Check out if a context can be resized
-
-\fn struct sc_hypervisor_policy_config *sc_hypervisor_get_config(unsigned sched_ctx)
-\ingroup API_SC_Hypervisor
-Returns the configuration structure of a context
-
-\fn void sc_hypervisor_set_config(unsigned sched_ctx, void *config)
-\ingroup API_SC_Hypervisor
-Set a certain configuration to a contexts
-
-\fn unsigned *sc_hypervisor_get_sched_ctxs()
-\ingroup API_SC_Hypervisor
-    Gets the contexts managed by the hypervisor
-
-\fn int sc_hypervisor_get_nsched_ctxs()
-\ingroup API_SC_Hypervisor
-    Gets the number of contexts managed by the hypervisor
-
-\fn struct sc_hypervisor_wrapper *sc_hypervisor_get_wrapper(unsigned sched_ctx)
-\ingroup API_SC_Hypervisor
-    Returns the wrapper corresponding the context \p sched_ctx
-
-\fn double sc_hypervisor_get_elapsed_flops_per_sched_ctx(struct sc_hypervisor_wrapper *sc_w)
-\ingroup API_SC_Hypervisor
-    Returns the flops of a context elapsed from the last resize
-
-
-*/

doc/doxygen/chapters/api/sc_hypervisor/sc_hypervisor_usage.doxy

@@ -1,201 +0,0 @@
-/* StarPU --- Runtime system for heterogeneous multicore architectures.
- *
- * Copyright (C) 2011-2013                                Inria
- * Copyright (C) 2010-2017                                CNRS
- * Copyright (C) 2009-2011,2014                           Université de Bordeaux
- *
- * StarPU is free software; you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as published by
- * the Free Software Foundation; either version 2.1 of the License, or (at
- * your option) any later version.
- *
- * StarPU is distributed in the hope that it will be useful, but
- * WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- *
- * See the GNU Lesser General Public License in COPYING.LGPL for more details.
- */
-
-/*! \defgroup API_SC_Hypervisor_usage Scheduling Context Hypervisor - Regular usage
-
-\fn void *sc_hypervisor_init(struct sc_hypervisor_policy *policy)
-\ingroup API_SC_Hypervisor_usage
-There is a single hypervisor that is in charge of resizing contexts
-and the resizing strategy is chosen at the initialization of the
-hypervisor. A single resize can be done at a time.
-
-The Scheduling Context Hypervisor Plugin provides a series of
-performance counters to StarPU. By incrementing them, StarPU can help
-the hypervisor in the resizing decision making process.
-
-This function initializes the hypervisor to use the strategy provided as parameter
-and creates the performance counters (see starpu_sched_ctx_performance_counters).
-These performance counters represent actually some callbacks that will
-be used by the contexts to notify the information needed by the
-hypervisor.
-
-Note: The Hypervisor is actually a worker that takes this role once
-certain conditions trigger the resizing process (there is no
-additional thread assigned to the hypervisor).
-
-\fn void sc_hypervisor_shutdown(void)
-\ingroup API_SC_Hypervisor_usage
-The hypervisor and all information concerning it is cleaned. There is
-no synchronization between this function and starpu_shutdown(). Thus,
-this should be called after starpu_shutdown(), because the performance
-counters will still need allocated callback functions.
-
-\fn void sc_hypervisor_register_ctx(unsigned sched_ctx, double total_flops)
-\ingroup API_SC_Hypervisor_usage
-Scheduling Contexts that have to be resized by the hypervisor must be
-first registered to the hypervisor. 
-This function registers the context to the hypervisor, and indicate the number of
-flops the context will execute (used for Gflops rate based strategy
-or any other custom strategy needing it, for the others we can pass 0.0)
-
-\fn void sc_hypervisor_unregister_ctx(unsigned sched_ctx)
-\ingroup API_SC_Hypervisor_usage
-Whenever we want to exclude
-contexts from the resizing process we have to unregister them from the
-hypervisor.
-
-\fn void sc_hypervisor_resize_ctxs(unsigned *sched_ctxs, int nsched_ctxs , int *workers, int nworkers)
-\ingroup API_SC_Hypervisor_usage
-Requires reconsidering the distribution of ressources over the indicated scheduling contexts 
-
-\fn void sc_hypervisor_stop_resize(unsigned sched_ctx)
-\ingroup API_SC_Hypervisor_usage
-The user can totally forbid the resizing of a certain context or can
-then change his mind and allow it (in this case the resizing is
-managed by the hypervisor, that can forbid it or allow it)
-
-\fn void sc_hypervisor_start_resize(unsigned sched_ctx)
-\ingroup API_SC_Hypervisor_usage
-Allow resizing of a context. The user can then provide information to
-the hypervisor concerning the conditions of resizing.
-
-\fn char *sc_hypervisor_get_policy();
-\ingroup API_SC_Hypervisor_usage
-Returns the name of the resizing policy the hypervisor uses
-
-\fn void sc_hypervisor_add_workers_to_sched_ctx(int* workers_to_add, unsigned nworkers_to_add, unsigned sched_ctx)
-\ingroup API_SC_Hypervisor_usage
-Ask the hypervisor to add workers to a sched_ctx 
-
-\fn void sc_hypervisor_remove_workers_from_sched_ctx(int* workers_to_remove, unsigned nworkers_to_remove, unsigned sched_ctx, unsigned now)
-\ingroup API_SC_Hypervisor_usage
-Ask the hypervisor to remove workers from a sched_ctx 
-
-\fn void sc_hypervisor_move_workers(unsigned sender_sched_ctx, unsigned receiver_sched_ctx, int *workers_to_move, unsigned nworkers_to_move, unsigned now)
-\ingroup API_SC_Hypervisor_usage
-Moves workers from one context to another
-   
-\fn void sc_hypervisor_size_ctxs(unsigned *sched_ctxs, int nsched_ctxs, int *workers, int nworkers)
-\ingroup API_SC_Hypervisor_usage
-Ask the hypervisor to chose a distribution of workers in the required contexts
-   
-
-\fn void sc_hypervisor_set_type_of_task(struct starpu_codelet *cl, unsigned sched_ctx, uint32_t footprint, size_t data_size)
-\ingroup API_SC_Hypervisor_usage
-Indicate the types of tasks a context will execute in order to better decide the sizing of ctxs
-
-\fn void sc_hypervisor_update_diff_total_flops(unsigned sched_ctx, double diff_total_flops)
-\ingroup API_SC_Hypervisor_usage
-Change dynamically the total number of flops of a context, move the deadline of the finishing time of the context
-
-\fn void sc_hypervisor_update_diff_elapsed_flops(unsigned sched_ctx, double diff_task_flops)
-\ingroup API_SC_Hypervisor_usage
-Change dynamically the number of the elapsed flops in a context, modify the past in order to better compute the speed 
-
-\fn void sc_hypervisor_ctl(unsigned sched_ctx, ...)
-\ingroup API_SC_Hypervisor_usage
-Inputs conditions to the context sched_ctx with the following
-arguments. The argument list must be zero-terminated.
-
-\def SC_HYPERVISOR_MAX_IDLE
-\ingroup API_SC_Hypervisor_usage
-This macro is used when calling sc_hypervisor_ctl() and must be
-followed by 3 arguments: an array of int for the workerids to apply
-the condition, an int to indicate the size of the array, and a double
-value indicating the maximum idle time allowed for a worker before the
-resizing process should be triggered
-
-\def SC_HYPERVISOR_PRIORITY
-\ingroup API_SC_Hypervisor_usage
-This macro is used when calling sc_hypervisor_ctl() and must be
-followed by 3 arguments: an array of int for the workerids to apply
-the condition, an int to indicate the size of the array, and an int
-value indicating the priority of the workers previously mentioned. The
-workers with the smallest priority are moved the first.
-
-\def SC_HYPERVISOR_MIN_WORKERS
-\ingroup API_SC_Hypervisor_usage
-This macro is used when calling sc_hypervisor_ctl() and must be
-followed by 1 argument(int) indicating the minimum number of workers a
-context should have, underneath this limit the context cannot execute.
-
-\def SC_HYPERVISOR_MAX_WORKERS
-\ingroup API_SC_Hypervisor_usage
-This macro is used when calling sc_hypervisor_ctl() and must be
-followed by 1 argument(int) indicating the maximum number of workers a
-context should have, above this limit the context would not be able to
-scale
-
-\def SC_HYPERVISOR_GRANULARITY
-\ingroup API_SC_Hypervisor_usage
-This macro is used when calling sc_hypervisor_ctl() and must be
-followed by 1 argument(int) indicating the granularity of the resizing
-process (the number of workers should be moved from the context once
-it is resized) This parameter is ignore for the Gflops rate based
-strategy (see \ref ResizingStrategies), the number of workers that have to
-be moved is calculated by the strategy.
-
-\def SC_HYPERVISOR_FIXED_WORKERS
-\ingroup API_SC_Hypervisor_usage
-This macro is used when calling sc_hypervisor_ctl() and must be
-followed by 2 arguments: an array of int for the workerids to apply
-the condition and an int to indicate the size of the array. These
-workers are not allowed to be moved from the context.
-
-\def SC_HYPERVISOR_MIN_TASKS
-\ingroup API_SC_Hypervisor_usage
-This macro is used when calling sc_hypervisor_ctl() and must be
-followed by 1 argument (int) that indicated the minimum number of
-tasks that have to be executed before the context could be resized.
-This parameter is ignored for the Application Driven strategy (see
-\ref ResizingStrategies) where the user indicates exactly when the resize
-should be done.
-
-\def SC_HYPERVISOR_NEW_WORKERS_MAX_IDLE
-\ingroup API_SC_Hypervisor_usage
-This macro is used when calling sc_hypervisor_ctl() and must be
-followed by 1 argument, a double value indicating the maximum idle
-time allowed for workers that have just been moved from other contexts
-in the current context.
-
-\def SC_HYPERVISOR_TIME_TO_APPLY
-\ingroup API_SC_Hypervisor_usage
-This macro is used when calling sc_hypervisor_ctl() and must be
-followed by 1 argument (int) indicating the tag an executed task
-should have such that this configuration should be taken into account.
-
-
-\def SC_HYPERVISOR_ISPEED_W_SAMPLE
-\ingroup API_SC_Hypervisor_usage
-This macro is used when calling sc_hypervisor_ctl() and must be
-followed by 1 argument, a double, that indicates the number of flops
-needed to be executed before computing the speed of a worker
-
-\def SC_HYPERVISOR_ISPEED_CTX_SAMPLE
-\ingroup API_SC_Hypervisor_usage
-This macro is used when calling sc_hypervisor_ctl() and must be
-followed by 1 argument, a double, that indicates the number of flops
-needed to be executed before computing the speed of a context
-
-
-\def SC_HYPERVISOR_NULL
-\ingroup API_SC_Hypervisor_usage
-This macro is used when calling sc_hypervisor_ctl() and must be
-followed by 1 arguments
-
-*/

doc/doxygen/doxygen.cfg

@@ -1626,6 +1626,7 @@ PREDEFINED             = STARPU_USE_OPENCL=1 \
 			 STARPU_OPENMP=1 \
 			 STARPU_MKL=1 \
 			 STARPU_WORKER_CALLBACKS=1 \
+			 STARPU_HAVE_GLPK_H=1 \
                          __GCC__
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then

doc/doxygen/refman.tex

@@ -256,8 +256,9 @@ Documentation License”.
 \input{group__API__Scheduling__Contexts}
 \input{group__API__Scheduling__Policy}
 \input{group__API__Tree}
-\input{group__API__SC__Hypervisor__usage}
 \input{group__API__SC__Hypervisor}
+\input{group__API__SC__Hypervisor__usage}
+\input{group__API__SC__Hypervisor__LP}
 \input{group__API__Modularized__Scheduler}
 \input{group__API__Clustering__Machine}
 \input{group__API__Interop__Support}

sc_hypervisor/include/sc_hypervisor.h

@@ -1,7 +1,7 @@
 /* StarPU --- Runtime system for heterogeneous multicore architectures.
  *
  * Copyright (C) 2011-2015                                Inria
- * Copyright (C) 2012,2013,2017                           CNRS
+ * Copyright (C) 2012,2013,2017,2019                      CNRS
  *
  * StarPU is free software; you can redistribute it and/or modify
  * it under the terms of the GNU Lesser General Public License as published by
@@ -29,130 +29,267 @@ extern "C"
 {
 #endif
 
-/* synchronise the hypervisor when several workers try to update its information */
+/**
+   @defgroup API_SC_Hypervisor_usage Scheduling Context Hypervisor - Regular usage
+   There is a single hypervisor that is in charge of resizing contexts
+   and the resizing strategy is chosen at the initialization of the
+   hypervisor. A single resize can be done at a time.
+
+   The Scheduling Context Hypervisor Plugin provides a series of
+   performance counters to StarPU. By incrementing them, StarPU can
+   help the hypervisor in the resizing decision making process.
+
+   The function sc_hypervisor_init() initializes the hypervisor to use
+   the strategy provided as parameter and creates the performance
+   counters (see starpu_sched_ctx_performance_counters). These
+   performance counters represent actually some callbacks that will be
+   used by the contexts to notify the information needed by the
+   hypervisor.
+
+   Scheduling Contexts that have to be resized by the hypervisor must
+   be first registered to the hypervisor using the function
+   sc_hypervisor_register_ctx()
+
+   Note: The Hypervisor is actually a worker that takes this role once
+   certain conditions trigger the resizing process (there is no
+   additional thread assigned to the hypervisor).
+   @{
+*/
+
+/**
+   synchronise the hypervisor when several workers try to update its
+   information
+*/
 extern starpu_pthread_mutex_t act_hypervisor_mutex;
 
-/* platform of resizing contexts */
+/**
+   @ingroup API_SC_Hypervisor
+   Methods to implement a hypervisor resizing policy.
+*/
 struct sc_hypervisor_policy
 {
-	/* name of the strategy */
+	/**
+	   Indicate the name of the policy, if there is not a custom
+	   policy, the policy corresponding to this name will be used
+	   by the hypervisor
+	*/
 	const char* name;
 
-	/* indicate if it is a policiy create by the user or not */
+	/**
+	   Indicate whether the policy is custom or not
+	*/
 	unsigned custom;
 
-	/* Distribute workers to contexts even at the begining of the program */
+	/**
+	   Distribute workers to contexts even at the begining of the
+	   program
+	*/
 	void (*size_ctxs)(unsigned *sched_ctxs, int nsched_ctxs , int *workers, int nworkers);
 
-	/* Require explicit resizing */
+	/**
+	   Require explicit resizing
+	*/
 	void (*resize_ctxs)(unsigned *sched_ctxs, int nsched_ctxs , int *workers, int nworkers);
 
-	/* the hypervisor takes a decision when the worker was idle for another cyle in this ctx */
+	/**
+	   Called whenever the indicated worker executes another idle
+	   cycle in sched_ctx
+	*/
 	void (*handle_idle_cycle)(unsigned sched_ctx, int worker);
 
-	/* the hypervisor takes a decision when another task was pushed on this worker in this ctx */
+	/**
+	   Called whenever a task is pushed on the worker’s queue
+	   corresponding to the context sched_ctx
+	*/
 	void (*handle_pushed_task)(unsigned sched_ctx, int worker);
 
-	/* the hypervisor takes a decision when another task was poped from this worker in this ctx */
+	/**
+	   Called whenever a task is poped from the worker’s queue
+	   corresponding to the context sched_ctx
+	*/
 	void (*handle_poped_task)(unsigned sched_ctx, int worker,struct starpu_task *task, uint32_t footprint);
 
-	/* the hypervisor takes a decision when the worker stoped being idle in this ctx */
+	/**
+	   Called whenever a task is executed on the indicated worker
+	   and context after a long period of idle time
+	*/
 	void (*handle_idle_end)(unsigned sched_ctx, int worker);
 
-	/* the hypervisor takes a decision when a certain task finished executing in this ctx */
+	/**
+	   Called whenever a tag task has just been executed. The
+	   table of resize requests is provided as well as the tag
+	*/
 	void (*handle_post_exec_hook)(unsigned sched_ctx, int task_tag);
 
-	/* the hypervisor takes a decision when a job was submitted in this ctx */
+	/**
+	   the hypervisor takes a decision when a job was submitted in
+	   this ctx
+	*/
 	void (*handle_submitted_job)(struct starpu_codelet *cl, unsigned sched_ctx, uint32_t footprint, size_t data_size);
-	
-	/* the hypervisor takes a decision when a certain ctx was deleted */
+
+	/**
+	   the hypervisor takes a decision when a certain ctx was
+	   deleted
+	*/
 	void (*end_ctx)(unsigned sched_ctx);
 
-	/* the hypervisor takes a decision when a certain ctx was registerd */
+	/**
+	   the hypervisor takes a decision when a certain ctx was
+	   registerd
+	*/
 	void (*start_ctx)(unsigned sched_ctx);
-	
-	/* the hypervisor initializes values for the workers */
+
+	/**
+	   the hypervisor initializes values for the workers
+	*/
 	void (*init_worker)(int workerid, unsigned sched_ctx);
 };
 
-/* start the hypervisor indicating the resizing policy to user */
+/**
+   Start the hypervisor with the given policy
+*/
 void* sc_hypervisor_init(struct sc_hypervisor_policy *policy);
 
-/* shutdown the hypervisor */
+/**
+   Shutdown the hypervisor.
+   The hypervisor and all information concerning it is cleaned. There
+   is no synchronization between this function and starpu_shutdown().
+   Thus, this should be called after starpu_shutdown(), because the
+   performance counters will still need allocated callback functions.
+*/
 void sc_hypervisor_shutdown(void);
 
-/* only registered contexts are resized by the hypervisor */
+/**
+   Register the context to the hypervisor, and indicate the number of
+   flops the context will execute (used for Gflops rate based strategy)
+*/
 void sc_hypervisor_register_ctx(unsigned sched_ctx, double total_flops);
 
-/* remove a worker from the hypervisor's list */
+/**
+   Unregister a context from the hypervisor, and so exclude the
+   context from the resizing process
+*/
 void sc_hypervisor_unregister_ctx(unsigned sched_ctx);
 
-/* submit a requirement of resizing when a task taged with task_tag is executed */
+/**
+   Require resizing the context \p sched_ctx whenever a task tagged
+   with the id \p task_tag finished executing
+*/
 void sc_hypervisor_post_resize_request(unsigned sched_ctx, int task_tag);
 
-/* reevaluate the distribution of the resources and eventually resize if needed */
+/**
+   Require reconsidering the distribution of ressources over the
+   indicated scheduling contexts, i.e reevaluate the distribution of
+   the resources and eventually resize if needed
+*/
 void sc_hypervisor_resize_ctxs(unsigned *sched_ctxs, int nsched_ctxs , int *workers, int nworkers);
 
-/* don't allow the hypervisor to resize a context */
+/**
+   Do not allow the hypervisor to resize a context.
+*/
 void sc_hypervisor_stop_resize(unsigned sched_ctx);
 
-/* allow the hypervisor to resize a context */
+/**
+   Allow the hypervisor to resize a context if necessary.
+*/
 void sc_hypervisor_start_resize(unsigned sched_ctx);
 
-/* check out the current policy of the hypervisor */
+/**
+   Return the name of the resizing policy used by the hypervisor
+*/
 const char *sc_hypervisor_get_policy();
 
-/* ask the hypervisor to add workers to a sched_ctx */
+/**
+   Ask the hypervisor to add workers to a sched_ctx
+*/
 void sc_hypervisor_add_workers_to_sched_ctx(int* workers_to_add, unsigned nworkers_to_add, unsigned sched_ctx);
 
-/* ask the hypervisor to remove workers from a sched_ctx */
+/**
+   Ask the hypervisor to remove workers from a sched_ctx
+*/
 void sc_hypervisor_remove_workers_from_sched_ctx(int* workers_to_remove, unsigned nworkers_to_remove, unsigned sched_ctx, unsigned now);
 
-/* ask the hypervisor to move workers from one context to another */
+/**
+   Ask the hypervisor to move workers from one context to another
+*/
 void sc_hypervisor_move_workers(unsigned sender_sched_ctx, unsigned receiver_sched_ctx, int *workers_to_move, unsigned nworkers_to_move, unsigned now);
 
-/* ask the hypervisor to chose a distribution of workers in the required contexts */
+/**
+   Ask the hypervisor to choose a distribution of workers in the
+   required contexts
+*/
 void sc_hypervisor_size_ctxs(unsigned *sched_ctxs, int nsched_ctxs, int *workers, int nworkers);
 
-/* check if there are pending demands of resizing */
+/**
+   Check if there are pending demands of resizing
+*/
 unsigned sc_hypervisor_get_size_req(unsigned **sched_ctxs, int* nsched_ctxs, int **workers, int *nworkers);
 
-/* save a demand of resizing */
+/**
+   Save a demand of resizing
+*/
 void sc_hypervisor_save_size_req(unsigned *sched_ctxs, int nsched_ctxs, int *workers, int nworkers);
 
-/* clear the list of pending demands of resizing */
+/**
+   Clear the list of pending demands of resizing
+*/
 void sc_hypervisor_free_size_req(void);
 
-/* check out if a context can be resized */
+/**
+   Check out if a context can be resized
+*/
 unsigned sc_hypervisor_can_resize(unsigned sched_ctx);
 
-/* indicate the types of tasks a context will execute in order to better decide the sizing of ctxs */
+/**
+   Indicate the types of tasks a context will execute in order to
+   better decide the sizing of ctxs
+*/
 void sc_hypervisor_set_type_of_task(struct starpu_codelet *cl, unsigned sched_ctx, uint32_t footprint, size_t data_size);
 
-/* change dynamically the total number of flops of a context, move the deadline of the finishing time of the context */
+/**
+   Change dynamically the total number of flops of a context, move the
+   deadline of the finishing time of the context
+*/
 void sc_hypervisor_update_diff_total_flops(unsigned sched_ctx, double diff_total_flops);
 
-/* change dynamically the number of the elapsed flops in a context, modify the past in order to better compute the speed */
+/**
+   Change dynamically the number of the elapsed flops in a context,
+   modify the past in order to better compute the speed
+*/
 void sc_hypervisor_update_diff_elapsed_flops(unsigned sched_ctx, double diff_task_flops);
 
-/* updates the min and max workers needed by each context */
+/**
+   Update the min and max workers needed by each context
+*/
 void sc_hypervisor_update_resize_interval(unsigned *sched_ctxs, int nsched_ctxs, int max_nworkers);
 
-/* returns a list of contexts that are on the same level in the hierarchy of contexts */
+/**
+   Return a list of contexts that are on the same level in the
+   hierarchy of contexts
+*/
 void sc_hypervisor_get_ctxs_on_level(unsigned **sched_ctxs, int *nsched_ctxs, unsigned hierarchy_level, unsigned father_sched_ctx_id);
 
-/* returns the number of levels of ctxs registered to the hyp */
+/**
+   Returns the number of levels of ctxs registered to the hyp
+*/
 unsigned sc_hypervisor_get_nhierarchy_levels(void);
 
-/* return the leaves ctxs from the list of ctxs */
+/**
+   Return the leaves ctxs from the list of ctxs
+*/
 void sc_hypervisor_get_leaves(unsigned *sched_ctxs, int nsched_ctxs, unsigned *leaves, int *nleaves);
 
-/* returns the nready flops of all ctxs below in hierachy of sched_ctx */
+/**
+   Return the nready flops of all ctxs below in hierachy of sched_ctx
+*/
 double sc_hypervisor_get_nready_flops_of_all_sons_of_sched_ctx(unsigned sched_ctx);
 
 void sc_hypervisor_print_overhead();
 
 void sc_hypervisor_init_worker(int workerid, unsigned sched_ctx);
+
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif

sc_hypervisor/include/sc_hypervisor_config.h

@@ -1,7 +1,7 @@
 /* StarPU --- Runtime system for heterogeneous multicore architectures.
  *
  * Copyright (C) 2011,2013                                Inria
- * Copyright (C) 2013,2017                                CNRS
+ * Copyright (C) 2013,2017,2019                           CNRS
  *
  * StarPU is free software; you can redistribute it and/or modify
  * it under the terms of the GNU Lesser General Public License as published by
@@ -25,73 +25,206 @@ extern "C"
 {
 #endif
 
-/* ctl properties*/
+/**
+   @ingroup API_SC_Hypervisor
+   @{
+*/
+
+/**
+   This macro is used when calling sc_hypervisor_ctl() and must be
+   followed by 3 arguments: an array of int for the workerids to apply
+   the condition, an int to indicate the size of the array, and a
+   double value indicating the maximum idle time allowed for a worker
+   before the resizing process should be triggered
+*/
 #define SC_HYPERVISOR_MAX_IDLE -1
+
 #define SC_HYPERVISOR_MIN_WORKING -2
+
+/**
+   This macro is used when calling sc_hypervisor_ctl() and must be
+   followed by 3 arguments: an array of int for the workerids to apply
+   the condition, an int to indicate the size of the array, and an int
+   value indicating the priority of the workers previously mentioned.
+   The workers with the smallest priority are moved the first.
+*/
 #define SC_HYPERVISOR_PRIORITY -3
+
+/**
+   This macro is used when calling sc_hypervisor_ctl() and must be
+   followed by 1 argument(int) indicating the minimum number of
+   workers a context should have, underneath this limit the context
+   cannot execute.
+*/
 #define SC_HYPERVISOR_MIN_WORKERS -4
+
+/**
+   This macro is used when calling sc_hypervisor_ctl() and must be
+   followed by 1 argument(int) indicating the maximum number of
+   workers a context should have, above this limit the context would
+   not be able to scale
+*/
 #define SC_HYPERVISOR_MAX_WORKERS -5
+
+/**
+   This macro is used when calling sc_hypervisor_ctl() and must be
+   followed by 1 argument(int) indicating the granularity of the
+   resizing process (the number of workers should be moved from the
+   context once it is resized) This parameter is ignore for the Gflops
+   rate based strategy (see \ref ResizingStrategies), the number of
+   workers that have to be moved is calculated by the strategy.
+*/
 #define SC_HYPERVISOR_GRANULARITY -6
+
+/**
+   This macro is used when calling sc_hypervisor_ctl() and must be
+   followed by 2 arguments: an array of int for the workerids to apply
+   the condition and an int to indicate the size of the array. These
+   workers are not allowed to be moved from the context.
+*/
 #define SC_HYPERVISOR_FIXED_WORKERS -7
+
+/**
+   This macro is used when calling sc_hypervisor_ctl() and must be
+   followed by 1 argument (int) that indicated the minimum number of
+   tasks that have to be executed before the context could be resized.
+   This parameter is ignored for the Application Driven strategy (see
+   \ref ResizingStrategies) where the user indicates exactly when the
+   resize should be done.
+*/
 #define SC_HYPERVISOR_MIN_TASKS -8
+
+/**
+   This macro is used when calling sc_hypervisor_ctl() and must be
+   followed by 1 argument, a double value indicating the maximum idle
+   time allowed for workers that have just been moved from other
+   contexts in the current context.
+*/
 #define SC_HYPERVISOR_NEW_WORKERS_MAX_IDLE -9
+
+/**
+   This macro is used when calling sc_hypervisor_ctl() and must be
+   followed by 1 argument (int) indicating the tag an executed task
+   should have such that this configuration should be taken into
+   account.
+*/
 #define SC_HYPERVISOR_TIME_TO_APPLY -10
+
+/**
+   This macro is used when calling sc_hypervisor_ctl() and must be
+   followed by 1 argument
+ */
 #define SC_HYPERVISOR_NULL -11
+
+/**
+   This macro is used when calling sc_hypervisor_ctl() and must be
+   followed by 1 argument, a double, that indicates the number of
+   flops needed to be executed before computing the speed of a worker
+*/
 #define	SC_HYPERVISOR_ISPEED_W_SAMPLE -12
+
+/**
+   This macro is used when calling sc_hypervisor_ctl() and must be
+   followed by 1 argument, a double, that indicates the number of
+   flops needed to be executed before computing the speed of a context
+*/
 #define SC_HYPERVISOR_ISPEED_CTX_SAMPLE -13
-#define SC_HYPERVISOR_TIME_SAMPLE -14
 
+#define SC_HYPERVISOR_TIME_SAMPLE -14
 
 #define MAX_IDLE_TIME 5000000000
 #define MIN_WORKING_TIME 500
 
+/**
+   Methods that implement a hypervisor resizing policy.
+*/
 struct sc_hypervisor_policy_config
 {
-	/* underneath this limit we cannot resize */
+	/**
+	   Indicate the minimum number of workers needed by the context
+	*/
 	int min_nworkers;
 
-	/* above this limit we cannot resize */
+	/**
+	   Indicate the maximum number of workers needed by the context
+	*/
 	int max_nworkers;
 
-	/*resize granularity */
+	/**
+	   Indicate the workers granularity of the context
+	*/
 	int granularity;
 
-	/* priority for a worker to stay in this context */
-	/* the smaller the priority the faster it will be moved */
-	/* to another context */
+	/**
+	   Indicate the priority of each worker to stay in the context
+	   the smaller the priority the faster it will be moved to
+	   another context
+	*/
 	int priority[STARPU_NMAXWORKERS];
 
-	/* above this limit the priority of the worker is reduced */
+	/**
+	   Indicate the maximum idle time accepted before a resize is
+	   triggered
+	   above this limit the priority of the worker is reduced
+	*/
 	double max_idle[STARPU_NMAXWORKERS];
 
-	/* underneath this limit the priority of the worker is reduced */
+	/**
+	   Indicate that underneath this limit the priority of the
+	   worker is reduced
+	*/
 	double min_working[STARPU_NMAXWORKERS];
 
-	/* workers that will not move */
+	/**
+	   Indicate which workers can be moved and which ones are
+	   fixed
+	*/
 	int fixed_workers[STARPU_NMAXWORKERS];
 
-	/* max idle for the workers that will be added during the resizing process*/
+	/**
+	   Indicate the maximum idle time accepted before a resize is
+	   triggered for the workers that just arrived in the new
+	   context
+	*/
 	double new_workers_max_idle;
 
-	/* sample used to compute the instant speed per worker*/
+	/**
+	   Indicate the sample used to compute the instant speed per
+	   worker
+	*/
 	double ispeed_w_sample[STARPU_NMAXWORKERS];
 
-	/* sample used to compute the instant speed per ctx*/
+	/**
+	   Indicate the sample used to compute the instant speed per
+	   ctxs
+	*/
 	double ispeed_ctx_sample;
-	
-        /* sample used to compute the instant speed per ctx (in seconds)*/
+
+        /**
+	   Indicate the sample used to compute the instant speed per
+	   ctx (in seconds)
+	*/
 	double time_sample;
 };
 
-/* set a certain configuration to a context */
+/**
+   Specify the configuration for a context
+*/
 void sc_hypervisor_set_config(unsigned sched_ctx, void *config);
 
-/* check out the configuration of a context */
+/**
+   Return the configuration of a context
+*/
 struct sc_hypervisor_policy_config *sc_hypervisor_get_config(unsigned sched_ctx);
 
-/* impose different parameters to a configuration of a context */
+/**
+   Specify different parameters for the configuration of a context.
+   The list must be zero-terminated
+*/
 void sc_hypervisor_ctl(unsigned sched_ctx, ...);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif

sc_hypervisor/include/sc_hypervisor_lp.h

@@ -1,7 +1,7 @@
 /* StarPU --- Runtime system for heterogeneous multicore architectures.
  *
  * Copyright (C) 2010-2014                                Inria
- * Copyright (C) 2012,2013,2017                           CNRS
+ * Copyright (C) 2012,2013,2017,2019                           CNRS
  *
  * StarPU is free software; you can redistribute it and/or modify
  * it under the terms of the GNU Lesser General Public License as published by
@@ -26,67 +26,102 @@ extern "C"
 {
 #endif
 
-/*
- * GNU Linear Programming Kit backend
- */
+/**
+   @defgroup API_SC_Hypervisor_LP Scheduling Context Hypervisor - Linear Programming
+   @{
+*/
+
 #ifdef STARPU_HAVE_GLPK_H
 #include <glpk.h>
 #endif //STARPU_HAVE_GLPK_H
 
-struct sc_hypervisor_policy_task_pool; 
+struct sc_hypervisor_policy_task_pool;
 struct types_of_workers;
-/* returns tmax, and computes in table res the nr of workers needed by each context st the system ends up in the smallest tmax*/
-double sc_hypervisor_lp_get_nworkers_per_ctx(int nsched_ctxs, int ntypes_of_workers, double res[nsched_ctxs][ntypes_of_workers], 
+/**
+   return tmax, and compute in table res the nr of workers needed by each context st the system ends up in the smallest tma
+*/
+double sc_hypervisor_lp_get_nworkers_per_ctx(int nsched_ctxs, int ntypes_of_workers, double res[nsched_ctxs][ntypes_of_workers],
 					     int total_nw[ntypes_of_workers], struct types_of_workers *tw, unsigned *in_sched_ctxs);
 
-/* returns tmax of the system */
+/**
+   return tmax of the system
+*/
 double sc_hypervisor_lp_get_tmax(int nw, int *workers);
 
-/* the linear programme determins a rational number of ressources for each ctx, we round them depending on the type of ressource */
+/**
+   the linear programme determins a rational number of ressources for each ctx, we round them depending on the type of ressource
+*/
 void sc_hypervisor_lp_round_double_to_int(int ns, int nw, double res[ns][nw], int res_rounded[ns][nw]);
 
-/* redistribute the ressource in contexts by assigning the first x available ressources to each one */
+/**
+   redistribute the ressource in contexts by assigning the first x available ressources to each one
+*/
 void sc_hypervisor_lp_redistribute_resources_in_ctxs(int ns, int nw, int res_rounded[ns][nw], double res[ns][nw], unsigned *sched_ctxs, struct types_of_workers *tw);
 
-/* make the first distribution of ressource in contexts by assigning the first x available ressources to each one */
+/**
+   make the first distribution of ressource in contexts by assigning the first x available ressources to each one
+*/
 void sc_hypervisor_lp_distribute_resources_in_ctxs(unsigned* sched_ctxs, int ns, int nw, int res_rounded[ns][nw], double res[ns][nw], int *workers, int nworkers, struct types_of_workers *tw);
 
-/* make the first distribution of ressource in contexts by assigning the first x available ressources to each one, share not integer no of workers */
+/**
+   make the first distribution of ressource in contexts by assigning the first x available ressources to each one, share not integer no of workers
+*/
 void sc_hypervisor_lp_distribute_floating_no_resources_in_ctxs(unsigned* sched_ctxs, int ns, int nw, double res[ns][nw], int *workers, int nworkers, struct types_of_workers *tw);
 
-/* place resources in contexts dependig on whether they already have workers or not */
+/**
+   place resources in contexts dependig on whether they already have workers or not
+*/
 void sc_hypervisor_lp_place_resources_in_ctx(int ns, int nw, double w_in_s[ns][nw], unsigned *sched_ctxs, int *workers, unsigned do_size, struct types_of_workers *tw);
 
-/* not used resources are shared between all contexts */
+/**
+   not used resources are shared between all contexts
+*/
 void sc_hypervisor_lp_share_remaining_resources(int ns, unsigned *sched_ctxs,  int nworkers, int *workers);
 
-/* dichotomy btw t1 & t2 */
+/**
+   dichotomy btw t1 & t2
+*/
 double sc_hypervisor_lp_find_tmax(double t1, double t2);
 
-/* execute the lp trough dichotomy */
+/**
+   execute the lp trough dichotomy
+*/
 unsigned sc_hypervisor_lp_execute_dichotomy(int ns, int nw, double w_in_s[ns][nw], unsigned solve_lp_integer, void *specific_data,
 					    double tmin, double tmax, double smallest_tmax,
-					    double (*lp_estimated_distrib_func)(int ns, int nw, double draft_w_in_s[ns][nw], 
+					    double (*lp_estimated_distrib_func)(int ns, int nw, double draft_w_in_s[ns][nw],
 									     unsigned is_integer, double tmax, void *specifc_data));
 
 #ifdef STARPU_HAVE_GLPK_H
-/* linear program that returns 1/tmax, and computes in table res the nr of workers needed by each context st 
-   the system ends up in the smallest tmax*/
-double sc_hypervisor_lp_simulate_distrib_flops(int nsched_ctxs, int ntypes_of_workers, double speed[nsched_ctxs][ntypes_of_workers], 
-					       double flops[nsched_ctxs], double res[nsched_ctxs][ntypes_of_workers], int total_nw[ntypes_of_workers], 
+/**
+   linear program that returns 1/tmax, and computes in table res the
+   nr of workers needed by each context st the system ends up in the
+   smallest tmax
+*/
+double sc_hypervisor_lp_simulate_distrib_flops(int nsched_ctxs, int ntypes_of_workers, double speed[nsched_ctxs][ntypes_of_workers],
+					       double flops[nsched_ctxs], double res[nsched_ctxs][ntypes_of_workers], int total_nw[ntypes_of_workers],
 					       unsigned sched_ctxs[nsched_ctxs], double vmax);
 
-/* linear program that simulates a distribution of tasks that minimises the execution time of the tasks in the pool */
+/**
+   linear program that simulates a distribution of tasks that
+   minimises the execution time of the tasks in the pool
+*/
 double sc_hypervisor_lp_simulate_distrib_tasks(int ns, int nw, int nt, double w_in_s[ns][nw], double tasks[nw][nt],
 					       double times[nw][nt], unsigned is_integer, double tmax, unsigned *in_sched_ctxs,
 					       struct sc_hypervisor_policy_task_pool *tmp_task_pools);
 
-/* linear program that simulates a distribution of flops over the workers on particular sample of the execution
-   of the application such that the entire sample would finish in a minimum amount of time */
-double sc_hypervisor_lp_simulate_distrib_flops_on_sample(int ns, int nw, double final_w_in_s[ns][nw], unsigned is_integer, double tmax, 
+/**
+   linear program that simulates a distribution of flops over the
+   workers on particular sample of the execution of the application
+   such that the entire sample would finish in a minimum amount of
+   time
+*/
+double sc_hypervisor_lp_simulate_distrib_flops_on_sample(int ns, int nw, double final_w_in_s[ns][nw], unsigned is_integer, double tmax,
 							 double **speed, double flops[ns], double **final_flops_on_w);
 #endif // STARPU_HAVE_GLPK_H
 
+
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif

sc_hypervisor/include/sc_hypervisor_monitoring.h

@@ -2,7 +2,7 @@
  *
  * Copyright (C) 2011,2013,2014                           Inria
  * Copyright (C) 2015                                     Mathieu Lirzin
- * Copyright (C) 2013,2017                                CNRS
+ * Copyright (C) 2013,2017,2019                           CNRS
  *
  * StarPU is free software; you can redistribute it and/or modify
  * it under the terms of the GNU Lesser General Public License as published by
@@ -26,144 +26,254 @@ extern "C"
 {
 #endif
 
-/* structure to indicate when the moving of workers was actually done 
-   (moved workers can be seen in the new ctx ) */
+/**
+   @ingroup API_SC_Hypervisor
+   @{
+*/
+
+/**
+   Structure to check if the workers moved to another context are
+   actually taken into account in that context.
+*/
 struct sc_hypervisor_resize_ack
 {
-	/* receiver context */
+	/**
+	   The context receiving the new workers
+	*/
 	int receiver_sched_ctx;
-	/* list of workers required to be moved */
+
+	/**
+	   List of workers required to be moved
+	*/
 	int *moved_workers;
-	/* number of workers required to be moved */
+
+	/**
+	   Number of workers required to be moved
+	*/
 	int nmoved_workers;
-	/* list of workers that actually got in the receiver ctx */
+
+	/**
+	   List of workers that actually got in the receiver ctx. If
+	   the value corresponding to a worker is 1, this worker got
+	   moved in the new context.
+	*/
 	int *acked_workers;
 };
 
-/* wrapper attached to a sched_ctx storing monitoring information */
+/**
+   Wrapper of the contexts available in StarPU which contains all
+   information about a context obtained by incrementing the
+   performance counters. it is attached to a sched_ctx storing
+   monitoring information
+*/
 struct sc_hypervisor_wrapper
 {
-	/* the sched_ctx it monitors */
+	/**
+	   the monitored context
+	*/
 	unsigned sched_ctx;
 
-	/* user configuration meant to limit resizing */
+	/**
+	   The corresponding resize configuration
+	*/
 	struct sc_hypervisor_policy_config *config;
 
-
-	/* the start time of the resizing sample of the workers of this context*/
+	/**
+	   the start time of the resizing sample of the workers of
+	   this context
+	*/
 	double start_time_w[STARPU_NMAXWORKERS];
 
-	/* idle time of workers in this context */
+	/**
+	   The idle time counter of each worker of the context
+	*/
 	double current_idle_time[STARPU_NMAXWORKERS];
 
-	/* idle time from the last resize */
+	/**
+	   The time the workers were idle from the last resize
+	*/
 	double idle_time[STARPU_NMAXWORKERS];
 
-	/* time when the idle started */
+	/**
+	   The moment when the workers started being idle
+	*/
 	double idle_start_time[STARPU_NMAXWORKERS];
-	
-	/* time during which the worker executed tasks */
+
+	/**
+	   Time during which the worker executed tasks
+	*/
 	double exec_time[STARPU_NMAXWORKERS];
 
-	/* time when the worker started executing a task */
+	/**
+	   Time when the worker started executing a task
+	*/
 	double exec_start_time[STARPU_NMAXWORKERS];
 
-	/* list of workers that will leave this contexts (lazy resizing process) */
+	/**
+	   List of workers that will leave the context (lazy resizing
+	   process)
+	*/
 	int worker_to_be_removed[STARPU_NMAXWORKERS];
 
-	/* number of tasks pushed on each worker in this ctx */
+	/**
+	   Number of tasks pushed on each worker in this context
+	*/
 	int pushed_tasks[STARPU_NMAXWORKERS];
 
-	/* number of tasks poped from each worker in this ctx */
+	/**
+	   Number of tasks poped from each worker in this context
+	*/
 	int poped_tasks[STARPU_NMAXWORKERS];
 
-	/* number of flops the context has to execute */
+	/**
+	   The total number of flops to execute by the context
+	*/
 	double total_flops;
 
-	/* number of flops executed since the beginning until now */
+	/**
+	   The number of flops executed by each workers of the context
+	*/
 	double total_elapsed_flops[STARPU_NMAXWORKERS];
 
-	/* number of flops executed since last resizing */
+	/**
+	   number of flops executed since last resizing
+	*/
 	double elapsed_flops[STARPU_NMAXWORKERS];
 
-	/* data quantity executed on each worker in this ctx */
+	/**
+	   Quantity of data (in bytes) used to execute tasks on each
+	   worker in this context
+	*/
 	size_t elapsed_data[STARPU_NMAXWORKERS];
 
-	/* nr of tasks executed on each worker in this ctx */
+	/**
+	   Number of tasks executed on each worker in this context
+	*/
 	int elapsed_tasks[STARPU_NMAXWORKERS];
 
-	/* the average speed of the type of workers when they belonged to this context */
-	/* 0 - cuda 1 - cpu */
+	/**
+	   the average speed of the type of workers when they belonged
+	   to this context
+	   0 - cuda 1 - cpu
+	*/
 	double ref_speed[2];
 
-	/* number of flops submitted to this ctx */
+	/**
+	   Number of flops submitted to this context
+	*/
 	double submitted_flops;
 
-	/* number of flops that still have to be executed in this ctx */
+	/**
+	   Number of flops that still have to be executed by the
+	   workers in this context
+	*/
 	double remaining_flops;
-	
-	/* the start time of the resizing sample of this context*/
+
+	/**
+	   Start time of the resizing sample of this context
+	*/
 	double start_time;
 
-	/* the first time a task was pushed to this context*/
+	/**
+	   First time a task was pushed to this context
+	*/
 	double real_start_time;
-	
-	/* the start time for sample in which the hyp is not allowed to react
-	   bc too expensive */
+
+	/**
+	   Start time for sample in which the hypervisor is not allowed to
+	   react bc too expensive */
 	double hyp_react_start_time;
 
-	/* the workers don't leave the current ctx until the receiver ctx 
-	   doesn't ack the receive of these workers */
+	/**
+	   Structure confirming the last resize finished and a new one
+	   can be done.
+	   Workers do not leave the current context until the receiver
+	   context does not ack the receive of these workers
+	*/
 	struct sc_hypervisor_resize_ack resize_ack;
 
-	/* mutex to protect the ack of workers */
+	/**
+	   Mutex needed to synchronize the acknowledgment of the
+	   workers into the receiver context
+	*/
 	starpu_pthread_mutex_t mutex;
 
-	/* boolean indicating if the resizing strategy can see the
-	   flops of all the execution or not */
+	/**
+	   Boolean indicating if the hypervisor can use the flops
+	   corresponding to the entire execution of the context
+	*/
 	unsigned total_flops_available;
 
-	/* boolean indicating that a context is being sized */
+	/**
+	   boolean indicating that a context is being sized
+	*/
 	unsigned to_be_sized;
 
-	/* boolean indicating if we add the idle of this worker to 
-	   the idle of the context */
+	/**
+	   Boolean indicating if we add the idle of this worker to the
+	   idle of the context
+	*/
 	unsigned compute_idle[STARPU_NMAXWORKERS];
 
-	/* boolean indicating if we add the entiere idle of this 
-	   worker to the idle of the context or just half*/
+	/**
+	   Boolean indicating if we add the entiere idle of this
+	   worker to the idle of the context or just half
+	*/
 	unsigned compute_partial_idle[STARPU_NMAXWORKERS];
 
-	/* consider the max in the lp */
+	/**
+	   consider the max in the lp
+	*/
 	unsigned consider_max;
-
-
 };
 
-/* return the wrapper of context that saves its monitoring information */
+/**
+   Return the wrapper of the given context
+   @ingroup API_SC_Hypervisor
+*/
 struct sc_hypervisor_wrapper *sc_hypervisor_get_wrapper(unsigned sched_ctx);
 
-/* get the list of registered contexts */
+/**
+   Get the list of registered contexts
+   @ingroup API_SC_Hypervisor
+*/
 unsigned *sc_hypervisor_get_sched_ctxs();
 
-/* get the number of registered contexts */
+/**
+   Get the number of registered contexts
+   @ingroup API_SC_Hypervisor
+*/
 int sc_hypervisor_get_nsched_ctxs();
 
-/* get the number of workers of a certain architecture in a context */
+/**
+   Get the number of workers of a certain architecture in a context
+*/
 int sc_hypervisor_get_nworkers_ctx(unsigned sched_ctx, enum starpu_worker_archtype arch);
 
-/* get the number of flops executed by a context since last resizing (reset to 0 when a resizing is done)*/
+/**
+   Get the number of flops executed by a context since last resizing
+   (reset to 0 when a resizing is done)
+   @ingroup API_SC_Hypervisor
+*/
 double sc_hypervisor_get_elapsed_flops_per_sched_ctx(struct sc_hypervisor_wrapper *sc_w);
 
-/* get the number of flops executed by a context since the begining */
+/**
+   Get the number of flops executed by a context since the begining
+*/
 double sc_hypervisor_get_total_elapsed_flops_per_sched_ctx(struct sc_hypervisor_wrapper* sc_w);
 
-/* compute an average value of the cpu/cuda speed */
+/**
+   Compute an average value of the cpu/cuda speed
+*/
 double sc_hypervisorsc_hypervisor_get_speed_per_worker_type(struct sc_hypervisor_wrapper* sc_w, enum starpu_worker_archtype arch);
 
-/* compte the actual speed of all workers of a specific type of worker */
+/**
+   Compte the actual speed of all workers of a specific type of worker
+*/
 double sc_hypervisor_get_speed(struct sc_hypervisor_wrapper *sc_w, enum starpu_worker_archtype arch);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif

sc_hypervisor/include/sc_hypervisor_policy.h

@@ -1,7 +1,7 @@
 /* StarPU --- Runtime system for heterogeneous multicore architectures.
  *
  * Copyright (C) 2010-2014                                Inria
- * Copyright (C) 2012,2013,2017                           CNRS
+ * Copyright (C) 2012,2013,2017,2019                      CNRS
  * Copyright (C) 2012,2013                                Université de Bordeaux
  *
  * StarPU is free software; you can redistribute it and/or modify
@@ -26,6 +26,10 @@ extern "C"
 {
 #endif
 
+/**
+   @defgroup API_SC_Hypervisor Scheduling Context Hypervisor - Building a new resizing policy
+   @{
+*/
 
 #define HYPERVISOR_REDIM_SAMPLE 0.02
 #define HYPERVISOR_START_REDIM_SAMPLE 0.1
@@ -40,100 +44,185 @@ struct types_of_workers
 	unsigned nw;
 };
 
+/**
+   Task wrapper linked list
+   @ingroup API_SC_Hypervisor
+*/
 struct sc_hypervisor_policy_task_pool
 {
+	/**
+	   Which codelet has been executed
+	*/
 	struct starpu_codelet *cl;
+
+	/**
+	   Task footprint key
+	*/
 	uint32_t footprint;
+
+	/**
+	   Context the task belongs to
+	*/
 	unsigned sched_ctx_id;
+
+	/**
+	   Number of tasks of this kind
+	*/
 	unsigned long n;
+
+	/**
+	   The quantity of data(in bytes) needed by the task to execute
+	*/
 	size_t data_size;
+
+	/**
+	   Other task kinds
+	*/
 	struct sc_hypervisor_policy_task_pool *next;
 };
 
-/* add task information to a task wrapper linked list */
+/**
+   add task information to a task wrapper linked list
+*/
 void sc_hypervisor_policy_add_task_to_pool(struct starpu_codelet *cl, unsigned sched_ctx, uint32_t footprint, struct sc_hypervisor_policy_task_pool **task_pools, size_t data_size);
 
-/* remove task information from a task wrapper linked list */
+/**
+   remove task information from a task wrapper linked list
+*/
 void sc_hypervisor_policy_remove_task_from_pool(struct starpu_task *task, uint32_t footprint, struct sc_hypervisor_policy_task_pool **task_pools);
 
-/* clone a task wrapper linked list */
+/**
+   clone a task wrapper linked list
+*/
 struct sc_hypervisor_policy_task_pool* sc_hypervisor_policy_clone_task_pool(struct sc_hypervisor_policy_task_pool *tp);
 
-/* get the execution time of the submitted tasks out of starpu's calibration files */
+/**
+   get the execution time of the submitted tasks out of starpu's calibration files
+*/
 void sc_hypervisor_get_tasks_times(int nw, int nt, double times[nw][nt], int *workers, unsigned size_ctxs, struct sc_hypervisor_policy_task_pool *task_pools);
 
-/* find the context with the lowest priority in order to move some workers */
+/**
+   find the context with the lowest priority in order to move some workers
+*/
 unsigned sc_hypervisor_find_lowest_prio_sched_ctx(unsigned req_sched_ctx, int nworkers_to_move);
 
-/* find the first most idle workers of a context*/
+/**
+   find the first most idle workers of a contex
+*/
 int* sc_hypervisor_get_idlest_workers(unsigned sched_ctx, int *nworkers, enum starpu_worker_archtype arch);
 
-/* find the first most idle workers in a list */
+/**
+   find the first most idle workers in a list
+*/
 int* sc_hypervisor_get_idlest_workers_in_list(int *start, int *workers, int nall_workers,  int *nworkers, enum starpu_worker_archtype arch);
 
-/* find workers that can be moved from a context (if the constraints of min, max, etc allow this) */
+/**
+   find workers that can be moved from a context (if the constraints of min, max, etc allow this)
+*/
 int sc_hypervisor_get_movable_nworkers(struct sc_hypervisor_policy_config *config, unsigned sched_ctx, enum starpu_worker_archtype arch);
 
-/* compute how many workers should be moved from this context */
+/**
+   compute how many workers should be moved from this context
+*/
 int sc_hypervisor_compute_nworkers_to_move(unsigned req_sched_ctx);
 
-/* check the policy's constraints in order to resize */
+/**
+   check the policy's constraints in order to resize
+*/
 unsigned sc_hypervisor_policy_resize(unsigned sender_sched_ctx, unsigned receiver_sched_ctx, unsigned force_resize, unsigned now);
 
-/* check the policy's constraints in order to resize  and find a context willing the resources */
+/**
+   check the policy's constraints in order to resize  and find a context willing the resources
+*/
 unsigned sc_hypervisor_policy_resize_to_unknown_receiver(unsigned sender_sched_ctx, unsigned now);
 
-/* compute the speed of a context */
+/**
+   compute the speed of a context
+*/
 double sc_hypervisor_get_ctx_speed(struct sc_hypervisor_wrapper* sc_w);
 
-/* get the time of execution of the slowest context */
+/**
+   get the time of execution of the slowest context
+*/
 double sc_hypervisor_get_slowest_ctx_exec_time(void);
 
-/* get the time of execution of the fastest context */
+/**
+   get the time of execution of the fastest context
+*/
 double sc_hypervisor_get_fastest_ctx_exec_time(void);
 
-/* compute the speed of a workers in a context */
-double sc_hypervisor_get_speed_per_worker(struct sc_hypervisor_wrapper *sc_w, unsigned worker); 
+/**
+   compute the speed of a workers in a context
+*/
+double sc_hypervisor_get_speed_per_worker(struct sc_hypervisor_wrapper *sc_w, unsigned worker);
 
-/* compute the speed of a type of worker in a context */
+/**
+   compute the speed of a type of worker in a context
+*/
 double sc_hypervisor_get_speed_per_worker_type(struct sc_hypervisor_wrapper* sc_w, enum starpu_worker_archtype arch);
 
-/* compute the speed of a type of worker in a context depending on its history */ 
+/**
+   compute the speed of a type of worker in a context depending on its history
+*/
 double sc_hypervisor_get_ref_speed_per_worker_type(struct sc_hypervisor_wrapper* sc_w, enum starpu_worker_archtype arch);
 
-/* compute the average speed of a type of worker in all ctxs from the begining of appl */
+/**
+   compute the average speed of a type of worker in all ctxs from the begining of appl
+*/
 double sc_hypervisor_get_avg_speed(enum starpu_worker_archtype arch);
 
-/* verify if we need to consider the max in the lp */
+/**
+   verify if we need to consider the max in the lp
+*/
 void sc_hypervisor_check_if_consider_max(struct types_of_workers *tw);
 
-/* get the list of workers grouped by type */
+/**
+   get the list of workers grouped by type
+*/
 void sc_hypervisor_group_workers_by_type(struct types_of_workers *tw, int *total_nw);
 
-/* get what type of worker corresponds to a certain index of types of workers */
+/**
+   get what type of worker corresponds to a certain index of types of workers
+*/
 enum starpu_worker_archtype sc_hypervisor_get_arch_for_index(unsigned w, struct types_of_workers *tw);
 
-/* get the index of types of workers corresponding to the type of workers indicated */
+/**
+   get the index of types of workers corresponding to the type of workers indicated
+*/
 unsigned sc_hypervisor_get_index_for_arch(enum starpu_worker_archtype arch, struct types_of_workers *tw);
 
-/* check if we trigger resizing or not */
+/**
+   check if we trigger resizing or not
+*/
 unsigned sc_hypervisor_criteria_fulfilled(unsigned sched_ctx, int worker);
 
-/* check if worker was idle long enough */
+/**
+   check if worker was idle long enough
+*/
 unsigned sc_hypervisor_check_idle(unsigned sched_ctx, int worker);
 
-/* check if there is a speed gap btw ctxs */
+/**
+   check if there is a speed gap btw ctxs
+*/
 unsigned sc_hypervisor_check_speed_gap_btw_ctxs(unsigned *sched_ctxs, int nsched_ctxs, int *workers, int nworkers);
 
-/* check if there is a speed gap btw ctxs on one level */
+/**
+   check if there is a speed gap btw ctxs on one level
+*/
 unsigned sc_hypervisor_check_speed_gap_btw_ctxs_on_level(int level, int *workers_in, int nworkers_in, unsigned father_sched_ctx_id, unsigned **sched_ctxs, int *nsched_ctxs);
 
-/* check what triggers resizing (idle, speed, etc.)*/
+/**
+   check what triggers resizing (idle, speed, etc.
+*/
 unsigned sc_hypervisor_get_resize_criteria();
 
-/* load information concerning the type of workers into a types_of_workers struct */
+/**
+   load information concerning the type of workers into a types_of_workers struct
+*/
 struct types_of_workers* sc_hypervisor_get_types_of_workers(int *workers, unsigned nworkers);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif