From 48002ffc39049714d5bc5d4ffa051cf4307c198b Mon Sep 17 00:00:00 2001
From: deepikabhavnani <deepika.bhavnani@arm.com>
Date: Wed, 4 Apr 2018 12:28:57 -0500
Subject: [PATCH] Added description of tz_module and MBED_TZ_DEFAULT_ACCESS

---
 rtos/Thread.cpp |  4 ++++
 rtos/Thread.h   | 19 +++++++++++--------
 2 files changed, 15 insertions(+), 8 deletions(-)

diff --git a/rtos/Thread.cpp b/rtos/Thread.cpp
index d122f4ea92..f43d39e3ec 100644
--- a/rtos/Thread.cpp
+++ b/rtos/Thread.cpp
@@ -43,6 +43,10 @@ extern "C" void thread_terminate_hook(osThreadId_t id)
 
 namespace rtos {
 
+#ifndef MBED_TZ_DEFAULT_ACCESS
+#define MBED_TZ_DEFAULT_ACCESS   0
+#endif
+
 void Thread::constructor(uint32_t tz_module, osPriority priority,
         uint32_t stack_size, unsigned char *stack_mem, const char *name) {
 
diff --git a/rtos/Thread.h b/rtos/Thread.h
index a41367d517..43d9775c1d 100644
--- a/rtos/Thread.h
+++ b/rtos/Thread.h
@@ -72,16 +72,16 @@ namespace rtos {
  * Memory considerations: The thread control structures will be created on current thread's stack, both for the mbed OS
  * and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
  * Additionally the stack memory for this thread will be allocated on the heap, if it wasn't supplied to the constructor.
+ *
+ * @note
+ * MBED_TZ_DEFAULT_ACCESS (default:0) flag can be used to change the default access of all user threads in non-secure mode.
+ * MBED_TZ_DEFAULT_ACCESS set to 1, means all non-secure user threads have access to call secure functions.
+ * MBED_TZ_DEFAULT_ACCESS set to 0, means none of the non-secure user thread have access to call secure functions,
+ * to give access to particular thread used overloaded constructor with `tz_module` as argument during thread creation.
+ *
+ * MBED_TZ_DEFAULT_ACCESS is target specific define, should be set in targets.json file for Cortex-M23/M33 devices.
  */
 
-/* This flag can be used to change the default access of all threads in non-secure mode.
-   MBED_TZ_DEFAULT_ACCESS set to 1, means all non-secure threads have access to call secure functions.
-   MBED_TZ_DEFAULT_ACCESS is target specific define, should be set in targets.json file for Cortex-M23/M33 devices.
-*/
-#ifndef MBED_TZ_DEFAULT_ACCESS
-#define MBED_TZ_DEFAULT_ACCESS 0
-#endif
-
 class Thread : private mbed::NonCopyable<Thread> {
 public:
     /** Allocate a new thread without starting execution
@@ -102,6 +102,9 @@ public:
 
     /** Allocate a new thread without starting execution
       @param   tz_module      trustzone thread identifier (osThreadAttr_t::tz_module)
+                              Context of RTOS threads in non-secure state must be saved when calling secure functions.
+                              tz_module ID is used to allocate context memory for threads, and it can be safely set to zero for
+                              threads not using secure calls at all. See "TrustZone RTOS Context Management" for more details.
       @param   priority       initial priority of the thread function. (default: osPriorityNormal).
       @param   stack_size     stack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE).
       @param   stack_mem      pointer to the stack area to be used by this thread (default: NULL).