@c Copyright (C) 1995 Free Software Foundation, Inc.

@menu
* Introduction::
* Low Level System Information::
* Object Files::
* Program Loading and Dynamic Linking::
@end menu

@node Introduction
@section MA-TRI-ARC Application Binary Interface (Draft)

@display
Version: 1.2
Date: 950528
Author: Doug Evans
Email: dje@@cygnus.com
@end display

This document is a draft of the MA-TRI-ARC Application Binary Interface (ABI).
The decimal part of the version number is incremented when incompatible
changes are made.

Note that this is not an official document for anything other than the
GNU toolchain.  However, it is intended to be generally applicable.

The reader is assumed to have access to the following documents.

@enumerate 1
@item
AT&T System V Application Binary Interface;
Published by Prentice Hall
(ISBN: 0-13-877598-2)

@item
AT&T System V Application Binary Interface,
SPARC Processor Supplement;
Published by Prentice Hall
(ISBN 0-13-877630-X)

@item
AT&T System V Application Binary Interface,
MIPS Processor Supplement;
Published by Prentice Hall
(ISBN 0-13-880170-3)
@footnote{This book is apparently out of print.  Attempts are being made
to find the relevant details in electronic form.}
@end enumerate

These documents provide more than we need since they define an ABI for
Unix systems, but we can use them as a base for defining an ABI for
embedded systems like the MA-TRI-ARC.  The processor specific information
is, of course, not relevant to the ARC, but we will use the SPARC and MIPS
processor supplements as guides both in content and in the style of this
manual.  The main document (1) defines the ELF object file format which is
used on the MA-TRI-ARC and other things of a general nature upon which
the processor supplements are built.

The following ARC processor documents are also refered to:

@enumerate 4
@item
ARC Programmers Reference Manual,
Version: 5.02@*
Date: 941018

@item
Sliced Bread Project: Console Main Application Specific Integrated
Circuit (ASIC) 
(Design Specification)
@*
Version: 1.8.1 (SBP Document Number: SBP-D492)
@end enumerate

The rest of this document will follow the general format of System V ABI
Processor Supplements.  In many cases, we will refer directly to the above
documents.

Unresolved issues will be denoted with "???".

@node Low Level System Information
@section Low Level System Information

@menu
* Data Representation::
* Function Calling Sequence::
* Coding Examples::
@end menu

@node Data Representation
@subsection Data Representation

@subheading Byte Order

The MA-TRI-ARC is "little endian".

The ARC itself is bi-endian but we will use little endian here.

@subheading Fundamental Types

Refer to the MIPS ABI Supplement, page 3-4, figure 3-5 "Scalar Types".
All information is identical.  Other ARC documents refer to a "word"
as a two byte quantity.  This document defines a "word" to be a four
byte quantity.

Floating point data representation is IEEE 754.

Pointers to functions have the following additional specification.
A pointer to a function shall have the same format as the STATUS
register (that is the address is right shifted by two), and all flag
bits shall be 0.

GNU C supports the following additional data types.  They are not part
of this ABI as not all C compilers support them.  Nor are they in the
ANSI/ISO C standard and portable code should not use them.

@smallexample
C data type = long long, sizeof = 8, alignment = 8
C data type = __complex__ int, sizeof = 8, alignment = 4
C data type = __complex__ float, sizeof = 8, alignment = 4
C data type = __complex__ double, sizeof = 16, alignment = 8
@end smallexample

See the GNU C manual for more information on these data types.

@subheading Aggregates and Unions

Refer to the MIPS ABI Supplement, page 3-4 "Aggregates and Unions".
All information is identical.

@subheading Bit-Fields

Refer to the MIPS ABI Supplement, page 3-8 "Bit-Fields".
All information is identical with the following exceptions.

@display
1) Since the MA-TRI-ARC is little endian, replace Figure 3-12 with

@smallexample
           +--------+--------+--------+--------+
           |0       |1       |2       |3       |
0x01020304 |   04   |   03   |   02   |   01   |
           |7      0|15     8|23    16|31    24|
           +--------+--------+--------+--------+
@end smallexample

With endian-ness taken into account, the rest of the examples are
identical.
@end display

@node Function Calling Sequence
@subsection Function Calling Sequence

