Core: PSA APIs alignment
Update PSA Client and Secure Partition APIs and some related files:
- Add psa_panic() to indicate an internal fault in a secure partition.
- Introduce a message type parameter to the psa_call() function which
is delivered as part of the psa_msg_t data to the RoT Service.
- Change 'minor version' to 'version'.
- Add PSA_HANDLE_IS_VALID() and PSA_HANDLE_TO_ERROR() macros.
- Move the definition of PSA_MAX_IOVEC and PSA_IPC_CALL from
psa/service.h to psa/client.h.
- Change the error code returned by psa_get() when the message could
not be delivered. It now returns PSA_ERROR_DOES_NOT_EXIST.
Change-Id: Ia717f591c80484699f4f491d1ed6dbc4fd7c050f
Signed-off-by: Summer Qin <summer.qin@arm.com>
diff --git a/interface/include/psa/service.h b/interface/include/psa/service.h
index 9af3f67..94eb082 100644
--- a/interface/include/psa/service.h
+++ b/interface/include/psa/service.h
@@ -20,26 +20,31 @@
/********************** PSA Secure Partition Macros and Types ****************/
-/* PSA wait timeouts */
+/**
+ * A timeout value that requests a polling wait operation.
+ */
#define PSA_POLL (0x00000000u)
+
+/**
+ * A timeout value that requests a blocking wait operation.
+ */
#define PSA_BLOCK (0x80000000u)
-/* A mask value that includes all Secure Partition signals */
-#define PSA_WAIT_ANY (~0u)
+/**
+ * A mask value that includes all Secure Partition signals.
+ */
+#define PSA_WAIT_ANY (0xFFFFFFFFu)
-/* Doorbell signal */
+/**
+ * The signal number for the Secure Partition doorbell.
+ */
#define PSA_DOORBELL (0x00000008u)
/* PSA message types */
-#define PSA_IPC_CONNECT (1)
-#define PSA_IPC_CALL (2)
-#define PSA_IPC_DISCONNECT (3)
-
-/* Maximum number of input and output vectors */
-#define PSA_MAX_IOVEC (4)
-
-/* Return code from psa_get() */
-#define PSA_ERR_NOMSG (INT32_MIN + 3)
+/* An IPC message type that indicates a new connection. */
+#define PSA_IPC_CONNECT (-1)
+/* An IPC message type that indicates the end of a connection. */
+#define PSA_IPC_DISCONNECT (-2)
/* Store a set of one or more Secure Partition signals */
typedef uint32_t psa_signal_t;
@@ -48,9 +53,9 @@
* Describe a message received by an RoT Service after calling \ref psa_get().
*/
typedef struct psa_msg_t {
- uint32_t type; /* One of the following values:
+ int32_t type; /* One of the following values:
* \ref PSA_IPC_CONNECT
- * \ref PSA_IPC_CALL
+ * >= 0
* \ref PSA_IPC_DISCONNECT
*/
psa_handle_t handle; /* A reference generated by the SPM to the
@@ -97,8 +102,8 @@
*
* \retval PSA_SUCCESS Success, *msg will contain the delivered
* message.
- * \retval PSA_ERR_NOMSG Message could not be delivered.
- * \retval "Does not return" The call is invalid because one or more of the
+ * \retval PSA_ERROR_DOES_NOT_EXIST Message could not be delivered.
+ * \retval "PROGRAMMER ERROR" The call is invalid because one or more of the
* following are true:
* \arg signal has more than a single bit set.
* \arg signal does not correspond to an RoT Service.
@@ -118,7 +123,7 @@
* \retval void Success, rhandle will be provided with all
* subsequent messages delivered on this
* connection.
- * \retval "Does not return" msg_handle is invalid.
+ * \retval "PROGRAMMER ERROR" msg_handle is invalid.
*/
void psa_set_rhandle(psa_handle_t msg_handle, void *rhandle);
@@ -137,7 +142,7 @@
* \retval >0 Number of bytes copied.
* \retval 0 There was no remaining data in this input
* vector.
- * \retval "Does not return" The call is invalid, one or more of the
+ * \retval "PROGRAMMER ERROR" The call is invalid, one or more of the
* following are true:
* \arg msg_handle is invalid.
* \arg msg_handle does not refer to a
@@ -162,11 +167,11 @@
* \retval >0 Number of bytes skipped.
* \retval 0 There was no remaining data in this input
* vector.
- * \retval "Does not return" The call is invalid, one or more of the
+ * \retval "PROGRAMMER ERROR" The call is invalid, one or more of the
* following are true:
* \arg msg_handle is invalid.
- * \arg msg_handle does not refer to a
- * \ref PSA_IPC_CALL message.
+ * \arg msg_handle does not refer to a request
+ * message.
* \arg invec_idx is equal to or greater than
* \ref PSA_MAX_IOVEC.
*/
@@ -183,11 +188,11 @@
* vector.
*
* \retval void Success
- * \retval "Does not return" The call is invalid, one or more of the
+ * \retval "PROGRAMMER ERROR" The call is invalid, one or more of the
* following are true:
* \arg msg_handle is invalid.
- * \arg msg_handle does not refer to a
- * \ref PSA_IPC_CALL message.
+ * \arg msg_handle does not refer to a request
+ * message.
* \arg outvec_idx is equal to or greater than
* \ref PSA_MAX_IOVEC.
* \arg The memory reference for buffer is invalid.
@@ -205,7 +210,7 @@
* client.
*
* \retval void Success.
- * \retval "Does not return" The call is invalid, one or more of the
+ * \retval "PROGRAMMER ERROR" The call is invalid, one or more of the
* following are true:
* \arg msg_handle is invalid.
* \arg An invalid status code is specified for the
@@ -219,7 +224,7 @@
* \param[in] partition_id Secure Partition ID of the target partition.
*
* \retval void Success.
- * \retval "Does not return" partition_id does not correspond to a Secure
+ * \retval "PROGRAMMER ERROR" partition_id does not correspond to a Secure
* Partition.
*/
void psa_notify(int32_t partition_id);
@@ -228,7 +233,7 @@
* \brief Clear the PSA_DOORBELL signal.
*
* \retval void Success.
- * \retval "Does not return" The Secure Partition's doorbell signal is not
+ * \retval "PROGRAMMER ERROR" The Secure Partition's doorbell signal is not
* currently asserted.
*/
void psa_clear(void);
@@ -239,7 +244,7 @@
* \param[in] irq_signal The interrupt signal that has been processed.
*
* \retval void Success.
- * \retval "Does not return" The call is invalid, one or more of the
+ * \retval "PROGRAMMER ERROR" The call is invalid, one or more of the
* following are true:
* \arg irq_signal is not an interrupt signal.
* \arg irq_signal indicates more than one signal.
@@ -247,6 +252,14 @@
*/
void psa_eoi(psa_signal_t irq_signal);
+/**
+ * \brief Terminate execution within the calling Secure Partition and will not
+ * return.
+ *
+ * \retval "Does not return"
+ */
+void psa_panic(void);
+
#ifdef __cplusplus
}
#endif