* doc/c-sparc.texi: Add syntax section.

[deliverable/binutils-gdb.git] / gas / doc / c-sparc.texi

@c Copyright 1991, 1992, 1993, 1994, 1995, 1997, 1999, 2002
@c Free Software Foundation, Inc.
@c This is part of the GAS manual.
@c For copying conditions, see the file as.texinfo.
@ifset GENERIC
@page
@node Sparc-Dependent
@chapter SPARC Dependent Features
@end ifset
@ifclear GENERIC
@node Machine Dependencies
@chapter SPARC Dependent Features
@end ifclear

@cindex SPARC support
@menu
* Sparc-Opts::                  Options
* Sparc-Aligned-Data::          Option to enforce aligned data
* Sparc-Syntax::                Syntax
* Sparc-Float::                 Floating Point
* Sparc-Directives::            Sparc Machine Directives
@end menu

@node Sparc-Opts
@section Options

@cindex options for SPARC
@cindex SPARC options
@cindex architectures, SPARC
@cindex SPARC architectures
The SPARC chip family includes several successive levels, using the same
core instruction set, but including a few additional instructions at
each level.  There are exceptions to this however.  For details on what
instructions each variant supports, please see the chip's architecture
reference manual.

By default, @code{@value{AS}} assumes the core instruction set (SPARC
v6), but ``bumps'' the architecture level as needed: it switches to
successively higher architectures as it encounters instructions that
only exist in the higher levels.

If not configured for SPARC v9 (@code{sparc64-*-*}) GAS will not bump
passed sparclite by default, an option must be passed to enable the
v9 instructions.

GAS treats sparclite as being compatible with v8, unless an architecture
is explicitly requested.  SPARC v9 is always incompatible with sparclite.

@c The order here is the same as the order of enum sparc_opcode_arch_val
@c to give the user a sense of the order of the "bumping".

@table @code
@kindex -Av6
@kindex Av7
@kindex -Av8
@kindex -Asparclet
@kindex -Asparclite
@kindex -Av9
@kindex -Av9a
@item -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
@itemx -Av8plus | -Av8plusa | -Av9 | -Av9a
Use one of the @samp{-A} options to select one of the SPARC
architectures explicitly.  If you select an architecture explicitly,
@code{@value{AS}} reports a fatal error if it encounters an instruction
or feature requiring an incompatible or higher level.

@samp{-Av8plus} and @samp{-Av8plusa} select a 32 bit environment.

@samp{-Av9} and @samp{-Av9a} select a 64 bit environment and are not
available unless GAS is explicitly configured with 64 bit environment
support.

@samp{-Av8plusa} and @samp{-Av9a} enable the SPARC V9 instruction set with
UltraSPARC extensions.

@item -xarch=v8plus | -xarch=v8plusa
For compatibility with the Solaris v9 assembler.  These options are
equivalent to -Av8plus and -Av8plusa, respectively.

@item -bump
Warn whenever it is necessary to switch to another level.
If an architecture level is explicitly requested, GAS will not issue
warnings until that level is reached, and will then bump the level
as required (except between incompatible levels).

@item -32 | -64
Select the word size, either 32 bits or 64 bits.
These options are only available with the ELF object file format,
and require that the necessary BFD support has been included.
@end table

@node Sparc-Aligned-Data
@section Enforcing aligned data

@cindex data alignment on SPARC
@cindex SPARC data alignment
SPARC GAS normally permits data to be misaligned.  For example, it
permits the @code{.long} pseudo-op to be used on a byte boundary.
However, the native SunOS and Solaris assemblers issue an error when
they see misaligned data.

@kindex --enforce-aligned-data
You can use the @code{--enforce-aligned-data} option to make SPARC GAS
also issue an error about misaligned data, just as the SunOS and Solaris
assemblers do.

The @code{--enforce-aligned-data} option is not the default because gcc
issues misaligned data pseudo-ops when it initializes certain packed
data structures (structures defined using the @code{packed} attribute).
You may have to assemble with GAS in order to initialize packed data
structures in your own code.

@cindex SPARC syntax
@cindex syntax, SPARC
@node Sparc-Syntax
@section Sparc Syntax
The assembler syntax closely follows The Sparc Architecture Manual,
versions 8 and 9, as well as most extensions defined by Sun
for their UltraSPARC and Niagara line of processors.

@menu
* Sparc-Chars::                Special Characters
* Sparc-Regs::                 Register Names
* Sparc-Relocs::               Relocations
@end menu

@node Sparc-Chars
@subsection Special Characters

