Interface: Provide implementation of tfm_ns_interface_dispatch()
This patch provides implementation of tfm_ns_interface_dispatch for
bare metal and RTOS use cases. This is needed to simplify TF-M
integration with NS application.
For more details refer to
"Default implementation of tfm_ns_interface_dispatch()" mailing thread:
https://lists.trustedfirmware.org/archives/list/tf-m@lists.trustedfirmware.org/message/ZCBRUODVTBK26JGAZKKIJEQ62D3XIMSO/
and TF-M tech forum presentation
"Default implemeation of tsm_ns_interface_dispatch":
https://www.trustedfirmware.org/meetings/tf-m-technical-forum/
Following things are done:
* tfm_ns_interface.c was moved from test repo to TF-M repo
tfm_ns_interface_rtos.c file
* tfm_ns_interface_bare_metal.c is added.
* required NS OS wrapper header files are moved from test to TFM repo
* tfm_ns_interface.c.example is removed as no longer needed
are provided.
* documentation is updated
Signed-off-by: Bohdan Hunko <Bohdan.Hunko@infineon.com>
Signed-off-by: Chris Brand <chris.brand@cypress.com>
Change-Id: I3e7fd80946bd674cb562ddac8fbc8c7053e30478
diff --git a/interface/include/os_wrapper/common.h b/interface/include/os_wrapper/common.h
new file mode 100644
index 0000000..6494723
--- /dev/null
+++ b/interface/include/os_wrapper/common.h
@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2017-2019, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#ifndef __OS_WRAPPER_COMMON_H__
+#define __OS_WRAPPER_COMMON_H__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdint.h>
+
+#define OS_WRAPPER_SUCCESS (0x0)
+#define OS_WRAPPER_ERROR (0xFFFFFFFFU)
+#define OS_WRAPPER_WAIT_FOREVER (0xFFFFFFFFU)
+#define OS_WRAPPER_DEFAULT_STACK_SIZE (-1)
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __OS_WRAPPER_COMMON_H__ */
diff --git a/interface/include/os_wrapper/mutex.h b/interface/include/os_wrapper/mutex.h
new file mode 100644
index 0000000..ffdf92c
--- /dev/null
+++ b/interface/include/os_wrapper/mutex.h
@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2017-2019, Arm Limited. All rights reserved.
+ * Copyright (c) 2023 Cypress Semiconductor Corporation (an Infineon company)
+ * or an affiliate of Cypress Semiconductor Corporation. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#ifndef __OS_WRAPPER_MUTEX_H__
+#define __OS_WRAPPER_MUTEX_H__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include "os_wrapper/common.h"
+
+/**
+ * \brief Creates a mutex for mutual exclusion of resources
+ *
+ * \return The handle of the created mutex on success or NULL on error
+ */
+void *os_wrapper_mutex_create(void);
+
+/**
+ * \brief Acquires a mutex that is created by \ref os_wrapper_mutex_create()
+ *
+ * \param[in] handle The handle of the mutex to acquire. Should be one of the
+ * handles returned by \ref os_wrapper_mutex_create()
+ * \param[in] timeout The maximum amount of time(in tick periods) for the
+ * thread to wait for the mutex to be available.
+ * If timeout is zero, the function will return immediately.
+ * Setting timeout to \ref OS_WRAPPER_WAIT_FOREVER will
+ * cause the thread to wait indefinitely
+ *
+ * \return \ref OS_WRAPPER_SUCCESS on success or \ref OS_WRAPPER_ERROR on error
+ * or timeout
+ */
+uint32_t os_wrapper_mutex_acquire(void *handle, uint32_t timeout);
+
+/**
+ * \brief Releases the mutex acquired previously
+ *
+
+ * \param[in] handle The handle of the mutex that has been acquired
+ *
+ * \return \ref OS_WRAPPER_SUCCESS on success or \ref OS_WRAPPER_ERROR on error
+ */
+uint32_t os_wrapper_mutex_release(void *handle);
+
+/**
+ * \brief Deletes a mutex that is created by \ref os_wrapper_mutex_create()
+ *
+ * \param[in] handle The handle of the mutex to be deleted
+ *
+ * \return \ref OS_WRAPPER_SUCCESS on success or \ref OS_WRAPPER_ERROR on error
+ */
+uint32_t os_wrapper_mutex_delete(void *handle);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __OS_WRAPPER_MUTEX_H__ */
diff --git a/interface/include/tfm_ns_interface.h b/interface/include/tfm_ns_interface.h
index fa0cc31..6b55fc3 100644
--- a/interface/include/tfm_ns_interface.h
+++ b/interface/include/tfm_ns_interface.h
@@ -1,5 +1,7 @@
/*
* Copyright (c) 2017-2021, Arm Limited. All rights reserved.
+ * Copyright (c) 2023 Cypress Semiconductor Corporation (an Infineon company)
+ * or an affiliate of Cypress Semiconductor Corporation. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*
@@ -24,8 +26,9 @@
* desired veneer function, to be called with the parameters
* described from arg0 to arg3.
*
- * \note NSPE shall implement this dispatcher according to NS specific
- * implementation and actual usage scenario.
+ * \note NSPE can use default implementation of this function or implement
+ * this function according to NS specific implementation and actual
+ * usage scenario.
*
* \param[in] fn Function pointer to the veneer function desired
* \param[in] arg0 Argument 0 of fn
@@ -43,6 +46,19 @@
uint32_t arg0, uint32_t arg1,
uint32_t arg2, uint32_t arg3);
+/**
+ * \brief NS interface initialization function
+ *
+ * \details This function initializes TF-M NS interface.
+ *
+ * \note NSPE can use default implementation of this function or implement
+ * this function according to NS specific implementation and actual
+ * usage scenario.
+ *
+ * \return \ref OS_WRAPPER_SUCCESS on success or \ref OS_WRAPPER_ERROR on error
+ */
+uint32_t tfm_ns_interface_init(void);
+
#ifdef __cplusplus
}
#endif
diff --git a/interface/src/os_wrapper/tfm_ns_interface_bare_metal.c b/interface/src/os_wrapper/tfm_ns_interface_bare_metal.c
new file mode 100644
index 0000000..01da8b8
--- /dev/null
+++ b/interface/src/os_wrapper/tfm_ns_interface_bare_metal.c
@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2023 Cypress Semiconductor Corporation (an Infineon company)
+ * or an affiliate of Cypress Semiconductor Corporation. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+/* This file provides implementation of TF-M NS os wrapper functions for the
+ * bare metal use case.
+ *
+ * \note This implementation does not provide multithread safety, so it
+ * shouldn't be used in RTOS environment.
+ */
+
+#include "tfm_ns_interface.h"
+
+int32_t tfm_ns_interface_dispatch(veneer_fn fn,
+ uint32_t arg0, uint32_t arg1,
+ uint32_t arg2, uint32_t arg3)
+{
+ return fn(arg0, arg1, arg2, arg3);
+}
diff --git a/interface/src/os_wrapper/tfm_ns_interface_rtos.c b/interface/src/os_wrapper/tfm_ns_interface_rtos.c
new file mode 100644
index 0000000..a1f7727
--- /dev/null
+++ b/interface/src/os_wrapper/tfm_ns_interface_rtos.c
@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2017-2021, Arm Limited. All rights reserved.
+ * Copyright (c) 2023 Cypress Semiconductor Corporation (an Infineon company)
+ * or an affiliate of Cypress Semiconductor Corporation. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+/* This file provides implementation of TF-M NS os wrapper functions for the
+ * RTOS use case. This implementation provides multithread safety, so it
+ * can be used in RTOS environment.
+ */
+
+#include <stdint.h>
+
+#include "os_wrapper/mutex.h"
+
+#include "tfm_ns_interface.h"
+
+/**
+ * \brief the ns_lock ID
+ */
+static void *ns_lock_handle = NULL;
+
+int32_t tfm_ns_interface_dispatch(veneer_fn fn,
+ uint32_t arg0, uint32_t arg1,
+ uint32_t arg2, uint32_t arg3)
+{
+ int32_t result;
+
+ /* TFM request protected by NS lock */
+ while (os_wrapper_mutex_acquire(ns_lock_handle, OS_WRAPPER_WAIT_FOREVER)
+ != OS_WRAPPER_SUCCESS) {
+ }
+
+ result = fn(arg0, arg1, arg2, arg3);
+
+ while (os_wrapper_mutex_release(ns_lock_handle) != OS_WRAPPER_SUCCESS) {
+ }
+
+ return result;
+}
+
+uint32_t tfm_ns_interface_init(void)
+{
+ void *handle;
+
+ handle = os_wrapper_mutex_create();
+ if (!handle) {
+ return OS_WRAPPER_ERROR;
+ }
+
+ ns_lock_handle = handle;
+ return OS_WRAPPER_SUCCESS;
+}
diff --git a/interface/src/tfm_ns_interface.c.example b/interface/src/tfm_ns_interface.c.example
deleted file mode 100644
index 520aba2..0000000
--- a/interface/src/tfm_ns_interface.c.example
+++ /dev/null
@@ -1,58 +0,0 @@
-/*
- * Copyright (c) 2017-2021, Arm Limited. All rights reserved.
- *
- * SPDX-License-Identifier: BSD-3-Clause
- *
- */
-
-/*
- * An example to implement tfm_ns_interface_dispatch() in NS RTOS to integrate
- * TF-M interface on Armv8-M TrustZone based platforms.
- *
- * In this example, NS OS calls mutex in tfm_ns_interface_dispatch() to
- * synchronize multiple NS client calls.
- * NS OS pseudo code in this example is not based on any specific RTOS.
- *
- * Please note that this example cannot be built directly.
- */
-
-#include <stdint.h>
-
-/* Include NS RTOS specific mutex declarations */
-#include "mutex.h"
-#include "tfm_ns_interface.h"
-
-/* Static ns lock handle */
-static void *ns_lock_handle = NULL;
-
-/* Initialize the ns lock */
-int32_t ns_interface_lock_init(...)
-{
- /* NS RTOS specific mutex creation/initialization */
- ns_lock_handle = os_mutex_create(...);
- if (ns_lock_handle) {
- return OS_SUCCESS;
- }
-
- return OS_ERROR;
-}
-
-int32_t tfm_ns_interface_dispatch(veneer_fn fn,
- uint32_t arg0, uint32_t arg1,
- uint32_t arg2, uint32_t arg3)
-{
- int32_t result;
-
- /* TF-M request protected by NS lock. */
- while (os_mutex_acquire(ns_lock_handle, ...) != OS_SUCCESS);
-
- result = fn(arg0, arg1, arg2, arg3);
-
- /*
- * Whether to check/handle lock release return code depends on NS RTOS
- * specific implementation and usage scenario.
- */
- os_mutex_release(ns_lock_handle, ...);
-
- return result;
-}