Add documentation of mambo API used in exercise 2

The following functions are documented:
---------------------------------------

In api/plugin_support.h:
------------------------
mambo_alloc
mambo_free
mambo_set_plugin_data
mambo_get_plugin_data
mambo_set_thread_plugin_data
mambo_get_thread_plugin_data
mambo_get_source_addr
mambo_get_thread_id
get_symbol_info_by_addr

In api/hash_table.h:
--------------------
mambo_ht_init
mambo_ht_add
mambo_ht_get

api/hash_table.h

@@ -17,6 +17,10 @@
   limitations under the License.
 */
 
+/**
+ * @file hash_table.h
+ */
+
 #ifndef __MAMBO_HASH_TABLE_H__
 #define __MAMBO_HASH_TABLE_H__
 
@@ -43,19 +47,53 @@ typedef struct {
 } mambo_ht_t;
 
 /**
- * @brief Initialises a hash-table with specific configuration.
+ * @brief Initialises a pre-allocated hash-table.
+ *
+ * @pre @c index_shift must be within the range [0, 20].
+ * @pre @c fill_factor must be within the range [10, 90].
  *
- * Initialises a hash-table 
- * 
- * @pre @c ctx->thread_data must not be @c NULL.
- * 
- * @param ctx The context that holds the plugin state.
- * @return The id of the calling thread.
+ * @param ht The hash-table to be initialised.
+ * @param initial_size The initial size of the hash-table. Will be round up to a
+ * power of 2.
+ * @param index_shift The number of bits a key is shifted to determine the index in
+ * the hash-table where the value belongs.
+ * @param fill_factor The percentage of elements relative to the hash-table's
+ * size that must be filled, to trigger a hash-table resize.
+ * @param allow_resize If true, the hash-table will automatically resize when
+ * resize threshold is reached.
+ * @return Error code of the hash-table initialisation ( @c 0 for success ).
  */
 int mambo_ht_init(mambo_ht_t *ht, size_t initial_size, int index_shift, int fill_factor, bool allow_resize);
 int mambo_ht_add_nolock(mambo_ht_t *ht, uintptr_t key, uintptr_t value);
+
+/**
+ * @brief Atomically adds a key-value pair to a hash-table.
+ *
+ * @pre @c key must be greater than 0.
+ *
+ * @param ht The hash-table to add the key-value pair.
+ * @param key The key of the key-value pair. The key can often be an address in
+ * the hosted application that can be associated with data stored in @c value.
+ * @param value The value of the key-value pair. Could be also used to store a
+ * pointer to a more complex data structure.
+ * @return 0 on success or -1 on error.
+ */
 int mambo_ht_add(mambo_ht_t *ht, uintptr_t key, uintptr_t value);
 int mambo_ht_get_nolock(mambo_ht_t *ht, uintptr_t key, uintptr_t *value);
+
+/**
+ * @brief Atomically returns a value from a key-value pair stored in a
+ * hash-table.
+ *
+ * @pre @c key must be greater than 0.
+ * @pre @c value must not be NULL.
+ *
+ * @param ht The hash-table to retrieve the value from.
+ * @param key The key used to locate the value within the hash-table.
+ * @param value Pointer where the address of the retrieved value will be stored
+ * after this call. Unchanged on error.
+ * @return 0 on success or -1 on error.
+ */
 int mambo_ht_get(mambo_ht_t *ht, uintptr_t key, uintptr_t *value);
 
 #endif

api/plugin_support.h

@@ -219,13 +219,71 @@ int mambo_register_function_cb(mambo_context *ctx, char *fn_name,
                                mambo_callback cb_pre, mambo_callback cb_post, int max_args);
 
 /* Memory management */
+/**
+ * @brief A wrapper of mmap to allocate memory space optimised to support the
+ * DBM use case.
+ *
+ * An mmap wrapper that allocates private to MAMBO memory space with read/write
+ * permissions. This function shoud be used instead of the regular libc malloc
+ * inside plugins.
+ *
+ * @param ctx The context that holds the plugin state. Currently unused.
+ * @param size The allocation size requested. Will round up to a multiple of
+ * page size due to calling mmap.
+ * @return Pointer to the mapped area or @c (void*)-1 on error.
+ */
 void *mambo_alloc(mambo_context *ctx, size_t size);
+
+/**
+ * @brief Frees memory space pointed by @c ptr which must have been returned by a
+ * previous call to mambo_alloc.
+ *
+ * Currently this function is just and empty wrapper.
+ *
+ * @param ctx The context that holds the plugin state. Currently unused.
+ * @param ptr Pointer to memory space requested for freeing. Currently unused.
+ */
 void mambo_free(mambo_context *ctx, void *ptr);
 
 /* Access plugin data */
+/**
+ * @brief Stores an address to a global structure, making data storedat that
+ * address accessible between callbacks of all threads running in MAMBO.
+ *
+ * @param ctx The context that holds the plugin state.
+ * @param data The address to be stored.
+ * @return MAMBO_SUCCESS on success or MAMBO_INVALID_PLUGIN_ID on error.
+ */
 int mambo_set_plugin_data(mambo_context *ctx, void *data);
+
+/**
+ * @brief Retrieves an address from a global structure accessible between
+ * callbacks of all threads running in MAMBO.
+ *
+ * @param ctx The context that holds the plugin state.
+ * @return Pointer to the address holding the data.
+ */
 void *mambo_get_plugin_data(mambo_context *ctx);
+
+/**
+ * @brief Stores an address holding data to a structure allocated in the calling
+ * thread, making data accessible between callbacks of that thread running in
+ * MAMBO.
+ *
+ * @param ctx The context that holds the plugin state.
+ * @param data Pointer to the address where data will be stored.
+ * @return MAMBO_SUCCESS on success, or MAMBO_INVALID_PLUGIN_ID or
+ * MAMBO_INVALID_THREAD on error.
+ */
 int mambo_set_thread_plugin_data(mambo_context *ctx, void *data);
+
+/**
+ * @brief Retrieves an address holding data to a structure allocated in the
+ * calling thread, accessible between its callbacks running in MAMBO.
+ *
+ * @param ctx The context that holds the plugin state.
+ * @return Pointer to the address holding the data.
+ */
 void *mambo_get_thread_plugin_data(mambo_context *ctx);
 
 /* Scratch register management */
@@ -298,6 +356,19 @@ int mambo_reserve_cc_space(mambo_context *ctx, size_t size);
 mambo_branch_type mambo_get_branch_type(mambo_context *ctx);
 
 /* Symbol-related functions */
+
+/**
+ * @brief Uses the untranslated address of the application's instruction to
+ * return the symbol name, the starting address of the symbol and the
+ * filename that this instruction belongs to.
+ *
+ * @param addr The untranslated address of the application's instruction.
+ * @param sym_name Pointer to a string where the symbol name will be stored.
+ * @param start_addr Pointer to the pointer where the starting address of the
+ * symbol will be stored.
+ * @param filename Pointer to a string where the filename will be stored.
+ * @return 0 on success or -1 on error.
+ */
 int get_symbol_info_by_addr(uintptr_t addr, char **sym_name, void **start_addr, char **filename);
 typedef int (*stack_frame_handler)(void *data, void *addr, char *sym_name, void *symbol_start_addr, char *filename);
 int get_backtrace(stack_frame_t *fp, stack_frame_handler handler, void *ptr);