1			==========================
2			KERNEL ABIS FOR METAG ARCH
3			==========================
4
5This document describes the Linux ABIs for the metag architecture, and has the
6following sections:
7
8 (*) Outline of registers
9 (*) Userland registers
10 (*) Kernel registers
11 (*) System call ABI
12 (*) Calling conventions
13
14
15====================
16OUTLINE OF REGISTERS
17====================
18
19The 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
34GP registers form part of the main context.
35
36Extended context registers (EXT) may not be present on all hardware threads and
37can be context switched if support is enabled and the appropriate bits are set
38in e.g. the D0.8 register to indicate what extended state to preserve.
39
40Global registers are shared between threads and are privilege protected.
41
42See arch/metag/include/asm/metag_regs.h for definitions relating to core
43registers and the fields and bits they contain. See the TRMs for further details
44about special registers.
45
46Several special registers are preserved in the main context, these are the
47interesting 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
56Some of the general registers have special purposes in the ABI and therefore
57have 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==================
79USERLAND REGISTERS
80==================
81
82All the general purpose D0, D1, A0, A1 registers are preserved when entering the
83kernel (including asynchronous events such as interrupts and timer ticks) except
84the 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
99On UP A0.15 is used to store the kernel stack pointer for storing the userland
100context. A0.15 is global between hardware threads though which means it cannot
101be used on SMP for this purpose. Since no protected local registers are
102available A1GbP is reserved for use as a temporary to allow a percpu stack
103pointer to be loaded for storing the rest of the context.
104
105
106================
107KERNEL REGISTERS
108================
109
110When 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===============
121SYSTEM CALL ABI
122===============
123
124When 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
137Due to the limited number of argument registers and some system calls with badly
138aligned 64-bit arguments, 64-bit values are always packed in consecutive
139arguments, even if this is contrary to the normal calling conventions (where the
140two halves would go in a matching pair of data registers).
141
142For example fadvise64_64 usually has the signature:
143
144	long sys_fadvise64_64(i32 fd, i64 offs, i64 len, i32 advice);
145
146But 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
152So 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===================
162CALLING CONVENTIONS
163===================
164
165These calling conventions apply to both user and kernel code. The stack grows
166from low addresses to high addresses in the metag ABI. The stack pointer (A0StP)
167should always point to the next free address on the stack and should at all
168times be 64-bit aligned. The following registers are effective at the point of a
169call:
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
19064-bit arguments are placed in matching pairs of registers (i.e. the same
191register number in both D0 and D1 units), with the least significant half in D0
192and the most significant half in D1, leaving a gap where necessary. Further
193arguments are stored on the stack in reverse order (earlier arguments at higher
194addresses):
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
202Function 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
217At 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
231Function epilogues tend to differ depending on the use of a frame pointer. An
232example 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
243If the function hasn't touched the frame pointer, MGETL cannot be safely used
244with A0StP as it always increments and that would expose the stack to clobbering
245by interrupts (kernel) or signals (user). Therefore it's common to see the MGETL
246split 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
257