[mirror_ubuntu-artful-kernel.git] / Documentation / mn10300 / ABI.txt

			   =========================
			   MN10300 FUNCTION CALL ABI
			   =========================

=======
GENERAL
=======

The MN10300/AM33 kernel runs in little-endian mode; big-endian mode is not
supported.

The stack grows downwards, and should always be 32-bit aligned. There are
separate stack pointer registers for userspace and the kernel.


================
ARGUMENT PASSING
================

The first two arguments (assuming up to 32-bits per argument) to a function are
passed in the D0 and D1 registers respectively; all other arguments are passed
on the stack.

If 64-bit arguments are being passed, then they are never split between
registers and the stack. If the first argument is a 64-bit value, it will be
passed in D0:D1. If the first argument is not a 64-bit value, but the second
is, the second will be passed entirely on the stack and D1 will be unused.

Arguments smaller than 32-bits are not coalesced within a register or a stack
word. For example, two byte-sized arguments will always be passed in separate
registers or word-sized stack slots.


=================
CALLING FUNCTIONS
=================

The caller must allocate twelve bytes on the stack for the callee's use before
it inserts a CALL instruction. The CALL instruction will write into the TOS
word, but won't actually modify the stack pointer; similarly, the RET
instruction reads from the TOS word of the stack, but doesn't move the stack
pointer beyond it.


	Stack:
	|		|
	|		|
	|---------------| SP+20
	| 4th Arg	|
	|---------------| SP+16
	| 3rd Arg	|
	|---------------| SP+12
	| D1 Save Slot	|
	|---------------| SP+8
	| D0 Save Slot	|
	|---------------| SP+4
	| Return Addr	|
	|---------------| SP
	|		|
	|		|


The caller must leave space on the stack (hence an allocation of twelve bytes)
in which the callee may store the first two arguments.


============
RETURN VALUE
============

The return value is passed in D0 for an integer (or D0:D1 for a 64-bit value),
or A0 for a pointer.

If the return value is a value larger than 64-bits, or is a structure or an
array, then a hidden first argument will be passed to the callee by the caller:
this will point to a piece of memory large enough to hold the result of the
function. In this case, the callee will return the value in that piece of
memory, and no value will be returned in D0 or A0.


===================
REGISTER CLOBBERING
===================

The values in certain registers may be clobbered by the callee, and other
values must be saved:

	Clobber:	D0-D1, A0-A1, E0-E3
	Save:		D2-D3, A2-A3, E4-E7, SP

All other non-supervisor-only registers are clobberable (such as MDR, MCRL,
MCRH).


=================
SPECIAL REGISTERS
=================

Certain ordinary registers may carry special usage for the compiler:

	A3:	Frame pointer
	E2:	TLS pointer


==========
KERNEL ABI
==========

The kernel may use a slightly different ABI internally.

 (*) E2

     If CONFIG_MN10300_CURRENT_IN_E2 is defined, then the current task pointer
     will be kept in the E2 register, and that register will be marked
     unavailable for the compiler to use as a scratch register.

     Normally the kernel uses something like:

	MOV	SP,An
	AND	0xFFFFE000,An
	MOV	(An),Rm		// Rm holds current
	MOV	(yyy,Rm)	// Access current->yyy

     To find the address of current; but since this option permits current to
     be carried globally in an register, it can use:

	MOV	(yyy,E2)	// Access current->yyy

     instead.


===============
SYSTEM CALL ABI
===============

System calls are called with the following convention:

	REGISTER	ENTRY			EXIT
	===============	=======================	=======================
	D0		Syscall number		Return value
	A0		1st syscall argument	Saved
	D1		2nd syscall argument	Saved
	A3		3rd syscall argument	Saved
	A2		4th syscall argument	Saved
	D3		5th syscall argument	Saved
	D2		6th syscall argument	Saved