@subheading CPU Registers

The ARC is defined in two parts.  The "base" ARC defines the basic ARC cpu
and is applicable to all ARC variants.  One can then add to the base ARC
enhancements that tune the cpu to the particular task it is intended to
perform.  This document defines only the base ARC, but it shall apply to
all ARC variants.  Refer to (5) for additional register information on the
three known ARC variants (host, graphics, and audio).

@smallexample
Register Name       Use
(software name)
------------------------------------------------------------
r0 - r7             Used for passing arguments to functions.
                    Additional argumentsare passed on the
                    stack (see below).  r0,r1 is also used
                    to return the result of function calls.
                    The values of these registers are not
                    preserved across function calls.

r8 - r15            Temporary registers for expression
                    evaluation.  The values of these
                    registers are not preserved across
                    function calls.

r16 - r23           Temporary registers for expression
                    evaluation.  The values of these
                    registers are preserved across function
                    calls.

r24, r25            Temporary registers for expression
                    evaluation.  The values of these
                    registers are not preserved across
                    function calls.  r24 is also used as
                    the static chain pointer in nested
                    functions (a GNU C extension), and may
                    not be used in the function calling
                    sequence or prologue of functions.
                    r25 is reserved for use in the PIC
                    calling sequence (if ever necessary),
                    and may not be used in the function
                    calling sequence or the prologue of
                    functions.

r26 (gp)            Global pointer and context pointer.
                    This register is call saved.

r27 (fp)            Frame pointer.

r28 (sp)            Stack pointer.

Special CPU Registers
---------------------

r29 (ilink1)        Interrupt 1 link register.

r30 (ilink2)        Interrupt 2 link register.

r31 (blink)         Branch link register.  The value is
                    the address to which the function
                    should return control.

r32 - r59           Reserved for ARC extensions.

r60 (lp_count)      Loop count register.

r61 - r63           Reserved for encoding immediate
                    data.
@end smallexample

@subheading Floating Point Registers

The base ARC has no floating point registers and neither do any of the
currently defined extensions.  However, this ABI does not preclude them
in any way.

@subheading The Stack Frame

The generic information regarding stack frames in the MIPS ABI Supplement
apply here.  In particular:

@enumerate
@item
The stack grows downwards from high addresses to low addresses.
@item
A leaf function need not allocate a stack frame if it doesn't need one.
@item
A frame pointer need not be allocated.
@item
The stack pointer shall always be aligned to 8 byte boundaries
The hardware doesn't require this, but the alignment is kept
stricter for future considerations.
@item
The register save area shall be aligned to an 8 byte boundary.
@end enumerate

Stack frames for functions that take a fixed number of arguments
look like:

@smallexample
            Before call                     After call
 FP+0->+---------------------+       +---------------------+
       |                     |       |                     |
  high | local variables,    |       | local variables,    |
  mem  | reg save area, etc. |       | reg save area, etc. |
       |                     |       |                     |
       +---------------------+       +---------------------+
       |                     |       |                     |
       | arguments on stack  |       | arguments on stack  |
       |                     |       |                     |
FP+16->+---------------------+FP+16->+---------------------+
       | reserved (4 bytes)  |       | reserved (4 bytes)  |
       | prev gp save area   |       | prev gp save area   |
       | return addr save    |       | return addr save    |
       | prev fp save area   |       | prev fp save area   |
 SP+0->+---------------------+ FP+0->+---------------------+
                                     |                     |
                                     | local variables     |
                                     |                     |
                                     +---------------------+
                                     |                     |
                                     | register save area  |
                                     |                     |
                                     +---------------------+
                                     |                     |
                                     | alloca allocations  |
                                     |                     |
                                     +---------------------+
                                     |                     |
                                     | arguments on stack  |
                                     |                     |
                              SP+16->+---------------------+
 low                                 | 4 word save area    |
 memory                              | for return addr,    |
                                     | etc.                |
                               SP+0->+---------------------+

Stack frames for functions that take a variable number of
arguments look like:

            Before call                     After call
 FP+0->+---------------------+       +---------------------+
       |                     |       |                     |
  high | local variables,    |       | local variables,    |
  mem  | reg save area, etc. |       | reg save area, etc. |
       |                     |       |                     |
       +---------------------+       +---------------------+
       |                     |       |                     |
       | arguments on stack  |       | arguments on stack  |
       |                     |       |                     |