@cindex line comment character, Sparc
@cindex Sparc line comment character
@samp{#} is the line comment character.

@cindex line separator, Sparc
@cindex statement separator, Sparc
@cindex Sparc line separator
@samp{;} can be used instead of a newline to separate statements.

@node Sparc-Regs
@subsection Register Names
@cindex Sparc registers
@cindex register names, Sparc

The Sparc integer register file is broken down into global,
outgoing, local, and incoming.

@itemize @bullet
@item
The 8 global registers are referred to as @samp{%g@var{n}}.

@item
The 8 outgoing registers are referred to as @samp{%o@var{n}}.

@item
The 8 local registers are referred to as @samp{%l@var{n}}.

@item
The 8 incoming registers are referred to as @samp{%i@var{n}}.

@item
The frame pointer register @samp{%i6} can be referenced using
the alias @samp{%fp}.

@item
The stack pointer register @samp{%o6} can be referenced using
the alias @samp{%sp}.
@end itemize

Floating point registers are simply referred to as @samp{%f@var{n}}.
When assembling for pre-V9, only 32 floating point registers
are available.  For V9 and later there are 64, but there are
restrictions when referencing the upper 32 registers.  They
can only be accessed as double or quad, and thus only even
or quad numbered accesses are allowed.  For example, @samp{%f34}
is a legal floating point register, but @samp{%f35} is not.

Certain V9 instructions allow access to ancillary state registers.
Most simply they can be referred to as @samp{%asr@var{n}} where
@var{n} can be from 16 to 31.  However, there are some aliased
defined to reference ASR registers defined for various UltraSPARC
processors:

@itemize @bullet
@item
The tick compare register is referred to as @samp{%tick_cmpr}.

@item
The system tick register is referred to as @samp{%sys_tick}.

@item
The system tick compare register is referred to as @samp{%sys_tick_cmpr}.

@item
The software interrupt register is referred to as @samp{%softint}.

@item
The set software interrupt register is referred to as @samp{%set_softint}.

@item
The clear software interrupt register is referred to as
@samp{%clear_softint}.

@item
The performance instrumentation counters register is referred to as
@samp{%pic}.

@item
The performance control register is referred to as @samp{%pcr}.

@item
The graphics status register is referred to as @samp{%gsr}.

@item
The dispatch control register is referred to as @samp{%dcr}.
@end itemize

Various V9 branch and conditional move instructions allow
specification of which set of integer condition codes to
test.  These are referred to as @samp{%xcc} and @samp{%icc}.

In V9, there are 4 sets of floating point condition codes
which are referred to as @samp{%fcc@var{n}}.

Several special privileged and non-privileged registers
exist:

@itemize @bullet
@item
The V9 address space identifier register is referred to as @samp{%asi}.

@item
The V9 restorable windows register is referred to as @samp{%canrestore}.

@item
The V9 savable windows register is referred to as @samp{%cansave}.

@item
The V9 clean windows register is referred to as @samp{%cleanwin}.

@item
The V9 current window pointer register is referred to as @samp{%cwp}.

@item
The floating-point queue register is referred to as @samp{%fq}.

@item
The co-processor queue register is referred to as @samp{%cq}.

@item
The floating point status register is referred to as @samp{%fsr}.

@item
The other windows register is referred to as @samp{%otherwin}.

@item
The V9 program counter register is referred to as @samp{%pc}.

@item
The V9 next program counter register is referred to as @samp{%npc}.

@item
The V9 processor interrupt level register is referred to as @samp{%pil}.

@item
The V9 processor state register is referred to as @samp{%pstate}.

@item
The trap base address register is referred to as @samp{%tba}.

@item
The V9 tick register is referred to as @samp{%tick}.

@item
The V9 trap level is referred to as @samp{%tl}.

@item
The V9 trap program counter is referred to as @samp{%tpc}.

@item
The V9 trap next program counter is referred to as @samp{%tnpc}.

@item
The V9 trap state is referred to as @samp{%tstate}.

@item
The V9 trap type is referred to as @samp{%tt}.

@item
The V9 condition codes is referred to as @samp{%ccr}.

@item
The V9 floating-point registers state is referred to as @samp{%fprs}.

@item
The V9 version register is referred to as @samp{%ver}.

@item
The V9 window state register is referred to as @samp{%wstate}.

@item
The Y register is referred to as @samp{%y}.

@item
The V8 window invalid mask register is referred to as @samp{%wim}.

@item
The V8 processor state register is referred to as @samp{%psr}.

@item
The global register level register is referred to as @samp{%gl}.
@end itemize

Several special register names exist for hypervisor mode code:

@itemize @bullet
@item
The hyperprivileged processor state register is referred to as
@samp{%hpstate}.

@item
The hyperprivileged trap state register is referred to as @samp{%htstate}.

@item
The hyperprivileged interrupt pending register is referred to as
@samp{%hintp}.

@item
The hyperprivileged trap base address register is referred to as
@samp{%htba}.

@item
The hyperprivileged implementation version register is referred
to as @samp{%hver}.

@item
The hyperprivileged system tick compare register is referred
to as @samp{%hstick_cmpr}.
@end itemize

@node Sparc-Relocs
@subsection Relocations
@cindex Sparc relocations
@cindex relocations, Sparc

ELF relocations are available as defined in the 32-bit and 64-bit
Sparc ELF specifications.

@code{R_SPARC_HI22} is obtained using @samp{%hi} and @code{R_SPARC_LO10}
is obtained using @samp{%lo}.  Likewise @code{R_SPARC_HIX22} is
obtained from @samp{%hix} and @code{R_SPARC_LOX10} is obtained
using @samp{%lox}.  For example:

@example
sethi %hi(symbol), %g1
or    %g1, %lo(symbol), %g1

sethi %hix(symbol), %g1
xor   %g1, %lox(symbol), %g1
@end example

These ``high'' mnemonics extract bits 31:10 of their operand,
and the ``low'' mnemonics extract bits 9:0 of their operand.

V9 code model relocations can be requested as follows:

@itemize @bullet
@item
@code{R_SPARC_HH22} is requested using @samp{%hh}.  It can
also be generated using @samp{%uhi}.
@item
@code{R_SPARC_HM10} is requested using @samp{%hm}.  It can
also be generated using @samp{%ulo}.
@item
@code{R_SPARC_LM22} is requested using @samp{%lm}.

@item
@code{R_SPARC_H44} is requested using @samp{%h44}.
@item
@code{R_SPARC_M44} is requested using @samp{%m44}.
@item
@code{R_SPARC_L44} is requested using @samp{%l44}.
@end itemize

The PC relative relocation @code{R_SPARC_PC22} can be obtained by
enclosing an operand inside of @samp{%pc22}.  Likewise, the
@code{R_SPARC_PC10} relocation can be obtained using @samp{%pc10}.
These are mostly used when assembling PIC code.  For example, the
standard PIC sequence on Sparc to get the base of the global offset
table, PC relative, into a register, can be performed as:

@example
sethi %pc22(_GLOBAL_OFFSET_TABLE_-4), %l7
add   %l7, %pc10(_GLOBAL_OFFSET_TABLE_+4), %l7
@end example

Several relocations exist to allow the link editor to potentially
optimize GOT data references.  The @code{R_SPARC_GOTDATA_OP_HIX22}
relocation can obtained by enclosing an operand inside of
@samp{%gdop_hix22}.  The @code{R_SPARC_GOTDATA_OP_LOX10}
relocation can obtained by enclosing an operand inside of
@samp{%gdop_lox10}.  Likewise, @code{R_SPARC_GOTDATA_OP} can be
obtained by enclosing an operand inside of @samp{%gdop}.
For example, assuming the GOT base is in register @code{%l7}:

@example
sethi %gdop_hix22(symbol), %l1
xor   %l1, %gdop_lox10(symbol), %l1
ld    [%l7 + %l1], %l2, %gdop(symbol)
@end example

There are many relocations that can be requested for access to
thread local storage variables.  All of the Sparc TLS mnemonics
are supported:

@itemize @bullet
@item
@code{R_SPARC_TLS_GD_HI22} is requested using @samp{%tgd_hi22}.
@item
@code{R_SPARC_TLS_GD_LO10} is requested using @samp{%tgd_lo10}.
@item
@code{R_SPARC_TLS_GD_ADD} is requested using @samp{%tgd_add}.
@item
@code{R_SPARC_TLS_GD_CALL} is requested using @samp{%tgd_call}.

@item
@code{R_SPARC_TLS_LDM_HI22} is requested using @samp{%tldm_hi22}.
@item
@code{R_SPARC_TLS_LDM_LO10} is requested using @samp{%tldm_lo10}.
@item
@code{R_SPARC_TLS_LDM_ADD} is requested using @samp{%tldm_add}.
@item
@code{R_SPARC_TLS_LDM_CALL} is requested using @samp{%tldm_call}.

@item
@code{R_SPARC_TLS_LDO_HIX22} is requested using @samp{%tldo_hix22}.
@item
@code{R_SPARC_TLS_LDO_LOX10} is requested using @samp{%tldo_lox10}.
@item
@code{R_SPARC_TLS_LDO_ADD} is requested using @samp{%tldo_add}.

@item
@code{R_SPARC_TLS_IE_HI22} is requested using @samp{%tie_hi22}.
@item
@code{R_SPARC_TLS_IE_LO10} is requested using @samp{%tie_lo10}.
@item
@code{R_SPARC_TLS_IE_LD} is requested using @samp{%tie_ld}.
@item
@code{R_SPARC_TLS_IE_LDX} is requested using @samp{%tie_ldx}.
@item
@code{R_SPARC_TLS_IE_ADD} is requested using @samp{%tie_add}.

@item
@code{R_SPARC_TLS_LE_HIX22} is requested using @samp{%tle_hix22}.
@item
@code{R_SPARC_TLS_LE_LOX10} is requested using @samp{%tle_lox10}.
@end itemize

Here are some example TLS model sequences.

First, General Dynamic:

@example
sethi  %tgd_hi22(symbol), %l1
add    %l1, %tgd_lo10(symbol), %l1
add    %l7, %l1, %o0, %tgd_add(symbol)
call   __tls_get_addr, %tgd_call(symbol)
nop
@end example

Local Dynamic:

@example
sethi  %tldm_hi22(symbol), %l1
add    %l1, %tldm_lo10(symbol), %l1
add    %l7, %l1, %o0, %tldm_add(symbol)
call   __tls_get_addr, %tldm_call(symbol)
nop

sethi  %tldo_hix22(symbol), %l1
xor    %l1, %tldo_lox10(symbol), %l1
add    %o0, %l1, %l1, %tldo_add(symbol)
@end example

Initial Exec:

@example
sethi  %tie_hi22(symbol), %l1
add    %l1, %tie_lo10(symbol), %l1
ld     [%l7 + %l1], %o0, %tie_ld(symbol)
add    %g7, %o0, %o0, %tie_add(symbol)

sethi  %tie_hi22(symbol), %l1
add    %l1, %tie_lo10(symbol), %l1
ldx    [%l7 + %l1], %o0, %tie_ldx(symbol)
add    %g7, %o0, %o0, %tie_add(symbol)
@end example

And finally, Local Exec:

@example
sethi  %tle_hix22(symbol), %l1
add    %l1, %tle_lox10(symbol), %l1
add    %g7, %l1, %l1
@end example

When assembling for 64-bit, and a secondary constant addend is
specified in an address expression that would normally generate
an @code{R_SPARC_LO10} relocation, the assembler will emit an
@code{R_SPARC_OLO10} instead.

@node Sparc-Float
@section Floating Point

@cindex floating point, SPARC (@sc{ieee})
@cindex SPARC floating point (@sc{ieee})
The Sparc uses @sc{ieee} floating-point numbers.

@node Sparc-Directives
@section Sparc Machine Directives

@cindex SPARC machine directives
@cindex machine directives, SPARC
The Sparc version of @code{@value{AS}} supports the following additional
machine directives:

@table @code
@cindex @code{align} directive, SPARC
@item .align
This must be followed by the desired alignment in bytes.

@cindex @code{common} directive, SPARC
@item .common
This must be followed by a symbol name, a positive number, and
@code{"bss"}.  This behaves somewhat like @code{.comm}, but the
syntax is different.

@cindex @code{half} directive, SPARC
@item .half
This is functionally identical to @code{.short}.

@cindex @code{nword} directive, SPARC
@item .nword
On the Sparc, the @code{.nword} directive produces native word sized value,
ie. if assembling with -32 it is equivalent to @code{.word}, if assembling
with -64 it is equivalent to @code{.xword}.

@cindex @code{proc} directive, SPARC
@item .proc
This directive is ignored.  Any text following it on the same
line is also ignored.

@cindex @code{register} directive, SPARC
@item .register
This directive declares use of a global application or system register.
It must be followed by a register name %g2, %g3, %g6 or %g7, comma and
the symbol name for that register.  If symbol name is @code{#scratch},
it is a scratch register, if it is @code{#ignore}, it just suppresses any
errors about using undeclared global register, but does not emit any
information about it into the object file.  This can be useful e.g. if you
save the register before use and restore it after.

@cindex @code{reserve} directive, SPARC
@item .reserve
This must be followed by a symbol name, a positive number, and
@code{"bss"}.  This behaves somewhat like @code{.lcomm}, but the
syntax is different.

@cindex @code{seg} directive, SPARC
@item .seg
This must be followed by @code{"text"}, @code{"data"}, or
@code{"data1"}.  It behaves like @code{.text}, @code{.data}, or
@code{.data 1}.

@cindex @code{skip} directive, SPARC
@item .skip
This is functionally identical to the @code{.space} directive.

@cindex @code{word} directive, SPARC
@item .word
On the Sparc, the @code{.word} directive produces 32 bit values,
instead of the 16 bit values it produces on many other machines.

@cindex @code{xword} directive, SPARC
@item .xword
On the Sparc V9 processor, the @code{.xword} directive produces
64 bit values.
@end table