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/client.h b/interface/include/psa/client.h
index 33e3f2d..d040834 100644
--- a/interface/include/psa/client.h
+++ b/interface/include/psa/client.h
@@ -19,17 +19,44 @@
/*********************** PSA Client Macros and Types *************************/
-#define PSA_FRAMEWORK_VERSION (0x0100)
+/**
+ * The version of the PSA Framework API that is being used to build the calling
+ * firmware.
+ */
+#define PSA_FRAMEWORK_VERSION (0x0100u)
-#define PSA_VERSION_NONE (0)
+/**
+ * Return value from psa_version() if the requested RoT Service is not present
+ * in the system.
+ */
+#define PSA_VERSION_NONE (0u)
-/* PSA response types */
-#define PSA_CONNECTION_REFUSED (INT32_MIN + 1)
-#define PSA_CONNECTION_BUSY (INT32_MIN + 2)
-#define PSA_DROP_CONNECTION (INT32_MIN)
+/**
+ * The zero-value null handle can be assigned to variables used in clients and
+ * RoT Services, indicating that there is no current connection or message.
+ */
+#define PSA_NULL_HANDLE ((psa_handle_t)0)
-/* PSA message handles */
-#define PSA_NULL_HANDLE ((psa_handle_t)0)
+/**
+ * Tests whether a handle value returned by psa_connect() is valid.
+ */
+#define PSA_HANDLE_IS_VALID(handle) ((psa_handle_t)(handle) > 0)
+
+/**
+ * Converts the handle value returned from a failed call psa_connect() into
+ * an error code.
+ */
+#define PSA_HANDLE_TO_ERROR(handle) ((psa_status_t)(handle))
+
+/**
+ * Maximum number of input and output vectors for a request to psa_call().
+ */
+#define PSA_MAX_IOVEC (4u)
+
+/**
+ * An IPC message type that indicates a generic client request.
+ */
+#define PSA_IPC_CALL (0)
typedef int32_t psa_handle_t;
@@ -64,15 +91,14 @@
uint32_t psa_framework_version(void);
/**
- * \brief Retrieve the minor version of an RoT Service or indicate that it is
- * not present on this system.
+ * \brief Retrieve the version of an RoT Service or indicate that it is not
+ * present on this system.
*
* \param[in] sid ID of the RoT Service to query.
*
* \retval PSA_VERSION_NONE The RoT Service is not implemented, or the
* caller is not permitted to access the service.
- * \retval > 0 The minor version of the implemented RoT
- * Service.
+ * \retval > 0 The version of the implemented RoT Service.
*/
uint32_t psa_version(uint32_t sid);
@@ -80,23 +106,28 @@
* \brief Connect to an RoT Service by its SID.
*
* \param[in] sid ID of the RoT Service to connect to.
- * \param[in] minor_version Requested version of the RoT Service.
+ * \param[in] version Requested version of the RoT Service.
*
* \retval > 0 A handle for the connection.
- * \retval PSA_CONNECTION_REFUSED The SPM or RoT Service has refused the
+ * \retval PSA_ERROR_CONNECTION_REFUSED The SPM or RoT Service has refused the
* connection.
- * \retval PSA_CONNECTION_BUSY The SPM or RoT Service cannot make the
+ * \retval PSA_ERROR_CONNECTION_BUSY The SPM or RoT Service cannot make the
* connection at the moment.
- * \retval "Does not return" The RoT Service ID and version are not
- * supported, or the caller is not permitted to
- * access the service.
+ * \retval "PROGRAMMER ERROR" The call is a PROGRAMMER ERROR if one or more
+ * of the following are true:
+ * \arg The RoT Service ID is not present.
+ * \arg The RoT Service version is not supported.
+ * \arg The caller is not allowed to access the RoT
+ * service.
*/
-psa_handle_t psa_connect(uint32_t sid, uint32_t minor_version);
+psa_handle_t psa_connect(uint32_t sid, uint32_t version);
/**
* \brief Call an RoT Service on an established connection.
*
* \param[in] handle A handle to an established connection.
+ * \param[in] type The reuqest type.
+ * Must be zero( \ ref PSA_IPC_CALL) or positive.
* \param[in] in_vec Array of input \ref psa_invec structures.
* \param[in] in_len Number of input \ref psa_invec structures.
* \param[in/out] out_vec Array of output \ref psa_outvec structures.
@@ -104,19 +135,18 @@
*
* \retval >=0 RoT Service-specific status value.
* \retval <0 RoT Service-specific error code.
- * \retval PSA_DROP_CONNECTION The connection has been dropped by the RoT
- * Service. This indicates that either this or
- * a previous message was invalid.
- * \retval "Does not return" The call is invalid, one or more of the
- * following are true:
+ * \retval PSA_ERROR_PROGRAMMER_ERROR The connection has been terminated by the
+ * RoT Service. The call is a PROGRAMMER ERROR if
+ * one or more of the following are true:
* \arg An invalid handle was passed.
* \arg The connection is already handling a request.
+ * \arg type < 0.
* \arg An invalid memory reference was provided.
* \arg in_len + out_len > PSA_MAX_IOVEC.
* \arg The message is unrecognized by the RoT
* Service or incorrectly formatted.
*/
-psa_status_t psa_call(psa_handle_t handle,
+psa_status_t psa_call(psa_handle_t handle, int32_t type,
const psa_invec *in_vec,
size_t in_len,
psa_outvec *out_vec,
@@ -129,11 +159,12 @@
* null handle.
*
* \retval void Success.
- * \retval "Does not return" The call is invalid, one or more of the
- * following are true:
+ * \retval "PROGRAMMER ERROR" The call is a PROGRAMMER ERROR if one or more
+ * of the following are true:
* \arg An invalid handle was provided that is not
* the null handle.
- * \arg The connection is handling a request.
+ * \arg The connection is currently handling a
+ * request.
*/
void psa_close(psa_handle_t handle);
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