add function descriptions for performance knobs and counters

doc/doxygen/Makefile.am

@@ -103,6 +103,8 @@ chapters =	\
 	chapters/api/opencl_extensions.doxy \
 	chapters/api/openmp_runtime_support.doxy \
 	chapters/api/mic_extensions.doxy \
+	chapters/api/perf_monitoring.doxy \
+	chapters/api/perf_steering.doxy \
 	chapters/api/scheduling_contexts.doxy \
 	chapters/api/scheduling_policy.doxy \
 	chapters/api/versioning.doxy \
@@ -212,6 +214,8 @@ dox_inputs = $(DOX_CONFIG) 				\
 	$(top_srcdir)/include/starpu_mod.f90		\
 	$(top_srcdir)/include/starpu_opencl.h		\
 	$(top_srcdir)/include/starpu_openmp.h		\
+	$(top_srcdir)/include/starpu_perf_monitoring.h	\
+	$(top_srcdir)/include/starpu_perf_steering.h	\
 	$(top_srcdir)/include/starpu_perfmodel.h	\
 	$(top_srcdir)/include/starpu_profiling.h	\
 	$(top_srcdir)/include/starpu_rand.h		\

doc/doxygen/chapters/520_files.doxy

@@ -40,6 +40,8 @@
 \file starpu_mod.f90
 \file starpu_opencl.h
 \file starpu_openmp.h
+\file starpu_perf_monitoring.h
+\file starpu_perf_steering.h
 \file starpu_perfmodel.h
 \file starpu_profiling.h
 \file starpu_rand.h

doc/doxygen/doxygen-config.cfg.in

@@ -42,6 +42,8 @@ INPUT                  = @top_srcdir@/doc/doxygen/chapters \
 			 @top_srcdir@/include/starpu_mod.f90 \
 			 @top_srcdir@/include/starpu_opencl.h \
 			 @top_srcdir@/include/starpu_openmp.h \
+			 @top_srcdir@/include/starpu_perf_monitoring.h \
+			 @top_srcdir@/include/starpu_perf_steering.h \
 			 @top_srcdir@/include/starpu_perfmodel.h \
 			 @top_srcdir@/include/starpu_profiling.h \
 			 @top_srcdir@/include/starpu_rand.h \

doc/doxygen/refman.tex

@@ -230,6 +230,8 @@ Documentation License”.
 \input{group__API__Codelet__And__Tasks}
 \input{group__API__Insert__Task}
 \input{group__API__Explicit__Dependencies}
+\input{group__API__Perf__Monitoring}
+\input{group__API__Perf__Steering}
 \input{group__API__Performance__Model}
 \input{group__API__Profiling}
 \input{group__API__Theoretical__Lower__Bound__on__Execution__Time}
@@ -286,6 +288,8 @@ Documentation License”.
 \input{starpu__mpi__lb_8h}
 \input{starpu__opencl_8h}
 \input{starpu__openmp_8h}
+\input{starpu__perf__monitoring_8h}
+\input{starpu__perf__steering_8h}
 \input{starpu__perfmodel_8h}
 \input{starpu__profiling_8h}
 \input{starpu__rand_8h}

include/starpu_perf_monitoring.h

@@ -25,73 +25,177 @@ extern "C"
 #endif
 
 /**
-   @defgroup API_Perf_Monitoring Perf_Monitoring
+   @defgroup API_Perf_Monitoring Performance Monitoring Counters
+   @brief This section describes the interface to access performance monitoring counters.
    @{
 */
 
+/**
+   @name API
+   \anchor PM_API
+   @{
+*/
+/**
+   Enum of all possible performance counter scopes.
+ */
 enum starpu_perf_counter_scope
 {
-	starpu_perf_counter_scope_undefined     = 0,
-	starpu_perf_counter_scope_global        = 2,
-	starpu_perf_counter_scope_per_worker    = 4,
-	starpu_perf_counter_scope_per_codelet   = 6
+	starpu_perf_counter_scope_undefined     = 0, /** undefined scope */
+	starpu_perf_counter_scope_global        = 2, /** global scope */
+	starpu_perf_counter_scope_per_worker    = 4, /** per-worker scope */
+	starpu_perf_counter_scope_per_codelet   = 6  /** per-codelet scope */
 };
 
