Melinda's remarks

Author: Oren Cohen

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);

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);
 

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);