SP+16->+---------------------+FP+48->+---------------------+
       | PIC return addr     |       |                     |
       | prev gp save area   |       | save area for       |
       | return addr save    |       | anonymous parms     |
       | prev fp save area   |       | passed in registers |
 SP+0->+---------------------+       | (the size of this   |
                                     |  area may be zero)  |
                                     |                     |
                              FP+16->+---------------------+
                                     | 4 word save area    |
                                     | for return addr,    |
                                     | etc.                |
                               FP+0->+---------------------+
                                     |                     |
                                     | local variables     |
                                     |                     |
                                     +---------------------+
                                     |                     |
                                     | register save area  |
                                     |                     |
                                     +---------------------+
                                     |                     |
                                     | alloca allocations  |
                                     |                     |
                                     +---------------------+
                                     |                     |
                                     | arguments on stack  |
                                     |                     |
                              SP+16->+---------------------+
 low                                 | 4 word save area    |
 memory                              | for return addr,    |
                                     | etc.                |
                               SP+0->+---------------------+
@end smallexample

Notes:
@enumerate
@item
fp,blink are saved in the *caller's* frame at sp,sp+4 respectively.
The reason for doing it this way is that it allows for a more efficient
prologue/epilogue.
@item
PIC function entry stubs are responsible for setting/restoring `gp'.
These stubs use sp+8,sp+12 to save/restore the previous `gp' and return
address respectively.
@end enumerate

@subheading Standard Called Function Rules

To simplify stack back-tracing and prologue parsing, the following rules
must be adhered to.
@*
??? These rules may be relaxed in the future as the ABI develops.

Prologue:

@enumerate
@item
The first thing a function with a variable number of arguments must do
is allocate room for the anonymous arguments passed in registers,
rounded up to a multiple of 8 (to keep the stack 8 byte aligned).  If
no anonymous arguments are passed in registers, then no additional
space shall be allocated.
@*
EG: sub sp,sp,32.
@item
If the function is a non-leaf function, blink must be saved next.
@*
IE: st blink,[sp,4]
@item
If a frame pointer exists, it must be set up next.
@*
IE: st fp,[sp] ; mov fp,sp
@item
If a stack frame exists, it must be allocated next.
Since the ARC supports 32 bit immediate data, the stack frame must be
set up with one instruction (either an `add' or a `sub').
@*
IE: sub sp,sp,X (where X is the size of the stack frame)
@item
If call-saved registers are used, they must be saved next.
They must be saved as offsets from the stack pointer.
@item
All instructions in the prologue must occur in the first basic block
of the function.
@item
The registers used in the calling sequence (r0-r7) must be saved to
stack in varargs function at some point, but when is unspecified.
@*
??? Will we need to specify it for debuggers (at least in non-optimized
code) ?
@end enumerate

Epilogue:

@enumerate
@item
There must be only one exit point from a function; which is a jump to
the blink instruction (which may have a delay slot).
@item
The frame pointer must be restored with an ld.a instruction that
also restores the stack pointer.
@*
IE: ld.a fp,[sp,X] (where X is the size of the frame).
@item
The delay slot of a function which takes a variable number of arguments
must be "add sp,sp,N" where `N' is the number of bytes of anonymous
arguments passed in registers.
@item
All instructions in the epilogue must occur in the last basic block
of the function.
@end enumerate

Notes:

@enumerate
@item
PIC functions can assume `gp' is correct and they needn't do anything
special to set/restore it (that is the PLT/PET's job).
@item
These rules needn't be followed by interrupt handlers.
@*
(??? Will we want any rules for them?)
@end enumerate

@subheading Argument Passing

Arguments are passed to a function using first registers and then memory
if the argument passing registers are used up.  Each register is assigned
an argument until all are used.   Unused argument registers have undefined
values on entry.  The following rules must be adhered to.

@enumerate
@item
All integral arguments in registers smaller than a word (32 bits) must
be passed as properly sign extended 32 bit words.  That is, even
signed and unsigned "char" and "short" arguments can be properly
referenced as 32 bit values.
@item
Scalar quantities (integers and floats) of 8 bytes or less are passed
in registers if available, then memory.  Larger scalar quantities are
passed by reference.
@item
All aggregates (structures and unions) are passed by reference.
@item
Arguments passed by reference are passed using the "callee copies"
rule. That is, the caller passes a pointer to the "live" value and it
is the callee's responsibility to make a copy if the value will be
modified.
@*
??? A possible exception to this rule is arguments that match the
ellipsis of a variable argument function, here the caller makes a copy.
@item
The data types specified by this ABI are never passed in registers
and memory.  Structures are never passed in regs and scalar types
can't be due to alignment requirements.  The exception to this rule
are the complex data types having 4 byte alignment (or less), but
these data types are not part of this ABI.  If the first 7 registers
are in use and the next argument is a complex float, for example,
the first word is passed in register r7 and the next word is passed
in memory.
@item
If the called function returns an aggregate, the caller passes
the address of an area large enough to receive the result in r0,
the first argument register.  All arguments are then shifted down
by one.
@item
Arguments passed on the stack begin at sp+16 with respect to the
caller (and fp+16 with respect to the callee).  Space for all
arguments is rounded up to a multiple of 4 bytes or their alignment
requirements, which ever is larger.
@end enumerate

@subheading Function Return Values

Integers and floating point values 8 bytes or less are returned
in register r0 (and r1 if necessary).

Aggregates are returned by having the caller pass the address of a
buffer to hold the value in r0 as an "invisible" first argument.
The address of this buffer is returned in r0.

@subheading Operating System Interface

Since this is an embedded system this section is irrelevant, except to
say that the page size is 4k (??? what this means is open to discussion).

@node Coding Examples
@subsection Coding Examples

The general descriptive text in either (2) or (3) apply here.

Embedded ARC applications can follow either the "absolute" or
"position independent" model.

@subheading Code Model Overview

The standard method for accessing globals in Position Independent
Code (PIC) is via a "Global Offset Table" (GOT).  This table holds
the addresses of globals accessed by the program.  Such accesses
require an extra indirection to fetch the address out of the table
and since this is an embedded environment the speed penalty is
unacceptable.  The solution chosen is to not provide support for
global variables common to multiple images in the ABI and leave it
up to the programmer to handle it (*).  This can be done by either
fixing the address of an object at link time or providing a function
that returns the address of the object.  That leaves globals accessible
within the image.  These shall be accessed off of a "global pointer".

(*) GOTs could be added at a future date if necessary.

The other standard technique that makes PIC work in Unix systems is
to keep the text and data segments at the same relative offsets from
each other.  They can be loaded anywhere, but the relative offset
between them must remain constant.  This allows one to store the
necessary offsets from an object in one to an object in another in the
image and all that remains to be done is add the load address to that
offset. In an embedded situation that won't work because ROM and RAM
live at fixed addresses and maintaining a fixed offset from the text
segment of an image to its data segment is impossible.

The MIPS and SPARC ABIs give various examples for accessing variables
and calling functions in both the absolute and position independent
code models.  Since the ARC can access objects with a full 32 bit address,
examples for the absolute code model are pretty trivial and won't be
described here.

Objects living in ROM can be accessed using the absolute code model:
the addresses of these objects is known at link time and will not change.
This won't be true, however, if more than one slot is available to plug a
ROM cartridge into.  Presumably each slot will have a fixed address, but
either slot may be used.  Fortunately, the relative offset between text
and data in ROM is constant.

@subheading Position Independent Function Prologue

PIC function prologues and epilogues are identical to non-PIC functions.

@subheading Data Objects

Data objects in PIC mode are kept in a "Global Data Area" and are
accessed via the `gp' register.  The Global Data Area consists of
a header, the PLT/PET (see below), and followed by the variables of
the image layed out in semi-random order.

Position Independent Load and Store:

@smallexample
C                               Assembly
extern int src;
extern int dst;
extern int *ptr;
ptr = &dst;                     add r8,gp,dst_gp_offset
                                st r8,[gp,ptr_gp_offset]
*ptr = src;                     ld r9,[gp,src_gp_offset]
                                ld r8,[gp,ptr_gp_offset]
                                st r9,[r8]
@end smallexample

@subheading Function Calls

Absolute Direct Calls:

@smallexample
C                               Assembly
extern void function ();
function ();                    bl function
@end smallexample

Calls outside the range of of the `bl' instruction are handled as:

@smallexample
                                lr blink,[status]
                                add blink,blink,3
                                j.nd %st(function)
@end smallexample

Absolute Indirect Calls:

@smallexample
C                               Assembly
extern void (*ptr) ();
(*ptr)();                       ld r8,[ptr]
                                lr blink,[status]
                                j.d r8
                                add blink,blink,2
@end smallexample

Position Independent Direct Calls:

Calls to static functions (in the C sense) use `bl' instruction.  Such
functions are known to use the current value of `gp' and thus need not
ever go through the PLT/PET.  This is not necessarily true, however,
if a static function has its address taken.  Static functions that
have their address taken get PLT/PET entries.

All other function calls must (at least initially) go through the PLT.
The linker can optimize intra-image calls (calls within the same image)
by bypassing the PLT/PET.

??? It is certainly possible to call other functions with `bl'.  The
problem is how to know when this can be done.  The "MA-TRI-ARC paging
system" needs to be more clearly defined.

Position Independent Indirect Calls:

The addresses of functions external to the image, functions whose
address is taken, and for prespecified (*) functions are kept in the
"Procedure Linkage Table".
((*) ??? How they are specified is still unknown.)

The PLT is a subset of the "Global Data Area" (GDA) and lives in front
of `gp'.  That is the PLT is accessed with negative offsets from the
`gp' register.  This is done to make greater use of short immediate data.

@smallexample
C                               Assembly
extern void name ();
name ();                        ld r8,[gp,name_gp_offset]
                                lr blink,[status]
                                j.d r8
                                add blink,blink,2
@end smallexample

Each PLT entry is 4 bytes: the address of the stub to call the function.

This "stub table" will be called the Procedure Entry Table, or PET, so
we can refer to it and so we can distinguish it from the PLT.  The PET
lives in the GDA after the header and before the PLT (see below).  Its
contents are stubs for each function that needs one.  See below for a
description of stub table contents.

Switch Tables:

Absolute code model:

@smallexample
C                               Assembly
void foo ()
@{
...
switch (j)                      ld r8,[j]
@{                              sub.f 0,r8,0
case 0:                         lsl r8,r8
        ...                     blt.nd .Ldef
case 2:                         lsl r8,r8
        ...                     ld r9,[r8,.Ltab]
case 3:                         j.nd r9
        ...
default:
        ...
@}
...
@}
                                .section .rodata
                        .Ltab:  .word %st(.Lcase0)
                                .word %st(.Ldef)
                                .word %st(.Lcase2)
                                .word %st(.Lcase3)
@end smallexample

PIC code model:

@smallexample
@group
C                               Assembly
void foo ()
@{
...
switch (j)                      ld r8,[gp,j_gp_offset]
@{                              sub.f 0,r8,0
case 0:                         lsl r8,r8
        ...                     blt.nd .Ldef
case 2:                         lsl r8,r8
        ...                     ld r9,[gp,.Ltab_addr_gp_offset]
case 3:                         ld r9,[r9]
        ...                     ld r10,[r8,r9]
default:                        ld r11,[status]
        ...             .Lsw    and r11,0x7fffff
@}                              add r12,r10,r11
...                             j.nd r12
@}
                                .section .rodata
                        .Ltab:  .word %st(.Lcase0 - .Lsw)
                                .word %st(.Ldef - .Lsw)
                                .word %st(.Lcase2 - .Lsw)
                                .word %st(.Lcase3 - .Lsw)
@end group
@end smallexample

@subheading Dynamic Allocation of Stack Space

While C does not require dynamic stack allocation within a function,
this ABI supports them.  The stack pointer must be kept aligned to 8
byte boundaries.

@node Object Files
@section Object Files

@menu
* ELF Header::
* Sections::
* Symbol Table::
* Global Data Area::
* Relocation::
@end menu

@node ELF Header
@subsection ELF Header

@smallexample
ARC Identification, e_ident[]:

e_ident[EI_CLASS]       ELFCLASS32
e_ident[EI_DATA]        ELFDATA2LSB

Processor Specific Flags, e_flags:

EF_ARC_ARCH             0x0000000f
E_ARC_BASE              0x00000000
E_ARC_HOST              0x00000001
E_ARC_GRAPHICS          0x00000002
E_ARC_AUDIO             0x00000003

EF_ARC_ARCH     Specificies the particular architecture.
                There are currently four defined
                architecture variants:
                base, host, graphics, and audio.

Bits 0x000000f0 are reserved.  New flags shall be added
in bits 0xffffff00.
@end smallexample

@node Sections
@subsection Sections

@subheading Section Indices

@smallexample
SHN_ARC_ACOMMON         Identical to MIPS version.

SHN_ARC_SCOMMON         Identical to MIPS version.

SHN_ARC_SUNDEFINED      Identical to MIPS version.
@end smallexample

@subheading Section Types

There are no ARC specific section types.

@subheading Section Flags

@smallexample
SHF_ARC_GPREL   The section contains data that must be
                part of the Global Data Area.  Data in
                this area is addressable with a `gp'
                relative address.
@end smallexample

@subheading Special Sections

@iftex
@let@nonarrowing=@comment
@end iftex
@smallexample
Name        Type            Attributes
--------------------------------------------------
.sdata      SHT_PROGBITS    SHF_ALLOC + SHF_WRITE + SHF_ARC_GPREL
.sbss       SHT_NOBITS      SHF_ALLOC + SHF_WRITE + SHF_ARC_GPREL
.dynamic    SHT_DYNAMIC     SHF_ALLOC
.rel.dyn    SHT_ALLOC       SHF_ALLOC

.sdata      This section holds initialized data accessible via a
            positive 8 bit offset from `gp'.

.sbss       This section holds uninitialized data accessible via
            a positive 8 bit offset from `gp'.

.dynamic    This is the same as the generic ABI section of the
            same type, but the ARC-specific version as not 
            include the SHF_WRITE attribute.

.rel.dyn    This section contains the relocation entries
            necessary for run-time dynamic linking.
@end smallexample
@iftex
@let@nonarrowing=@relax
@end iftex

The MIPS ABI implements .sdata/.sbss by allowing the user to specify
how small an object must be before it is put in one of these sections.
It also has a complicated system for helping users choose the best
value.  Accesses via 9 bit signed offsets are faster than 32 bit offsets
so we want to implement this scheme.  ??? It's not clear how one will be
able to choose what variables go in here yet.

@node Symbol Table
@subsection Symbol Table

The ARC version of this table is the same as the MIPS or SPARC version,
except that the PLT contains stub addresses, not instructions.

@node Global Data Area
@subsection Global Data Area

The GDA of the ARC is similar to the MIPS version.  However, since
the ARC has no limitation on the size of the area, all global data
can be stored here.

The GDA consists of all sections that have the SHF_ARC_GPREL attribute.

The GDA is layed out in memory as:

@smallexample
                        low memory
        header
        .pet
        .plt
        .sdata          <-- `gp' points here
        .sbss
        .data
        .bss
                        high memory
@end smallexample

??? It is not clear what to put in `header' yet.

The `gp' registers points at the .sdata section so that at least a few
variables can be accessed with short immediate offsets and several PLT
entries can be similarily accessed.

@node Relocation
@subsection Relocation

The MIPS and SPARC ABIs are useful here for describing relocation
in general.

@subheading Relocation Types

Relocation Fields:

@smallexample
+----------------------------+
|           word32           |
|31                         0|
+----------------------------+

+----------------------------+
|                  |  lit9   |
|31                |8       0|
+----------------------------+

+----------------------------+
|     |    disp22    |       |
|31   |26           7|      0|
+----------------------------+

+----------------------------+
|       |       targ24       |
|31     |23                 0|
+----------------------------+

The symbols used to describe the various relocation
have the following meanings.

A       The addend used in computing the relocation.

EA      The effective address of the symbol prior to
        relocation.

GP0     The value of `gp' used to create the object.

GP      The value of `gp'.

L       The offset of the symbol's PLT entry.

P       The place (section offset or address) of the
        storage unit being relocated (computed using
        r_offset).

S       The value of the symbol being relocated.

The ARC uses Elf32_Rel relocation entries, the relocated
field holds the addend.

Name            Value   Field           Calculation
---------------------------------------------------
R_ARC_NONE      0       none            none
R_ARC_32        1       T-word32        A + S
R_ARC_B26       2       V-targ24        (A + S) >> 2
R_ARC_B22_PCREL 3       V-disp22        (A + S - P) >> 2

R_ARC_REL32     4       T-word32        A + S - EA
R_ARC_GPREL9    5       V-lit9          A + S + GP0 - GP
R_ARC_GPREL32   6       T-word32        A + S + GP0 - GP
R_ARC_GPPLT32   7       T-word32        A + L + GP0 - GP

*** The values are subject to change. ***
@end smallexample

@node Program Loading and Dynamic Linking
@section Program Loading and Dynamic Linking

@menu
* Program Loading::
* Program Header::
* Dynamic Linking::
@end menu

@node Program Loading
@subsection Program Loading

??? It's not clear what to say here given that this is an embedded
system with no virtual memory.  Execution begins at location 0.
Beyond that the program is on its own.

@node Program Header
@subsection Program Header

@subheading Segment Contents

@smallexample
Text Segment
        .dynamic
        .rel.dyn
        .dynsym
        .dynstr
        .hash
        .rodata
        .init
        .fini
        .text

Data Segment
        header
        .pet
        .plt
        .sdata
        .sbss
        .data
        .bss
@end smallexample

@node Dynamic Linking
@subsection Dynamic Linking

@subheading Dynamic Section

The dynamic linker uses the .dynamic section to get started.
It is expected that only the following standard entries will be
necessary.  See the generic ABI for a description.

@smallexample
DT_HASH
DT_STRTAB
DT_STRSZ
DT_SYMTAB
DT_SYMENT
DT_REL
DT_RELSZ
DT_RELENT
DT_INIT
DT_FINI
DT_PLTGOT
@end smallexample

@c Name            Value           d_un    Executable      Shared Object
@c ---------------------------------------------------------------------
There are currently no ARC specific values.


@subheading Global Offset Table

This ABI does not define a GOT.  It may be added at a later date.
For now, images must make their own arrangements for accessing
variables in others.  When one is added, it is expected to live next
to the PLT (ie: identical to the MIPS).

@subheading Function Addresses

This section in the SPARC ABI applies here.

@subheading Calling Position-Independent Functions

This section in the MIPS ABI applies here.
We call the actual table of stubs the Procedure Entry Table.

When the program starts (ie: when the system boots) the dynamic linker
creates the PET and sets up each PLT entry to point to its corresponding
PET entry.

Ignoring the case of uncompressing a group of functions from ROM into
RAM, a typical stub might look like this.

@smallexample
stub_foo:
        st blink,[sp,12]
        st gp,[sp,8]
        mov gp,new_gp_value
        lr blink,[status]       ; (*)
        add blink,blink,3       ; (*)
        j.nd %st(function)      ; (*)
        ld blink,[sp,12]
        j.d blink
        ld gp,[sp,8]
@end smallexample

These 3 instructions can be replaced by a `bl' instruction if the
function is close enough.

This may seem quite expensive and it is.  However, the goal has been to
optimize the important things and let less important things suffer.

Note that:

@enumerate
@item
Intra-image calling has zero overhead.
@item
If the linker can know that a function won't need the gp then the
above stub can be changed to:

@smallexample
        j.nd %st(function)
@end smallexample

This can be done by coding special information in front of each
function.
@item
If we made `gp' call-clobbered all function entry would have to go
through stubs and we couldn't optimize intra-image calling.
@item
We could move the "ld gp,[sp,8]" into the called function and have
a special entry point that did "st gp,[sp,8] for intra-image calls,
but that is two extra memory references for every intra-image call.
@item
There are other schemes where the called function saves/restores `gp',
but again that is two extra memory references for every intra-image call.
@end enumerate

Doing "lazy binding" in an embedded environment does not make as much
sense as it does in a virtual addressing environment.  However, one can
use the same techniques to implement the paging of functions (either
compressed or not) from ROM into RAM.  A stub for that might look like:

@smallexample
stub_foo:
        j.d loader
        mov gp,foo_plt_index
@end smallexample

Function `loader' could then load `foo' into RAM, update the PET entry,
set `gp', [sp,8], and [sp,12] and branch to it.