+/**
+  Enum of all possible performance counter value type.
+ */
 enum starpu_perf_counter_type
 {
-	starpu_perf_counter_type_undefined = 0,
-	starpu_perf_counter_type_int32     = 1,
-	starpu_perf_counter_type_int64     = 2,
-	starpu_perf_counter_type_float     = 3,
-	starpu_perf_counter_type_double    = 4
+	starpu_perf_counter_type_undefined = 0, /** underfined value type */
+	starpu_perf_counter_type_int32     = 1, /** signed 32-bit integer value */
+	starpu_perf_counter_type_int64     = 2, /** signed 64-bit integer value */
+	starpu_perf_counter_type_float     = 3, /** 32-bit single precision floating-point value */
+	starpu_perf_counter_type_double    = 4  /** 64-bit double precision floating-point value */
 };
 
 struct starpu_perf_counter_listener;
 struct starpu_perf_counter_sample;
 struct starpu_perf_counter_set;
 
+/**
+  Translate scope name constant string to scope id.
+  */
 int starpu_perf_counter_scope_name_to_id(const char *name);
+/**
+  Translate scope id to scope name constant string.
+  */
 const char *starpu_perf_counter_scope_id_to_name(enum starpu_perf_counter_scope scope);
 
+/**
+  Translate type name constant string to type id.
+  */
 int starpu_perf_counter_type_name_to_id(const char *name);
+/**
+  Translate type id to type name constant string.
+  */
 const char *starpu_perf_counter_type_id_to_name(enum starpu_perf_counter_type type);
 
+/**
+  Return the number of performance counters for the given scope.
+  */
 int starpu_perf_counter_nb(enum starpu_perf_counter_scope scope);
+/**
+  Translate a performance counter name to its id.
+  */
 int starpu_perf_counter_name_to_id(enum starpu_perf_counter_scope scope, const char *name);
+/**
+  Translate a performance counter rank in its scope to its counter id.
+  */
 int starpu_perf_counter_nth_to_id(enum starpu_perf_counter_scope scope, int nth);
+/**
+  Translate a counter id to its name constant string.
+  */
 const char *starpu_perf_counter_id_to_name(int id);
+/**
+  Return the counter's type id.
+  */
 int starpu_perf_counter_get_type_id(int id);
+/**
+  Return the counter's help string.
+  */
 const char *starpu_perf_counter_get_help_string(int id);
 
+/**
+  Display the list of counters defined in the given scope.
+  */
 void starpu_perf_counter_list_avail(enum starpu_perf_counter_scope scope);
+/**
+  Display the list of counters defined in all scopes.
+  */
 void starpu_perf_counter_list_all_avail(void);
 
+/**
+  Allocate a new performance counter set.
+  */
 struct starpu_perf_counter_set *starpu_perf_counter_set_alloc(enum starpu_perf_counter_scope scope);
+/**
+  Free a performance counter set.
+  */
 void starpu_perf_counter_set_free(struct starpu_perf_counter_set *set);
 
+/**
+  Enable a given counter in the set.
+  */
 void starpu_perf_counter_set_enable_id(struct starpu_perf_counter_set *set, int id);
+/**
+  Disable a given counter in the set.
+  */
 void starpu_perf_counter_set_disable_id(struct starpu_perf_counter_set *set, int id);
 
+/**
+  Initialize a new performance counter listener.
+  */
 struct starpu_perf_counter_listener *starpu_perf_counter_listener_init(struct starpu_perf_counter_set *set, void (*callback)(struct starpu_perf_counter_listener *listener, struct starpu_perf_counter_sample *sample, void *context), void *user_arg);
+/**
+  End a performance counter listener.
+  */
 void starpu_perf_counter_listener_exit(struct starpu_perf_counter_listener *listener);
 
+/**
+  Set a listener for the global scope.
+  */
 void starpu_perf_counter_set_global_listener(struct starpu_perf_counter_listener *listener);
+/**
+  Set a listener for the per_worker scope on a given worker.
+  */
 void starpu_perf_counter_set_per_worker_listener(unsigned workerid, struct starpu_perf_counter_listener *listener);
+/**
+  Set a common listener for all workers.
+  */
 void starpu_perf_counter_set_all_per_worker_listeners(struct starpu_perf_counter_listener *listener);
+/**
+  Set a per_codelet listener for a codelet.
+  */
 void starpu_perf_counter_set_per_codelet_listener(struct starpu_codelet *cl, struct starpu_perf_counter_listener *listener);
 
+/**
+  Unset the global listener.
+  */
 void starpu_perf_counter_unset_global_listener();
