diff options
Diffstat (limited to 'docs/technical_references/tfm_secure_partition_interrupt_handling.rst')
-rw-r--r-- | docs/technical_references/tfm_secure_partition_interrupt_handling.rst | 234 |
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.* |