Docs: Move design documents from wiki to source
Moving design documents from Phabricator
(https://developer.trustedfirmware.org/w/tf_m/design/) to the source
tree.
The documents moved in this commit are:
- Code Generation With Jinja2
- Non-Secure Interrupt Handling
- Non-Secure Client Management
- Secure Partition Interrupt Handling
- Uniform Secure Service Signature
Change-Id: I442f1c63633f493e3f0d1b9ffc42211f584a6ecc
Signed-off-by: Mate Toth-Pal <mate.toth-pal@arm.com>
diff --git a/docs/design_documents/tfm_code_generation_with_jinja2.rst b/docs/design_documents/tfm_code_generation_with_jinja2.rst
new file mode 100644
index 0000000..8a0317d
--- /dev/null
+++ b/docs/design_documents/tfm_code_generation_with_jinja2.rst
@@ -0,0 +1,83 @@
+###########################
+Code Generation With Jinja2
+###########################
+
+:Author: Mate Toth-Pal
+:Organization: Arm Limited
+:Contact: Mate Toth-Pal <mate.toth-pal@arm.com>
+:Status: Accepted
+
+***************************************
+Generating files from templates in TF-M
+***************************************
+
+Some of the files in TF-M are generated from template files. The files to be
+generated are listed in ``tools/tfm_generated_file_list.yaml``. For each
+generated file ``<path_to_file>/<filename>`` the template file is
+``<path_to_file>/<filename>.template``. The templates are populated with
+partition information from the partition manifests. The manifests to be used for
+the generation are listed in ``tools/tfm_manifest_list.yaml``.
+
+****************************************
+Custom generator script - Current method
+****************************************
+
+``tools/tfm_parse_manifest_list.py`` Python script is used to generate files
+from the templates. This script calls the ``tools/generate_from_template.py`` to
+parse the template files, and uses ``tools/keyword_substitution.py`` to
+substitute the keychains with actual values from the manifest files.
+
+*************************************
+Use Jinja2 template engine - proposal
+*************************************
+
+The proposal is to eliminate the template parser and substituter scripts, and
+call the Jinja2 template engine library from
+``tools/tfm_parse_manifest_list.py`` to do the substitution.
+
+More information on jinja2: http://jinja.pocoo.org/
+
+Changes needed:
+===============
+
+- ``tools/tfm_parse_manifest_list.py`` have to be modified to call the Jinja2
+ library instead of the custom scripts. The data structure required by the
+ library is very similar to the one required by the current scripts.
+- template files needs to be rewritten to the Jinja syntax: The control
+ characters to be replaced (like ``@!`` -> ``{%``) and ``for`` statements to be
+ added to iterate over the substitutions.
+
+Improvements over the current solution
+======================================
+
+- Compatible with Python 2.7 and Python 3, while current solution only supports
+ Python 2.7
+- More advanced functionality: direct control over the list of items for a
+ keychain, meta information on that list (like length)
+- Well documented (see website)
+- Jinja2 is free and open-source software, BSD licensed, just like TF-M. It is a
+ well established software in contrast with the current proprietary solution.
+
+*******
+Example
+*******
+
+Below code snippet enumerates the secure function IDs:
+
+.. code-block::
+
+ {% for manifest in manifests %}
+ {% if manifest.attr.conditional %}
+ #ifdef {{manifest.attr.conditional}}
+ {% endif %}
+ /******** {{manifest.manifest.tfm_partition_name}} ********/
+ {% for sec_func in manifest.manifest.secure_functions %}
+ {{'{'}}{{sec_func.tfm_symbol}}, {{sec_func.sfid}}{{'}'}},
+ {% endfor %}
+ {% if manifest.attr.conditional %}
+ #endif /* {{manifest.attr.conditional}} */
+ {% endif %}
+
+ {% endfor %}
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/tfm_non-secure_interrupt_handling.rst b/docs/design_documents/tfm_non-secure_interrupt_handling.rst
new file mode 100644
index 0000000..fd10fb1
--- /dev/null
+++ b/docs/design_documents/tfm_non-secure_interrupt_handling.rst
@@ -0,0 +1,324 @@
+#############################
+Non-Secure Interrupt Handling
+#############################
+
+:Author: Mate Toth-Pal
+:Organization: Arm Limited
+:Contact: Mate Toth-Pal <mate.toth-pal@arm.com>
+:Status: Accepted
+
+
+*****
+Terms
+*****
+
+========== ================================================
+Term Meaning
+========== ================================================
+AIRCR Application Interrupt and Reset Control Register
+AIRCR.PRIS PRIoritize Secure exceptions
+ISR Interrupt Service Routine
+NS Non-Secure
+NSPM Non-Secure Partition Manager
+SAU Security Attribution Unit
+SPM Secure Partition Manager
+TF-M Trusted Firmware-M
+========== ================================================
+
+************
+Introduction
+************
+
+In the current design it is possible to use Non-secure interrupts, however the
+Non-secure interrupts cannot pre-empt Secure service execution. TF-M core
+achieves this by making the following configurations:
+
+1. ``AIRCR.PRIS`` is set to 1 during TF-M core initialisation. This
+ de-prioritizes Non-secure exceptions compared to Secure exceptions, so that
+ they cannot interupt Secure Handler mode. the ``AIRCR.PRIS`` bit remains set
+ during TF-M run. The bit is set in the function
+
+.. code-block:: c
+
+ static int32_t tfm_core_set_secure_exception_priorities(void);
+
+.. Note::
+
+ Setting ``AIRCR.PRIS`` in itself doesn't prevent NS interrupts to pre-empt
+ Secure Thread mode when it runs on normal priority i.e., 256.
+
+2. On Secure service entry ``PRIMASK_NS`` is set, to boost the Non-secure
+ execution priority so that all NS interrupts are masked. This is done in the
+ ``TFM_NS_EXC_DISABLE()`` macro called from
+
+.. code-block:: c
+
+ static int32_t tfm_start_partition(struct tfm_sfn_req_s *desc_ptr, uint32_t excReturn)
+
+.. Note::
+
+ '2.' is only in Library model.
+
+In the below chapters a design is proposed to enable Non-secure interrupts to
+pre-empt Secure Thread mode.
+
+**********************************
+Limitations of the proposed design
+**********************************
+
+Library model
+=============
+
+The proposed design keeps the Secure lock in place, which means Non-secure code
+can do a single Secure service call, all further calls to Secure services will
+be rejected until the first Secure service call returns.
+
+IPC model
+=========
+
+The PSA client API can only be entered once. All the functions in the client API
+(``psa_framework_version``, ``psa_version``, ``psa_connect``, ``psa_call``,
+``psa_close``) are part of the same critical section.
+
+Non-secure software
+===================
+
+The Non-secure API functions that wraps the Secure service veneers (either
+Library or IPC model) should continue to use the NS locking mechanism currently
+implemented by calling ``tfm_ns_lock_dispatch(...)``.
+
+If any of the Non-secure software decides to bypass the locking mechanism, then
+concurrent access of veneer functions is detected by TF-M, and NS software
+execution is halted.
+
+.. Note::
+
+ This makes denial of service attack possible by a malicious NS application
+
+***************************************************
+Enabling NS interrupts to pre-empt Secure execution
+***************************************************
+
+To enable NS interrupts, 2) described in chapter 'Current design' must be turned
+off. (For details see implementation notes)
+
+When a Non-secure interrupt is triggered during Secure code execution, and the
+ISR have to be executed based on the priority settings, the hardware saves the
+current execution context on the current Secure stack, and clears the general
+purpose registers, to prevents data leakage. After that the NS ISR starts
+execution.
+
+When the Non-secure ISR returns with the EXC_RETURN value provided to it in the
+link register, the context is fetched from the Secure stack, and the Secure code
+continues execution.
+
+If TF-M is used with a single threaded NS software, the mechanisms provided by
+the HW is enough to maintain the consistency of the system, and keep the
+secrets.
+
+However if the NS software is allowed to change execution context during an
+interrupt (e.g an NS operating system schedules another thread during a SysTick
+interrupt), then the Secure code can return execution to an NS thread, with the
+context of a different thread. So extra measures needs to be introduced in TF-M
+to prevent this.
+
+For IPC model
+=============
+
+In the current implementation there is no locking mechanism on the Secure side
+that would prevent the Non-secure code to enter psa_client functions multiple
+times. (For the Library model the ``tfm_secure_lock global`` variable is used
+for this purpose). Note, that the ``tfm_ns_lock_dispatch(...)`` function that
+is used by the NS service API implementations to prevent Secure services to be
+called simultaneously can be bypassed by a malicious Non-secure application, so
+a Secure side locking mechanism have to be implemented.
+
+When an NS client calls a PSA client API function, the client ID of the calling
+NS context have to be saved, and execution can only return to NS if the current
+scheduled NS thread is the one that did the call.
+
+For Library model
+=================
+
+As currently there is no scheduling in the Library model, the calls follow each
+other just like in an ordinary function call scheme. Then when the original
+Secure service that was called from the NS code is about to return, it has to
+check for the current NS client ID, and only return if it is the same as the one
+saved on Secure service entry from NS. If the ID's don't match, the Secure side
+waits so that NS OS can do context switch.
+
+Common measures
+===============
+
+Exception priorities
+--------------------
+
+The priority of the Secure SVC and the Secure faults must be higher than any
+Secure exception in the system. Once this is done, the following fixme can be
+removed from ``secure_fw\core\tfm_core.c``:
+``tfm_core_set_secure_exception_priorities``:
+
+.. code-block:: c
+
+ /* FixMe: Explicitly set secure fault and Secure SVC priority to highest */
+
+.. note::
+
+ The priority of PendSV Is set to be the lowest priority Secure interrupt,
+ but still higher than the maximum possible NS execution priority when
+ ``AIRCR.PRIS`` is set.
+
+NSPM
+----
+
+If the Non-secure software allows the use of multiple threads, it needs to use
+the NSPM feature of TF-M. It is expected, that all the NS context that use
+Secure services have a unique client ID, and the other contexts, that don't use
+Secure service need to have a client ID that doesn't match with any of the
+client IDs of the Secure service calling contexts.
+
+In other words, for all the *cs(0)*, *cs(1)*, ..., *cs(n)* NS contexts that use
+Secure services and for all *cn(0)*, *cn(1)*, ..., *cn(m)* NS contexts that
+don't use Secure service (where *n* > 0, *m* >= 0):
+
+- *cs(i).client_id* != *cs(j).client_id* (where 0 <= *i* < *j* <= *n*)
+- *cs(i).client_id* != *cn(j).client_id* (where 0 <= *i* <= *n* and 0 <= *j*
+ <= *m*)
+
+Entering from Non-secure to Secure
+----------------------------------
+
+The Secure code can be entered through the following gateways:
+
+1. NSPM related functions (``TZ_<operation>(...)``,
+ ``tfm_register_client_id(...)``)
+
+ These functions are expected to be called from Handler mode. The execution
+ priority, after the execution crosses the security boundary will be the same
+ as it was during NS execution. This means a malicious Non-secure application,
+ can set up Non-secure interrupt priorities in a way that it can enter one or
+ more of the NSPM APIs simultaneously.
+
+ This might leave the NSPM database in an inconsistent state, however if the
+ attacker has influence over the interrupt priorities, they can gain no
+ additional privilege by this.
+
+ .. Note::
+ The NS software is able to consume the main stack of the Secure software.
+ The Main Secure stack have to be protected by MSPLIM, to prevent stack
+ overflow. However a denial of service attack is still possible.
+
+2. PSA Client API, Library model service veneers
+
+ When a veneer is called from Non-secure, the Secure code have to check
+ whether the veneer is only entered by a single NS thread. This can be done by
+ checking the veneer stack usage. It can only contain the locals of the veneer
+ implementation. If the veneer has been entered from multiple NS threads,
+ there is at least one extra context stack frame that was created by the
+ hardware when the veneer execution had been interrupted by the NS systick.
+
+********************
+Implementation notes
+********************
+
+IPC model
+=========
+
+Save NS client ID on Secure service veneer entry
+------------------------------------------------
+
+As long as the Secure lock is in place, a single client ID have to be stored, so
+it can be done in a global variable.
+
+The caller client ID can be saved in the function
+``void tfm_psa_ipc_request_handler(uint32_t svc_ctx[])`` depending on the return
+value of the PSA API function. (Doesn't execute any Secure service code, only
+sets signals, and triggrs scheduling. If the return value is success, that means
+a scheduling is to happen, and a secure service is about to be entered.)
+
+Check client ID on Secure service return
+----------------------------------------
+
+The saved client ID can be compared with the current client ID in the function
+``tfm_core_ns_ipc_request``, after the SVC return. Before doing the comparison,
+``BASEPRI_NS`` must be set to 1.
+
+The original ``BASEPRI_NS`` value can be stored in a global variable (because of
+the single context).
+
+If the client ID's don't match, ``BASEPRI_NS`` must be reset, WFI to be issued,
+and start the checking sequence from the beginning.
+
+Library model
+=============
+
+Save NS client ID on Secure veneer entry
+----------------------------------------
+
+As long as the Secure lock is in place, only a single client ID have to be
+stored, so it can be done in a global variable.
+
+The caller client ID can be saved in the function
+``uint32_t tfm_core_partition_request_svc_handler(uint32_t *svc_args, uint32_t excReturn)``.
+
+Check client ID on SP return
+----------------------------
+
+The saved client ID can be compared with the current client ID in the function
+``tfm_core_partition_request``, after the ``tfm_core_sfn_request return``.
+
+If the client ID's don't match, WFI to be issued, and the checking sequence have
+to be started from the beginning.
+
+Common
+======
+
+Enforce single NS entry to Secure
+---------------------------------
+
+On Secure service entry (from the SVC implementation) check that (pseudocode)
+
+.. code-block:: c
+
+ svc_handler()
+ {
+ /* If there are multiple context stacked in veneer stack, hang NSPE */
+ expected_sp_top = veneer_stack_addr -
+ sizeof(svc_state_context) + sizeof(locals);
+ if (__get_PSP() != expected_sp_top) {
+ /* Multiple frames are existing, panic */
+ panic();
+ }
+ }
+
+*******
+Testing
+*******
+
+Basic scenario
+==============
+
+Basic testing of the feature is possible, by adding a new scenario to the
+existing IRQ test. The flow of the test would be something like this:
+
+============ ===================== ===========================================
+IRQ_TEST_1 prepare test scenario Do nothing
+CORE_TEST_2 prepare test scenario Do nothing
+NS prepare test scenario Initialise and start timer
+IRQ_TEST_1 execute test scenario Do nothing
+CORE_TEST_2 execute test scenario Busy wait until NS interrupt is
+ acknowledged (a flag in non Secure data is
+ set) set flag CORE_TEST_2 waits on
+NS execute test scenario Do nothing
+============ ===================== ===========================================
+
+The test is successful if NS execute test scenario returns
+
+Advanced scenarios
+==================
+
+Testing advanced scenarios (that involves NS scheduling during secure execution,
+NS interrupting Secure interrupt, Secure interrupting NS interrupt) would
+require more advanced test framework and are not covered in this proposal.
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/tfm_non_secure_client_management.rst b/docs/design_documents/tfm_non_secure_client_management.rst
new file mode 100644
index 0000000..970550a
--- /dev/null
+++ b/docs/design_documents/tfm_non_secure_client_management.rst
@@ -0,0 +1,388 @@
+############################
+Non-secure Client Management
+############################
+
+:Author: Miklos Balint
+:Organization: Arm Limited
+:Contact: Miklos Balint <miklos.balint@arm.com>
+:Status: Accepted
+
+***********
+Terminology
+***********
+
+**Secure service call**: request to a secure partition by a secure or non-secure
+client thread
+
+**Secure function call**: any function call from NSPE to SPE
+
+**TrustZone (TZ) API**: the set of functions defined by CMSIS for RTOS secure
+context management
+
+**Client ID**: the identifier defining a single entity within the system,
+determining its access policies for any given secure assets
+
+*************************
+Assumptions, restrictions
+*************************
+
+This design considers as its baseline the current operation of TF-M: an
+operating mode where at any given time only a single non-secure access is
+permitted to call a secure service.
+
+If a non-secure RTOS/bare-metal application does not use the API calls defined
+in this design, that non-secure application is still able to use secure services
+using a single, default non-secure client context. That remains a supported use
+case and use of this API is optional and is only needed if multiple access
+policies and/or concurrent secure contexts initiated by non-secure threads are
+required.
+
+Investigation is ongoing to address the option of enabling multiple concurrent
+calls by non-secure threads without the use of the context management API below.
+
+******
+Issues
+******
+
+The topics being discussed in this document:
+
+- NS client/thread awareness in TF-M Core
+- "Known client" list
+
+Improvements, alternatives, investigations
+
+- Concurrent secure service requests
+- NS to S priority inheritance
+- NS privilege to be derived from CONTROL_NS register
+
+**************
+Design details
+**************
+
+NS thread awareness in TF-M Core
+================================
+
+Description
+-----------
+
+TrustZone context management API defines a set of secure function calls from NS
+RTOS handler mode to TF-M Core to get notification of context switch.
+
+While CMSIS context management can be used to directly expose secure context
+management to the non-secure OS, TF-M has a proprietary implementation: the
+context management API is used to get notification of NS context switches and
+to track various non-secure clients.
+
+.. _`API definition`:
+
+API definition
+--------------
+
+TZ_MemoryId_t data type
+^^^^^^^^^^^^^^^^^^^^^^^
+
+TZ Memory ID identifies an allocated memory slot.
+
+TF-M usage
+""""""""""
+
+``TZ_MemoryId_t`` is used for an index into an array containing active NS client
+IDs. The memory ID is required by CMSIS to be a positive integer, so it is
+mapped to the array index by being decremented by 1.
+
+Signature
+"""""""""
+
+.. code-block:: c
+
+ typedef uint32_t TZ_MemoryId_t;
+
+Context management initialization: TZ_InitContextSystem_S
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Initialize secure context memory system.
+
+Return value
+""""""""""""
+
+This function returns execution status: 1 for success, 0 for error.
+
+TF-M usage
+""""""""""
+
+This function call is used to identify a non-secure RTOS that has TZ context
+management capabilities, as this function is expected to be called before any
+other TZ API function is used.
+
+Signature
+""""""""""
+
+.. code-block:: c
+
+ uint32_t TZ_InitContextSystem_S (void);
+
+Context allocation: TZ_AllocModuleContext_S
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Allocate context memory for calling secure software modules in TrustZone.
+
+Parameters
+""""""""""
+
+``module`` [input]: identifies software modules called from non-secure mode
+
+Return value
+""""""""""""
+
+``value != 0`` TrustZone memory slot identifier
+``value == 0`` no memory available or internal error
+
+TF-M usage
+""""""""""
+
+This function is used to identify a new non-secure thread that may be identified
+as a client in the non-secure domain. The ``module`` parameter is unused. The
+returned ``TZ_MemoryId_t`` value is the index in the ``NsClientIdList`` array
+where the client ID for the newly allocated context is stored.
+
+Signature
+"""""""""
+
+.. code-block:: c
+
+ TZ_MemoryId_t TZ_AllocModuleContext_S (TZ_ModuleId_t module);
+
+Context freeing: TZ_FreeModuleContext_S
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Free context memory that was previously allocated with TZ_AllocModuleContext_S
+
+Parameters
+""""""""""
+
+``id`` [input]: TrustZone memory slot identifier
+
+Return value
+""""""""""""
+
+Execution status (1: success, 0: error)
+
+TF-M usage
+""""""""""
+
+This function indicates that a non-secure client is inactive, meaning that any
+subsequent references to the client ID are considered erroneous. In effect, the
+client ID indexed by ``(id – 1)`` is cleared and the memory slot flagged as
+free.
+
+Signature
+"""""""""
+
+.. code-block:: c
+
+ uint32_t TZ_FreeModuleContext_S (TZ_MemoryId_t id);
+
+Context activation: TZ_LoadContext_S
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Load secure context (called on RTOS thread context switch)
+
+Parameters
+""""""""""
+
+``id`` [input]: TrustZone memory slot identifier
+
+Return value
+""""""""""""
+
+Execution status (1: success, 0: error)
+
+TF-M usage
+""""""""""
+
+The client ID indexed by ``(id – 1)`` becomes the active NS client. Any
+subsequent secure service requests coming from non-secure domain will be
+associated with this client ID.
+
+Signature
+"""""""""
+
+.. code-block:: c
+
+ uint32_t TZ_LoadContext_S (TZ_MemoryId_t id);
+
+Context deactivation: TZ_StoreContext_S
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Store secure context (called on RTOS thread context switch)
+
+Parameters
+""""""""""
+
+``id`` [input]: TrustZone memory slot identifier
+
+Return value
+""""""""""""
+
+Execution status (1: success, 0: error)
+
+TF-M usage
+""""""""""
+
+The client ID indexed by ``(id – 1)`` becomes inactive. Any subsequent secure
+service requests coming from non-secure domain will be invalid until a new NS
+context is loaded.
+
+Signature
+"""""""""
+
+.. code-block:: c
+
+ uint32_t TZ_StoreContext_S (TZ_MemoryId_t id);
+
+Security implications (to be assessed separately if needed)
+-----------------------------------------------------------
+
+If NS RTOS / NS handler mode is compromised, NS clients’ data can be disclosed
+to unauthorised non-secure actors, as it’s not in the scope of TF-M to guarantee
+non-secure client isolation. Support for this API is only an enabler for a
+non-secure RTOS feature.
+
+Vulnerabilities of the NS handler mode cannot and will not lead to disclosure of
+assets owned by secure entities to non-secure actors after the introduction of
+this feature as a malicious NS handler can only ever assume the identity of
+another non-secure client and cannot elevate its access privileges to those of
+secure clients.
+
+Known client list
+=================
+
+Description
+-----------
+
+A different – but related – API to that defined by CMSIS is proposed in this
+design to register a specific client ID to the active non-secure thread.
+
+The purpose of this API is to provide non-secure privileged code with the
+ability to associate the active non-secure context with a pre-defined identity.
+This enables the application of a pre-set access policy on the secure side to be
+applied to the non-secure thread.
+
+Use cases
+---------
+
+It is valid for non-secure privileged code to only support the TF-M-specific API
+defined below and not the CMSIS TZ API defined previously. In this case the
+single non-secure client is still able to access resources based on a
+pre-defined access policy in secure services without relying on the default
+non-secure identity configured in TF-M.
+
+If used in conjunction with the TZ API, this function can provide a means to
+assign and identify multiple non-secure client IDs based on the active context,
+overriding TF-M’s default non-secure client identity assignment policy.
+
+API definition
+--------------
+
+NS RTOS client registration API – secure function calls from NS handler mode to
+TF-M Core to associate a “known” Client ID to the active non-secure thread.
+
+Register specific client ID: ``tfm_register_client_id``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Assign client ID to the current TZ context.
+
+**Note**: This function must be called from handler mode so that TF-M can verify
+that it was sent by a privileged entity.
+
+This function call must follow all TZ_AllocModuleContext_S function calls to
+override the default NS client IDs allocated by TF-M.
+
+Secure and non-secure client IDs are allocated from different ranges (negative
+IDs for non-secure clients, positive for secure clients). The function call is
+rejected if called with a secure ID.
+
+Parameters
+""""""""""
+
+``ns_client_id`` [input]: The client ID to be assigned to the current context
+
+Return value
+""""""""""""
+
+``TFM_SUCCESS`` (0) if the client ID assigned successfully, a non-zero error
+code in case of error.
+
+Signature
+"""""""""
+
+.. code-block:: c
+
+ enum tfm_status_e tfm_register_client_id (int32_t ns_client_id);
+
+********************
+Implementation notes
+********************
+
+Option to reduce required context switch notifications
+======================================================
+
+According to TrustZone API definition ``TZ_StoreContext_S()`` is to be called
+"at thread context switch after running a thread" and ``TZ_LoadContext_S`` "at
+thread context switch before running a thread". The API definition does not
+define the course of action to be taken if two ``TZ_LoadContext_S()`` calls are
+made without an interleaving StoreContext.
+
+The proposal for TF-M is to accept this as a valid scenario where the second
+``TZ_LoadContext_S()`` call is taken to imply a ``TZ_StoreContext_S()`` with
+the previous active Memory_Id.
+
+This assumption does not alter the intended use of ``TZ_StoreContext_S()``,
+which remains a valid call with the behaviour as defined in the
+`API definition`_ section above.
+
+******************************************
+Investigations, improvements, alternatives
+******************************************
+
+Concurrent secure service requests
+==================================
+
+If there are concurrent services requests, TF-M needs to identify the client for
+each request and should make their corresponding context available in the secure
+domain. Client ID needs to be associated with the secure service request so that
+a NS context switch does not break client identification.
+
+If a non-secure client is blocked on an asynchronous secure service completion,
+the NS TFM library must provide a semaphore the NS thread can wait on, whereby
+NS RTOS can schedule a different context.
+
+Should a secure service completion happen for an inactive NS context, a
+notification mechanism needs to be created to activate the given NS context.
+
+The proposal is for the NS TFM library to include a NS IRQ handler for a
+reserved interrupt signal. The ISR would identify the context to be activated
+and release the corresponding semaphore.
+
+NS to S priority inheritance
+============================
+
+Whether or not NS thread priorities should be influencing secure service
+prioritization needs to be analysed. It is raised as a topic of discussion and
+is not detailed in this document further at this stage.
+
+NS privilege check for secure function calls
+============================================
+
+Non-secure privilege can be derived from CONTROL_NS instead of requiring NS to
+call context management veneers in handler mode. This can be a more generic
+approach, but implications are to be investigated.
+
+**********
+References
+**********
+
+Description of the TZ API:
+https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
\ No newline at end of file
diff --git a/docs/design_documents/tfm_secure_partition_interrupt_handling.rst b/docs/design_documents/tfm_secure_partition_interrupt_handling.rst
new file mode 100644
index 0000000..a0c998e
--- /dev/null
+++ b/docs/design_documents/tfm_secure_partition_interrupt_handling.rst
@@ -0,0 +1,230 @@
+###################################
+Secure Partition Interrupt Handling
+###################################
+
+:Author: Miklos Balint
+:Organization: Arm Limited
+:Contact: Miklos Balint <miklos.balint@arm.com>
+:Status: Accepted
+
+Secure Partitions that implement peripheral drivers may need to use interrupts
+to efficiently manage PE utilization.
+
+************************
+Partition implementation
+************************
+
+IRQ lines declared in manifest files for Secure Partitions are assigned IRQ
+signals as described in PSA Firmware Framework.
+
+Interrupt handling is implemented as interrupt service routines (Partition ISR)
+that are executed in the partition context.
+
+Partitions that are owners of IRQ must define interrupt service routines for
+them.
+
+manifest file IRQ declaration example
+=====================================
+
+.. code-block:: json
+
+ "irqs": [
+ {
+ "line_num": 17,
+ "signal": "RTC"
+ },
+ {
+ "line_name": "UART1_IRQ",
+ "signal": "UART1"
+ }
+ ]
+
+Partition ISR function
+======================
+
+The symbol name of the ISR implemented for a given interrupt must be
+``manifest[‘irqs’][idx].signal`` attribute post-fixed with "_isr".
+
+Partition ISR has the signature of a regular interrupt service routine, e.g.:
+
+.. code-block:: c
+
+ void UART1_isr(void);
+
+*************
+SPM behaviour
+*************
+
+In the vector table, each interrupt that has an associated partition ISR is
+assigned to an SPM interrupt handler (SPM ISR) that delegates handling to a
+Partition ISR.
+
+Each partition is allocated an asserted signal mask. Every IRQ associated with
+the partition is assigned a position in the signal mask.
+
+When a secure hardware interrupt is asserted, the SPM:
+
+- Acknowledges the interrupt and masks the hardware interrupt line.
+
+- Identifies the Secure Partition which has registered the interrupt (in the
+ manifest). This identification can happen either
+
+ - using a runtime lookup or
+
+ - by registering different instances of the SPM ISR for each interrupt, so the
+ runtime lookup is avoided both for the partition Id and the ISR function
+ location.
+
+- Sets up execution environment for the secure partition that has registered the
+ interrupt.
+
+- Asserts the IRQ signal for the interrupt in the partition's signal mask.
+
+- Execute Partition ISR. If the partition’s stack is active at the time of
+ pre-emption by the interrupt (i.e. the Secure Partition is not in idle state),
+ the Partition ISR stack frame will be amended to that. If the Secure Partition
+ had been idle, a stack frame will be reserved for the duration of the
+ Partition ISR execution. The Secure Partition state is changed to running for
+ the duration of the Partition ISR.
+
+When the Secure Partition ISR returns, execution is returned to the context
+pre-empted by the IRQ.
+
+Implementation notes
+====================
+
+Interrupts can pre-empt NSPE or secure service execution. Pre-emption of an
+interrupt is only possible by an interrupt of a higher priority, ensuring
+deterministic nesting/un-nesting of stack frames.
+
+*************
+API functions
+*************
+
+psa_wait()
+==========
+
+A call to ``psa_wait()`` from a secure service yields execution to the framework
+and becomes blocked waiting for the assertion of a signal. In the meantime, SPM
+will schedule other contexts that are ready to run. The client remains blocked
+until the service function returns.
+
+If an IRQ signal matching one in ``signal_mask`` to ``psa_wait()`` is asserted,
+the Secure Partition becomes ready to run. When the scheduler activates the
+Secure Partition, the IRQ signal(s) that had been asserted are returned by
+``psa_wait()``. When the service function completes its execution and returns,
+control is taken back to client.
+
+.. Note::
+
+ The only signals implemented in the current TF-M implementation are
+ interrupt signals.
+
+Signature
+---------
+
+.. code-block:: c
+
+ psa_signal_t psa_wait(psa_signal_t signal_mask, uint32_t timeout);
+
+Parameters
+----------
+
+``psa_signal_t signal_mask`` defines the set of interrupt signals that can
+resume execution of the secure service.
+
+``uint32_t timeout`` defines timeout for the function, as defined in PSA
+Firmware Framework 1.0-beta-0 (Chapter 4.3.3).
+
+Return
+------
+
+The return value indicates the signal(s) that triggered the resumption of the
+service; i.e. If multiple interrupt events have been handled, it will be
+indicated by the mask value in the return code.
+
+tfm_enable_irq()
+================
+
+A call to ``tfm_enable_irq()`` from a secure service enables an irq.
+
+Signature
+---------
+
+.. code-block:: c
+
+ void tfm_enable_irq(psa_signal_t irq_signal);
+
+Parameters
+----------
+
+``psa_signal_t irq_signal`` defines the interrupt signal to be enabled.
+
+Return
+------
+
+``void`` Success.
+
+Does not return: The call is invalid, one or more of the following are true:
+
+- irq_signal is not an interrupt signal.
+- irq_signal indicates more than one signal.
+
+tfm_disable_irq()
+=================
+
+A call to ``tfm_disable_irq()`` from a secure service disables an irq.
+
+Signature
+---------
+
+.. code-block:: c
+
+ void tfm_disable_irq(psa_signal_t irq_signal);
+
+Parameters
+----------
+``psa_signal_t irq_signal`` defines the interrupt signal to be disabled.
+
+Return
+------
+
+``void``: Success.
+
+Does not return: The call is invalid, one or more of the following are true:
+
+- irq_signal is not an interrupt signal.
+- irq_signal indicates more than one signal.
+
+psa_eoi()
+=========
+
+A call ``to psa_eoi()`` from a secure service function or a Partition ISR
+informs SPM that an interrupt has been processed. This clears the IRQ signal in
+the asserted signal mask associated with the partition.
+
+Signature
+---------
+
+.. code-block:: c
+
+ void psa_eoi(psa_signal_t irq_signal);
+
+Parameters
+----------
+
+``psa_signal_t irq_signal`` defines the interrupt signal that has been
+processed.
+
+Return
+------
+
+``void``: Success.
+
+Does not return: The call is invalid, one or more of the following are true:
+
+- ``irq_signal`` is not an interrupt signal.
+- ``irq_signal`` indicates more than one signal.
+- ``irq_signal`` is not currently asserted.
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
\ No newline at end of file
diff --git a/docs/design_documents/tfm_uniform_secure_service_signature.rst b/docs/design_documents/tfm_uniform_secure_service_signature.rst
new file mode 100644
index 0000000..70c6c60
--- /dev/null
+++ b/docs/design_documents/tfm_uniform_secure_service_signature.rst
@@ -0,0 +1,114 @@
+################################
+Uniform Secure Service Signature
+################################
+
+:Author: Miklos Balint
+:Organization: Arm Limited
+:Contact: Miklos Balint <miklos.balint@arm.com>
+:Status: Accepted
+
+**********************************
+Declaring secure service interface
+**********************************
+
+The following alternative secure service signature is proposed as an
+amendment to existing implementation.
+
+Individual signatures - current method
+======================================
+
+A ``<service_name>_veneers.c`` file is created in the ``secure_fw/ns_callable``
+directory, that specifies the signature for each veneer function, and calls the
+secure function from the veneers. The respective
+``interface/include/<service_name>_veneers.h`` file with the veneer declarations
+have to be created and maintained manually.
+Note that at present TF-M framework limits the range of valid return values a
+secure service can provide, reserving a range for framework error codes.
+
+Uniform signatures - proposal
+=============================
+
+The proposal is to use a uniform signature for all the secure functions of the
+secure service. There are multiple advantages of this method:
+
+- TF-M Core can do a sanity check on the access rights of the veneer
+ parameters, and there is no need for the secure services to make these checks
+ individually. Please note that in the present implementation sanity check is
+ only fully supported for level 1 isolation.
+
+- The veneer declarations and implementations for the secure functions can be
+ generated automatically from a template (using the secure function list in the
+ secure service's manifest)
+
+The signature for such secure services would look like this:
+
+.. code-block:: c
+
+ psa_status_t secure_function_name(struct psa_invec *in_vec, size_t in_len,
+ struct psa_outvec *out_vec, size_t out_len);
+
+where
+
+Return value:
+-------------
+
+``psa_status_t`` is a status code whose values are described in PSA Firmware
+Framework (as in version 1.0-beta-0 chapter 4.3.3).
+
+Note:
+-----
+The return value limitations imposed by TF-M framework for proprietary
+secure service veneers would not apply to secure services using the uniform
+signature. This is analogous to how PSA Firmware Framework handles values
+returned by ``psa_reply()`` function.
+
+Arguments:
+----------
+
+.. code-block:: c
+
+ /**
+ * A read-only input memory region provided to a RoT Service.
+ */
+ typedef struct psa_invec {
+ const void *base; /*!< the start address of the memory buffer */
+ size_t len; /*!< the size in bytes */
+ } psa_invec;
+
+ /**
+ * A writable output memory region provided to a RoT Service.
+ */
+ typedef struct psa_outvec {
+ void *base; /*!< the start address of the memory buffer */
+ size_t len; /*!< the size in bytes */
+ } psa_outvec;
+
+ /**
+ * in_len: the number of input parameters, i.e. psa_invecs
+ * out_len: the number of output parameters, i.e. psa_outvecs
+ */
+
+The number of vectors that can be passed to a secure service is constrained:
+
+.. code-block:: c
+
+ in_len + out_len <= PSA_MAX_IOVEC
+
+The veneer function declarations and implementations are generated in the
+``interface/include/tfm_veneers.h`` and ``secure_fw\ns_callable\tfm_veneers.c``
+files respectively. The veneer functions are created with the name
+``tfm_<secure_function_name>_veneer``
+
+Services that implement the uniform signature do not need to manually fill
+the template veneer function to call ``TFM_CORE_SFN_REQUEST`` macro.
+
+*************
+Compatibility
+*************
+
+Note that the proposal is for the two types of services (those with proprietary
+signatures and those with uniform signatures) to co-exist, with the intention of
+eventually phasing out proprietary signatures in favour of the more robust,
+uniform signature.
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
\ No newline at end of file