aboutsummaryrefslogtreecommitdiff
path: root/docs/technical_references/tfm_secure_partition_interrupt_handling.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/technical_references/tfm_secure_partition_interrupt_handling.rst')
-rw-r--r--docs/technical_references/tfm_secure_partition_interrupt_handling.rst234
1 files changed, 234 insertions, 0 deletions
diff --git a/docs/technical_references/tfm_secure_partition_interrupt_handling.rst b/docs/technical_references/tfm_secure_partition_interrupt_handling.rst
new file mode 100644
index 0000000000..6d9a5e1d04
--- /dev/null
+++ b/docs/technical_references/tfm_secure_partition_interrupt_handling.rst
@@ -0,0 +1,234 @@
+###################################
+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"
+ }
+ ]}
+
+See
+:doc:`secure IRQ handling </docs/technical_references/tfm_secure_irq_handling>`
+for further information on IRQ source and signal.
+
+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-2021, Arm Limited. All rights reserved.*