+/**
+  Unset the per_worker listener.
+  */
 void starpu_perf_counter_unset_per_worker_listener(unsigned workerid);
+/**
+  Unset all per_worker listeners.
+  */
 void starpu_perf_counter_unset_all_per_worker_listeners(void);
+/**
+  Unset a per_codelet listener.
+  */
 void starpu_perf_counter_unset_per_codelet_listener(struct starpu_codelet *cl);
 
+/**
+  Read an int32 counter value from a sample.
+  */
 int32_t starpu_perf_counter_sample_get_int32_value(struct starpu_perf_counter_sample *sample, const int counter_id);
+/**
+  Read an int64 counter value from a sample.
+  */
 int64_t starpu_perf_counter_sample_get_int64_value(struct starpu_perf_counter_sample *sample, const int counter_id);
+/**
+  Read a float counter value from a sample.
+  */
 float starpu_perf_counter_sample_get_float_value(struct starpu_perf_counter_sample *sample, const int counter_id);
+/**
+  Read a double counter value from a sample.
+  */
 double starpu_perf_counter_sample_get_double_value(struct starpu_perf_counter_sample *sample, const int counter_id);
 
 /** @} */
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif

include/starpu_perf_steering.h

@@ -25,77 +25,199 @@ extern "C"
 #endif
 
 /**
-   @defgroup API_Perf_Steering Perf_Steering
+   @defgroup API_Perf_Steering Performance Steering Knobs
+   @brief This section describes the interface to access performance steering counters.
    @{
 */
 
+/**
+   @name API
+   \anchor PM_API
+   @{
+*/
+/**
+   Enum of all possible performance knob scopes.
+ */
 enum starpu_perf_knob_scope
 {
-	starpu_perf_knob_scope_undefined     = 0,
-	starpu_perf_knob_scope_global        = 1,
-	starpu_perf_knob_scope_per_worker    = 3,
-	starpu_perf_knob_scope_per_scheduler = 5
+	starpu_perf_knob_scope_undefined     = 0, /** undefined scope */
+	starpu_perf_knob_scope_global        = 1, /** global scope */
+	starpu_perf_knob_scope_per_worker    = 3, /** per-worker scope */
+	starpu_perf_knob_scope_per_scheduler = 5  /** per-scheduler scope */
 };
 
+/**
+  Enum of all possible performance knob value type.
+ */
 enum starpu_perf_knob_type
 {
-	starpu_perf_knob_type_undefined = 0,
-	starpu_perf_knob_type_int32     = 1,
-	starpu_perf_knob_type_int64     = 2,
-	starpu_perf_knob_type_float     = 3,
-	starpu_perf_knob_type_double    = 4
+	starpu_perf_knob_type_undefined = 0, /** underfined value type */
+	starpu_perf_knob_type_int32     = 1, /** signed 32-bit integer value */
+	starpu_perf_knob_type_int64     = 2, /** signed 64-bit integer value */
+	starpu_perf_knob_type_float     = 3, /** 32-bit single precision floating-point value */
+	starpu_perf_knob_type_double    = 4  /** 64-bit double precision floating-point value */
 };
 
+/**
+  Translate scope name constant string to scope id.
+  */
 int starpu_perf_knob_scope_name_to_id(const char *name);
+/**
+  Translate scope id to scope name constant string.
+  */
 const char *starpu_perf_knob_scope_id_to_name(enum starpu_perf_knob_scope scope);
 
+/**
+  Translate type name constant string to type id.
+  */
 int starpu_perf_knob_type_name_to_id(const char *name);
+/**
+  Translate type id to type name constant string.
+  */
 const char *starpu_perf_knob_type_id_to_name(enum starpu_perf_knob_type type);
 
+/**
+  Return the number of performance steering knobs for the given scope.
+  */
 int starpu_perf_knob_nb(enum starpu_perf_knob_scope scope);
+/**
+  Translate a performance knob name to its id.
+  */
 int starpu_perf_knob_name_to_id(enum starpu_perf_knob_scope scope, const char *name);
+/**
+  Translate a performance knob name to its id.
+  */
 int starpu_perf_knob_nth_to_id(enum starpu_perf_knob_scope scope, int nth);
+/**
+  Translate a performance knob rank in its scope to its knob id.
+  */
 const char *starpu_perf_knob_id_to_name(int id);
+/**
+  Translate a knob id to its name constant string.
+  */
 int starpu_perf_knob_get_type_id(int id);