All other registers are saved.  The layout is a consequence of the way the MOVM
instruction stores registers onto the stack.
Commit	Line	Data
b920de1b DH	1	=========================
	2	MN10300 FUNCTION CALL ABI
	3	=========================
	4
	5	=======
	6	GENERAL
	7	=======
	8
	9	The MN10300/AM33 kernel runs in little-endian mode; big-endian mode is not
	10	supported.
	11
	12	The stack grows downwards, and should always be 32-bit aligned. There are
	13	separate stack pointer registers for userspace and the kernel.
	14
	15
	16	================
	17	ARGUMENT PASSING
	18	================
	19
	20	The first two arguments (assuming up to 32-bits per argument) to a function are
	21	passed in the D0 and D1 registers respectively; all other arguments are passed
	22	on the stack.
	23
	24	If 64-bit arguments are being passed, then they are never split between
	25	registers and the stack. If the first argument is a 64-bit value, it will be
	26	passed in D0:D1. If the first argument is not a 64-bit value, but the second
	27	is, the second will be passed entirely on the stack and D1 will be unused.
	28
19f59460	29	Arguments smaller than 32-bits are not coalesced within a register or a stack
b920de1b DH	30	word. For example, two byte-sized arguments will always be passed in separate
	31	registers or word-sized stack slots.
	32
	33
	34	=================
	35	CALLING FUNCTIONS
	36	=================
	37
	38	The caller must allocate twelve bytes on the stack for the callee's use before
	39	it inserts a CALL instruction. The CALL instruction will write into the TOS
	40	word, but won't actually modify the stack pointer; similarly, the RET
	41	instruction reads from the TOS word of the stack, but doesn't move the stack
	42	pointer beyond it.
	43
	44
	45	Stack:
	46	\| \|
	47	\| \|
	48	\|---------------\| SP+20
	49	\| 4th Arg \|
	50	\|---------------\| SP+16
	51	\| 3rd Arg \|
	52	\|---------------\| SP+12
	53	\| D1 Save Slot \|
	54	\|---------------\| SP+8
	55	\| D0 Save Slot \|
	56	\|---------------\| SP+4
	57	\| Return Addr \|
	58	\|---------------\| SP
	59	\| \|
	60	\| \|
	61
	62
	63	The caller must leave space on the stack (hence an allocation of twelve bytes)
	64	in which the callee may store the first two arguments.
	65
	66
	67	============
	68	RETURN VALUE
	69	============
	70
	71	The return value is passed in D0 for an integer (or D0:D1 for a 64-bit value),
	72	or A0 for a pointer.
	73
	74	If the return value is a value larger than 64-bits, or is a structure or an
	75	array, then a hidden first argument will be passed to the callee by the caller:
	76	this will point to a piece of memory large enough to hold the result of the
	77	function. In this case, the callee will return the value in that piece of
	78	memory, and no value will be returned in D0 or A0.
	79
	80
	81	===================
	82	REGISTER CLOBBERING
	83	===================
	84
	85	The values in certain registers may be clobbered by the callee, and other
	86	values must be saved:
	87
	88	Clobber: D0-D1, A0-A1, E0-E3
	89	Save: D2-D3, A2-A3, E4-E7, SP
	90
	91	All other non-supervisor-only registers are clobberable (such as MDR, MCRL,
	92	MCRH).
	93
94
95	=================
96	SPECIAL REGISTERS
97	=================
98
99	Certain ordinary registers may carry special usage for the compiler:
100
101	A3: Frame pointer
102	E2: TLS pointer
103
104
105	==========
106	KERNEL ABI
107	==========
108
109	The kernel may use a slightly different ABI internally.
110
111	(*) E2
112
113	If CONFIG_MN10300_CURRENT_IN_E2 is defined, then the current task pointer
114	will be kept in the E2 register, and that register will be marked
115	unavailable for the compiler to use as a scratch register.
116
117	Normally the kernel uses something like:
118
119	MOV SP,An
120	AND 0xFFFFE000,An
121	MOV (An),Rm // Rm holds current
122	MOV (yyy,Rm) // Access current->yyy
123
124	To find the address of current; but since this option permits current to
125	be carried globally in an register, it can use:
126
127	MOV (yyy,E2) // Access current->yyy
128
129	instead.
130
131
132	===============
133	SYSTEM CALL ABI
134	===============
135
136	System calls are called with the following convention:
137
138	REGISTER ENTRY EXIT
139	=============== ======================= =======================
140	D0 Syscall number Return value
141	A0 1st syscall argument Saved
142	D1 2nd syscall argument Saved
143	A3 3rd syscall argument Saved
144	A2 4th syscall argument Saved
145	D3 5th syscall argument Saved
146	D2 6th syscall argument Saved
147
148	All other registers are saved. The layout is a consequence of the way the MOVM
149	instruction stores registers onto the stack.