documentation/interrupt_handling.md

   1 Entry and exit of secure world
   2 ==============================
   3
   4 #Introduction
   5 Depending on configuration of the system secure world can be entered during
   6 different conditions. This document will describe only the configuration
   7 used by OP-TEE.
   8
   9 Monitor vector is VBAR_EL3 in AArch64 and MVBAR in ARMv7/AArch32. State
  10 vector is any of:
  11 * VBAR_EL2 or VBAR_EL1 (secure and non-secure) for AArch64, depending on
  12   configuration of hypervisor
  13 * HVBAR or VBAR (secure and non-secure) for ARMv7, depending on
  14   configuration of hypervisor
  15
  16 The processor is configured to use:
  17 * Monitor vector for FIQ exceptions while SCR_NS is set and state vector
  18   when SCR_NS is cleared
  19 * Monitor vector for SMC exceptions
  20 * State vector for IRQ exceptions
  21
  22 Two types of interrupt are defined in optee_os:
  23 * Native interrupt - The interrupt handled by optee_os
  24   (for example: secure interrupt)
  25 * Foreign interrupt - The interrupt not handled by optee_os
  26   (for example: non-secure interrupt which is handled by normal world)
  27
  28 For ARM GICv2 mode, native interrupt is sent as FIQ and foreign interrupt is
  29 sent as IRQ.
  30
  31 For ARM GICv3 mode, foreign interrupt is sent as FIQ which could be handled
  32 by either secure world (EL3 in AArch64) or normal world. This mode is not
  33 supported yet.
  34
  35 Since IRQs are received using the state vector the actual vector used
  36 depends on the current state of the CPU. If the NS (non-secure) bit in SCR
  37 (Secure Control Register) is set then either HVBAR or VBAR (non-secure) is
  38 used when receiving the IRQ, if the NS bit in SCR is cleared the secure
  39 VBAR is used instead. This has the consequence that secure world can
  40 receive IRQ that are supposed to be handled by normal world. When secure
  41 world receives an IRQ it has to be forwarded to normal world for
  42 processing.
  43
  44 # The monitor
  45 The monitor manages all entry and exit of secure world. To enter secure
  46 world from normal world the monitor saves the state of normal world
  47 (general purpose registers and system registers which are not banked) and
  48 restores the previous state of secure world. Then a return from exception
  49 is performed and the restored secure state is resumed. Exit from secure
  50 world to normal world is the reverse.
  51
  52 Some general purpose registers are not saved and restored on entry and
  53 exit, those are used to pass parameters between secure and normal world
  54 (see ARM_DEN0028A_SMC_Calling_Convention for details).
  55
  56 # Entry and exit of Trusted OS
  57 On entry and exit of Trusted OS each CPU is uses a separate entry stack and
  58 runs with IRQ and FIQ blocked.
  59
  60 During the entry phase a context is selected to start/resume execution in.
  61 Only when a context has been restored/entered may IRQ and FIQ be unblocked.
  62
  63 On exit IRQ and FIQ are blocked, the context is saved and the entry stack
  64 is used again.
  65
  66 ![SMC entry of secure world](images/interrupt_handling/tee_invoke.png "SMC entry of secure world")
  67
  68 # Forward IRQ from secure world to normal world
  69 When an IRQ is received in secure world as an IRQ exception then secure world:
  70
  71 1. Saves thread context (entire state of all processor modes for ARMv7)
  72 2. Blocks FIQ (IRQ is already blocked)
  73 3. Switches to entry stack
  74 4. Issues an SMC with a value to indicates to normal world that an IRQ has
  75    been delivered and last SMC call should be continued
  76
  77 The monitor restores normal world context with a return code indicating
  78 that an IRQ is about to be delivered. Normal world issues a new SMC
  79 indicating that it should continue last SMC.
  80
  81 The monitor restores secure world context which locates the previously
  82 saved context and checks that it is a return from IRQ that is requested
  83 before restoring the context and lets the secure world IRQ handler return
  84 from exception where the execution would be resumed.
  85
  86 Note that the monitor itself does not know/care that it has just forwarded
  87 an IRQ to normal world. The bookkeeping is done in the thread handling in
  88 Trusted OS. Normal world is responsible to decide when the secure world
  89 thread should resume execution. If secure world really need to execute
  90 something at a specific time it has to do that in FIQ context.
  91
  92 ![IRQ received in secure world and forwarded to normal world](images/interrupt_handling/irq.png "IRQ received in secure world and forwarded to normal world")
  93
  94 # Deliver FIQ to secure world
  95 A FIQ can be received during two different states, either in non-secure
  96 world (SCR_NS is set) or in secure world (SCR_NS is cleared). When the
  97 secure monitor is active (ARMv8 EL3 or ARMv7 Monitor mode) FIQ is masked.
  98 FIQ reception in the two different states is described below.
  99
 100 ## Deliver FIQ to secure world when SCR_NS is set
 101 When the monitor gets an FIQ exception it:
 102
 103 1. Saves normal world context and restores secure world context from last
 104    secure world exit (which will have IRQ and FIQ blocked)
 105 2. Clears SCR_FIQ when clearing SCR_NS
 106 3. Sets “FIQ” as parameter to secure world entry
 107 4. Does a return from exception into secure context
 108 5. Secure world unmasks FIQs because of the “FIQ” parameter
 109 6. FIQ is received as in exception using the state vector
 110 7. Secure world issues an SMC to return to normal world
 111 8. Monitor saves secure world context and restores normal world context
 112 9. Does a return from exception into restored context
 113
 114 ![FIQ received when SCR_NS is set](images/interrupt_handling/fiq.png "FIQ received when SCR_NS is set")
 115
 116 ![FIQ received while processing an IRQ forwarded from secure world](images/interrupt_handling/irq_fiq.png "FIQ received while processing an IRQ forwarded from secure world")
 117
 118 ## Deliver FIQ to secure world when SCR_NS is cleared
 119 Since SCR_FIQ is cleared when SCR_NS is cleared a FIQ will be delivered
 120 using the state vector (VBAR) in secure world. The FIQ is received as any
 121 other exception by Trusted OS, the monitor is not involved at all.