Core: Align with PSA FF specification 1.0-beta-0
- Renamed psa_error_t to psa_status_t
- All functions that accept or return signals now use the psa_signal_t
type
- Removed PSA_CONNECTION_ACCEPTED and replaced its use in connection
messages by PSA_SUCCESS
- Added PSA_CONNECTION_BUSY to indicate transient error conditions
during calls to psa_connect() and renumbered the PSA error codes
- Removed psa_identity() and replaced it with client_id in psa_msg_t
- Renamed psa_end() to psa_reply()
- Combine psa_wait_any() and psa_wait_interrupt() into psa_wait().
Change-Id: Id3ba56f145a29aff297cc56e66810e0dbe0f913b
Signed-off-by: Edison Ai <edison.ai@arm.com>
Co-authored-by: Summer Qin <summer.qin@arm.com>
diff --git a/interface/include/psa_service.h b/interface/include/psa_service.h
index 38467b0..753fab7 100644
--- a/interface/include/psa_service.h
+++ b/interface/include/psa_service.h
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2018, Arm Limited. All rights reserved.
+ * Copyright (c) 2018-2019, Arm Limited. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*
@@ -14,11 +14,16 @@
#include <inttypes.h>
+/********************** PSA Secure Partition Macros and Types ****************/
+
/* PSA wait timeouts */
#define PSA_POLL (0x00000000u)
#define PSA_BLOCK (0x80000000u)
-/* doorbell signal */
+/* A mask value that includes all Secure Partition signals */
+#define PSA_WAIT_ANY (~0u)
+
+/* Doorbell signal */
#define PSA_DOORBELL (0x00000008u)
/* PSA message types */
@@ -26,227 +31,219 @@
#define PSA_IPC_CALL (2)
#define PSA_IPC_DISCONNECT (3)
-/* PSA response types */
-#define PSA_CONNECTION_ACCEPTED (0)
-
-/* maximum number of input and output vectors */
+/* Maximum number of input and output vectors */
#define PSA_MAX_IOVEC (4)
+/* Return code from psa_get() */
+#define PSA_ERR_NOMSG (INT32_MIN + 3)
+
+/* Store a set of one or more Secure Partition signals */
typedef uint32_t psa_signal_t;
/**
- * Describes a message received by a RoT Service after calling \ref psa_get().
+ * Describe a message received by an RoT Service after calling \ref psa_get().
*/
typedef struct psa_msg_t {
- uint32_t type;
- psa_handle_t handle;
- void *rhandle;
- size_t in_size[PSA_MAX_IOVEC];
- size_t out_size[PSA_MAX_IOVEC];
+ uint32_t type; /* One of the following values:
+ * \ref PSA_IPC_CONNECT
+ * \ref PSA_IPC_CALL
+ * \ref PSA_IPC_DISCONNECT
+ */
+ psa_handle_t handle; /* A reference generated by the SPM to the
+ * message returned by psa_get().
+ */
+ int32_t client_id; /* Partition ID of the sender of the message */
+ void *rhandle; /* Be useful for binding a connection to some
+ * application-specific data or function
+ * pointer within the RoT Service
+ * implementation.
+ */
+ size_t in_size[PSA_MAX_IOVEC]; /* Provide the size of each client input
+ * vector in bytes.
+ */
+ size_t out_size[PSA_MAX_IOVEC];/* Provide the size of each client output
+ * vector in bytes.
+ */
} psa_msg_t;
-/* ******** ******** PSA Secure Function API ******** ******** */
+/************************* PSA Secure Partition API **************************/
/**
- * \brief Returns the set of signals that have been asserted for a Sercure
- * Partition.
+ * \brief Return the Secure Partition interrupt signals that have been asserted
+ * from a subset of signals provided by the caller.
*
- * \param[in] timeout Specify either blocking or polling operation
+ * \param[in] signal_mask A set of signals to query. Signals that are not
+ * in this set will be ignored.
+ * \param[in] timeout Specify either blocking \ref PSA_BLOCK or
+ * polling \ref PSA_POLL operation.
*
- * \retval >0 At least one signal is asserted
- * \retval 0 No signals are asserted. This is only seen if the
- * caller used a polling timeout
+ * \retval >0 At least one signal is asserted.
+ * \retval 0 No signals are asserted. This is only seen when
+ * a polling timeout is used.
*/
-uint32_t psa_wait_any(uint32_t timeout);
+psa_signal_t psa_wait(psa_signal_t signal_mask, uint32_t timeout);
/**
- * \brief Returns the Secure Partition interrupt signals that have been
- * asserted from the subset of signals indicated in the bitmask provided.
- *
- * \param[in] signal_mask A set of interrupt and doorbell signals to query.
- * Signals that are not in this set will be ignored
- * \param[in] timeout Specify either blocking or polling operation
- *
- * \retval >0 At least one signal is asserted
- * \retval 0 No signals are asserted. This case is only seen if
- * caller used a polling timeout
- * \retval "Does not return" The call is invalid, one or more of the following
- * are true:
- * \arg signal_mask does not include any interrupt or
- * doorbell signals
- * \arg signal_mask includes one or more RoT Service
- * signals
- */
-uint32_t psa_wait_interrupt(psa_signal_t signal_mask, uint32_t timeout);
-
-/**
- * \brief Get the message which corresponds to a given RoT Service signal
+ * \brief Retrieve the message which corresponds to a given RoT Service signal
* and remove the message from the RoT Service queue.
*
- * \param[in] signal The signal value for an asserted RoT Service
- * \param[out] msg Pointer to \ref psa_msg_t object for receiving
- * the message
+ * \param[in] signal The signal value for an asserted RoT Service.
+ * \param[out] msg Pointer to \ref psa_msg_t object for receiving
+ * the message.
*
- * \retval void Success
- * \retval "Does not return" 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 a RoT Service
- * \arg The RoT Service signal is not currently asserted
- * \arg The msg pointer provided is not a valid memory
- * reference
+ * \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
+ * following are true:
+ * \arg signal has more than a single bit set.
+ * \arg signal does not correspond to an RoT Service.
+ * \arg The RoT Service signal is not currently
+ * asserted.
+ * \arg The msg pointer provided is not a valid memory
+ * reference.
*/
-void psa_get(psa_signal_t signal, psa_msg_t *msg);
+psa_status_t psa_get(psa_signal_t signal, psa_msg_t *msg);
/**
- * \brief Get the Partition ID of the sender of a message.
+ * \brief Associate some RoT Service private data with a client connection.
*
- * \param[in] msg_handle Message handle for an incoming message
+ * \param[in] msg_handle Handle for the client's message.
+ * \param[in] rhandle Reverse handle allocated by the RoT Service.
*
- * \retval >0 ID of a Secure Partition
- * \retval <0 ID of an NSPE client
- * \retval "Does not return" msg_handle is invalid
- *
- * \note Bit[31] is set if the caller is from the NSPE.
- */
-int32_t psa_identity(psa_handle_t msg_handle);
-
-/**
- * \brief Associates some caller-provided private data with a specified client
- * connection.
- *
- * \param[in] msg_handle Handle for the client's message
- * \param[in] rhandle Reverse handle allocated by the RoT Service
- *
- * \retval void Success, rhandle will be provided with all
- * subsequent messages delivered on this connection
- * \retval "Does not return" msg_handle is invalid
+ * \retval void Success, rhandle will be provided with all
+ * subsequent messages delivered on this
+ * connection.
+ * \retval "Does not return" msg_handle is invalid.
*/
void psa_set_rhandle(psa_handle_t msg_handle, void *rhandle);
/**
- * \brief Read a message parameter or part of a message parameter from the
- * client input vector.
+ * \brief Read a message parameter or part of a message parameter from a client
+ * input vector.
*
- * \param[in] msg_handle Handle for the client's message
- * \param[in] invec_idx Index of the input vector to read from. Must be
- * less than \ref PSA_MAX_IOVEC
- * \param[out] buffer Buffer in the Secure Partition to copy the
- * requested data to
- * \param[in] num_bytes Maximum number of bytes to be read from the client
- * input vector
+ * \param[in] msg_handle Handle for the client's message.
+ * \param[in] invec_idx Index of the input vector to read from. Must be
+ * less than \ref PSA_MAX_IOVEC.
+ * \param[out] buffer Buffer in the Secure Partition to copy the
+ * requested data to.
+ * \param[in] num_bytes Maximum number of bytes to be read from the
+ * client input vector.
*
- * \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 following
- * are true:
- * \arg msg_handle is invalid
- * \arg msg_handle does not refer to a \ref PSA_IPC_CALL
- * message
- * \arg invec_idx is equal to or greater than
- * PSA_MAX_IOVEC
- * \arg the memory reference for buffer is invalid or
- * not writable
+ * \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
+ * following are true:
+ * \arg msg_handle is invalid.
+ * \arg msg_handle does not refer to a
+ * \ref PSA_IPC_CALL message.
+ * \arg invec_idx is equal to or greater than
+ * \ref PSA_MAX_IOVEC.
+ * \arg the memory reference for buffer is invalid or
+ * not writable.
*/
size_t psa_read(psa_handle_t msg_handle, uint32_t invec_idx,
- void *buffer, size_t num_bytes);
+ void *buffer, size_t num_bytes);
/**
- * \brief Skip a given number of bytes for an input vector.
+ * \brief Skip over part of a client input vector.
*
- * \param[in] msg_handle Handle for the client's message
- * \param[in] invec_idx Index of input vector in message to skip from.
- * Must be less than \ref PSA_MAX_IOVEC
- * \param[in] num_bytes Maximum number of bytes to skip in the client input
- * vector
+ * \param[in] msg_handle Handle for the client's message.
+ * \param[in] invec_idx Index of input vector to skip from. Must be
+ * less than \ref PSA_MAX_IOVEC.
+ * \param[in] num_bytes Maximum number of bytes to skip in the client
+ * input vector.
*
- * \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 following
- * are true:
- * \arg msg_handle is invalid
- * \arg msg_handle does not refer to a \ref PSA_IPC_CALL
- * message
- * \arg invec_idx is equal to or greater than
- * PSA_MAX_IOVEC
+ * \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
+ * following are true:
+ * \arg msg_handle is invalid.
+ * \arg msg_handle does not refer to a
+ * \ref PSA_IPC_CALL message.
+ * \arg invec_idx is equal to or greater than
+ * \ref PSA_MAX_IOVEC.
*/
size_t psa_skip(psa_handle_t msg_handle, uint32_t invec_idx, size_t num_bytes);
/**
- * \brief Write a message response to the client output vector.
+ * \brief Write a message response to a client output vector.
*
- * \param[in] msg_handle Handle for the client's message
- * \param[out] outvec_idx Index of output vector in message to write to.
- * Must be less than \ref PSA_MAX_IOVEC
- * \param[in] buffer Buffer with the data to write
- * \param[in] num_bytes Number of bytes to write to the client output
- * vector
+ * \param[in] msg_handle Handle for the client's message.
+ * \param[out] outvec_idx Index of output vector in message to write to.
+ * Must be less than \ref PSA_MAX_IOVEC.
+ * \param[in] buffer Buffer with the data to write.
+ * \param[in] num_bytes Number of bytes to write to the client output
+ * vector.
*
- * \retval void Success
- * \retval "Does not return" 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 outvec_idx is equal to or greater than
- * \ref PSA_MAX_IOVEC
- * \arg the memory reference for buffer is invalid
- * \arg the call attempts to write data past the end of
- * the client output vector
+ * \retval void Success
+ * \retval "Does not return" 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 outvec_idx is equal to or greater than
+ * \ref PSA_MAX_IOVEC.
+ * \arg The memory reference for buffer is invalid.
+ * \arg The call attempts to write data past the end
+ * of the client output vector.
*/
void psa_write(psa_handle_t msg_handle, uint32_t outvec_idx,
- const void *buffer, size_t num_bytes);
+ const void *buffer, size_t num_bytes);
/**
- * \brief Completes handling of a specific message and unblocks the client.
+ * \brief Complete handling of a specific message and unblock the client.
*
- * \param[in] msg_handle Handle for the client's message or the null handle
- * \param[in] retval Return value to be reported to the client
+ * \param[in] msg_handle Handle for the client's message.
+ * \param[in] status Message result value to be reported to the
+ * client.
*
- * \retval void Success
- * \retval "Does not return" The call is invalid, one or more of the following
- * are true:
- * \arg msg_handle is invalid and is not the null handle
- * \arg An invalid return code is specified for the type
- * of message
+ * \retval void Success.
+ * \retval "Does not return" 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
+ * type of message.
*/
-void psa_end(psa_handle_t msg_handle, psa_error_t retval);
+void psa_reply(psa_handle_t msg_handle, psa_status_t status);
/**
- * \brief Sends a PSA_DOORBELL signal to a specific Secure Partition.
+ * \brief Send a PSA_DOORBELL signal to a specific Secure Partition.
*
- * \param[in] partition_id Secure Partition ID of the target partition
+ * \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
- * Partition
+ * \retval void Success.
+ * \retval "Does not return" partition_id does not correspond to a Secure
+ * Partition.
*/
void psa_notify(int32_t partition_id);
/**
- * \brief Clears the PSA_DOORBELL signal.
+ * \brief Clear the PSA_DOORBELL signal.
*
* \param[in] void
*
- * \retval void Success
- * \retval "Does not return" The Secure Partition's doorbell signal is not
- * currently asserted
+ * \retval void Success.
+ * \retval "Does not return" The Secure Partition's doorbell signal is not
+ * currently asserted.
*/
void psa_clear(void);
/**
- * \brief Informs the SPM that an interrupt has been handled (end of interrupt).
+ * \brief Inform the SPM that an interrupt has been handled (end of interrupt).
*
- * \param[in] irq_signal The interrupt signal that has been processed
+ * \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 following
- * are true:
- * \arg irq_signal is not an interrupt signal
- * \arg irq_signal indicates more than one signal
- * \arg irq_signal is not currently asserted
+ * \retval void Success.
+ * \retval "Does not return" 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.
+ * \arg irq_signal is not currently asserted.
*/
-void psa_eoi(uint32_t irq_signal);
+void psa_eoi(psa_signal_t irq_signal);
#ifdef __cplusplus
}