diff --git a/components/TARGET_PSA/spm/COMPONENT_SPE/handles_manager.h b/components/TARGET_PSA/spm/COMPONENT_SPE/handles_manager.h index 6190b3639f..3e7818bd9a 100644 --- a/components/TARGET_PSA/spm/COMPONENT_SPE/handles_manager.h +++ b/components/TARGET_PSA/spm/COMPONENT_SPE/handles_manager.h @@ -27,21 +27,21 @@ /* -------------------------------- Handle Manager Module ---------------------------- */ /* - * The Handle Manager module 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" + * The Handle Manager module generates and exposes a unique + * identifier (handle) per handle memory (handle_mem) it receives. + * You 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] + * You 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] + * handle identifier [`handle_get_mem`]. + * - Remove a handle from the handle manager module [`handle_destroy`]. * * Note: * Handle generation is done exclusively. * Once you have a handle, you can remove or get its memory non-exclusively. - * The assumption is that only one context is dealing with a handle after it was + * The assumption is that only one context is dealing with a handle after it is * generated. */ @@ -59,9 +59,9 @@ extern "C" { #define PSA_HANDLE_MGR_INVALID_FRIEND_OWNER 0 // Denoting invalid friend or invalid owner -// Handles manager pool indexes must be in range 0 - 0x7FFF. -// The reason for this limitation is that the index is stored in the upper 16 bits of a handle, -// and the most significant bit must be zero to keep handles non negative. +// Handle manager pool indexes must be in range 0 - 0x7FFF. +// This is because the index is stored in the upper 16 bits of a handle, +// and the most significant bit must be zero to keep handles non-negative. #define PSA_HANDLE_MGR_MAX_HANDLES_NUM 0x8000 @@ -70,19 +70,19 @@ extern "C" { typedef struct psa_handle_item_t { - psa_handle_t handle; /* The user exposed handle [unique identifier] */ - int32_t handle_owner; /* The partition id of the handle creator - allowed to get_mem() / destroy() */ - int32_t handle_friend; /* The partition id of a "friend" partition - allowed to get_mem() */ - void *handle_mem; /* Points to memory allocated by the user */ + psa_handle_t handle; /* The user-exposed handle [unique identifier]. */ + int32_t handle_owner; /* The partition ID of the handle creator. Allowed to get_mem() / destroy(). */ + int32_t handle_friend; /* The partition ID of a "friend" partition. Allowed to get_mem(). */ + void *handle_mem; /* Points to memory allocated by the use.r */ } psa_handle_item_t; typedef struct psa_handle_manager_t { - uint32_t handle_generator; /* A counter supplying handle numbers */ - uint32_t pool_size; /* The maximum number of handles that pool can contain */ - psa_handle_item_t *handles_pool; /* Holding couples of handles and their memory "blocks" */ + uint32_t handle_generator; /* A counter supplying handle numbers. */ + uint32_t pool_size; /* The maximum number of handles that pool can contain. */ + psa_handle_item_t *handles_pool; /* Holds couples of handles and their memory "blocks". */ } psa_handle_manager_t; @@ -109,40 +109,40 @@ handles_pool /* - * @brief create unique handle identifier + * @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. + * This function will panic in the case of non-vacant space use. * * @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 + * @param[in] handle_mem A pointer to a pre-allocated handle memory for which to get a handle identifier. + * @param[in] friend_pid The partition ID allowed to `get_mem()` and `destroy()` in addition to the handle owner. + * Use `PSA_HANDLE_MGR_INVALID_FRIEND_OWNER` to denote that 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. + * @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 + * @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 + * @brief De-reference handle * * This function retrieves the pointer associated with the input . * - * @note This function will panic in case caller not allowed to dereference the memory - * or handler does not correspond to a valid existing handle + * @note This function will panic if caller is not allowed to de-reference 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 you request the corresponding memory handle.