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