+/**
+  Return the knob's help string.
+  */
 const char *starpu_perf_knob_get_help_string(int id);
 
+/**
+  Display the list of knobs defined in the given scope.
+  */
 void starpu_perf_knob_list_avail(enum starpu_perf_knob_scope scope);
+/**
+  Display the list of knobs defined in all scopes.
+  */
 void starpu_perf_knob_list_all_avail(void);
 
+/**
+  Get knob value for Global scope.
+  */
 int32_t starpu_perf_knob_get_global_int32_value (const int knob_id);
+/**
+  Get knob value for Global scope.
+  */
 int64_t starpu_perf_knob_get_global_int64_value (const int knob_id);
+/**
+  Get knob value for Global scope.
+  */
 float   starpu_perf_knob_get_global_float_value (const int knob_id);
+/**
+  Get knob value for Global scope.
+  */
 double  starpu_perf_knob_get_global_double_value(const int knob_id);
 
+/**
+  Set int32 knob value for Global scope.
+  */
 void starpu_perf_knob_set_global_int32_value (const int knob_id, int32_t new_value);
+/**
+  Set int64 knob value for Global scope.
+  */
 void starpu_perf_knob_set_global_int64_value (const int knob_id, int64_t new_value);
+/**
+  Set float knob value for Global scope.
+  */
 void starpu_perf_knob_set_global_float_value (const int knob_id, float   new_value);
+/**
+  Set double knob value for Global scope.
+  */
 void starpu_perf_knob_set_global_double_value(const int knob_id, double  new_value);
 
 
+/**
+ Get int32 value for Per_worker scope.
+  */
 int32_t starpu_perf_knob_get_per_worker_int32_value (const int knob_id, unsigned workerid);
+/**
+ Get int64 value for Per_worker scope.
+  */
 int64_t starpu_perf_knob_get_per_worker_int64_value (const int knob_id, unsigned workerid);
+/**
+ Get float value for Per_worker scope.
+  */
 float   starpu_perf_knob_get_per_worker_float_value (const int knob_id, unsigned workerid);
+/**
+ Get double value for Per_worker scope.
+  */
 double  starpu_perf_knob_get_per_worker_double_value(const int knob_id, unsigned workerid);
 
+/**
+ Set int32 value for Per_worker scope.
+  */
 void starpu_perf_knob_set_per_worker_int32_value (const int knob_id, unsigned workerid, int32_t new_value);
+/**
+ Set int64 value for Per_worker scope.
+  */
 void starpu_perf_knob_set_per_worker_int64_value (const int knob_id, unsigned workerid, int64_t new_value);
+/**
+ Set float value for Per_worker scope.
+  */
 void starpu_perf_knob_set_per_worker_float_value (const int knob_id, unsigned workerid, float   new_value);
+/**
+ Set double value for Per_worker scope.
+  */
 void starpu_perf_knob_set_per_worker_double_value(const int knob_id, unsigned workerid, double  new_value);
 
 
+/**
+ Get int32 value for per_scheduler scope.
+  */
 int32_t starpu_perf_knob_get_per_scheduler_int32_value (const int knob_id, const char * sched_policy_name);
+/**
+ Get int64 value for per_scheduler scope.
+  */
 int64_t starpu_perf_knob_get_per_scheduler_int64_value (const int knob_id, const char * sched_policy_name);
+/**
+ Get float value for per_scheduler scope.
+  */
 float   starpu_perf_knob_get_per_scheduler_float_value (const int knob_id, const char * sched_policy_name);
+/**
+ Get double value for per_scheduler scope.
+  */
 double  starpu_perf_knob_get_per_scheduler_double_value(const int knob_id, const char * sched_policy_name);
 
+/**
+ Set int32 value for per_scheduler scope.
+  */
 void starpu_perf_knob_set_per_scheduler_int32_value (const int knob_id, const char * sched_policy_name, int32_t new_value);
+/**
+ Set int64 value for per_scheduler scope.
+  */
 void starpu_perf_knob_set_per_scheduler_int64_value (const int knob_id, const char * sched_policy_name, int64_t new_value);
+/**
+ Set float value for per_scheduler scope.
+  */
 void starpu_perf_knob_set_per_scheduler_float_value (const int knob_id, const char * sched_policy_name, float   new_value);
+/**
+ Set double value for per_scheduler scope.
+  */
 void starpu_perf_knob_set_per_scheduler_double_value(const int knob_id, const char * sched_policy_name, double  new_value);
 
 /** @} */
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif