diff --git a/api/hash_table.h b/api/hash_table.h index 05cd499d..f2066328 100644 --- a/api/hash_table.h +++ b/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 \ No newline at end of file diff --git a/api/plugin_support.h b/api/plugin_support.h index 128ac1c9..27504497 100644 --- a/api/plugin_support.h +++ b/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 stored at 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);