Handle manager documentation fix

Move function description to header files

Note: it is not in Doxygen format since it is an internal module and
        Doxygen should not be generated for it

Author: Alexander Zilberkant

components/TARGET_PSA/spm/COMPONENT_SPE/handles_manager.c

@@ -29,56 +29,15 @@
 #include <stdlib.h>
 
 
-
 /* ------------------------------------ Definitions ---------------------------------- */
 
 #define PSA_HANDLE_MGR_HANDLE_INDEX_POS         16
 #define PSA_HANDLE_MGR_HANDLE_INDEX_MSK         0xFFFF
 
 
-
-/* -------------------------------- Handle Manager Module ---------------------------- */
-
-/* The Handle Manager Module manages handles.
- *
- * It basically generates and exposes a unique handle identifier [handle] per
- * handle memory [handle_mem] it receives from the user.
- * Then users can use the exposed handle identifier to relate to the "registered"
- * handle memory.
- *
- * Users can:
- * - Ask for a unique handle identifier for a given handle memory [handle_create]
- * - Ask for a pointer to the handle memory corresponding to a
- *   handle identifier [handle_get_mem]
- * - Remove a handle from the handle manager module [handle_destroy]
- *
- * Note:
- * Handles generation is done exclusively.
- * Once we got a handle, removing a handle or getting its memory can be
- * done non-exclusive.
- * The assumption is that only one context is dealing with a handle after it was
- * generated.
- */
-
 /* ------------------------------------- Functions ----------------------------------- */
 
-/**********************************************************************************************************************************
- * Function   : psa_hndl_mgr_handle_create
- *
- * Description: This function generates a unique handle identifier, and "couples" it with the received handle memory.
- *              If there is no vacant space for the new handle, the function fails.
- *
- * Note:        This function is expected to pass since it is always coupled with memory pool allocation of the same size.
- *              In case memory pool allocation fails, this function should not be called.
- *              This function will panic on non vacant space use case.
- *
- * Parameters : handle_mgr - [IN]  A pointer to the handle manager object
- *              handle_mem - [IN]  A pointer to a pre-allocated handle memory to get a handle identifier for
- *              friend_pid - [IN]  The partition id which is allowed to get_mem() and destroy() in addition to the handle owner.
- *                                 Use PSA_HANDLE_MGR_INVALID_FRIEND_OWNER to denote there is no friend partition.
- *
- * Return     : The created handle identifier
- *********************************************************************************************************************************/
+
 psa_handle_t psa_hndl_mgr_handle_create(psa_handle_manager_t *handle_mgr, void *handle_mem, int32_t friend_pid)
 {
     // Make sanity checks on arguments
@@ -137,16 +96,6 @@ psa_handle_t psa_hndl_mgr_handle_create(psa_handle_manager_t *handle_mgr, void *
 }
 
 
-/**********************************************************************************************************************************
- * Function   : psa_hndl_mgr_handle_destroy
- *
- * Description: This function removes a handle from the handle manager.
- *
- * Parameters : handle_mgr - [IN]  A pointer to the handle manager object
- *              handle     - [IN]  The handle to be removed
- *
- * Return     : Void
- *********************************************************************************************************************************/
 void psa_hndl_mgr_handle_destroy(psa_handle_manager_t *handle_mgr, psa_handle_t handle)
 {
     // Make sanity checks on arguments
@@ -180,17 +129,6 @@ void psa_hndl_mgr_handle_destroy(psa_handle_manager_t *handle_mgr, psa_handle_t
 }
 
 
-/**********************************************************************************************************************************
- * Function   : psa_hndl_mgr_handle_get_mem
- *
- * Description: This function looks for the handle memory corresponding to <handle>.
- *              If it is not found in the expected index in the handles pool, the function fails.
- *
- * Parameters : handle_mgr - [IN]  A pointer to the handle manager object.
- *              handle     - [IN]  The handle for which we request the corresponding memory handle.
- *
- * Return     : A pointer to the memory corresponding to the handle.
- *********************************************************************************************************************************/
 void *psa_hndl_mgr_handle_get_mem(psa_handle_manager_t *handle_mgr, psa_handle_t handle)
 {
     SPM_ASSERT(handle_mgr != NULL);

components/TARGET_PSA/spm/COMPONENT_SPE/handles_manager.h

@@ -24,7 +24,28 @@
 
 #include <stdint.h>
 
+/* -------------------------------- Handle Manager Module ---------------------------- */
 
+/* The Handle Manager Module manages handles.
+ *
+ * It basically generates and exposes a unique handle identifier [handle] per
+ * handle memory [handle_mem] it receives from the user.
+ * Then users can use the exposed handle identifier to relate to the "registered"
+ * handle memory.
+ *
+ * Users can:
+ * - Ask for a unique handle identifier for a given handle memory [handle_create]
+ * - Ask for a pointer to the handle memory corresponding to a
+ *   handle identifier [handle_get_mem]
+ * - Remove a handle from the handle manager module [handle_destroy]
+ *
+ * Note:
+ * Handles generation is done exclusively.
+ * Once we got a handle, removing a handle or getting its memory can be
+ * done non-exclusive.
+ * The assumption is that only one context is dealing with a handle after it was
+ * generated.
+ */
 
 /* --------------------------------- extern "C" wrapper ------------------------------ */
 
@@ -88,8 +109,47 @@ handles_pool
 
 /* ------------------------------------- Functions ----------------------------------- */
 
+
+/*
+ * @brief create unique handle identifier
+ * 
+ * This function generates a unique handle identifier, and "couples" it with the received handle memory.
+ * If there is no vacant space for the new handle, the function fails.
+ * 
+ * @note This function is expected to pass since it is always coupled with memory pool allocation of the same size.
+ *       In case memory pool allocation fails, this function should not be called.
+ *       This function will panic on non vacant space use case.
+ * 
+ * @param[in] handle_mgr   A pointer to the handle manager object
+ * @param[in] handle_mem   A pointer to a pre-allocated handle memory to get a handle identifier for
+ * @param[in] friend_pid   The partition id which is allowed to get_mem() and destroy() in addition to the handle owner.
+ *                          Use PSA_HANDLE_MGR_INVALID_FRIEND_OWNER to denote there is no friend partition.
+ * @return The created handle identifier
+ */
 psa_handle_t psa_hndl_mgr_handle_create(psa_handle_manager_t *handle_mgr, void *handle_mem, int32_t friend_pid);
+
+
+/*
+ * @brief remove a handle from the handle manager.
+ * 
+ * @param handle_mgr   A pointer to the handle manager object
+ * @param handle       The handle to be removed
+ */
 void psa_hndl_mgr_handle_destroy(psa_handle_manager_t *handle_mgr, psa_handle_t handle);
+
+
+/*
+ * @brief dereference handle
+ * 
+ * This function retrieves the pointer associated with the input <handle>.
+ *  
+ * @note  This function will panic in case caller not allowed to dereference the memory
+ *         or handler does not correspond to a valid existing handle
+ * 
+ * @param handle_mgr   A pointer to the handle manager object.
+ * @param handle       The handle for which we request the corresponding memory handle.
+ * @return void*       A pointer to the memory corresponding to the handle.
+ */
 void *psa_hndl_mgr_handle_get_mem(psa_handle_manager_t *handle_mgr, psa_handle_t handle);