tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
metag: Basic documentation
Add basic metag documentation. This includes an outline description of
the ABIs (including syscall ABI) and calling conventions, similar to the
one in Documentation/frv/.
Signed-off-by: James Hogan <james.hogan@imgtec.com>
Cc: Rob Landley <rob@landley.net>
Cc: Al Viro <viro@ZenIV.linux.org.uk>
Cc: linux-doc@vger.kernel.org
+266
+2
Documentation/00-INDEX
+2
Documentation/00-INDEX
···
226
226
- Hotpluggable memory support, how to use and current status.
227
227
memory.txt
228
228
- info on typical Linux memory problems.
229
+
metag/
230
+
- directory with info about Linux on Meta architecture.
229
231
mips/
230
232
- directory with info about Linux on MIPS architecture.
231
233
mmc/
+4
Documentation/kernel-parameters.txt
+4
Documentation/kernel-parameters.txt
···
970
970
If specified, z/VM IUCV HVC accepts connections
971
971
from listed z/VM user IDs only.
972
972
973
+
hwthread_map= [METAG] Comma-separated list of Linux cpu id to
974
+
hardware thread id mappings.
975
+
Format: <cpu>:<hwthread>
976
+
973
977
keep_bootcon [KNL]
974
978
Do not unregister boot console at start. This is only
975
979
useful for debugging when something happens in the window
+4
Documentation/metag/00-INDEX
+4
Documentation/metag/00-INDEX
+256
Documentation/metag/kernel-ABI.txt
+256
Documentation/metag/kernel-ABI.txt
···
1
+
==========================
2
+
KERNEL ABIS FOR METAG ARCH
3
+
==========================
4
+
5
+
This document describes the Linux ABIs for the metag architecture, and has the
6
+
following sections:
7
+
8
+
(*) Outline of registers
9
+
(*) Userland registers
10
+
(*) Kernel registers
11
+
(*) System call ABI
12
+
(*) Calling conventions
13
+
14
+
15
+
====================
16
+
OUTLINE OF REGISTERS
17
+
====================
18
+
19
+
The main Meta core registers are arranged in units:
20
+
21
+
UNIT Type DESCRIPTION GP EXT PRIV GLOBAL
22
+
======= ======= =============== ======= ======= ======= =======
23
+
CT Special Control unit
24
+
D0 General Data unit 0 0-7 8-15 16-31 16-31
25
+
D1 General Data unit 1 0-7 8-15 16-31 16-31
26
+
A0 General Address unit 0 0-3 4-7 8-15 8-15
27
+
A1 General Address unit 1 0-3 4-7 8-15 8-15
28
+
PC Special PC unit 0 1
29
+
PORT Special Ports
30
+
TR Special Trigger unit 0-7
31
+
TT Special Trace unit 0-5
32
+
FX General FP unit 0-15
33
+
34
+
GP registers form part of the main context.
35
+
36
+
Extended context registers (EXT) may not be present on all hardware threads and
37
+
can be context switched if support is enabled and the appropriate bits are set
38
+
in e.g. the D0.8 register to indicate what extended state to preserve.
39
+
40
+
Global registers are shared between threads and are privilege protected.
41
+
42
+
See arch/metag/include/asm/metag_regs.h for definitions relating to core
43
+
registers and the fields and bits they contain. See the TRMs for further details
44
+
about special registers.
45
+
46
+
Several special registers are preserved in the main context, these are the
47
+
interesting ones:
48
+
49
+
REG (ALIAS) PURPOSE
50
+
======================= ===============================================
51
+
CT.1 (TXMODE) Processor mode bits (particularly for DSP)
52
+
CT.2 (TXSTATUS) Condition flags and LSM_STEP (MGET/MSET step)
53
+
CT.3 (TXRPT) Branch repeat counter
54
+
PC.0 (PC) Program counter
55
+
56
+
Some of the general registers have special purposes in the ABI and therefore
57
+
have aliases:
58
+
59
+
D0 REG (ALIAS) PURPOSE D1 REG (ALIAS) PURPOSE
60
+
=============== =============== =============== =======================
61
+
D0.0 (D0Re0) 32bit result D1.0 (D1Re0) Top half of 64bit result
62
+
D0.1 (D0Ar6) Argument 6 D1.1 (D1Ar5) Argument 5
63
+
D0.2 (D0Ar4) Argument 4 D1.2 (D1Ar3) Argument 3
64
+
D0.3 (D0Ar2) Argument 2 D1.3 (D1Ar1) Argument 1
65
+
D0.4 (D0FrT) Frame temp D1.4 (D1RtP) Return pointer
66
+
D0.5 Call preserved D1.5 Call preserved
67
+
D0.6 Call preserved D1.6 Call preserved
68
+
D0.7 Call preserved D1.7 Call preserved
69
+
70
+
A0 REG (ALIAS) PURPOSE A1 REG (ALIAS) PURPOSE
71
+
=============== =============== =============== =======================
72
+
A0.0 (A0StP) Stack pointer A1.0 (A1GbP) Global base pointer
73
+
A0.1 (A0FrP) Frame pointer A1.1 (A1LbP) Local base pointer
74
+
A0.2 A1.2
75
+
A0.3 A1.3
76
+
77
+
78
+
==================
79
+
USERLAND REGISTERS
80
+
==================
81
+
82
+
All the general purpose D0, D1, A0, A1 registers are preserved when entering the
83
+
kernel (including asynchronous events such as interrupts and timer ticks) except
84
+
the following which have special purposes in the ABI:
85
+
86
+
REGISTERS WHEN STATUS PURPOSE
87
+
=============== ======= =============== ===============================
88
+
D0.8 DSP Preserved ECH, determines what extended
89
+
DSP state to preserve.
90
+
A0.0 (A0StP) ALWAYS Preserved Stack >= A0StP may be clobbered
91
+
at any time by the creation of a
92
+
signal frame.
93
+
A1.0 (A1GbP) SMP Clobbered Used as temporary for loading
94
+
kernel stack pointer and saving
95
+
core context.
96
+
A0.15 !SMP Protected Stores kernel stack pointer.
97
+
A1.15 ALWAYS Protected Stores kernel base pointer.
98
+
99
+
On UP A0.15 is used to store the kernel stack pointer for storing the userland
100
+
context. A0.15 is global between hardware threads though which means it cannot
101
+
be used on SMP for this purpose. Since no protected local registers are
102
+
available A1GbP is reserved for use as a temporary to allow a percpu stack
103
+
pointer to be loaded for storing the rest of the context.
104
+
105
+
106
+
================
107
+
KERNEL REGISTERS
108
+
================
109
+
110
+
When in the kernel the following registers have special purposes in the ABI:
111
+
112
+
REGISTERS WHEN STATUS PURPOSE
113
+
=============== ======= =============== ===============================
114
+
A0.0 (A0StP) ALWAYS Preserved Stack >= A0StP may be clobbered
115
+
at any time by the creation of
116
+
an irq signal frame.
117
+
A1.0 (A1GbP) ALWAYS Preserved Reserved (kernel base pointer).
118
+
119
+
120
+
===============
121
+
SYSTEM CALL ABI
122
+
===============
123
+
124
+
When a system call is made, the following registers are effective:
125
+
126
+
REGISTERS CALL RETURN
127
+
=============== ======================= ===============================
128
+
D0.0 (D0Re0) Return value (or -errno)
129
+
D1.0 (D1Re0) System call number Clobbered
130
+
D0.1 (D0Ar6) Syscall arg #6 Preserved
131
+
D1.1 (D1Ar5) Syscall arg #5 Preserved
132
+
D0.2 (D0Ar4) Syscall arg #4 Preserved
133
+
D1.2 (D1Ar3) Syscall arg #3 Preserved
134
+
D0.3 (D0Ar2) Syscall arg #2 Preserved
135
+
D1.3 (D1Ar1) Syscall arg #1 Preserved
136
+
137
+
Due to the limited number of argument registers and some system calls with badly
138
+
aligned 64-bit arguments, 64-bit values are always packed in consecutive
139
+
arguments, even if this is contrary to the normal calling conventions (where the
140
+
two halves would go in a matching pair of data registers).
141
+
142
+
For example fadvise64_64 usually has the signature:
143
+
144
+
long sys_fadvise64_64(i32 fd, i64 offs, i64 len, i32 advice);
145
+
146
+
But for metag fadvise64_64 is wrapped so that the 64-bit arguments are packed:
147
+
148
+
long sys_fadvise64_64_metag(i32 fd, i32 offs_lo,
149
+
i32 offs_hi, i32 len_lo,
150
+
i32 len_hi, i32 advice)
151
+
152
+
So the arguments are packed in the registers like this:
153
+
154
+
D0 REG (ALIAS) VALUE D1 REG (ALIAS) VALUE
155
+
=============== =============== =============== =======================
156
+
D0.1 (D0Ar6) advice D1.1 (D1Ar5) hi(len)
157
+
D0.2 (D0Ar4) lo(len) D1.2 (D1Ar3) hi(offs)
158
+
D0.3 (D0Ar2) lo(offs) D1.3 (D1Ar1) fd
159
+
160
+
161
+
===================
162
+
CALLING CONVENTIONS
163
+
===================
164
+
165
+
These calling conventions apply to both user and kernel code. The stack grows
166
+
from low addresses to high addresses in the metag ABI. The stack pointer (A0StP)
167
+
should always point to the next free address on the stack and should at all
168
+
times be 64-bit aligned. The following registers are effective at the point of a
169
+
call:
170
+
171
+
REGISTERS CALL RETURN
172
+
=============== ======================= ===============================
173
+
D0.0 (D0Re0) 32bit return value
174
+
D1.0 (D1Re0) Upper half of 64bit return value
175
+
D0.1 (D0Ar6) 32bit argument #6 Clobbered
176
+
D1.1 (D1Ar5) 32bit argument #5 Clobbered
177
+
D0.2 (D0Ar4) 32bit argument #4 Clobbered
178
+
D1.2 (D1Ar3) 32bit argument #3 Clobbered
179
+
D0.3 (D0Ar2) 32bit argument #2 Clobbered
180
+
D1.3 (D1Ar1) 32bit argument #1 Clobbered
181
+
D0.4 (D0FrT) Clobbered
182
+
D1.4 (D1RtP) Return pointer Clobbered
183
+
D{0-1}.{5-7} Preserved
184
+
A0.0 (A0StP) Stack pointer Preserved
185
+
A1.0 (A0GbP) Preserved
186
+
A0.1 (A0FrP) Frame pointer Preserved
187
+
A1.1 (A0LbP) Preserved
188
+
A{0-1},{2-3} Clobbered
189
+
190
+
64-bit arguments are placed in matching pairs of registers (i.e. the same
191
+
register number in both D0 and D1 units), with the least significant half in D0
192
+
and the most significant half in D1, leaving a gap where necessary. Futher
193
+
arguments are stored on the stack in reverse order (earlier arguments at higher
194
+
addresses):
195
+
196
+
ADDRESS 0 1 2 3 4 5 6 7
197
+
=============== ===== ===== ===== ===== ===== ===== ===== =====
198
+
A0StP -->
199
+
A0StP-0x08 32bit argument #8 32bit argument #7
200
+
A0StP-0x10 32bit argument #10 32bit argument #9
201
+
202
+
Function prologues tend to look a bit like this:
203
+
204
+
/* If frame pointer in use, move it to frame temp register so it can be
205
+
easily pushed onto stack */
206
+
MOV D0FrT,A0FrP
207
+
208
+
/* If frame pointer in use, set it to stack pointer */
209
+
ADD A0FrP,A0StP,#0
210
+
211
+
/* Preserve D0FrT, D1RtP, D{0-1}.{5-7} on stack, incrementing A0StP */
212
+
MSETL [A0StP++],D0FrT,D0.5,D0.6,D0.7
213
+
214
+
/* Allocate some stack space for local variables */
215
+
ADD A0StP,A0StP,#0x10
216
+
217
+
At this point the stack would look like this:
218
+
219
+
ADDRESS 0 1 2 3 4 5 6 7
220
+
=============== ===== ===== ===== ===== ===== ===== ===== =====
221
+
A0StP -->
222
+
A0StP-0x08
223
+
A0StP-0x10
224
+
A0StP-0x18 Old D0.7 Old D1.7
225
+
A0StP-0x20 Old D0.6 Old D1.6
226
+
A0StP-0x28 Old D0.5 Old D1.5
227
+
A0FrP --> Old A0FrP (frame ptr) Old D1RtP (return ptr)
228
+
A0FrP-0x08 32bit argument #8 32bit argument #7
229
+
A0FrP-0x10 32bit argument #10 32bit argument #9
230
+
231
+
Function epilogues tend to differ depending on the use of a frame pointer. An
232
+
example of a frame pointer epilogue:
233
+
234
+
/* Restore D0FrT, D1RtP, D{0-1}.{5-7} from stack, incrementing A0FrP */
235
+
MGETL D0FrT,D0.5,D0.6,D0.7,[A0FrP++]
236
+
/* Restore stack pointer to where frame pointer was before increment */
237
+
SUB A0StP,A0FrP,#0x20
238
+
/* Restore frame pointer from frame temp */
239
+
MOV A0FrP,D0FrT
240
+
/* Return to caller via restored return pointer */
241
+
MOV PC,D1RtP
242
+
243
+
If the function hasn't touched the frame pointer, MGETL cannot be safely used
244
+
with A0StP as it always increments and that would expose the stack to clobbering
245
+
by interrupts (kernel) or signals (user). Therefore it's common to see the MGETL
246
+
split into separate GETL instructions:
247
+
248
+
/* Restore D0FrT, D1RtP, D{0-1}.{5-7} from stack */
249
+
GETL D0FrT,D1RtP,[A0StP+#-0x30]
250
+
GETL D0.5,D1.5,[A0StP+#-0x28]
251
+
GETL D0.6,D1.6,[A0StP+#-0x20]
252
+
GETL D0.7,D1.7,[A0StP+#-0x18]
253
+
/* Restore stack pointer */
254
+
SUB A0StP,A0StP,#0x30
255
+
/* Return to caller via restored return pointer */
256
+
MOV PC,D1RtP