--- /dev/null
+ =================================
+ INTERNAL KERNEL ABI FOR FR-V ARCH
+ =================================
+
+The internal FRV kernel ABI is not quite the same as the userspace ABI. A
+number of the registers are used for special purposed, and the ABI is not
+consistent between modules vs core, and MMU vs no-MMU.
+
+This partly stems from the fact that FRV CPUs do not have a separate
+supervisor stack pointer, and most of them do not have any scratch
+registers, thus requiring at least one general purpose register to be
+clobbered in such an event. Also, within the kernel core, it is possible to
+simply jump or call directly between functions using a relative offset.
+This cannot be extended to modules for the displacement is likely to be too
+far. Thus in modules the address of a function to call must be calculated
+in a register and then used, requiring two extra instructions.
+
+This document has the following sections:
+
+ (*) System call register ABI
+ (*) CPU operating modes
+ (*) Internal kernel-mode register ABI
+ (*) Internal debug-mode register ABI
+ (*) Virtual interrupt handling
+
+
+========================
+SYSTEM CALL REGISTER ABI
+========================
+
+When a system call is made, the following registers are effective:
+
+ REGISTERS CALL RETURN
+ =============== ======================= =======================
+ GR7 System call number Preserved
+ GR8 Syscall arg #1 Return value
+ GR9-GR13 Syscall arg #2-6 Preserved
+
+
+===================
+CPU OPERATING MODES
+===================
+
+The FR-V CPU has three basic operating modes. In order of increasing
+capability:
+
+ (1) User mode.
+
+ Basic userspace running mode.
+
+ (2) Kernel mode.
+
+ Normal kernel mode. There are many additional control registers
+ available that may be accessed in this mode, in addition to all the
+ stuff available to user mode. This has two submodes:
+
+ (a) Exceptions enabled (PSR.T == 1).
+
+ Exceptions will invoke the appropriate normal kernel mode
+ handler. On entry to the handler, the PSR.T bit will be cleared.
+
+ (b) Exceptions disabled (PSR.T == 0).
+
+ No exceptions or interrupts may happen. Any mandatory exceptions
+ will cause the CPU to halt unless the CPU is told to jump into
+ debug mode instead.
+
+ (3) Debug mode.
+
+ No exceptions may happen in this mode. Memory protection and
+ management exceptions will be flagged for later consideration, but
+ the exception handler won't be invoked. Debugging traps such as
+ hardware breakpoints and watchpoints will be ignored. This mode is
+ entered only by debugging events obtained from the other two modes.
+
+ All kernel mode registers may be accessed, plus a few extra debugging
+ specific registers.
+
+
+=================================
+INTERNAL KERNEL-MODE REGISTER ABI
+=================================
+
+There are a number of permanent register assignments that are set up by
+entry.S in the exception prologue. Note that there is a complete set of
+exception prologues for each of user->kernel transition and kernel->kernel
+transition. There are also user->debug and kernel->debug mode transition
+prologues.
+
+
+ REGISTER FLAVOUR USE
+ =============== ======= ==============================================
+ GR1 Supervisor stack pointer
+ GR15 Current thread info pointer
+ GR16 GP-Rel base register for small data
+ GR28 Current exception frame pointer (__frame)
+ GR29 Current task pointer (current)
+ GR30 Destroyed by kernel mode entry
+ GR31 NOMMU Destroyed by debug mode entry
+ GR31 MMU Destroyed by TLB miss kernel mode entry
+ CCR.ICC2 Virtual interrupt disablement tracking
+ CCCR.CC3 Cleared by exception prologue
+ (atomic op emulation)
+ SCR0 MMU See mmu-layout.txt.
+ SCR1 MMU See mmu-layout.txt.
+ SCR2 MMU Save for EAR0 (destroyed by icache insns
+ in debug mode)
+ SCR3 MMU Save for GR31 during debug exceptions
+ DAMR/IAMR NOMMU Fixed memory protection layout.
+ DAMR/IAMR MMU See mmu-layout.txt.
+
+
+Certain registers are also used or modified across function calls:
+
+ REGISTER CALL RETURN
+ =============== =============================== ======================
+ GR0 Fixed Zero -
+ GR2 Function call frame pointer
+ GR3 Special Preserved
+ GR3-GR7 - Clobbered
+ GR8 Function call arg #1 Return value
+ (or clobbered)
+ GR9 Function call arg #2 Return value MSW
+ (or clobbered)
+ GR10-GR13 Function call arg #3-#6 Clobbered
+ GR14 - Clobbered
+ GR15-GR16 Special Preserved
+ GR17-GR27 - Preserved
+ GR28-GR31 Special Only accessed
+ explicitly
+ LR Return address after CALL Clobbered
+ CCR/CCCR - Mostly Clobbered
+
+
+================================
+INTERNAL DEBUG-MODE REGISTER ABI
+================================
+
+This is the same as the kernel-mode register ABI for functions calls. The
+difference is that in debug-mode there's a different stack and a different
+exception frame. Almost all the global registers from kernel-mode
+(including the stack pointer) may be changed.
+
+ REGISTER FLAVOUR USE
+ =============== ======= ==============================================
+ GR1 Debug stack pointer
+ GR16 GP-Rel base register for small data
+ GR31 Current debug exception frame pointer
+ (__debug_frame)
+ SCR3 MMU Saved value of GR31
+
+
+Note that debug mode is able to interfere with the kernel's emulated atomic
+ops, so it must be exceedingly careful not to do any that would interact
+with the main kernel in this regard. Hence the debug mode code (gdbstub) is
+almost completely self-contained. The only external code used is the
+sprintf family of functions.
+
+Furthermore, break.S is so complicated because single-step mode does not
+switch off on entry to an exception. That means unless manually disabled,
+single-stepping will blithely go on stepping into things like interrupts.
+See gdbstub.txt for more information.
+
+
+==========================
+VIRTUAL INTERRUPT HANDLING
+==========================
+
+Because accesses to the PSR is so slow, and to disable interrupts we have
+to access it twice (once to read and once to write), we don't actually
+disable interrupts at all if we don't have to. What we do instead is use
+the ICC2 condition code flags to note virtual disablement, such that if we
+then do take an interrupt, we note the flag, really disable interrupts, set
+another flag and resume execution at the point the interrupt happened.
+Setting condition flags as a side effect of an arithmetic or logical
+instruction is really fast. This use of the ICC2 only occurs within the
+kernel - it does not affect userspace.
+
+The flags we use are:
+
+ (*) CCR.ICC2.Z [Zero flag]
+
+ Set to virtually disable interrupts, clear when interrupts are
+ virtually enabled. Can be modified by logical instructions without
+ affecting the Carry flag.
+
+ (*) CCR.ICC2.C [Carry flag]
+
+ Clear to indicate hardware interrupts are really disabled, set otherwise.
+
+
+What happens is this:
+
+ (1) Normal kernel-mode operation.
+
+ ICC2.Z is 0, ICC2.C is 1.
+
+ (2) An interrupt occurs. The exception prologue examines ICC2.Z and
+ determines that nothing needs doing. This is done simply with an
+ unlikely BEQ instruction.
+
+ (3) The interrupts are disabled (local_irq_disable)
+
+ ICC2.Z is set to 1.
+
+ (4) If interrupts were then re-enabled (local_irq_enable):
+
+ ICC2.Z would be set to 0.
+
+ A TIHI #2 instruction (trap #2 if condition HI - Z==0 && C==0) would
+ be used to trap if interrupts were now virtually enabled, but
+ physically disabled - which they're not, so the trap isn't taken. The
+ kernel would then be back to state (1).
+
+ (5) An interrupt occurs. The exception prologue examines ICC2.Z and
+ determines that the interrupt shouldn't actually have happened. It
+ jumps aside, and there disabled interrupts by setting PSR.PIL to 14
+ and then it clears ICC2.C.
+
+ (6) If interrupts were then saved and disabled again (local_irq_save):
+
+ ICC2.Z would be shifted into the save variable and masked off
+ (giving a 1).
+
+ ICC2.Z would then be set to 1 (thus unchanged), and ICC2.C would be
+ unaffected (ie: 0).
+
+ (7) If interrupts were then restored from state (6) (local_irq_restore):
+
+ ICC2.Z would be set to indicate the result of XOR'ing the saved
+ value (ie: 1) with 1, which gives a result of 0 - thus leaving
+ ICC2.Z set.
+
+ ICC2.C would remain unaffected (ie: 0).
+
+ A TIHI #2 instruction would be used to again assay the current state,
+ but this would do nothing as Z==1.
+
+ (8) If interrupts were then enabled (local_irq_enable):
+
+ ICC2.Z would be cleared. ICC2.C would be left unaffected. Both
+ flags would now be 0.
+
+ A TIHI #2 instruction again issued to assay the current state would
+ then trap as both Z==0 [interrupts virtually enabled] and C==0
+ [interrupts really disabled] would then be true.
+
+ (9) The trap #2 handler would simply enable hardware interrupts
+ (set PSR.PIL to 0), set ICC2.C to 1 and return.
+
+(10) Immediately upon returning, the pending interrupt would be taken.
+
+(11) The interrupt handler would take the path of actually processing the
+ interrupt (ICC2.Z is clear, BEQ fails as per step (2)).
+
+(12) The interrupt handler would then set ICC2.C to 1 since hardware
+ interrupts are definitely enabled - or else the kernel wouldn't be here.
+
+(13) On return from the interrupt handler, things would be back to state (1).
+
+This trap (#2) is only available in kernel mode. In user mode it will
+result in SIGILL.
git.openpandora.org / pandora-kernel.git / blobdiff