Core: add PSA API header files
Add PSA service and client FF API headers.
Change-Id: I3be4100bad7978c6b867f1b0bf651c3c773b3fbb
Signed-off-by: Miklos Balint <miklos.balint@arm.com>
Co-authored-by: Summer Qin <summer.qin@arm.com>
diff --git a/interface/include/psa_client.h b/interface/include/psa_client.h
new file mode 100644
index 0000000..dbe0e72
--- /dev/null
+++ b/interface/include/psa_client.h
@@ -0,0 +1,135 @@
+/*
+ * Copyright (c) 2018, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#ifndef __PSA_CLIENT_H__
+#define __PSA_CLIENT_H__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdint.h>
+#include <stddef.h>
+
+/* ******** ******** PSA Common API ******** ******** */
+
+/* FixMe: PSA FF v0.9 has not been released. All PSA API subject to change */
+#define PSA_FRAMEWORK_VERSION (0x0009)
+
+#define PSA_VERSION_NONE (0)
+
+/* PSA response types */
+#define PSA_SUCCESS (0)
+#define PSA_CONNECTION_REFUSED (INT32_MIN + 1)
+#define PSA_DROP_CONNECTION (INT32_MIN)
+
+/* PSA message handles */
+#define PSA_NULL_HANDLE ((psa_handle_t)0)
+
+typedef int32_t psa_error_t;
+typedef int32_t psa_handle_t;
+
+/**
+ * A read-only input memory region provided to a RoT Service.
+ */
+typedef struct psa_invec {
+ const void *base; /*!< the start address of the memory buffer */
+ size_t len; /*!< the size in bytes */
+} psa_invec;
+
+/**
+ * A writable output memory region provided to a RoT Service.
+ */
+typedef struct psa_outvec {
+ void *base; /*!< the start address of the memory buffer */
+ size_t len; /*!< the size in bytes */
+} psa_outvec;
+
+/**
+ * \brief Retrieve the version of the PSA Framework API that is implemented.
+ *
+ * \return The version of the PSA Framework implementation that is providing
+ * the runtime services to the caller.
+ * \return The major and minor version are encoded as follows:
+ * \arg version[15:8] -- major version number
+ * \arg version[7:0] -- minor version number
+ */
+uint32_t psa_framework_version(void);
+
+/* ******** ******** PSA Client API ******** ******** */
+
+/**
+ * \brief Retrieve the minor version of a 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
+ */
+uint32_t psa_version(uint32_t sid);
+
+/**
+ * \brief Connect to a 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
+ *
+ * \retval >0 A handle for the connection
+ * \retval PSA_CONNECTION_REFUSED The RoT Service has refused the connection
+ * \retval "Does not return" The RoT Service ID and version are not
+ * supported, or the caller is not permitted
+ * to access the service
+ */
+psa_handle_t psa_connect(uint32_t sid, uint32_t minor_version);
+
+/**
+ * \brief Calls a RoT Service on an established connection.
+ *
+ * \param[in] handle A handle to an established connection
+ * \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_vec Array of input \ref psa_outvec structures
+ * \param[in] in_len Number of input \ref psa_outvec structures
+ *
+ * \retval >=0 Application-specific return code
+ * \retval <0 Application-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:
+ * \arg An invalid handle was passed
+ * \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_error_t psa_call(psa_handle_t handle,
+ const psa_invec *in_vec,
+ size_t in_len,
+ const psa_outvec *out_vec,
+ size_t out_len);
+
+/**
+ * \brief Closes a connection to a RoT Service.
+ *
+ * \param[in] handle A handle to an established connection, or the
+ * null handle
+ *
+ * \retval void Success
+ * \retval "Does not return" An invalid handle was provided that is not the
+ * null handle
+ */
+void psa_close(psa_handle_t handle);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __PSA_CLIENT_H__ */
diff --git a/interface/include/psa_service.h b/interface/include/psa_service.h
new file mode 100644
index 0000000..38467b0
--- /dev/null
+++ b/interface/include/psa_service.h
@@ -0,0 +1,255 @@
+/*
+ * Copyright (c) 2018, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#ifndef __PSA_SERVICE_H__
+#define __PSA_SERVICE_H__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <inttypes.h>
+
+/* PSA wait timeouts */
+#define PSA_POLL (0x00000000u)
+#define PSA_BLOCK (0x80000000u)
+
+/* doorbell signal */
+#define PSA_DOORBELL (0x00000008u)
+
+/* PSA message types */
+#define PSA_IPC_CONNECT (1)
+#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 */
+#define PSA_MAX_IOVEC (4)
+
+typedef uint32_t psa_signal_t;
+
+/**
+ * Describes a message received by a 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];
+} psa_msg_t;
+
+/* ******** ******** PSA Secure Function API ******** ******** */
+
+/**
+ * \brief Returns the set of signals that have been asserted for a Sercure
+ * Partition.
+ *
+ * \param[in] timeout Specify either blocking or polling 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
+ */
+uint32_t psa_wait_any(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
+ * 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
+ *
+ * \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
+ */
+void psa_get(psa_signal_t signal, psa_msg_t *msg);
+
+/**
+ * \brief Get the Partition ID of the sender of a message.
+ *
+ * \param[in] msg_handle Message handle for an incoming message
+ *
+ * \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
+ */
+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.
+ *
+ * \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
+ */
+size_t psa_read(psa_handle_t msg_handle, uint32_t invec_idx,
+ void *buffer, size_t num_bytes);
+
+/**
+ * \brief Skip a given number of bytes for an 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
+ *
+ * \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
+ */
+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.
+ *
+ * \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
+ */
+void psa_write(psa_handle_t msg_handle, uint32_t outvec_idx,
+ const void *buffer, size_t num_bytes);
+
+/**
+ * \brief Completes handling of a specific message and unblocks 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
+ *
+ * \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
+ */
+void psa_end(psa_handle_t msg_handle, psa_error_t retval);
+
+/**
+ * \brief Sends a PSA_DOORBELL signal to a specific Secure 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
+ */
+void psa_notify(int32_t partition_id);
+
+/**
+ * \brief Clears the PSA_DOORBELL signal.
+ *
+ * \param[in] void
+ *
+ * \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).
+ *
+ * \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
+ */
+void psa_eoi(uint32_t irq_signal);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __PSA_SERVICE_H__ */