doc/doxygen: update doc

doc/doxygen/chapters/api/top.doxy

@@ -0,0 +1,162 @@
+/*
+ * This file is part of the StarPU Handbook.
+ * Copyright (C) 2009--2011  Universit@'e de Bordeaux 1
+ * Copyright (C) 2010, 2011, 2012, 2013  Centre National de la Recherche Scientifique
+ * Copyright (C) 2011, 2012 Institut National de Recherche en Informatique et Automatique
+ * See the file version.doxy for copying conditions.
+ */
+
+/*! \defgroup StarPU-Top_Interface StarPU-Top Interface
+
+\struct starpu_top_data
+\brief todo
+\ingroup StarPU-Top_Interface
+\var starpu_top_data::id
+todo
+\var starpu_top_data::name
+todo
+\var starpu_top_data::int_min_value
+todo
+\var starpu_top_data::int_max_value
+todo
+\var starpu_top_data::double_min_value
+todo
+\var starpu_top_data::double_max_value
+todo
+\var starpu_top_data::active
+todo
+\var starpu_top_data::type
+todo
+\var starpu_top_data::next
+todo
+
+\struct starpu_top_param
+\brief todo
+\ingroup StarPU-Top_Interface
+\var starpu_top_param::id
+todo
+\var starpu_top_param::name
+todo
+\var starpu_top_param::type
+todo
+\var starpu_top_param::value
+todo
+\var starpu_top_param::enum_values
+only for enum type can be NULL
+\var starpu_top_param::nb_values
+todo
+\var starpu_top_param::callback
+todo
+\var starpu_top_param::int_min_value
+only for integer type
+\var starpu_top_param::int_max_value
+todo
+\var starpu_top_param::double_min_value
+only for double type
+\var starpu_top_param::double_max_value
+todo
+\var starpu_top_param::next
+todo
+
+@name Functions to call before the initialisation
+\ingroup StarPU-Top_Interface
+
+\fn struct starpu_top_data *starpu_top_add_data_boolean(const char* data_name, int active)
+\ingroup StarPU-Top_Interface
+This fonction register a data named data_name of type boolean.
+If \p active=0, the value will NOT be displayed to user by default.
+Any other value will make the value displayed by default.
+
+\fn struct starpu_top_data * starpu_top_add_data_integer(const char* data_name, int minimum_value, int maximum_value, int active)
+\ingroup StarPU-Top_Interface
+This fonction register a data named \p data_name of type integer. The
+minimum and maximum value will be usefull to define the scale in UI.
+If \p active=0, the value will NOT be displayed to user by default.
+Any other value will make the value displayed by default.
+
+\fn struct starpu_top_data* starpu_top_add_data_float(const char* data_name, double minimum_value, double maximum_value, int active)
+\ingroup StarPU-Top_Interface
+This fonction register a data named data_name of type float. The
+minimum and maximum value will be usefull to define the scale in UI.
+If \p active=0, the value will NOT be displayed to user by default.
+Any other value will make the value displayed by default.
+
+\fn struct starpu_top_param* starpu_top_register_parameter_boolean(const char* param_name, int* parameter_field, void (*callback)(struct starpu_top_param*))
+\ingroup StarPU-Top_Interface
+This fonction register a parameter named \p parameter_name, of type
+boolean. The \p callback fonction will be called when the parameter is
+modified by UI, and can be null.
+
+\fn struct starpu_top_param* starpu_top_register_parameter_float(const char* param_name, double* parameter_field, double minimum_value, double maximum_value, void (*callback)(struct starpu_top_param*))
+\ingroup StarPU-Top_Interface
+his fonction register a parameter named \p param_name, of type
+integer. Minimum and maximum value will be used to prevent user seting
+incorrect value. The \p callback fonction will be called when the
+parameter is modified by UI, and can be null.
+
+\fn struct starpu_top_param* starpu_top_register_parameter_integer(const char* param_name, int* parameter_field, int minimum_value, int maximum_value, void (*callback)(struct starpu_top_param*))
+\ingroup StarPU-Top_Interface
+This fonction register a parameter named \p param_name, of type float.
+Minimum and maximum value will be used to prevent user seting
+incorrect value. The \p callback fonction will be called when the
+parameter is modified by UI, and can be null.
+
+\fn struct starpu_top_param* starpu_top_register_parameter_enum(const char* param_name, int* parameter_field, char** values, int nb_values, void (*callback)(struct starpu_top_param*))
+\ingroup StarPU-Top_Interface
+This fonction register a parameter named \p param_name, of type enum.
+Minimum and maximum value will be used to prevent user seting
+incorrect value. The \p callback fonction will be called when the
+parameter is modified by UI, and can be null.
+
+@name Initialisation
+\ingroup StarPU-Top_Interface
+
+\fn void starpu_top_init_and_wait(const char *server_name)
+\ingroup StarPU-Top_Interface
+This function must be called when all parameters and data have been
+registered AND initialised (for parameters). This function will wait
+for a TOP to connect, send initialisation sentences, and wait for the
+GO message.
+
+@name To call after initialisation
+\ingroup StarPU-Top_Interface
+
+\fn void starpu_top_update_parameter(const struct starpu_top_param *param)
+\ingroup StarPU-Top_Interface
+This function should be called after every modification of a parameter
+from something other than starpu_top. This fonction notice UI that the
+configuration changed.
+
+\fn void starpu_top_update_data_boolean(const struct starpu_top_data *data, int value)
+\ingroup StarPU-Top_Interface
+This function updates the value of the starpu_top_data on UI.
+
+\fn void starpu_top_update_data_integer(const struct starpu_top_data *data, int value)
+\ingroup StarPU-Top_Interface
+This function updates the value of the starpu_top_data on UI.
+
+\fn void starpu_top_update_data_float(const struct starpu_top_data *data, double value)
+\ingroup StarPU-Top_Interface
+This function updates the value of the starpu_top_data on UI.
+
+\fn void starpu_top_task_prevision(struct starpu_task *task, int devid, unsigned long long start, unsigned long long end)
+\ingroup StarPU-Top_Interface
+This function notifies UI than the task have been planed to run from start to end, on computation-core.
+
+\fn void starpu_top_debug_log(const char *message)
+\ingroup StarPU-Top_Interface
+This function is useful in debug mode. The starpu developper doesn't
+need to check if the debug mode is active. This is checked by
+starpu_top itsefl. It just send a message to display by UI.
+
+\fn void starpu_top_debug_lock(const char *message)
+\ingroup StarPU-Top_Interface
+This function is useful in debug mode. The starpu developper doesn't
+need to check if the debug mode is active. This is checked by
+starpu_top itsefl. It send a message and wait for a continue message
+from UI to return. The lock (wich create a stop-point) should be
+called only by the main thread. Calling it from more than one thread
+is not supported.
+
+*/
+