Docs: Add Non-secure client extension integration guide
Add an integration guide for the non-secure client extension (NSCE) module.
Update the existing documents that mentioned the Non-secure client ID
and/or Non-secure context management because these are covered in the
NSCE module now.
Signed-off-by: David Wang <david.wang@arm.com>
Change-Id: Id00d1fe115a6c398668768d00783fa7eb879537b
diff --git a/docs/integration_guide/non-secure_client_extension_integration_guide.rst b/docs/integration_guide/non-secure_client_extension_integration_guide.rst
new file mode 100644
index 0000000..f6df7ca
--- /dev/null
+++ b/docs/integration_guide/non-secure_client_extension_integration_guide.rst
@@ -0,0 +1,271 @@
+#############################################
+Non-secure Client Extension Integration Guide
+#############################################
+
+This document introduces TF-M Non-secure Client Extension (NSCE) and how to
+integrate it with Non-secure Processing Environment (NSPE) RTOS.
+
+****************
+What is NSCE for
+****************
+
+Besides the secure services provided via PSA APIs, there are two interactions
+between TF-M and NSPE RTOS.
+
+- Non-secure context management in TF-M
+
+ When a NS task calls a secure service, a context is maintained in TF-M. If
+ TF-M supports multiple secure service calls, the context needs to be loaded
+ and saved with the corresponding NS task when the RTOS kernel (the kernel)
+ does scheduling.
+
+- Non-secure client ID (NSID) management
+
+ As per PSA Firmware Framework specification, NSID is required for a secure
+ service call from the NSPE. The NSID can be managed by either SPM (the same
+ NSID must be used for all connections) or the NSPE RTOS. For the latter case,
+ the NSPE RTOS must provide the NSID for each connection.
+
+NSCE is implemented to support the interactions above.
+
+- Provide the interface to NSPE RTOS for managing the context in TF-M.
+
+- Provide a mechanism to NSPE RTOS for providing the NSID for each connection.
+
+**********************
+NSCE component diagram
+**********************
+
+.. figure:: nsce-integ.svg
+ :align: center
+
+ Non-secure Client Extension Component Diagram
+
+This diagram shows the components of NSCE.
+
+- NSCE interface: The NSCE API interface to NSPE RTOS.
+
+- NS Client Context Manager: It is the internal component of SPM that is used to
+ manage the NS client context. It is not accessible to NSPE.
+
+******************************
+Group-based context management
+******************************
+
+NSCE introduces a group-based context management for NS clients. The purpose is
+to support diverse use scenarios in the IoT world.
+
+For rich-resource devices, TF-M could assign separate contexts for each
+connection. For resource-constrained devices, TF-M may support very limited
+context slots. Multiple NS connections could share the same context provided
+they have mutual exclusion access to the secure services.
+
+To support this flexibility, a group ID (gid) and a thread ID (tid) are
+specified for the connection of the NS client. NSCE allocates only one context
+for a given group. Threads in the same group share the context.
+
+The gid and tid are specified by NSPE RTOS via NSCE interface.
+
+**************
+NSCE interface
+**************
+
+NSCE defines a set of APIs as the interface for NSPE RTOS to manage the context
+in TF-M. NSID is provided as an input parameter of `tfm_nsce_load_ctx()`.
+
+NSCE APIs are typically called by the kernel and must be called from the
+non-secure handler mode.
+
+.. code-block:: c
+
+ uint32_t tfm_nsce_init(uint32_t ctx_requested)
+
+This function should be called before any other NSCE APIs below to do non-secure
+context intialization in NSCE for the calling NS entity. `ctx_requested` is the
+number of the contexts requested by the NS entity. The number of assigned
+context will be returned. It may be equal to or smaller than the equested
+context number based on the current available resource in TF-M. If
+`ctx_requested` is `0`, then the maximum available context number will be
+assigned and returned. If the initialization is failed, `0` should be returned.
+
+.. Note::
+ As TF-M only supports one context for now, so the return value is always `1`
+ if no error. Currently, it is safe to skip calling `tfm_nsce_init()`.
+ But, for future compatibility, it is recommended to do so.
+
+.. code-block:: c
+
+ uint32_t tfm_nsce_acquire_ctx(uint8_t group_id, uint8_t thread_id)
+
+This function allocates a context for the NS client connection. The `gid` and
+`tid` are the input paramemters. A token will be returned to the NSPE if TF-M
+has an available context slot. Otherwise, `TFM_NS_CLIENT_INVALID_TOKEN` is
+returned.
+It is the responsibility of NSPE RTOS to assign gid and tid for each NS client.
+
+.. code-block:: c
+
+ uint32_t tfm_nsce_release_ctx(uint32_t token)
+
+This function tries to release the context which was retrieved by
+`tfm_nsce_acquire_ctx()`. As the context may be shared with other threads
+within the same group, the context is only freed and back to the available
+context pool after all threads in the same group release the context.
+
+.. code-block:: c
+
+ uint32_t tfm_nsce_load_ctx(uint32_t token, int32_t nsid)
+
+This function should be called when NSPE RTOS schedules in a NS client. `token`
+is returned by `tfm_nsce_acquire_ctx()`. `nsid` is the non-secure client ID
+used for the following PSA service calls.
+
+The assignment of NSID is managed by the NSPE RTOS. It is not required to use
+the same NSID for a NS client when calling this function each time. This allows
+the NS client changing its NSID in the lifecycle. For example, the provisioning
+task may need to switch NSID to provision the keys for different NS clients
+created afterwards.
+
+.. code-block:: c
+
+ uint32_t tfm_nsce_save_ctx(uint32_t token)
+
+This function should be called when NSPE RTOS schedules out a NS client. The
+input parameter `token` is returned by `tfm_nsce_acquire_ctx()`.
+After the context is saved, no secure service call can be made from NSPE until a
+context is loaded via `tfm_nsce_load_ctx()`.
+
+**********************
+NSCE integration guide
+**********************
+
+Enable NSCE in TF-M
+===================
+
+To enable NSCE in TF-M, set the build flag `TFM_NS_MANAGE_NSID` to `ON` (default
+`OFF`).
+
+.. _Support NSCE in an RTOS:
+
+Support NSCE in an RTOS
+=======================
+
+For supporting NSCE in an RTOS, the integrator needs to do the following major
+work:
+
+- Integrate the NSCE API calls into the NS task lifecycle. For example,
+ creating/scheduling/destroying a NS task.
+
+- Manage the assignment for `gid`, `tid` and NSID.
+
+The typical steps are listed below:
+
+- Before programming, the integrator should plan the group assignment for
+ the NS tasks that need to call secure services. If the number of tasks is less
+ than or equal to TF-M non-secure context slots, then different gid can be
+ assigned to each task for taking dedicated context in TF-M.
+ Otherwise, the integrator need to think about grouping the tasks to share the
+ context.
+
+- In the kernel initialization stage, it calls `tfm_nsce_init()` with
+ requested context number to initialize the non-secure context in TF-M. The
+ actual allocated context number will be returned. `0` means initialization
+ failed. The kernel could use different group assignment sets according to the
+ context number allocated to it. TF-M only supports one context for now.
+
+- The kernel calls `tfm_nsce_acquire_ctx()` when creating a new task. This
+ should be done before the new task calls any secure service. A valid token
+ returned should be saved as part of the task context in NSPE RTOS.
+
+- When the kernel schedules in a task with a valid `token` associated,
+ `tfm_nsce_load_ctx()` should be called before resuming the execution of that
+ task. The NSID is specified by the kernel through the `nsid` parameter.
+ The mapping between NSID and task is managed by the kernel.
+ `tfm_nsce_load_ctx()` can be called multiple times without calling
+ `tfm_nsce_save_ctx()` for switching the NSID for the same task (same tid and
+ gid).
+
+- `tfm_nsce_save_ctx()` should be called if the current task has a valid
+ `token` before being switched to another task. Calling `tfm_nsce_load_ctx()`
+ for another task before saving the current context may result in NS context
+ lost in TF-M for the running task.
+
+- When the task is terminated, destroyed or crashed, the kernel should call
+ `tfm_nsce_release_ctx` to make sure the associated resource is back to the
+ pool in TF-M.
+
+Integration example
+===================
+
+.. figure:: nsce-rtos-example.svg
+ :align: center
+
+ RTOS/NSCE integration example
+
+This is the software module diagram of a typical RTOS/NSCE integration example.
+
+- Built-in Secure Context Manager: An RTOS may have an existing built-in secure
+ context manager with a group of secure context management APIs defined. Let's
+ take RTX which uses `Armv8-M TrustZone APIs <https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html>`_
+ as the example.
+
+.. Note::
+ RTOS may define the NS task context in the secure side as "secure context". It
+ is the same thing as the "non-secure context" (context for a secure service
+ call from NS client) from TF-M's point of view.
+
+- Shim Layer/Secure Context Manager: If the RTOS has a "Built-in Secure Context
+ Manager", then a shim layer should be provided to translate the built-in API
+ calls into the NSCE API calls. A reference shim layer for RTX TrustZone APIs
+ is `here <https://review.trustedfirmware.org/c/TF-M/tf-m-tests/+/11291>`_.
+
+ If the RTOS has no existing one, then a "Secure Context Manager" should be
+ implemented based on the NSCE APIs. You can refer to the shim layer example
+ above for the implementation. The timing of calling NSCE APIs in the kernel is
+ introduced in the :ref:`Support NSCE in an RTOS` section above.
+
+- NSID Manager: If NSPE RTOS manages the NSID, then this module is used by the
+ secure context manager or shim layer to manage the NSID assignment for the
+ NS tasks. The assignment is implementation defined. A `task name based NSID
+ manager <https://review.trustedfirmware.org/c/TF-M/tf-m-tests/+/11290>`_ is \
+ provided as a reference.
+
+Integration notes
+=================
+
+- `gid`: It is a `uint8_t` value (valid range is 0 - 255). So, maximum 256
+ groups (NSCE context slots) are supported by the NSCE interface.
+ TF-M only supports single context for now. So, it is recommended to use
+ single group ID at this stage.
+
+- `tid`: It is a `uint8_t` value (valid range is 0 - 255). Thread ID is used to
+ identify a NS client within a given group. `tid` has no special meaning for
+ TF-M. So, usually the kernel only needs to ensure a NS task has a unique `tid`
+ within a group.
+
+- `gid` and `tid` management: It is the responsibility of NSPE RTOS to manage
+ the assignment of `gid` and `tid`. Based on the explaination above, the `gid`
+ could be assigned as a constant value. And, the `tid` can be increased
+ globally when calling `tfm_nsce_acquire_ctx()` for a new task. Just notice
+ `tid` may overflow.
+
+- NSID management: It is the responsibility of NSPE RTOS to manage the
+ assignment of the NSID for each task. It is highly recommended that a NS
+ client uses the same NSID following a reboot or update. The binding of a NS
+ client to a specific NSID will ensure the correct access to the assets. For
+ example, the data saved in the protected storage.
+
+- Integrate with the existing secure context management APIs of NSPE RTOS: The
+ NSCE APIs are designed to be compatible with most known existing secure
+ context management APIs. A shim layer is needed to translate the API calls.
+ See the integration example above.
+
+- `tfm_nsce_acquire_ctx()` must be called before calling
+ `tfm_nsce_load_ctx()`, `tfm_nsce_save_ctx()` or `tfm_nsce_release_ctx()`.
+
+- `tfm_nsce_release_ctx()` can be called without calling `tfm_nsce_save_ctx()`
+ ahead.
+
+--------------
+
+*Copyright (c) 2021, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/nsce-integ.svg b/docs/integration_guide/nsce-integ.svg
new file mode 100644
index 0000000..05ee85a
--- /dev/null
+++ b/docs/integration_guide/nsce-integ.svg
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="685px" height="362px" viewBox="-0.5 -0.5 685 362" content="<mxfile host="Electron" modified="2021-09-22T02:36:34.394Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/15.2.7 Chrome/93.0.4577.63 Electron/14.0.1 Safari/537.36" etag="kxahZtW3ipt5d8RTBiDv" version="15.2.7" type="device"><diagram id="M-t0xCEkBnu72X0zHlki" name="Page-1">5Vltd5owFP41fmwPEIL4sVLXbT11rnan28cIQXIaiCfEqvv1SyQgb62tk7q1+kHy3OQG7nNfcrEHvHh9xdEiumEBpj3LCNY9cNmzLNMArvxRyCZD+gbIgDkngZ60A6bkN85XanRJApxWJgrGqCCLKuizJMG+qGCIc7aqTgsZre66QHPcAKY+ok30ngQiylAXGjv8MybzKN/ZNLQkRvlkDaQRCtiqBIFRD3icMZFdxWsPU2W83C7Zuk9PSIsb4zgRL1kw9O7dK0eMb/3vY8e7/nrGoX8GMy2PiC71A/csh0p9w0jy5MzV1XRyk4NS+w7XjyU2ua04WyYBVtuZUryKiMDTBfKVdCW9QykVMdXikFDqMcr4di0IEHZDX+Kp4OwBlySO7+JZKCWIknkiMV8+MJbC4SPmgkiqLrRgxoRgcXFnSozXT1rLLDiQzotZjAXfyCl6AXA1bdpvoaPHq50XgJzrqOwBOd9Ie9680L0jR15ofl7BldnCVY0BnAQXyunlKGGJBIcBSqOCkpL5s6U4aHj/XgOVDABbnj/HOKZIkMeq+jab6B0mjMiNC/ubdtX8oGbVlC25j/WistfX9DiDPYoE4nMsGoq2DBVPfThpVoO08VSO71D6cNT4CV0f+63xM3OhLUk5SlQUzq2taVvNqCjmlL3C6SoowAsS2O3dN2Xza8wTVZ26TmVhGFrtVATOzIFOx5mrvz9xWW0UdZe47JYY8EYS+aISeajMajkoVlZNZunieT6M1/MB1be1tGw/agVLRAnPPsehwzZqfLgtIdNWSGBXdDgfqY4AUDV//9BCUlcEBm9bSPrthcSjBG9v05MujNfq6gYl8lTK31EMFTnsuRgy3zKG3P0xJM/7C3UZUrzWwTQsxZVPUZoSv2p1Kc+7jEE21B0RPDfBfxBtsJbsHAMeFm11xhuKOo62wWn4lSzyzU8dodvBLzU4h/nwcl0WXm706KV+IZvnrd32FetT+Y81qNNunx/oQQDuVdWxD+UJqe1sauUnz/F0MiofSa0nj6Tb7F7xpmou1oW6nLg1tLdxjkkQqG1ai0K1bBwhm5u12AYubGRzu8XHumus2zrrOlEfjydo/ms8NZvpgic75+NHsuDkkVA8l7YoEWa/f8JqJ9SiGJ+Mr2ea84KOyUdlq/YqBdqnZqvZpk+xv+SyOTcmSFpKEJY06Pird74Qu4Hd1lS41gxsm4oj2NmuvRDp8p2VHO5e6GfniN3fImD0Bw==</diagram></mxfile>" style="background-color: rgb(255, 255, 255);"><defs/><g><rect x="369" y="190" width="300" height="120" rx="18" ry="18" fill="#dae8fc" stroke="#6c8ebf" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-end; justify-content: unsafe center; width: 298px; height: 1px; padding-top: 307px; margin-left: 370px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;"><h3>SPM</h3></div></div></div></foreignObject><text x="519" y="307" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">SPM</text></switch></g><path d="M 3 160 L 683 160" fill="none" stroke="#000000" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="stroke"/><rect x="109" y="50" width="120" height="60" rx="9" ry="9" fill="#f8cecc" stroke="#b85450" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 80px; margin-left: 110px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">NS Task</div></div></div></foreignObject><text x="169" y="84" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">NS Task</text></switch></g><rect x="59" y="190" width="220" height="120" rx="18" ry="18" fill="#fff2cc" stroke="#d6b656" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-end; justify-content: unsafe center; width: 218px; height: 1px; padding-top: 307px; margin-left: 60px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;"><h3>RTOS Kernel</h3></div></div></div></foreignObject><text x="169" y="307" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">RTOS Kernel</text></switch></g><rect x="389" y="210" width="100" height="50" fill="#f5f5f5" stroke="#666666" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 98px; height: 1px; padding-top: 235px; margin-left: 390px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(51, 51, 51); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">NSCE Interface </div></div></div></foreignObject><text x="439" y="239" fill="#333333" font-family="Helvetica" font-size="12px" text-anchor="middle">NSCE Interface </text></switch></g><path d="M 319 360 L 319 20" fill="none" stroke="#000000" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="stroke"/><rect x="549" y="210" width="110" height="50" fill="#f5f5f5" stroke="#666666" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 108px; height: 1px; padding-top: 235px; margin-left: 550px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(51, 51, 51); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">NS Client Context Manager</div></div></div></foreignObject><text x="604" y="239" fill="#333333" font-family="Helvetica" font-size="12px" text-anchor="middle">NS Client Context...</text></switch></g><path d="M 489.5 240 L 489.5 230 L 532.11 230 L 532.11 225 L 548.5 235 L 532.11 245 L 532.11 240 Z" fill="none" stroke="#000000" stroke-linejoin="round" stroke-miterlimit="10" pointer-events="all"/><path d="M 279.48 239.5 L 279.52 229.5 L 372.13 229.92 L 372.16 224.92 L 388.5 235 L 372.06 244.92 L 372.09 239.92 Z" fill="none" stroke="#000000" stroke-linejoin="round" stroke-miterlimit="10" pointer-events="all"/><rect x="149" y="15" width="40" height="20" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 38px; height: 1px; padding-top: 25px; margin-left: 150px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;"><h2>NSPE</h2></div></div></div></foreignObject><text x="169" y="29" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">NSPE</text></switch></g><rect x="499" y="15" width="40" height="20" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 38px; height: 1px; padding-top: 25px; margin-left: 500px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;"><h2>SPE</h2></div></div></div></foreignObject><text x="519" y="29" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">SPE</text></switch></g><rect x="19" y="130" width="40" height="20" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 38px; height: 1px; padding-top: 140px; margin-left: 20px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;"><h4>Unprivileged</h4></div></div></div></foreignObject><text x="39" y="144" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Unpriv...</text></switch></g><rect x="9" y="170" width="40" height="20" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 38px; height: 1px; padding-top: 180px; margin-left: 10px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;"><h4>Privileged</h4></div></div></div></foreignObject><text x="29" y="184" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Privil...</text></switch></g><rect x="459" y="50" width="120" height="60" rx="9" ry="9" fill="#d5e8d4" stroke="#82b366" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 80px; margin-left: 460px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Secure Partition</div></div></div></foreignObject><text x="519" y="84" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Secure Partition</text></switch></g></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://www.diagrams.net/doc/faq/svg-export-text-problems" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Viewer does not support full SVG 1.1</text></a></switch></svg>
\ No newline at end of file
diff --git a/docs/integration_guide/nsce-rtos-example.svg b/docs/integration_guide/nsce-rtos-example.svg
new file mode 100644
index 0000000..906f997
--- /dev/null
+++ b/docs/integration_guide/nsce-rtos-example.svg
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Do not edit this file with editors other than diagrams.net -->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="643px" height="352px" viewBox="-0.5 -0.5 643 352" content="<mxfile host="Electron" modified="2021-09-28T10:53:25.672Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/15.3.5 Chrome/94.0.4606.51 Electron/15.0.0 Safari/537.36" etag="FEoO8k56fKFBrY6cFsqN" version="15.3.5" type="device"><diagram id="M-t0xCEkBnu72X0zHlki" name="Page-1">5Vldc5s6EP01fkwHkJDhsfZN3a/4unU6nembDAI0AeQRcuzcX1/JCMyHnLq52GkT5yFwVhLmnN3VrjwC02w343id3LCQpCPHCncj8M/IcWzLgfKfQh5KxPX9Eog5DfWgA7Ck/5FqpkY3NCRFa6BgLBV03QYDluckEC0Mc8627WERS9tPXeOY9IBlgNM++p2GIilRz7UO+HtC46R6sm1pS4arwRooEhyybQMC1yMw5YyJ8irbTUmqyKt4Kee9O2KtvxgnuThlwmT63ZshMf8afJmj6aePV9wNrtxylXucbvQLjxyUyvUmCZBXsbpaLm4qUK5+wPVriYeKK842eUjU42xp3iZUkOUaB8q6ld6hFhVZqs0RTdMpSxnfzwUhJl4USLwQnN2RhgUFHllF0oJTGucSC+QLE2mc3BMuqJTqrTasmBAsq79ZkxrNlppBdg1IUzUjLCOCP8gh2upWUyq/RVrG7cELbF9jSdMDqoFYe15cr30QR15ofX5DK9ugVUcBkodvldPLu5zlEpyEuEhqSRr0H6WIhK2A6BPUIMA1vH+FcZJiQe/bYWTiRD9hwaj8JjX/vtumH3RYLdiGB0RPanp9Z50xsB9fSGAeE9FbaK9Q/dZPF83piTZfyvtbXNwNGj+RF5DAGD8rz4VSlEGiovZ4zSYEhqhwDF5xtqAAJySwr7f/Ks4/EZ6r3encqSyKIscsRYhWyEVnzly23dbIlLmAKXLPl7mgIQim1xL5oDJ5pHh1EM4UrfmqWD8uiPX7grjqz7i37D9qBstFAy8/A+0kqJ2BEAT9mLEMesBzyYFe00YC/Tb9Y+eJO0l3IeBddiepwtqU6pwqkc2Xi+tmhnOOZjjpvaKtZDs6tOzNUNLQL+uwjIaheowxTNuBPEB8ObCri9uLL2jwr64fDFenmQq1rlCvTye3Fz/PrVO/Nqt1gpUe3/I1p/c0JbHkoiEYfPmC2RZqFxJWv5C4rGCPFHu1HovXK1en04HPLVe/7FuSYMNlsWctsKRKUJb39Phfhwgu8UJoKvQ8ZwX2hd4QicxtE33RJgi8T7az4nOIfsT2TKwn+Y8NNpwMzJcf5D/rBuc4lr45ZDVNbEnz2ESyj8YAH0juMWrg/bg3w27V3N8tzlY1G0nu7xbLhGYS+YwfFMXvaueeymZCZZW/mX/gWB3+T3TySqfB+T+haykSvFaXUUp2un2ZNDqZIMVFQYNutpepSJ8727CcoG/dN95+RNkgEE7lixCuhKJ5LO2eNOqi32ysuLKtct3qBNk+NE6dLukkiS7UOHUjEHWUPbVx6jXA3YWGa5yMjuO9MMcp7ogIEp07Wm15mRGqwcB0NEXQkaOpsb+yrL/ALYEH3rTPhpEFn+aYhqUgvKhr+i/MNf9457H9YXJaXWY8U04znDFMNjQVV1RW1NaFKpETsskv0tMQhYrd6VIR7BcqYJhCUd4efq8tpTz86g2ufwI=</diagram></mxfile>" style="background-color: rgb(255, 255, 255);"><defs/><g><rect x="431" y="190" width="190" height="160" rx="24" ry="24" fill="#dae8fc" stroke="#6c8ebf" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-end; justify-content: unsafe center; width: 188px; height: 1px; padding-top: 347px; margin-left: 432px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;"><h3>SPM</h3></div></div></div></foreignObject><text x="526" y="347" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">SPM</text></switch></g><path d="M 5 160 L 641 160" fill="none" stroke="#000000" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="stroke"/><rect x="100" y="60" width="120" height="60" rx="9" ry="9" fill="#f8cecc" stroke="#b85450" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 90px; margin-left: 101px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">NS Task</div></div></div></foreignObject><text x="160" y="94" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">NS Task</text></switch></g><rect x="20" y="190" width="350" height="160" rx="24" ry="24" fill="#fff2cc" stroke="#d6b656" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-end; justify-content: unsafe center; width: 348px; height: 1px; padding-top: 347px; margin-left: 21px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;"><h3>RTOS Kernel</h3></div></div></div></foreignObject><text x="195" y="347" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">RTOS Kernel</text></switch></g><rect x="471" y="273" width="100" height="40" fill="#f5f5f5" stroke="#666666" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 98px; height: 1px; padding-top: 293px; margin-left: 472px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(51, 51, 51); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">NSCE Interface </div></div></div></foreignObject><text x="521" y="297" fill="#333333" font-family="Helvetica" font-size="12px" text-anchor="middle">NSCE Interface </text></switch></g><path d="M 401 350 L 401 10" fill="none" stroke="#000000" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="stroke"/><rect x="151" y="15" width="40" height="20" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 38px; height: 1px; padding-top: 25px; margin-left: 152px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;"><h2>NSPE</h2></div></div></div></foreignObject><text x="171" y="29" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">NSPE</text></switch></g><rect x="501" y="15" width="40" height="20" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 38px; height: 1px; padding-top: 25px; margin-left: 502px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;"><h2>SPE</h2></div></div></div></foreignObject><text x="521" y="29" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">SPE</text></switch></g><rect x="16" y="130" width="40" height="20" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 38px; height: 1px; padding-top: 140px; margin-left: 17px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;"><h4>Unprivileged</h4></div></div></div></foreignObject><text x="36" y="144" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Unpriv...</text></switch></g><rect x="11" y="170" width="40" height="20" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 38px; height: 1px; padding-top: 180px; margin-left: 12px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;"><h4>Privileged</h4></div></div></div></foreignObject><text x="31" y="184" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Privil...</text></switch></g><rect x="461" y="60" width="120" height="60" rx="9" ry="9" fill="#d5e8d4" stroke="#82b366" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 90px; margin-left: 462px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Secure Partition</div></div></div></foreignObject><text x="521" y="94" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Secure Partition</text></switch></g><rect x="51" y="275" width="100" height="40" fill="#e1d5e7" stroke="#9673a6" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 98px; height: 1px; padding-top: 295px; margin-left: 52px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">NSID Manager</div></div></div></foreignObject><text x="101" y="299" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">NSID Manager</text></switch></g><rect x="230" y="270" width="120" height="45" fill="#e1d5e7" stroke="#9673a6" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 293px; margin-left: 231px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Shim Layer/Secure Context Manager</div></div></div></foreignObject><text x="290" y="296" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Shim Layer/Secure Co...</text></switch></g><path d="M 351.5 300 L 351.5 290 L 452.07 290 L 452.07 284 L 470.5 295 L 452.07 306 L 452.07 300 Z" fill="none" stroke="#000000" stroke-linejoin="round" stroke-miterlimit="10" pointer-events="all"/><path d="M 287.5 235.5 L 299.5 235.5 L 299.5 252.07 L 306.5 252.07 L 293.5 272.5 L 280.5 252.07 L 287.5 252.07 Z" fill="#ffe6cc" stroke="#d79b00" stroke-width="3" stroke-linejoin="round" stroke-miterlimit="10" stroke-dasharray="9 9" pointer-events="all"/><path d="M 228.5 290 L 228.5 300 L 168.93 300 L 168.93 306 L 150.5 295 L 168.93 284 L 168.93 290 Z" fill="none" stroke="#000000" stroke-linejoin="round" stroke-miterlimit="10" pointer-events="all"/><rect x="226" y="194" width="130" height="40" fill="#ffe6cc" stroke="#d79b00" stroke-width="3" stroke-dasharray="9 9" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 128px; height: 1px; padding-top: 214px; margin-left: 227px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Built-in Secure Context Manager</div></div></div></foreignObject><text x="291" y="218" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Built-in Secure Conte...</text></switch></g></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://www.diagrams.net/doc/faq/svg-export-text-problems" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Viewer does not support full SVG 1.1</text></a></switch></svg>
\ No newline at end of file
diff --git a/docs/integration_guide/os_migration_guide_armv8m.rst b/docs/integration_guide/os_migration_guide_armv8m.rst
index a3b5806..4ef76ae 100644
--- a/docs/integration_guide/os_migration_guide_armv8m.rst
+++ b/docs/integration_guide/os_migration_guide_armv8m.rst
@@ -17,25 +17,8 @@
- If the OS manipulates directly the Link Register, the default Link Register
value used in Handler mode transitions needs to be differentiated between
Secure and Non Secure builds, i.e. ``0xFD`` and ``0xBC``, respectively.
-- If the OS supports the Thread Context Management for Armv8-M TrustZone APIs,
- as described
- `here <https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html>`__
- , and would like to use the non-secure client identification feature of TF-M,
- then it also have to use the
- ``enum tfm_status_e tfm_register_client_id (int32_t ns_client_id)``
- API function provided by TF-M, as described in
- :doc:`NS client identification documentation </docs/technical_references/design_docs/tfm_ns_client_identification>`.
-- if the OS doesn't support the API mentioned above, it should set
- ``TFM_NS_CLIENT_IDENTIFICATION`` to ``OFF`` in the cmake system.
-- .. Note::
-
- This is NOT REQUIRED when the Non Secure OS build is meant
- to be integrated with TF-M running in Secure world.
-
- If generic function calls into Secure world have to be supported in Non Secure
- builds, integrate an API for secure stack memory management (e.g. the
- TrustZone API for secure stack memory management described in
- ``tz_context.h``).
+- If the OS manages the non-secure client identification, pelase check the
+ :doc:`Non-secure Client Extension Integration Guide </docs/integration_guide/non-secure_client_extension_integration_guide>`.
--------------
diff --git a/docs/integration_guide/services/tfm_ps_integration_guide.rst b/docs/integration_guide/services/tfm_ps_integration_guide.rst
index 50c83a4..c5bb8ac 100644
--- a/docs/integration_guide/services/tfm_ps_integration_guide.rst
+++ b/docs/integration_guide/services/tfm_ps_integration_guide.rst
@@ -293,7 +293,7 @@
processing environment. It provides a dedicated API to retrieve the client ID
which performs the service request.
-:doc:`NS client identification documentation </docs/technical_references/design_docs/tfm_ns_client_identification>`
+:doc:`Non-secure Client Extension Integration Guide </docs/integration_guide/non-secure_client_extension_integration_guide>`
provides further details on how client identification works.
PS service uses that TF-M core API to retrieve the client ID and associate it
diff --git a/docs/integration_guide/tfm_integration_guide.rst b/docs/integration_guide/tfm_integration_guide.rst
index f0f2a1e..52156c46 100644
--- a/docs/integration_guide/tfm_integration_guide.rst
+++ b/docs/integration_guide/tfm_integration_guide.rst
@@ -134,8 +134,13 @@
NS client Identification
========================
-See
-:doc:`ns client identification documentation </docs/technical_references/design_docs/tfm_ns_client_identification>`.
+
+The NS client identification (NSID) is specified by either SPM or NSPE RTOS.
+If SPM manages the NSID (default option), then the same NSID (-1) will be used
+for all connections from NS clients.
+For the case that NSPE RTOS manages the NSID and/or different NSIDs should be
+used for different NS clients. See
+:doc:`Non-secure Client Extension Integration Guide </docs/integration_guide/non-secure_client_extension_integration_guide>`.
*********************
Non-secure interrupts
