blob: 8b0a5fc8bfd96cc64fe09f165b740f272196f654 [file] [log] [blame]
Horms08039262006-04-01 01:38:15 +02001 =================================
2 INTERNAL KERNEL ABI FOR FR-V ARCH
3 =================================
David Howells28baeba2006-02-14 13:53:20 -08004
Horms08039262006-04-01 01:38:15 +02005The internal FRV kernel ABI is not quite the same as the userspace ABI. A
6number of the registers are used for special purposed, and the ABI is not
7consistent between modules vs core, and MMU vs no-MMU.
David Howells28baeba2006-02-14 13:53:20 -08008
Horms08039262006-04-01 01:38:15 +02009This partly stems from the fact that FRV CPUs do not have a separate
10supervisor stack pointer, and most of them do not have any scratch
11registers, thus requiring at least one general purpose register to be
12clobbered in such an event. Also, within the kernel core, it is possible to
13simply jump or call directly between functions using a relative offset.
14This cannot be extended to modules for the displacement is likely to be too
15far. Thus in modules the address of a function to call must be calculated
16in a register and then used, requiring two extra instructions.
David Howells28baeba2006-02-14 13:53:20 -080017
18This document has the following sections:
19
20 (*) System call register ABI
21 (*) CPU operating modes
22 (*) Internal kernel-mode register ABI
23 (*) Internal debug-mode register ABI
24 (*) Virtual interrupt handling
25
26
27========================
28SYSTEM CALL REGISTER ABI
29========================
30
31When a system call is made, the following registers are effective:
32
33 REGISTERS CALL RETURN
34 =============== ======================= =======================
35 GR7 System call number Preserved
36 GR8 Syscall arg #1 Return value
37 GR9-GR13 Syscall arg #2-6 Preserved
38
39
40===================
41CPU OPERATING MODES
42===================
43
Horms08039262006-04-01 01:38:15 +020044The FR-V CPU has three basic operating modes. In order of increasing
45capability:
David Howells28baeba2006-02-14 13:53:20 -080046
47 (1) User mode.
48
49 Basic userspace running mode.
50
51 (2) Kernel mode.
52
Horms08039262006-04-01 01:38:15 +020053 Normal kernel mode. There are many additional control registers
54 available that may be accessed in this mode, in addition to all the
55 stuff available to user mode. This has two submodes:
David Howells28baeba2006-02-14 13:53:20 -080056
57 (a) Exceptions enabled (PSR.T == 1).
58
Horms08039262006-04-01 01:38:15 +020059 Exceptions will invoke the appropriate normal kernel mode
60 handler. On entry to the handler, the PSR.T bit will be cleared.
David Howells28baeba2006-02-14 13:53:20 -080061
62 (b) Exceptions disabled (PSR.T == 0).
63
Horms08039262006-04-01 01:38:15 +020064 No exceptions or interrupts may happen. Any mandatory exceptions
65 will cause the CPU to halt unless the CPU is told to jump into
66 debug mode instead.
David Howells28baeba2006-02-14 13:53:20 -080067
68 (3) Debug mode.
69
Horms08039262006-04-01 01:38:15 +020070 No exceptions may happen in this mode. Memory protection and
71 management exceptions will be flagged for later consideration, but
72 the exception handler won't be invoked. Debugging traps such as
73 hardware breakpoints and watchpoints will be ignored. This mode is
74 entered only by debugging events obtained from the other two modes.
David Howells28baeba2006-02-14 13:53:20 -080075
Horms08039262006-04-01 01:38:15 +020076 All kernel mode registers may be accessed, plus a few extra debugging
77 specific registers.
David Howells28baeba2006-02-14 13:53:20 -080078
79
80=================================
81INTERNAL KERNEL-MODE REGISTER ABI
82=================================
83
Horms08039262006-04-01 01:38:15 +020084There are a number of permanent register assignments that are set up by
85entry.S in the exception prologue. Note that there is a complete set of
86exception prologues for each of user->kernel transition and kernel->kernel
87transition. There are also user->debug and kernel->debug mode transition
88prologues.
David Howells28baeba2006-02-14 13:53:20 -080089
90
91 REGISTER FLAVOUR USE
Horms08039262006-04-01 01:38:15 +020092 =============== ======= ==============================================
David Howells28baeba2006-02-14 13:53:20 -080093 GR1 Supervisor stack pointer
94 GR15 Current thread info pointer
95 GR16 GP-Rel base register for small data
96 GR28 Current exception frame pointer (__frame)
97 GR29 Current task pointer (current)
98 GR30 Destroyed by kernel mode entry
99 GR31 NOMMU Destroyed by debug mode entry
100 GR31 MMU Destroyed by TLB miss kernel mode entry
101 CCR.ICC2 Virtual interrupt disablement tracking
Horms08039262006-04-01 01:38:15 +0200102 CCCR.CC3 Cleared by exception prologue
103 (atomic op emulation)
David Howells28baeba2006-02-14 13:53:20 -0800104 SCR0 MMU See mmu-layout.txt.
105 SCR1 MMU See mmu-layout.txt.
Horms08039262006-04-01 01:38:15 +0200106 SCR2 MMU Save for EAR0 (destroyed by icache insns
107 in debug mode)
David Howells28baeba2006-02-14 13:53:20 -0800108 SCR3 MMU Save for GR31 during debug exceptions
109 DAMR/IAMR NOMMU Fixed memory protection layout.
110 DAMR/IAMR MMU See mmu-layout.txt.
111
112
113Certain registers are also used or modified across function calls:
114
115 REGISTER CALL RETURN
Horms08039262006-04-01 01:38:15 +0200116 =============== =============================== ======================
David Howells28baeba2006-02-14 13:53:20 -0800117 GR0 Fixed Zero -
118 GR2 Function call frame pointer
119 GR3 Special Preserved
120 GR3-GR7 - Clobbered
Horms08039262006-04-01 01:38:15 +0200121 GR8 Function call arg #1 Return value
122 (or clobbered)
123 GR9 Function call arg #2 Return value MSW
124 (or clobbered)
David Howells28baeba2006-02-14 13:53:20 -0800125 GR10-GR13 Function call arg #3-#6 Clobbered
126 GR14 - Clobbered
127 GR15-GR16 Special Preserved
128 GR17-GR27 - Preserved
Horms08039262006-04-01 01:38:15 +0200129 GR28-GR31 Special Only accessed
130 explicitly
David Howells28baeba2006-02-14 13:53:20 -0800131 LR Return address after CALL Clobbered
132 CCR/CCCR - Mostly Clobbered
133
134
135================================
136INTERNAL DEBUG-MODE REGISTER ABI
137================================
138
Horms08039262006-04-01 01:38:15 +0200139This is the same as the kernel-mode register ABI for functions calls. The
140difference is that in debug-mode there's a different stack and a different
141exception frame. Almost all the global registers from kernel-mode
142(including the stack pointer) may be changed.
David Howells28baeba2006-02-14 13:53:20 -0800143
144 REGISTER FLAVOUR USE
Horms08039262006-04-01 01:38:15 +0200145 =============== ======= ==============================================
David Howells28baeba2006-02-14 13:53:20 -0800146 GR1 Debug stack pointer
147 GR16 GP-Rel base register for small data
Horms08039262006-04-01 01:38:15 +0200148 GR31 Current debug exception frame pointer
149 (__debug_frame)
David Howells28baeba2006-02-14 13:53:20 -0800150 SCR3 MMU Saved value of GR31
151
152
Horms08039262006-04-01 01:38:15 +0200153Note that debug mode is able to interfere with the kernel's emulated atomic
154ops, so it must be exceedingly careful not to do any that would interact
155with the main kernel in this regard. Hence the debug mode code (gdbstub) is
156almost completely self-contained. The only external code used is the
157sprintf family of functions.
David Howells28baeba2006-02-14 13:53:20 -0800158
Horms08039262006-04-01 01:38:15 +0200159Futhermore, break.S is so complicated because single-step mode does not
160switch off on entry to an exception. That means unless manually disabled,
161single-stepping will blithely go on stepping into things like interrupts.
162See gdbstub.txt for more information.
David Howells28baeba2006-02-14 13:53:20 -0800163
164
165==========================
166VIRTUAL INTERRUPT HANDLING
167==========================
168
Horms08039262006-04-01 01:38:15 +0200169Because accesses to the PSR is so slow, and to disable interrupts we have
170to access it twice (once to read and once to write), we don't actually
171disable interrupts at all if we don't have to. What we do instead is use
172the ICC2 condition code flags to note virtual disablement, such that if we
173then do take an interrupt, we note the flag, really disable interrupts, set
174another flag and resume execution at the point the interrupt happened.
175Setting condition flags as a side effect of an arithmetic or logical
176instruction is really fast. This use of the ICC2 only occurs within the
David Howells28baeba2006-02-14 13:53:20 -0800177kernel - it does not affect userspace.
178
179The flags we use are:
180
181 (*) CCR.ICC2.Z [Zero flag]
182
Horms08039262006-04-01 01:38:15 +0200183 Set to virtually disable interrupts, clear when interrupts are
184 virtually enabled. Can be modified by logical instructions without
185 affecting the Carry flag.
David Howells28baeba2006-02-14 13:53:20 -0800186
187 (*) CCR.ICC2.C [Carry flag]
188
189 Clear to indicate hardware interrupts are really disabled, set otherwise.
190
191
192What happens is this:
193
194 (1) Normal kernel-mode operation.
195
196 ICC2.Z is 0, ICC2.C is 1.
197
Horms08039262006-04-01 01:38:15 +0200198 (2) An interrupt occurs. The exception prologue examines ICC2.Z and
199 determines that nothing needs doing. This is done simply with an
200 unlikely BEQ instruction.
David Howells28baeba2006-02-14 13:53:20 -0800201
202 (3) The interrupts are disabled (local_irq_disable)
203
204 ICC2.Z is set to 1.
205
206 (4) If interrupts were then re-enabled (local_irq_enable):
207
208 ICC2.Z would be set to 0.
209
Horms08039262006-04-01 01:38:15 +0200210 A TIHI #2 instruction (trap #2 if condition HI - Z==0 && C==0) would
211 be used to trap if interrupts were now virtually enabled, but
212 physically disabled - which they're not, so the trap isn't taken. The
213 kernel would then be back to state (1).
David Howells28baeba2006-02-14 13:53:20 -0800214
Horms08039262006-04-01 01:38:15 +0200215 (5) An interrupt occurs. The exception prologue examines ICC2.Z and
216 determines that the interrupt shouldn't actually have happened. It
217 jumps aside, and there disabled interrupts by setting PSR.PIL to 14
218 and then it clears ICC2.C.
David Howells28baeba2006-02-14 13:53:20 -0800219
220 (6) If interrupts were then saved and disabled again (local_irq_save):
221
Horms08039262006-04-01 01:38:15 +0200222 ICC2.Z would be shifted into the save variable and masked off
223 (giving a 1).
David Howells28baeba2006-02-14 13:53:20 -0800224
Horms08039262006-04-01 01:38:15 +0200225 ICC2.Z would then be set to 1 (thus unchanged), and ICC2.C would be
226 unaffected (ie: 0).
David Howells28baeba2006-02-14 13:53:20 -0800227
228 (7) If interrupts were then restored from state (6) (local_irq_restore):
229
Horms08039262006-04-01 01:38:15 +0200230 ICC2.Z would be set to indicate the result of XOR'ing the saved
231 value (ie: 1) with 1, which gives a result of 0 - thus leaving
232 ICC2.Z set.
David Howells28baeba2006-02-14 13:53:20 -0800233
234 ICC2.C would remain unaffected (ie: 0).
235
Horms08039262006-04-01 01:38:15 +0200236 A TIHI #2 instruction would be used to again assay the current state,
237 but this would do nothing as Z==1.
David Howells28baeba2006-02-14 13:53:20 -0800238
239 (8) If interrupts were then enabled (local_irq_enable):
240
Horms08039262006-04-01 01:38:15 +0200241 ICC2.Z would be cleared. ICC2.C would be left unaffected. Both
242 flags would now be 0.
David Howells28baeba2006-02-14 13:53:20 -0800243
Horms08039262006-04-01 01:38:15 +0200244 A TIHI #2 instruction again issued to assay the current state would
245 then trap as both Z==0 [interrupts virtually enabled] and C==0
246 [interrupts really disabled] would then be true.
David Howells28baeba2006-02-14 13:53:20 -0800247
Horms08039262006-04-01 01:38:15 +0200248 (9) The trap #2 handler would simply enable hardware interrupts
249 (set PSR.PIL to 0), set ICC2.C to 1 and return.
David Howells28baeba2006-02-14 13:53:20 -0800250
251(10) Immediately upon returning, the pending interrupt would be taken.
252
Horms08039262006-04-01 01:38:15 +0200253(11) The interrupt handler would take the path of actually processing the
254 interrupt (ICC2.Z is clear, BEQ fails as per step (2)).
David Howells28baeba2006-02-14 13:53:20 -0800255
Horms08039262006-04-01 01:38:15 +0200256(12) The interrupt handler would then set ICC2.C to 1 since hardware
257 interrupts are definitely enabled - or else the kernel wouldn't be here.
David Howells28baeba2006-02-14 13:53:20 -0800258
259(13) On return from the interrupt handler, things would be back to state (1).
260
Horms08039262006-04-01 01:38:15 +0200261This trap (#2) is only available in kernel mode. In user mode it will
262result in SIGILL.