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/cmake/install.cmake b/cmake/install.cmake
index 561af35..f445df8 100644
--- a/cmake/install.cmake
+++ b/cmake/install.cmake
@@ -1,6 +1,6 @@
#-------------------------------------------------------------------------------
# Copyright (c) 2020-2023, Arm Limited. All rights reserved.
-# Copyright (c) 2022 Cypress Semiconductor Corporation (an Infineon company)
+# Copyright (c) 2022-2023 Cypress Semiconductor Corporation (an Infineon company)
# or an affiliate of Cypress Semiconductor Corporation. All rights reserved.
#
# SPDX-License-Identifier: BSD-3-Clause
@@ -128,8 +128,11 @@
DESTINATION ${INSTALL_INTERFACE_SRC_DIR})
endif()
+ install(DIRECTORY ${INTERFACE_INC_DIR}/os_wrapper
+ DESTINATION ${INSTALL_INTERFACE_INC_DIR})
+
if (CONFIG_TFM_USE_TRUSTZONE)
- install(FILES ${INTERFACE_SRC_DIR}/tfm_ns_interface.c.example
+ install(DIRECTORY ${INTERFACE_SRC_DIR}/os_wrapper
DESTINATION ${INSTALL_INTERFACE_SRC_DIR})
endif()
diff --git a/docs/integration_guide/index.rst b/docs/integration_guide/index.rst
index 75fbbac..e96445c 100644
--- a/docs/integration_guide/index.rst
+++ b/docs/integration_guide/index.rst
@@ -64,14 +64,21 @@
TF-M also exports a reference implementation of PSA APIs for NS clients in the
``<install_dir>/interface/src``.
-On Armv8-M TrustZone based platforms, NS OS shall implement interface API
-``tfm_ns_interface_dispatch()`` to integrate with TF-M implementation of PSA
-APIs. See ``interface/include/tfm_ns_interface.h`` for the detailed declaration
-of ``tfm_ns_interface_dispatch()``.
-TF-M provides an example of ``tfm_ns_interface_dispatch()`` implementation on
-Armv8-M TrustZone based platforms. In this example, NS OS calls mutex in
-``tfm_ns_interface_dispatch()`` to synchronize multiple NS client calls to TF-M.
-See ``interface/src/tfm_ns_interface.c.example`` for more details.
+On Armv8-M TrustZone based platforms, NS OS uses ``tfm_ns_interface_dispatch()``
+to integrate with TF-M implementation of PSA APIs. TF-M provides a reference
+implementation of this function for RTOS and bare metal use cases.
+RTOS implementation of ``tfm_ns_interface_dispatch()`` (provided in
+``interface\src\os_wrapper\tfm_ns_interface_rtos.c``) uses mutex to provide
+multithread safety. Mutex wrapper functions defined in
+``interface/include/os_wrapper/mutex.h`` are expected to be provided by NS RTOS.
+When reference RTOS implementation of dispatch function is used NS application
+should call ``tfm_ns_interface_init()`` function before first PSA API call.
+Bare metal implementation ``tfm_ns_interface_dispatch()`` (provided in
+``interface\src\os_wrapper\tfm_ns_interface_bare_metal.c``) does not
+provide multithread safety and does not require implementation of mutex
+interface.
+If needed, instead of using reference implementation, NS application may provide
+its own implementation of ``tfm_ns_interface_dispatch()`` function.
TF-M provides a reference implementation of NS mailbox on multi-core platforms,
under folder ``interface/src/multi_core``.
@@ -137,3 +144,5 @@
--------------
*Copyright (c) 2017-2022, Arm Limited. All rights reserved.*
+*Copyright (c) 2023 Cypress Semiconductor Corporation (an Infineon company)
+or an affiliate of Cypress Semiconductor Corporation. All rights reserved.*
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;
-}
diff --git a/lib/ext/tf-m-tests/repo_config_default.cmake b/lib/ext/tf-m-tests/repo_config_default.cmake
index 94a98fe..bfeb3ad 100644
--- a/lib/ext/tf-m-tests/repo_config_default.cmake
+++ b/lib/ext/tf-m-tests/repo_config_default.cmake
@@ -10,5 +10,5 @@
# Default configs of tf-m-tests repo
set(TFM_TEST_REPO_PATH "DOWNLOAD" CACHE PATH "Path to TFM-TEST repo (or DOWNLOAD to fetch automatically")
-set(TFM_TEST_REPO_VERSION "40096730" CACHE STRING "The version of tf-m-tests to use")
+set(TFM_TEST_REPO_VERSION "75ee82ba" CACHE STRING "The version of tf-m-tests to use")
set(CMSIS_5_PATH "DOWNLOAD" CACHE PATH "Path to CMSIS_5 (or DOWNLOAD to fetch automatically")