From c660d362a7e25edf78883d7a441119a8550d9dd4 Mon Sep 17 00:00:00 2001 From: Oren Cohen Date: Tue, 27 Nov 2018 18:14:35 +0200 Subject: [PATCH] Melinda's remarks --- .../spm/COMPONENT_SPE/handles_manager.h | 19 ++++++++-------- .../spm/COMPONENT_SPE/spm_internal.h | 22 +++++++++---------- .../TARGET_PSA/spm/COMPONENT_SPE/spm_server.h | 6 ++--- 3 files changed, 23 insertions(+), 24 deletions(-) diff --git a/components/TARGET_PSA/spm/COMPONENT_SPE/handles_manager.h b/components/TARGET_PSA/spm/COMPONENT_SPE/handles_manager.h index 8a1b7337ba..57d9cdfe1c 100644 --- a/components/TARGET_PSA/spm/COMPONENT_SPE/handles_manager.h +++ b/components/TARGET_PSA/spm/COMPONENT_SPE/handles_manager.h @@ -26,10 +26,9 @@ /* -------------------------------- 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. +/* + * It 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. * @@ -40,8 +39,8 @@ * - 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 + * Handle generation is done exclusively. + * Once you 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. @@ -113,16 +112,16 @@ handles_pool /* * @brief create unique handle identifier * - * This function generates a unique handle identifier, and "couples" it with the received handle memory. + * 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_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. + * @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 */ @@ -147,7 +146,7 @@ void psa_hndl_mgr_handle_destroy(psa_handle_manager_t *handle_mgr, psa_handle_t * 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. + * @param handle The handle for which you 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); diff --git a/components/TARGET_PSA/spm/COMPONENT_SPE/spm_internal.h b/components/TARGET_PSA/spm/COMPONENT_SPE/spm_internal.h index f158f5760e..0b3e1246b8 100644 --- a/components/TARGET_PSA/spm/COMPONENT_SPE/spm_internal.h +++ b/components/TARGET_PSA/spm/COMPONENT_SPE/spm_internal.h @@ -110,11 +110,11 @@ typedef struct spm_ipc_channel { struct spm_partition *src_partition; /* Pointer to the Partition which connects to the Root of Trust Service.*/ spm_rot_service_t *dst_rot_service; /* Pointer to the connected Root of Trust Service.*/ void *rhandle; /* Reverse handle to be used for this channel.*/ - void *msg_ptr; /* message data sent from user */ - struct spm_ipc_channel *next; /* Next channel in the chain */ + void *msg_ptr; /* Message data sent from user. */ + struct spm_ipc_channel *next; /* Next channel in the chain.*/ uint8_t msg_type; /* The message type.*/ uint8_t state; /* The current processing state of the channel.*/ - uint8_t is_dropped; + uint8_t is_dropped; /* Indicates whether the channel has been dropped by the partition.*/ } spm_ipc_channel_t; /* @@ -127,7 +127,7 @@ typedef struct spm_active_msg { } spm_active_msg_t; /* - * Structure containing resources and attributes of a Secure Partition. + * Structure containing resources and attributes of a secure partition. */ typedef struct spm_partition { const int32_t partition_id; /* The Partition ID.*/ @@ -136,7 +136,7 @@ typedef struct spm_partition { const uint32_t flags_interrupts; /* Mask of all the IRQs & doorbell which the partition supports.*/ spm_rot_service_t *rot_services; /* Array of the Partition's Root of Trust Services.*/ const uint32_t rot_services_count; /* Number of the Partition's Root of Trust Services.*/ - const uint32_t *extern_sids; /* Array of Root of Trust Service IDs which the partition can connect to.*/ + const uint32_t *extern_sids; /* Array of Root of Trust Service IDs that the partition can connect to.*/ const uint32_t extern_sids_count; /* Number of Root of Trust Services which the partition can connect to.*/ osMutexId_t mutex; /* Mutex for all rot_service's queues operations. */ spm_signal_to_irq_mapper_t irq_mapper; /* a function which maps signal to irq number*/ @@ -171,19 +171,19 @@ const mem_region_t *get_mem_regions(int32_t partition_id, uint32_t *region_count // Platform dependent APIs /* - * Validates a memory block is accessable from a specific partition + * Validates that a memory block accessible from a specific partition * - * @param[in] ptr pointer to the beggining of the memory block. - * @param[in] size size of the memory block in bytes. - * @param[in] accessing_partition which partition is trying to access the memory. - * @return true if the entire memory block is accessable from given partition. + * @param[in] ptr - Pointer to the beggining of the memory block. + * @param[in] size - Size of the memory block in bytes. + * @param[in] accessing_partition - Which partition is trying to access the memory. + * @return `true` if the entire memory block is accessable from given partition. */ bool is_buffer_accessible(const void *ptr, size_t size, spm_partition_t *accessing_partition); /** * Alerts NSPE that a proccess (connect or call) has ended. * - * @param[in] completion_sem_id semaphore id in NSPE. + * @param[in] completion_sem_id - semaphore id in NSPE. */ void nspe_done(osSemaphoreId_t completion_sem_id); diff --git a/components/TARGET_PSA/spm/COMPONENT_SPE/spm_server.h b/components/TARGET_PSA/spm/COMPONENT_SPE/spm_server.h index 718c512a2a..c99efd7a0f 100644 --- a/components/TARGET_PSA/spm/COMPONENT_SPE/spm_server.h +++ b/components/TARGET_PSA/spm/COMPONENT_SPE/spm_server.h @@ -35,7 +35,7 @@ extern "C" { #endif /** @addtogroup RoT-Service-API - * The C interface for a Root of Trust Service in a partition. + * The C interface for a root of trust (RoT) Service in a partition. * @{ */ @@ -75,8 +75,8 @@ int32_t psa_identity(psa_handle_t msg_handle); /** * Get the message that corresponds to a given signal. * - * @param[in] signum an asserted signal returned from psa_wait(). - * @param[out] msg pointer to a psa_msg structure. + * @param[in] signum An asserted signal returned from psa_wait(). + * @param[out] msg Pointer to a psa_msg structure. */ void psa_get(psa_signal_t signum, psa_msg_t *msg);