gcc/config/stormy16/stormy-abi

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