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, 0 insertions, 234 deletions
diff --git a/docs/technical_references/tfm_secure_partition_interrupt_handling.rst b/docs/technical_references/tfm_secure_partition_interrupt_handling.rst deleted file mode 100644 index 6d9a5e1d04..0000000000 --- a/docs/technical_references/tfm_secure_partition_interrupt_handling.rst +++ /dev/null @@ -1,234 +0,0 @@ -################################### -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.* |