1xStormy16 ABI
2************
3
4!!!!! NOTE !!!!!
5This document is a draft and is subject to change.
6!!!!! NOTE !!!!!
7
8This part of the file describes the conventions required to write
9ELF object files that are link-compatible with the ones produced
10by the GNU toolchains.
11
12Bit and Byte Ordering
13=====================
14
15This implementation is little-endian.   Bits are numbered starting
16from 0 being the LSB.
17
18In this document, 'word' means 16 bits.
19
20Calling Sequence
21================
22
23The registers are allocated as follows:
24
25Register	Purpose
26-------------------------------------------------------------------
27r0, r1          Call-volatile.  May be changed during the execution
28                of a call instruction.
29r2 through r7   Argument passing;  call-clobbered.
30r8, r9		Call-volatile.  May be changed during the execution
31		of a call instruction.
32r10 through r13	Call-saved.
33r14		Program status word.
34r15		Stack pointer.
35
36
37Scalar values are returned in register r2-r7 if the value fits.
38Otherwise, a pointer is passed as a 'hidden' first argument and
39the return value is placed there.
40
41Arguments are passed in registers starting in r2, then on the stack.
42Arguments of size not a multiple of a word are padded to whole words.
43If an argument would otherwise be passed partially in registers, and
44partially on the stack, the whole of it is passed on the stack.  The
45last argument is pushed on the stack first.
46
47After a procedure's arguments are pushed on the stack,
48the return address is pushed on the stack, as if by the call
49instruction.  The return address is on the top of the stack when
50a procedure is called.
51
52Objects whose size is a multiple of 16 bits are aligned to a 16-bit
53boundary.
54
55Pointers are 16 bits, referencing addresses between 0 and 0xFFFF.
56
57Procedure pointers are also implemented as 16-bit pointers.
58
59Variable Argument Functions
60===========================
61
62The C type 'va_list' is implemented as a structure, as follows:
63
64struct {
65  char *base;
66  unsigned count;
67}
68
69Both fields are 16 bits.  An argument of size N bytes
70(N will be even) is accessed as if by the following code:
71
72char *result;
73/* count = #bytes non-variable arguments */
74/* 12 = #bytes for register arguments */
75if (count + N > 12)
76  {
77    if (count < 12)
78      count = 12;
79    result = base - (count + N - 12 + 4);
80  }
81else
82  {
83    result = base + count;
84  }
85count += N;
86/* The argument is at `*result'.  */
87
88
89One implementation of this is if a variadic function first
90pushes registers 2 through 7 in sequence at entry, and
91sets 'base' to the address of the first word pushed,
92producing a stack that appears like:
93
94SP ->
95	[other data]
96	r7
97	r6
98	r5
99	r4
100	r3
101count->	r2
102	Return address (two words)
103	7th procedure parameter word
104	8th procedure parameter word
105	...
106	last procedure parameter word
107
108and initializes 'count' to be the number of bytes of non-variable
109arguments to the function.
110
111ELF File Format
112===============
113
114ELF file header
115---------------
116
117xStormy16 ELF files are distinguished by the value EM_XSTORMY16 in
118the e_machine field of the ELF file header:
119
120#define EM_XSTORMY16	        0xad45
121
122DWARF Register Number Mapping
123-----------------------------
124
125Registers r0 through r15 are mapped to numbers 0 through 15.
126
127Relocations
128-----------
129
130RELA relocs are used exclusively.  The relocation types defined are:
131
132Name			Value	Field	Calculation	Overflow
133----------------------------------------------------------------
134R_XSTORMY16_NONE		0	none	none		none
135R_XSTORMY16_32		1	32	S + A		none
136R_XSTORMY16_16		2	16	S + A		unsigned
137R_XSTORMY16_8		3	8	S + A		unsigned
138R_XSTORMY16_PC32		4	32	S + A - P	none
139R_XSTORMY16_PC16		5	16	S + A - P	signed
140R_XSTORMY16_PC8		6	8	S + A - P	signed
141R_XSTORMY16_REL_12	7	16:12:0	S + A - P	signed
142R_XSTORMY16_24		8	32:23:1	(S + A) >> 1	unsigned
143R_XSTORMY16_GNU_VTINHERIT 9	n/a	n/a		n/a
144R_XSTORMY16_GNU_VTENTRY	10	n/a	n/a		n/a
145
146In the 'Calculation' column, 'S' is the value of the symbol to which
147the reloc refers, 'A' is the addend, and 'P' represents the place of
148the storage unit being relocated.
149
150In the 'Field' column, the first number indicates whether the
151relocation refers to a byte, word or doubleword.  The second number,
152if any, indicates the size of the bit-field into which the relocation
153is to occur (and also the size for overflow checking).  The third
154number indicates the first bit of the bit-field in the word or
155doubleword, counting the LSB as bit 0.
156