Reference
The Reference section
describes the MIPS EABI and VR4300-specific attributes of the main GNUPro
tools.
-
Compiler
-
EABI Summary
-
Assembler
-
Linker
-
Debugger
Compiler
This section describes VR4300-specific
features of the GNUPro Compiler.
VR4300-specific command-line options
For a list of available generic
compiler options, refer to "GNU CC Command Options" in Using GNU CC in
GNUPro Compiler Tools. In addition, the following VR4300-specific command-line
options are supported:
Compile code for the processor in little endian mode.
-EB
Compile code for the processor in big-endian mode.
Preprocessor symbols
|
|
Compiler Options
which define the Symbol
|
|
|
|
|
|
|
|
|
|
|
|
only if ' -ansi'
and ' -EL' are not used |
|
|
only if ' -EL'
is not used |
|
|
only if ' -EL'
is not used |
|
|
only if ' -EL'
is not used |
|
|
|
|
|
|
|
|
only if ' -ansi'
is not used and ' -EL' is used |
|
|
|
|
|
|
|
|
|
Note:
If neither '
-EL'
or '
-EB' are defined big-endian is the default.
VR4300-specific
attributes
There are no VR4300-specific
attributes. See "Declaring Attributes of Functions" and "Specifying Attributes
of Variables" in "Extensions to the C Language Family" in Using GNU CC
in
GNUPro Compiler Tools for more information.
New compiler and linker features
The GNUPro compiler and linker
have been improved by Cygnus to provide even more benefits for customers
developing for embedded targets. These features are guaranteed order of
initialization at startup, and selective linking.
Initialization prioritization
In C++, you can define static
and global objects with constructors, or initialize static and global variables
from a function. This means that the constructors or functions are run
before the rest of your program starts. However, when you have these objects
spread over multiple files, the C++ standard does not specify the order
in which they are initialized, and for all practical purposes the order
is random. For an embedded system, this can be a problem, as you may want
to ensure that a static scheduler object is initialized before static threads
can attach to it, or that devices are initialized before they are used.
GNUPro solves this problem by allowing you to define a priority when the
static or global is declared. The following example shows the syntax:
static object_t myobj __attribute__((init_priority (30000) ));
The syntax is slightly different
if the object takes any arguments to its constructor:
static object_t myobj __attribute__((init_priority (30000) )) = \
object_t(arg1, arg2);
The numeric priority can
be from 1 to 65535, with 1 being the highest priority, and 65535 being
the lowest. The default priority for objects without this attribute is
65535. Constructors with a higher priority are guaranteed execution before
constructors with lower priority.
In all cases, you must provide
the argument '
-finit-priority' to the compiler on its command-line
for it to recognize this attribute when you are compiling your C++ source
files.
If you are using eCos, be
warned that eCos uses initialization priorities internally. Ensure you
choose an appropriate priority level so that other eCos subsystems will
have initialized before you refer to them in your own constructor.
Selective linking
When writing C and C++ code,
it is sometimes natural to include more than one function in a source file.
For example in C++, it is common to have all methods for a particular class
contained in the same C++ source file. However, there is a drawback that,
conventionally, if you use just one of these functions, then all the functions
defined in that file also get included in the final executable image. For
an embedded system, this can substantially and unnecessarily increase the
size of the final image stored in ROM, or loaded into RAM when debugging.
The GNUPro C and C++ compilers
can now optionally remove these unnecessary functions from the final image.
They also ensure that any shared global data is removed that is only referenced
by functions that are removed. This can be done by including the options
'-ffunction-sections' and '-fdata-sections'
on the command-line, when you invoke the C or C++ compiler.
The '-ffunction-sections ' option removes unnecessary
functions, and the '-fdata-sections' option removes unnecessary
data.
In addition, when classes
define virtual methods in C++, it is possible to remove any unused methods
from the final image by passing the option '
-fvtable-gc' to the
C++ compiler on its command-line.
In all cases, you must also
supply a command-line option when linking. If invoking the linker ld directly,
use '
--gc-sections' on its command-line; alternatively, if you
are using the preferred method of linking your executable, using the form
'
gcc -o <program name> <file1>.o <file2>.o',
then also pass the option '
-Wl,- -gc-sections' on the compiler
command-line, for example:
gcc -o prog f1.o f2.o -Wl,--gc-sections
EABI
Summary
This section describes the
MIPS EABI, which the VR4300 tools adhere to, by default.
Data type sizes
and alignments
The following table shows
the size and alignment for all data types:
-
Alignment within aggregates (structs and unions)
is as above, with padding added if needed
-
Aggregates have alignment equal to that of
their most aligned member
-
Aggregates have sizes which are a multiple
of their alignment
Subroutine calls
The following describes the
calling conventions for subroutine calls. The first table outlines the
registers used for passing parameters. The second table outlines other
register usage.
-
General-purpose and floating-point parameter
registers are allocated independently.
-
Structures that are less than or equal to 32
bits are passed as values.
-
Structures that are greater than 32 bits are
passed as pointers.
The
Stack Frame
This section describes VR4300
stack frame:
-
The stack grows downwards from high addresses
to low addresses.
-
A leaf function need not allocate a stack frame
if it does not need one.
-
A frame pointer need not be allocated.
-
The stack pointer shall always be aligned to
8-byte boundaries.
Stack frames for functions
that take a fixed number of arguments look like this:
*
If no '
alloca '
region, the frame pointer (FP) points to the same location as SP.
Stack frames for functions
that take a variable number of arguments look very similar, with the addition
of an area on the stack that contains the arguments that were passed in
registers.
Stack frames for functions
that take a variable number of arguments look like this:
*
If no '
alloca '
region, the frame pointer (FP) points to the same location as SP.
Parameter Assignment to Registers
Consider the parameters in
a function call as ordered from left (first parameter) to right. In this
algorithm, 'FR' contains the number of the next available floating-point
register (or register pair for modes in which floating-point registers
hold only 32 bits). 'GR' contains the number of the next available general-purpose
register. 'STARG' is the address of the next available stack parameter
word.
INITIALIZE:
Set 'GR=r4', 'FR=f12', and
'STARG' to point to parameter word 1.
SCAN:
If there are no more parameters,
terminate. Otherwise, select one of the following depending on the type
of the next parameter:
DOUBLE OR FLOAT:
If 'FR > f19', go to 'STACK'.
Otherwise, load the parameter value into
floating-point register 'FR'
and advance 'FR' to the next floating-point register (or register pair
in 32-bit mode). Then go to 'SCAN'.
SIMPLE ARG:
A SIMPLE ARG is one of the
following:
-
One of the simple integer types which will
fit into a general-purpose register
-
A pointer to an object of any type
-
A struct or union small enough to fit in a
register
-
A larger struct or union, which shall be treated
as a pointer to the object or to a copy of the object (See below for when
copies are made.)
If 'GR > r11', go to 'STACK'.
Otherwise, load the parameter value into general-purpose register 'GR'
and advance 'GR' to the next general-purpose register. Values shorter than
the register size are sign-extended or zero-extended depending on whether
they are signed or unsigned. Then go to 'SCAN'.
LONG LONG in 32-bit mode:
If 'GR > r10', go to 'STACK'.
Otherwise, if 'GR' is odd, advance 'GR' to the next register. Load the
64-bit '
long long' value into register pair 'GR' and 'GR+1'. Advance
'GR' to 'GR+2' and go to 'SCAN'.
STACK:
Parameters not otherwise
handled above are passed in the parameter words of the caller's stack frame.
SIMPLE ARGs, as defined above, are considered to have size and alignment
equal to the size of a general-purpose register, with simple argument types
shorter than this sign- or zero-extended to this width. float arguments
are considered to have size and alignment equal to the size of a floating-point
register. In 64-bit mode, floats are stored in the low-order 32 bits of
the 64-bit space allocated to them. '
double' and '
long long'
are considered to have 64-bit size and alignment. Round 'STARG' up to a
multiple of the alignment requirement of the parameter and copy the argument
byte-for-byte into 'STARG', 'STARG+1', ... 'STARG+size-1'. Set 'STARG'
to 'STARG+size' and go to 'SCAN'.
Structure passing
As noted above, code, which
passes structures and unions by value is implemented specially. (In this
section, "struct" will refer to structs and unions inclusively.) Structs
small enough to fit in a register are passed by value in a single register
or in a stack frame slot the size of a register. Larger structs are handled
by passing the address of the structure. In this case, a copy of the structure
will be made if necessary in order to preserve the pass-by-value semantics.
Copies of large structs are
made under the following rules:
In the case of normal (non-varargs)
large-struct parameters in ANSI mode, the callee is responsible for producing
the same effect as if a copy of the structure were passed, preserving the
pass-by-value semantics. This may be accomplished by having the callee
make a copy, but in some cases the callee may be able to determine that
a copy is not necessary in order to produce the same results. In such cases,
the callee may choose to avoid making a copy of the parameter.
Varargs handling
No special changes are needed
for handling varargs parameters other than the caller knowing that a copy
is needed on struct parameters larger than a register (see above).
The varargs macros set up
a two-part register save area, one part for the general-purpose registers
and one part for floating-point registers, and maintain separate pointers
for these two areas and for the stack parameter area. The register save
area lies between the caller and callee stack frame areas.
In the case of software floating-point
only the general-purpose registers need to be saved. Because the save area
lies between the two stack frames, the saved register parameters are contiguous
with parameters passed on the stack. This allows the varargs macros to
be much simpler. Only one pointer is needed, which advances from the register
save area into the caller's stack frame.
Function Return Values
Data types and register usage
for return values:
Structures and unions, which
will fit into two general-purpose registers are returned in 'r2',
or in 'r2' and 'r3' if necessary. They are aligned within
the register according to the endianness of the processor; in other words,
on a big-endian processor the first byte of the struct is returned in the
most significant byte of 'r2', while on a little-endian
processor the first byte is returned in the least significant byte of
'r2'. The caller handles larger structures and unions, by passing,
as a "hidden" first argument, a pointer to space allocated to receive the
return value.
Assembler
This
section describes VR4300-specific features of the GNUPro Assembler.
VR4300-specific
command-line options
For a list of available generic
assembler options, refer to "Command-Line Options" in
Using AS in
GNUPro
Utilities .
Any MIPS configuration of the assembler can select big-endian or
little-endian output at run time.
Use '-EB'
to select big-endian output, and '-EL' for little-endian. The
default is big-endian.
Syntax
For
information about the MIPS instruction set, see
MIPS RISC Architecture
, (Kane and Heindrich, Prentice-Hall). For an overview of MIPS assembly
conventions, see "Appendix D: Assembly Language Programming" in the same
volume.
Register
names
There are 32 64-bit general
(integer) registers, named '
$0' through '
$31'. There
are 32 64-bit floating-point registers, named '
$f0'
through '
$f31'.
The symbols '
$0'
through '
$31' refer to the general-purpose registers.
The following symbols can
be used as aliases for individual registers:
Assembler directives
This is a complete list of
the VR4300 assembler directives.
MIPS Synthetic Instructions
Supported for the VR4300
The VR4300 GAS assembler
supports the typical MIPS synthetic instructions (macros). What follows
is a list of synthetic instructions supported by the assembler, as well
as an example expansion of each instruction.
R1 R2 R3 - Integer registers
F1 F2 F3 - Floating point
registers
I1 I2 I3 - Immediate integer
values
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
sltiu $at,R1,I1 beqzl
$at,+I2
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
daddiu $at,$zero,-1
bne R3,$at,ddiv_2
daddiu $at,$zero,1
dsll32 $at,$at,0x1f
bne R2,$at,ddiv_2
nop
break 0x6
ddiv_2:
mflo R1 |
|
|
|
|
|
mflo R1 |
|
|
|
|
|
li $at,-1
bne R3,$at,div_2
lui $at,0x8000
bne R2,$at,div_2
nop
break 0x6
div_2:
mflo R1 |
|
|
|
|
|
mflo R1 |
|
|
|
|
|
|
|
|
|
|
|
daddiu $at,$zero,-1
bne R3,$at,drem_2
daddiu $at,$zero,1
dsll32 $at,$at,0x1f
bne R2,$at,drem_2
nop
break 0x6
drem_2:
mfhi R1 |
|
|
|
|
|
mfhi R1 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
li $at,-1
bne R3,$at,rem_2
lui $at,0x8000
bne R2,$at,rem_2
nop
break 0x6
rem_2:
mfhi R1 |
|
|
|
|
|
mfhi R1 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Linker
eCos generates linker scripts
appropriate for the exact eCos configuration you have chosen. Instructions
on how to use this linker script are provided in the manual
Getting
Started with eCos .
VR4300-specific command-line options
For a list of available generic
linker options, refer to "Linker scripts" in
Using LD in
GNUPro
Utilities . There are no VR4300-specific command-line linker options.
Debugger
The following instructions
connect GDB to the remote target board. To load your program onto the standard
evaluation board, build eCos for the hardware with RAM startup. Provided
the board is fitted with CygMon ROMs, or GDB loader stub ROMs, you may
connect to the target board in GDB using the command '
target remote<devicename>'
where '
<devicename>' will be a serial device such as '
com2'
(Windows NT) or '
/dev/ttyS1' (Linux). Then load the code onto
the target board by typing '
load'. After being downloaded, the
program can be executed.
Note:
When using the remote target,
GDB does not accept the '
run' command. However, since downloading
the program has the side effect of setting the PC to the start address,
you can start your program by typing '
continue' (the letter '
c'
works as a shortcut for the '
continue' command).
VR4300-specific
command-line options
For the available generic
debugger options, refer to
Debugging with GDB in
GNUPro Debugging
Tools . There are no VR4300-specific debugger command-line options.
Debugging programs with multiple threads
Programs with multiple threads
can be debugged using either the graphic user interface to GDB, GDBTk or
the GDB command line interface. The following describes how to debug multiple
threads using the GDB command line.
In some operating systems,
such as eCos, a single program may have more than one thread of execution.
The precise semantics of threads differ from one operating system to another,
but in general the threads of a single program are akin to multiple processes,
except that they share one address space (that is, they can all examine
and modify the same variables). On the other hand, each thread has its
own registers and execution stack, and perhaps private memory.
GDB provides the following
functions for debugging multi-thread programs
-
'info threads', a command to inquire
about existing threads
-
'thread <threadno>', a command
to switch among threads
-
'thread apply [<threadno>][<all>]
<args>',
a command to apply a command to a list of threads
-
thread-specific breakpoints
The GDB thread-debugging
facility allows you to observe all threads while your program runs, but
whenever GDB takes control, one thread in particular is always the focus
of debugging. This thread is called the current thread. Debugging commands
show program information from the perspective of the current thread.
For debugging purposes, GDB
associates its own thread number, always a single integer, with each thread
in your program.
Display a summary of all threads currently in your program. GDB
displays for each thread (in the following order):
-
The thread number assigned by GDB
-
The target system's thread ID
-
The current stack frame summary for that thread
An asterisk '
*'
to the left of the GDB thread number indicates the current thread. Use
the following example for clarity.
(gdb)
info threads
|
* 2 thread 2 breakme ()
|
at /eCos/packages/kernel/v1_2_2/tests/thread_gdb.c:91
|
Name: controller, State: running, Priority: 0, More: <none>
|
1 thread 1 Cyg_HardwareThread::thread_entry (thread=0x1111aaa2)
|
at /eCos/packages/kernel/v1_2_2/src/common/thread.cxx:68
|
Name: Idle Thread, State: running, Priority: 31, More: <none>
|
thread <threadno>
Make thread number '<threadno>' the current thread. The command
argument, '<threadno>', is the internal GDB thread number, as
shown in the first field of the 'info threads' display. GDB responds by
displaying the system identifier of the thread you selected, and its current
stack frame summary, as in the following output.
(gdb)
thread 2
|
[Switching to thread 2]
|
#0 change_state (id=0, newstate=0 '\000')
|
at /eCos/kernel/current/tests/bin_sem2.cxx:93
|
93 if (PHILO_LOOPS == state_changes++)
|
Current language: auto; currently c++
|
|
thread apply [<threadno>][<all>]
<args>
The thread apply command allows you to apply a command to one or more
threads. Specify the numbers of the threads that you want affected with
the command argument '<threadno>', where '<threadno>'
is the internal GDB thread number, as shown in the first field of the 'info
threads' display. To apply a command to all threads, use 'thread
apply all args '.
Whenever GDB stops your program,
due to a breakpoint or a signal, it automatically selects the thread where
that breakpoint or signal happened.
When your program has multiple
threads, you can choose whether to set breakpoints on all threads, or on
a particular thread.
break <linespec> thread <threadno>
If '
<linespec>'
specifies source lines, then there are several ways of writing them. Use
the qualifier '
thread <threadno>' with a breakpoint
command to specify that you only want GDB to stop the program when a particular
thread reaches this breakpoint. '
<threadno>' is one of the numeric
thread identifiers assigned by GDB, shown in the first column of the 'info
threads' display.
If you do not specify '
thread
<threadno>'
when you set a breakpoint, the breakpoint applies to all threads of your
program.
You can use the thread qualifier
on conditional breakpoints as well; in this case, place '
thread <threadno>
' before the breakpoint condition, as the following example shows.
(gdb) break frik.c:(13 thread 28 if bartab > lim
|
Whenever your program stops
under GDB for any reason, all threads of execution stop; not just the current
thread. This allows you to examine the overall state of the program, including
switching between threads, without worrying that things may change.
Conversely, whenever you
restart the program, all threads start executing. This is true even when
single stepping with commands like '
step ' or '
next'.
In particular, GDB cannot single-step all threads in lockstep. Since thread
scheduling is up to your debugging target's operating system (not controlled
by GDB), other threads may execute more than one statement while the current
thread completes a single step. In general other threads stop in the middle
of a statement, rather than at a clean statement boundary, when the program
stops.
You might even find your
program stopped in another thread after continuing or even single stepping.
This happens whenever some other thread runs into a breakpoint, a signal,
or an exception before the first thread completes whatever you requested.
SET SCHEDULER-LOCKING
For targets that support
it, GDB has a new command that helps to debug multi-threaded programs.
The '
set scheduler-locking [on off step]' command allows the GDB
user to exert some control over how threads are scheduled while debugging.
Normally GDB does not attempt
to interfere with thread scheduling. This means that in the default mode
('
scheduler-locking off'), the current thread may be scheduled
out, and a different thread may begin running, at any time (as determined
by the native scheduler). For instance, you may give a GDB command such
as '
step' or '
finish', and when the command completes,
you may be looking at a different thread.
If you set the scheduler-locking
mode to '
step', then GDB will try to interfere with the native
scheduler just enough to prevent another thread from popping up while you
debug. Other threads may get to run sometimes, but whenever a command such
as '
step' or '
finish' completes, you should be looking
at the same thread that was running before the command. Of course, if another
thread gets to run and hits a breakpoint, GDB will still switch you to
that thread (so if you don't want that to happen, then disable your breakpoints).
For even greater (and more
intrusive) control over the thread scheduler, GDB provides the mode '
scheduler-locking
on'. In this mode, the native scheduler is completely locked, and
no thread may run except the current one. Obviously this will radically
change the behavior of your program, and may lead to deadlock or other
unpleasant consequences, so use it with caution.
Syntax:
set scheduler-locking [off
on step]
Set mode for locking scheduler
during target execution.
No locking (threads
may preempt at any time).
on
Full locking (no
thread except the current thread may run).
step
The scheduler
is locked during every single-step operation. In this mode, no other thread
may run during a step command. However, other threads may run while stepping
over a function call ('
next').
