Table of Contents {#table-of-contents .TOCHeading}
=================
[1. Scheduler 2](#tf-m-scheduler)
[1.1. Objectives and Requirements 2](#objectives-and-requirements)
[1.2. Scheduler Rules for context switching between SPE and NSPE 2](#_Toc534029525)
[1.2.1. Rules for NSPE Exception handling 2](#rules-for-nspe-exception-handling)
[1.2.2. Rules for SPE Exception handling 3](#rules-for-spe-exception-handling)
[1.2.3. Rules for NSPE to SPM function call (and NSPE scheduler) 3](#rules-for-nspe-to-spm-function-call-and-nspe-scheduler)
[1.2.4. Rules for Function Return from SPE to NSPE with result 3](#rules-for-function-return-from-spe-to-nspe-with-result)
[1.2.5. Rules for Return from SPE to NSPE with SPM\_IDLE 3](#rules-for-return-from-spe-to-nspe-with-spm_idle)
[1.2.6. Rules for NSPE pend irq based return from SPE to NSPE 4](#rules-for-nspe-pend-irq-based-return-from-spe-to-nspe)
[1.2.7. Rules for ISR pre-emption 4](#rules-for-isr-pre-emption)
[1.3. Scheduling Scenarios 4](#scheduling-scenarios)
[1.3.1. NSPE interrupt when SPE executing 4](#nspe-interrupt-when-spe-executing)
[2. Annexe (to be removed) 5](#annexe-to-be-removed)
[2.1. Scheduler evolution stages 5](#scheduler-evolution-stages)
[2.1.1. Stage 0: Transition from NSPE to SPE in thread mode 5](#stage-0-transition-from-nspe-to-spe-in-thread-mode)
[2.1.2. Stage 1: Single context partition scheduling 5](#stage-1-single-context-partition-scheduling)
[2.1.3. Stage 2: Enable and validate NSPE IRQ handling 5](#stage-2-enable-and-validate-nspe-irq-handling)
[2.1.4. Stage 3: psa\_wait\_interrupt returns control to NSPE 5](#stage-3-psa_wait_interrupt-returns-control-to-nspe)
[2.1.5. Stage 4: Multiple secure contexts without secure interrupts 6](#stage-4-multiple-secure-contexts-without-secure-interrupts)
[2.1.6. Stage 5: Multiple secure contexts + SIRQ support with return to NSPE / pended SPE thread 6](#stage-5-multiple-secure-contexts-sirq-support-with-return-to-nspe-pended-spe-thread)
[2.2. Mutual exclusion 6](#mutual-exclusion)
[2.2.1. Critical section 6](#critical-section)
[2.3. NSPE Call Return Options 6](#nspe-call-return-options)
[2.3.1. Assumptions 7](#assumptions)
TF-M Scheduler
==============
Objectives and Requirements
---------------------------
a. Decoupling of scheduling decisions between NSPE and SPE
b. Efficient interrupt handling on SPE as well as NSPE
c. Reduce critical sections on the secure side to not block interrupts unnecessarily
d. Scalability to allow simplification/reduction of overheads to scale down the design for constrained devices
e. Reduce impact on NSPE software design
a. NSPE interrupt handling implementation should be independent
i. Worst case latency (TBD, can be blocked by SPM that runs at highest prio)
b. Impact on the NSPE scheduler should be minimal
c. No assumptions should be made about NSPE's scheduling capabilities
Scheduler Rules for context switching between SPE and NSPE
----------------------------------------------------------
To allow coherent cooperative scheduling, following set of rules are imposed on security state changes.
The switching between SPE and NSPE can be triggered in multiple ways.
**Involuntary security context switch;** when the software has no control over the switch
- A NSPE interrupt take control into NSPE from SPE
- A SPE interrupt takes control into NSPE from SPE
**Voluntary security context switch;** when software programmatically makes the switch
- A NSPE exception handler returns from NSPE to pre-empted SPE context
- A SPE exception handler returns from SPE to pre-empted NSPE context
- NSPE makes a function call into SPE
- SPE returns a call from NSPE
- SPE makes a function call into NSPE (not covered in current design)
- NSPE returns a call from SPE (not covered in current design)
In order to maintain the context integrity across NSPE and SPE, following rules are imposed on all security state switches.
### Rules for NSPE Exception handling
a. The NSPE exception handler is allowed to trigger a NSPE context switch (regardless of security state of the pre-empted context.
b. The NSPE scheduler must eventually 'restore' the pre-empted (by exception) context. This is a normal expected behaviour of any scheduler.
c. If NSPE exception results in a context switch, SPM must be informed of the scheduling decision; this must be done BEFORE the execution of scheduled-in context. Possible implementation options:
a. Every time NSPE scheduler changes the context it informs the SPM regardless of whether the new NSPE context would make a call to SPE or not.
OR
b. NSPE tags the contexts (threads) that are meant to make a call into SPE; scheduling in/out of only the tagged contexts is communicated to SPM. This approach may improve NSPE scheduler performance based on use-cases.
### Rules for SPE Exception handling
a. All of the SPE interrupts have higher priority than NSPE interrupts
b. The SPE interrupt handler is allowed to trigger a SPE context switch (regardless of security state of the pre-empted context
c. SPE scheduler must treat pre-empted context as one of the SPE contexts-
a. If the pre-empted SPE context is SP1, the TCB for SP1 should be used for saving the context
b. If SP1 was pre-empted by a NSPE interrupt, and subsequent NSPE execution is pre-empted by SPE exception (\_\_before\_\_ NSPE scheduling decision is communicated back to SPM) -- SP1 TCB must be used for saving the context
c. If SP1 was pre-empted by a NSPE interrupt, and subsequent NSPE execution is pre-empted by SPE exception (\_\_after\_\_ NSPE scheduling decision is communicated back to SPM) -- a TCB dedicated to NSPE should be used for saving the context
d. The SPE scheduler must eventually 'restore' the pre-empted (by exception) context. This is a normal expected behaviour of any scheduler.
e. All of the interrupts belonging to a partition must have same priority. i.e. ISR pre-emption within same partition is not allowed.
f. In case of nested interrupts, control must NOT return to thread mode until the lowest prio ISR has finished (TBD: check -- this must be handled in the hardware)
g. If the previously pre-empted context was a NSPE ISR context, SPE ISR handler MUST return to pre-empted NSPE context instead of returning to SPE thread mode. (TBD: check -- this must be handled in the hardware)
### Rules for NSPE to SPM function call (and NSPE scheduler)
a. Current NSPE context must have been communicated to SPM, otherwise SPM cannot guarantee NSPE function calling stack integrity.
### Rules for Function Return from SPE to NSPE with result
a. Last entry into secure world happens programmatically (**Voluntary security context switch into SPE)**, i.e. control is voluntarily given back by NSPE, either through a function call, or a context restore via 'return to SPE from NSPE'. As opposed to a SPE interrupt bringing back the execution into SPE.
b. The result available on SPE side are for currently active NSPE context.
c. The current NSPE call stack has not already been returned with SPM\_IDLE.
### Rules for Return from SPE to NSPE with SPM\_IDLE
This is optional part of the design as it introduces significant complexity on both sides.
It allows yielding of the CPU to NSPE when SPE has not CPU execution to do but it has not yet finished the previous request(s) from NSPE; i.e. SPE is waiting on arrival of a SPE interrupt.
a. Last entry into secure world happens programmatically (**Voluntary security context switch into SPE)**, i.e. control is voluntarily given back by NSPE, either through a function call, or a context restore via 'return to SPE from NSPE'. As opposed to a SPE interrupt bringing back the execution into SPE.
b. The result for the currently active NSPE entity is not yet available, the called service is waiting (on interrupt/event).
c. The current NSPE call stack has not already been returned with SPM\_IDLE.
### Rules for NSPE pend irq based return from SPE to NSPE
\[TBD\] explain pendIRQ based return
This is optional part of the design as it introduces significant complexity on both sides. This works in conjunction with [Rules for Return from SPE to NSPE with SPM\_IDLE](#rules-for-return-from-spe-to-nspe-with-spm_idle).
a. The SPE has finished a NSPE request.
b. The corresponding NSPE context has already been returned with SPM\_IDLE.
### Rules for ISR pre-emption
a. A higher priority NSPE interrupt is allowed to pre-empt a lower priority NSPE ISR
b. A higher priority SPE interrupt is allowed to pre-empt a lower priority SPE ISR
c. A SPE interrupt is allowed to pre-empt NSPE ISR
d. A NSPE interrupt can NOT pre-empt SPE ISR
e. All interrupts belonging to a service must have same priority
Scheduling Scenarios
--------------------
### NSPE interrupt when SPE executing
\[insert "NS interrupt"\]
\- NSPE1 makes call to secure service SP1
\- NSPE interrupt NS\_ITR1 is triggered while SP1 is running
\- Hardware takes control to NSPE ISR routine, secure context is pushed into SP1 stack
\- NSPE scheduler schedules second NSPE context, NSPE2; a context change notification is sent to SPM before NSPE2 is run
\[move to common -- context change notification handling\]
\- NSPE2 makes a call to SP2
\- SPM schedules SP2
\- SP2 finishes execution, returns to SPM