SPM: Add Non-secure Client extension support
The Non-secure client extension is the interface to the non-secure side
for managing the non-secure client context in TF-M side.
For now, the context is used for the non-secure client ID only.
Signed-off-by: David Wang <david.wang@arm.com>
Change-Id: I374ebb2ee148165a3e1d77665cf39a6941087bb6
diff --git a/interface/include/tfm_ns_client_ext.h b/interface/include/tfm_ns_client_ext.h
new file mode 100644
index 0000000..b6e944c
--- /dev/null
+++ b/interface/include/tfm_ns_client_ext.h
@@ -0,0 +1,109 @@
+/*
+ * Copyright (c) 2021, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#ifndef __TFM_NS_CLIENT_EXT_H__
+#define __TFM_NS_CLIENT_EXT_H__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdint.h>
+
+#define TFM_NS_CLIENT_INVALID_TOKEN 0xFFFFFFFF
+
+/* TF-M NSID Error code */
+#define TFM_NS_CLIENT_ERR_SUCCESS 0x0
+#define TFM_NS_CLIENT_ERR_INVALID_TOKEN 0x1
+#define TFM_NS_CLIENT_ERR_INVALID_NSID 0x2
+#define TFM_NS_CLIENT_ERR_INVALID_ACCESS 0x3
+
+/**
+ * \brief Initialize the non-secure client extension
+ *
+ * \details This function should be called before any other non-secure client
+ * APIs. It gives NSPE the opportunity to initialize the non-secure
+ * client extension in TF-M. Also, NSPE can get the number of allocated
+ * non-secure client context slots in the return value. That is useful
+ * if NSPE wants to decide the group (context) assignment at runtime.
+ *
+ * \param[in] ctx_requested The number of non-secure context requested from the
+ * NS entity. If request maximum available context, then set it to 0.
+ *
+ * \return Returns the number of non-secure context allocated to the NS entity.
+ * The allocated context number <= maximum supported context number.
+ * If the initialization is failed, then 0 is returned.
+ */
+uint32_t tfm_nsce_init(uint32_t ctx_requested);
+
+/**
+ * \brief Acquire the context for a non-secure client
+ *
+ * \details This function should be called before a non-secure client calling
+ * the PSA API into TF-M. It is to request the allocation of the
+ * context for the upcoming service call from that non-secure client.
+ * The non-secure clients in one group share the same context.
+ * The thread ID is used to identify the different non-secure clients.
+ *
+ * \param[in] group_id The group ID of the non-secure client
+ * \param[in] thread_id The thread ID of the non-secure client
+ *
+ * \return Returns the token of the allocated context. 0xFFFFFFFF means the
+ * allocation failed and the token is invalid.
+ */
+uint32_t tfm_nsce_acquire_ctx(uint8_t group_id, uint8_t thread_id);
+
+/**
+ * \brief Release the context for the non-secure client
+ *
+ * \details This function should be called when a non-secure client is going to
+ * be terminated or will not call TF-M secure services in the future.
+ * It is to release the context allocated for the calling non-secure
+ * client. If the calling non-secure client is the only thread in the
+ * group, then the context will be deallocated. Otherwise, the context
+ * will still be taken for the other threads in the group.
+ *
+ * \param[in] token The token returned by tfm_nsce_acquire_ctx
+ *
+ * \return Returns the error code.
+ */
+uint32_t tfm_nsce_release_ctx(uint32_t token);
+
+/**
+ * \brief Load the context for the non-secure client
+ *
+ * \details This function should be called when a non-secure client is going to
+ * be scheduled in at the non-secure side.
+ * The caller is usually the scheduler of the RTOS.
+ * The non-secure client ID is managed by the non-secure world and
+ * passed to TF-M as the input parameter of TF-M.
+ *
+ * \param[in] token The token returned by tfm_nsce_acquire_ctx
+ * \param[in] nsid The non-secure client ID for this client
+ *
+ * \return Returns the error code.
+ */
+uint32_t tfm_nsce_load_ctx(uint32_t token, int32_t nsid);
+
+/**
+ * \brief Save the context for the non-secure client
+ *
+ * \details This function should be called when a non-secure client is going to
+ * be scheduled out at the non-secure side.
+ * The caller is usually the scheduler of the RTOS.
+ *
+ * \param[in] token The token returned by tfm_nsce_acquire_ctx
+ *
+ * \return Returns the error code.
+ */
+uint32_t tfm_nsce_save_ctx(uint32_t token);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __TFM_NS_CLIENT_EXT_H__ */