Minimalist documentation of some internal functions

src/common/fxt.h

@@ -103,12 +103,19 @@
 #include <fxt/fxt.h>
 #include <fxt/fut.h>
 
+/* Initialize the FxT library. */
 void _starpu_start_fxt_profiling(void);
+
+/* Stop the FxT library, and generate the trace file. */
 void _starpu_stop_fxt_profiling(void);
+
+/* Associate the current processing unit to the identifier of the LWP that runs
+ * the worker. */
 void _starpu_fxt_register_thread(unsigned);
 
-/* sometimes we need something a little more specific than the wrappers from
- * FxT */
+/* Sometimes we need something a little more specific than the wrappers from
+ * FxT: these macro permit to put add an event with 3 (or 4) numbers followed
+ * by a string. */
 #define STARPU_FUT_DO_PROBE3STR(CODE, P1, P2, P3, str)				\
 do {									\
 	/* we add a \0 just in case ... */				\
@@ -297,6 +304,7 @@ do {										\
 
 #else // !STARPU_USE_FXT
 
+/* Dummy macros in case FxT is disabled */
 #define STARPU_TRACE_NEW_MEM_NODE(nodeid)	do {} while(0);
 #define TRACE_NEW_WORKER(a,b)			do {} while(0);
 #define STARPU_TRACE_WORKER_INIT_START(a,b,c)	do {} while(0);

src/common/hash.h

@@ -19,7 +19,14 @@
 
 #include <stdint.h>
 
+/* Compute the CRC of a 32bit number seeded by the inputcrc "current state".
+ * The return value should be considered as the new "current state" for future
+ * CRC computation. */
 uint32_t _starpu_crc32_be(uint32_t input, uint32_t inputcrc);
+
+/* Compute the CRC of a string seeded by the inputcrc "current state".  The
+ * return value should be considered as the new "current state" for future CRC
+ * computation. */
 uint32_t _starpu_crc32_string(char *str, uint32_t inputcrc);
 
 #endif // __HASH_H__

src/common/htable32.h

@@ -24,12 +24,19 @@
 
 #define STARPU_HTBL32_NODE_SIZE	16
 
+/* Hierarchical table: all nodes have a 2^16 arity . */
 typedef struct starpu_htbl32_node_s {
 	unsigned nentries;
 	struct starpu_htbl32_node_s *children[1<<STARPU_HTBL32_NODE_SIZE];
 } starpu_htbl32_node_t;
 
+/* Look for a 32bit key into the hierchical table. Returns the entry if
+ * something is found, NULL otherwise. */
 void *_starpu_htbl_search_32(struct starpu_htbl32_node_s *htbl, uint32_t key);
+
+/* Insert an entry indexed by the 32bit key into the hierarchical table.
+ * Returns the entry that was previously associated to that key if any, NULL
+ * otherwise. */
 void *_starpu_htbl_insert_32(struct starpu_htbl32_node_s **htbl, uint32_t key, void *entry);
 
 #endif // __GENERIC_HTABLE_H__

src/common/rwlock.h

@@ -20,21 +20,31 @@
 #include <stdint.h>
 #include <starpu.h>
 
+/* Dummy implementation of a RW-lock using a spinlock. */
 typedef struct starpu_rw_lock_s {
 	uint32_t busy;
 	uint8_t writer;
 	uint16_t readercnt;
 } starpu_rw_lock_t;
 
+/* Initialize the RW-lock */
 void _starpu_init_rw_lock(starpu_rw_lock_t *lock);
+
+/* Grab the RW-lock in a write mode */
 void _starpu_take_rw_lock_write(starpu_rw_lock_t *lock);
+
+/* Grab the RW-lock in a read mode */
 void _starpu_take_rw_lock_read(starpu_rw_lock_t *lock);
+
+/* Try to grab the RW-lock in a write mode. Returns 0 in case of success, -1
+ * otherwise. */
 int _starpu_take_rw_lock_write_try(starpu_rw_lock_t *lock);
+
+/* Try to grab the RW-lock in a read mode. Returns 0 in case of success, -1
+ * otherwise. */
 int _starpu_take_rw_lock_read_try(starpu_rw_lock_t *lock);
-void _starpu_release_rw_lock(starpu_rw_lock_t *lock);
 
-///* make sure to have the lock before using that function */
-//inline uint8_t _starpu_rw_lock_is_writer(starpu_rw_lock_t *lock);
-//unsigned _starpu_is_rw_lock_referenced(starpu_rw_lock_t *lock);
+/* Unlock the RW-lock. */
+void _starpu_release_rw_lock(starpu_rw_lock_t *lock);
 
 #endif

src/core/errorcheck.h

@@ -38,6 +38,9 @@ typedef enum {
 void _starpu_set_local_worker_status(starpu_worker_status st);
 starpu_worker_status _starpu_get_local_worker_status(void);
 
+/* It is forbidden to do blocking calls during some operations such as callback
+ * or during the execution of a task. This function indicates whether it is
+ * legal to call a blocking operation in the current context. */
 unsigned _starpu_worker_may_perform_blocking_calls(void);
 
 #endif // __ERRORCHECK_H__

src/core/task.h

@@ -25,6 +25,9 @@
  * task currently submitted */
 void _starpu_decrement_nsubmitted_tasks(void);
 
+/* A pthread key is used to store the task currently executed on the thread.
+ * _starpu_initialize_current_task_key initializes this pthread key and
+ * _starpu_set_current_task updates its current value. */
 void _starpu_initialize_current_task_key(void);
 void _starpu_set_current_task(struct starpu_task *task);
 

src/core/workers.h

@@ -124,14 +124,31 @@ struct starpu_machine_config_s {
 	unsigned running;
 };
 
+/* Has starpu_shutdown already been called ? */
 unsigned _starpu_machine_is_running(void);
 
+/* Check if there is a worker that may execute the task. */
 uint32_t _starpu_worker_exists(uint32_t task_mask);
+
+/* Is there a worker that can execute CUDA code ? */
 uint32_t _starpu_may_submit_cuda_task(void);
+
+/* Is there a worker that can execute CPU code ? */
 uint32_t _starpu_may_submit_cpu_task(void);
+
+/* Is there a worker that can execute OpenCL code ? */
 uint32_t _starpu_may_submit_opencl_task(void);
+
+/* Check if the worker specified by workerid can execute the codelet. */
 uint32_t _starpu_worker_may_execute_task(unsigned workerid, uint32_t where);
+
+/* Check whether there is anything that the worker should do instead of
+ * sleeping (waiting on something to happen). */
 unsigned _starpu_worker_can_block(unsigned memnode);
+
+/* This function must be called to block a worker. It puts the worker in a
+ * sleeping state until there is some event that forces the worker to wake up.
+ * */
 void _starpu_block_worker(int workerid, pthread_cond_t *cond, pthread_mutex_t *mutex);
 
 void _starpu_set_local_worker_key(struct starpu_worker_s *worker);
@@ -141,7 +158,11 @@ struct starpu_worker_s *_starpu_get_worker_struct(unsigned id);
 
 struct starpu_machine_config_s *_starpu_get_machine_config(void);
 
+/* Retrieve the status which indicates what the worker is currently doing. */
 starpu_worker_status _starpu_worker_get_status(int workerid);
+
+/* Change the status of the worker which indicates what the worker is currently
+ * doing (eg. executing a callback). */
 void _starpu_worker_set_status(int workerid, starpu_worker_status status);
 
 /* TODO move */

src/datawizard/data_request.c

@@ -224,6 +224,7 @@ void _starpu_data_request_append_callback(starpu_data_request_t r, void (*callba
 	}
 }
 
+/* This method is called with handle's header_lock taken */
 static void starpu_handle_data_request_completion(starpu_data_request_t r)
 {
 	unsigned do_delete = 0;
@@ -238,6 +239,8 @@ static void starpu_handle_data_request_completion(starpu_data_request_t r)
 	STARPU_TRACE_END_DRIVER_COPY(src_node, dst_node, size, r->com_id);
 #endif
 
+	/* Once the request has been fulfilled, we may submit the requests that
+	 * were chained to that request. */
 	unsigned chained_req;
 	for (chained_req = 0; chained_req < r->next_req_count; chained_req++)
 	{

src/profiling/profiling.h

@@ -22,15 +22,43 @@
 #include <starpu_profiling.h>
 #include <common/config.h>
 
+/* Create a task profiling info structure (with the proper time stamps) in case
+ * profiling is enabled. */
 struct starpu_task_profiling_info *_starpu_allocate_profiling_info_if_needed(void);
+
+/* Clear all the profiling info related to the worker. */
 void _starpu_worker_reset_profiling_info(int workerid);
+
+/* Update the per-worker profiling info after a task (or more) was executed.
+ * This tells StarPU how much time was spent doing computation. */
 void _starpu_worker_update_profiling_info_executing(int workerid, struct timespec *executing_time, int executed_tasks);
+
+/* Update the per-worker profiling info when StarPU wakes up: this indicates
+ * how much time was spent sleeping. */
 void _starpu_worker_update_profiling_info_sleeping(int workerid, struct timespec *sleeping_start, struct timespec *sleeping_end);
+
+/* Record the date when the worker started to sleep. This permits to measure
+ * how much time was spent sleeping when it becomes awake later on. */
 void _starpu_worker_register_sleeping_start_date(int workerid, struct timespec *sleeping_start);
+
+/* Record the date when the worker started to execute a piece of code. This
+ * permits to measure how much time was really spent doing computation at the
+ * end of the codelet. */
 void _starpu_worker_register_executing_start_date(int workerid, struct timespec *executing_start);
 
+/* When StarPU is initialized, a matrix describing all the bus between memory
+ * nodes is created: it indicates whether there is a physical link between two
+ * memory nodes or not. This matrix should contain the identifier of the bus
+ * between two nodes or -1 in case there is no link. */
 void _starpu_initialize_busid_matrix(void);
+
+/* Tell StarPU that there exists a link between the two memory nodes. This
+ * function returns the identifier associated to the bus which can be used to
+ * retrieve profiling information about the bus activity later on. */
 int _starpu_register_bus(int src_node, int dst_node);
+
+/* Tell StarPU that "size" bytes were transferred between the two specified
+ * memory nodes. */
 void _starpu_bus_update_profiling_info(int src_node, int dst_node, size_t size);
 
 #endif // __PROFILING_H__