SPARC Dependent Features
************************

Options
=======

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

By default, 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 (sparc64-*-*) GAS will not bump past 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.

-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
-Av8plus | -Av8plusa | -Av8plusb | -Av8plusc | -Av8plusd | -Av8plusv
-Av9 | -Av9a | -Av9b | -Av9c | -Av9d | -Av9v
-Asparc | -Asparcvis | -Asparcvis2 | -Asparcfmaf | -Asparcima
-Asparcvis3 | -Asparcvis3r
     Use one of the -A options to select one of the SPARC architectures explicitly.  If you select an architecture explicitly, AS reports a fatal error if it encounters an instruction or feature requiring an incompatible or higher level.

     -Av8plus, -Av8plusa, -Av8plusb, -Av8plusc, -Av8plusd, and -Av8plusv select a 32 bit environment.

     -Av9, -Av9a, -Av9b, -Av9c, -Av9d, and -Av9v select a 64 bit environment and are not available unless GAS is explicitly configured with 64 bit environment support.

     -Av8plusa and -Av9a enable the SPARC V9 instruction set with UltraSPARC VIS 1.0 extensions.

     -Av8plusb and -Av9b enable the UltraSPARC VIS 2.0 instructions, as well as the instructions enabled by -Av8plusa and -Av9a.

     -Av8plusc and -Av9c enable the UltraSPARC Niagara instructions, as well as the instructions enabled by -Av8plusb and -Av9b.

     -Av8plusd and -Av9d enable the floating point fused multiply-add, VIS 3.0, and HPC extension instructions, as well as the instructions enabled by -Av8plusc and -Av9c.

     -Av8plusv and -Av9v enable the 'random', transactional memory, floating point unfused multiply-add, integer multiply-add, and cache sparing store instructions, as well as the instructions enabled by -Av8plusd and -Av9d.

     -Asparc specifies a v9 environment.  It is equivalent to -Av9 if the word size is 64-bit, and -Av8plus otherwise.

     -Asparcvis specifies a v9a environment.  It is equivalent to -Av9a if the word size is 64-bit, and -Av8plusa otherwise.

     -Asparcvis2 specifies a v9b environment.  It is equivalent to -Av9b if the word size is 64-bit, and -Av8plusb otherwise.

     -Asparcfmaf specifies a v9b environment with the floating point fused multiply-add instructions enabled.

     -Asparcima specifies a v9b environment with the integer multiply-add instructions enabled.

     -Asparcvis3 specifies a v9b environment with the VIS 3.0, HPC , and floating point fused multiply-add instructions enabled.

     -Asparcvis3r specifies a v9b environment with the VIS 3.0, HPC, transactional memory, random, and floating point unfused multiply-add instructions enabled.

-xarch=v8plus | -xarch=v8plusa | -xarch=v8plusb | -xarch=v8plusc
-xarch=v8plusd | -xarch=v8plusv | -xarch=v9 | -xarch=v9a
-xarch=v9b | -xarch=v9c | -xarch=v9d | -xarch=v9v
-xarch=sparc | -xarch=sparcvis | -xarch=sparcvis2
-xarch=sparcfmaf | -xarch=sparcima | -xarch=sparcvis3
-xarch=sparcvis3r
     For compatibility with the SunOS v9 assembler.  These options are equivalent to -Av8plus, -Av8plusa, -Av8plusb, -Av8plusc, -Av8plusd, -Av8plusv, -Av9, -Av9a, -Av9b, -Av9c, -Av9d, -Av9v, -Asparc, -Asparcvis, -Asparcvis2, -Asparcfmaf, -Asparcima, -Asparcvis3, and -Asparcvis3r, respectively.

-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).

-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.

Enforcing aligned data
======================

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

You can use the --enforce-aligned-data option to make SPARC GAS also issue an error about misaligned data, just as the SunOS assemblers do.

The --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 packed attribute). You may have to assemble with GAS in order to initialize packed data structures in your own code.

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.

Special Characters
------------------

A ! character appearing anywhere on a line indicates the start of a comment that extends to the end of that line.

If a # appears as the first character of a line then the whole line is treated as a comment, but in this case the line could also be a logical line number directive (see Comments) or a preprocessor control command (see Preprocessing).

; can be used instead of a newline to separate statements.

Register Names
--------------

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

  * The 8 global registers are referred to as %gN.

  * The 8 outgoing registers are referred to as %oN.

  * The 8 local registers are referred to as %lN.

  * The 8 incoming registers are referred to as %iN.

  * The frame pointer register %i6 can be referenced using the alias %fp.

  * The stack pointer register %o6 can be referenced using the alias %sp.

Floating point registers are simply referred to as %fN. 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, %f34 is a legal floating point register, but %f35 is not.

Certain V9 instructions allow access to ancillary state registers. Most simply they can be referred to as %asrN where N can be from 16 to 31.  However, there are some aliases defined to reference ASR registers defined for various UltraSPARC processors:

  * The tick compare register is referred to as %tick_cmpr.

  * The system tick register is referred to as %stick.  An alias, %sys_tick, exists but is deprecated and should not be used by new software.

  * The system tick compare register is referred to as %stick_cmpr. An alias, %sys_tick_cmpr, exists but is deprecated and should not be used by new software.

  * The software interrupt register is referred to as %softint.

  * The set software interrupt register is referred to as %set_softint. The mnemonic %softint_set is provided as an alias.

  * The clear software interrupt register is referred to as %clear_softint.  The mnemonic %softint_clear is provided as an alias.

  * The performance instrumentation counters register is referred to as %pic.

  * The performance control register is referred to as %pcr.

  * The graphics status register is referred to as %gsr.

  * The V9 dispatch control register is referred to as %dcr.

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

In V9, there are 4 sets of floating point condition codes which are referred to as %fccN.

Several special privileged and non-privileged registers exist:

  * The V9 address space identifier register is referred to as %asi.

  * The V9 restorable windows register is referred to as %canrestore.

  * The V9 savable windows register is referred to as %cansave.

  * The V9 clean windows register is referred to as %cleanwin.

  * The V9 current window pointer register is referred to as %cwp.

  * The floating-point queue register is referred to as %fq.

  * The V8 co-processor queue register is referred to as %cq.

  * The floating point status register is referred to as %fsr.

  * The other windows register is referred to as %otherwin.

  * The V9 program counter register is referred to as %pc.

  * The V9 next program counter register is referred to as %npc.

  * The V9 processor interrupt level register is referred to as %pil.

  * The V9 processor state register is referred to as %pstate.

  * The trap base address register is referred to as %tba.

  * The V9 tick register is referred to as %tick.

  * The V9 trap level is referred to as %tl.

  * The V9 trap program counter is referred to as %tpc.

  * The V9 trap next program counter is referred to as %tnpc.

  * The V9 trap state is referred to as %tstate.

  * The V9 trap type is referred to as %tt.

  * The V9 condition codes is referred to as %ccr.

  * The V9 floating-point registers state is referred to as %fprs.

  * The V9 version register is referred to as %ver.

  * The V9 window state register is referred to as %wstate.

  * The Y register is referred to as %y.

  * The V8 window invalid mask register is referred to as %wim.

  * The V8 processor state register is referred to as %psr.

  * The V9 global register level register is referred to as %gl.

Several special register names exist for hypervisor mode code:

  * The hyperprivileged processor state register is referred to as %hpstate.

  * The hyperprivileged trap state register is referred to as %htstate.

  * The hyperprivileged interrupt pending register is referred to as %hintp.

  * The hyperprivileged trap base address register is referred to as %htba.

  * The hyperprivileged implementation version register is referred to as %hver.

  * The hyperprivileged system tick compare register is referred to as %hstick_cmpr.  Note that there is no %hstick register, the normal %stick is used.

Constants
---------

Several Sparc instructions take an immediate operand field for which mnemonic names exist.  Two such examples are membar and prefetch.  Another example are the set of V9 memory access instruction that allow specification of an address space identifier.

The membar instruction specifies a memory barrier that is the defined by the operand which is a bitmask.  The supported mask mnemonics are:

  * #Sync requests that all operations (including nonmemory reference operations) appearing prior to the membar must have been performed and the effects of any exceptions become visible before any instructions after the membar may be initiated.  This corresponds to membar cmask field bit 2.

  * #MemIssue requests that all memory reference operations appearing prior to the membar must have been performed before any memory operation after the membar may be initiated.  This corresponds to membar cmask field bit 1.

  * #Lookaside requests that a store appearing prior to the membar must complete before any load following the membar referencing the same address can be initiated.  This corresponds to membar cmask field bit 0.

  * #StoreStore defines that the effects of all stores appearing prior to the membar instruction must be visible to all processors before the effect of any stores following the membar.  Equivalent to the deprecated stbar instruction. This corresponds to membar mmask field bit 3.

  * #LoadStore defines all loads appearing prior to the membar instruction must have been performed before the effect of any stores following the membar is visible to any other processor.  This corresponds to membar mmask field bit 2.

  * #StoreLoad defines that the effects of all stores appearing prior to the membar instruction must be visible to all processors before loads following the membar may be performed. This corresponds to membar mmask field bit 1.

  * #LoadLoad defines that all loads appearing prior to the membar instruction must have been performed before any loads following the membar may be performed.  This corresponds to membar mmask field bit 0.

These values can be ored together, for example:

     membar #Sync
     membar #StoreLoad | #LoadLoad
     membar #StoreLoad | #StoreStore

The prefetch and prefetcha instructions take a prefetch function code.  The following prefetch function code constant mnemonics are available:

  * #n_reads requests a prefetch for several reads, and corresponds to a prefetch function code of 0.

     #one_read requests a prefetch for one read, and corresponds to a prefetch function code of 1.

     #n_writes requests a prefetch for several writes (and possibly reads), and corresponds to a prefetch function code of 2.

     #one_write requests a prefetch for one write, and corresponds to a prefetch function code of 3.

     #page requests a prefetch page, and corresponds to a prefetch function code of 4.

     #invalidate requests a prefetch invalidate, and corresponds to a prefetch function code of 16.

     #unified requests a prefetch to the nearest unified cache, and corresponds to a prefetch function code of 17.

     #n_reads_strong requests a strong prefetch for several reads, and corresponds to a prefetch function code of 20.

     #one_read_strong requests a strong prefetch for one read, and corresponds to a prefetch function code of 21.

     #n_writes_strong requests a strong prefetch for several writes, and corresponds to a prefetch function code of 22.

     #one_write_strong requests a strong prefetch for one write, and corresponds to a prefetch function code of 23.

     Onle one prefetch code may be specified.  Here are some examples:

          prefetch  [%l0 + %l2], #one_read
          prefetch  [%g2 + 8], #n_writes
          prefetcha [%g1] 0x8, #unified
          prefetcha [%o0 + 0x10] %asi, #n_reads

     The actual behavior of a given prefetch function code is processor specific.  If a processor does not implement a given prefetch function code, it will treat the prefetch instruction as a nop.

     For instructions that accept an immediate address space identifier, AS provides many mnemonics corresponding to V9 defined as well as UltraSPARC and Niagara extended values. For example, #ASI_P and #ASI_BLK_INIT_QUAD_LDD_AIUS. See the V9 and processor specific manuals for details.

Relocations
-----------

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

R_SPARC_HI22 is obtained using %hi and R_SPARC_LO10 is obtained using %lo.  Likewise R_SPARC_HIX22 is obtained from %hix and R_SPARC_LOX10 is obtained using %lox.  For example:

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

     sethi %hix(symbol), %g1
     xor   %g1, %lox(symbol), %g1

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:

  * R_SPARC_HH22 is requested using %hh.  It can also be generated using %uhi.

  * R_SPARC_HM10 is requested using %hm.  It can also be generated using %ulo.

  * R_SPARC_LM22 is requested using %lm.

  * R_SPARC_H44 is requested using %h44.

  * R_SPARC_M44 is requested using %m44.

  * R_SPARC_L44 is requested using %l44 or %l34.

  * R_SPARC_H34 is requested using %h34.

The %l34 generates a R_SPARC_L44 relocation because it calculates the necessary value, and therefore no explicit R_SPARC_L34 relocation needed to be created for this purpose.

The %h34 and %l34 relocations are used for the abs34 code model.  Here is an example abs34 address generation sequence:

     sethi %h34(symbol), %g1
     sllx  %g1, 2, %g1
     or    %g1, %l34(symbol), %g1

The PC relative relocation R_SPARC_PC22 can be obtained by enclosing an operand inside of %pc22.  Likewise, the R_SPARC_PC10 relocation can be obtained using %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:

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

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

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

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

  * R_SPARC_TLS_GD_HI22 is requested using %tgd_hi22.

  * R_SPARC_TLS_GD_LO10 is requested using %tgd_lo10.

  * R_SPARC_TLS_GD_ADD is requested using %tgd_add.

  * R_SPARC_TLS_GD_CALL is requested using %tgd_call.

  * R_SPARC_TLS_LDM_HI22 is requested using %tldm_hi22.

  * R_SPARC_TLS_LDM_LO10 is requested using %tldm_lo10.

  * R_SPARC_TLS_LDM_ADD is requested using %tldm_add.

  * R_SPARC_TLS_LDM_CALL is requested using %tldm_call.

  * R_SPARC_TLS_LDO_HIX22 is requested using %tldo_hix22.

  * R_SPARC_TLS_LDO_LOX10 is requested using %tldo_lox10.

  * R_SPARC_TLS_LDO_ADD is requested using %tldo_add.

  * R_SPARC_TLS_IE_HI22 is requested using %tie_hi22.

  * R_SPARC_TLS_IE_LO10 is requested using %tie_lo10.

  * R_SPARC_TLS_IE_LD is requested using %tie_ld.

  * R_SPARC_TLS_IE_LDX is requested using %tie_ldx.

  * R_SPARC_TLS_IE_ADD is requested using %tie_add.

  * R_SPARC_TLS_LE_HIX22 is requested using %tle_hix22.

  * R_SPARC_TLS_LE_LOX10 is requested using %tle_lox10.

Here are some example TLS model sequences.

First, General Dynamic:

     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

Local Dynamic:

     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)

Initial Exec:

     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)

And finally, Local Exec:

     sethi  %tle_hix22(symbol), %l1
     add    %l1, %tle_lox10(symbol), %l1
     add    %g7, %l1, %l1

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

Size Translations
-----------------

Often it is desirable to write code in an operand size agnostic manner.  AS provides support for this via operand size opcode translations.  Translations are supported for loads, stores, shifts, compare-and-swap atomics, and the clr synthetic instruction.

If generating 32-bit code, AS will generate the 32-bit opcode.  Whereas if 64-bit code is being generated, the 64-bit opcode will be emitted.  For example ldn will be transformed into ld for 32-bit code and ldx for 64-bit code.

Here is an example meant to demonstrate all the supported opcode translations:

     ldn   [%o0], %o1
     ldna  [%o0] %asi, %o2
     stn   %o1, [%o0]
     stna  %o2, [%o0] %asi
     slln  %o3, 3, %o3
     srln  %o4, 8, %o4
     sran  %o5, 12, %o5
     casn  [%o0], %o1, %o2
     casna [%o0] %asi, %o1, %o2
     clrn  %g1

In 32-bit mode AS will emit:

     ld   [%o0], %o1
     lda  [%o0] %asi, %o2
     st   %o1, [%o0]
     sta  %o2, [%o0] %asi
     sll  %o3, 3, %o3
     srl  %o4, 8, %o4
     sra  %o5, 12, %o5
     cas  [%o0], %o1, %o2
     casa [%o0] %asi, %o1, %o2
     clr  %g1

And in 64-bit mode AS will emit:

     ldx   [%o0], %o1
     ldxa  [%o0] %asi, %o2
     stx   %o1, [%o0]
     stxa  %o2, [%o0] %asi
     sllx  %o3, 3, %o3
     srlx  %o4, 8, %o4
     srax  %o5, 12, %o5
     casx  [%o0], %o1, %o2
     casxa [%o0] %asi, %o1, %o2
     clrx  %g1

Finally, the .nword translating directive is supported as well.  It is documented in the section on Sparc machine directives.

Floating Point
==============

The Sparc uses IEEE floating-point numbers.

Sparc Machine Directives
========================

The Sparc version of AS supports the following additional machine directives:

.align
     This must be followed by the desired alignment in bytes.

.common
     This must be followed by a symbol name, a positive number, and "bss".  This behaves somewhat like .comm, but the syntax is different.

.half
     This is functionally identical to .short.

.nword
     On the Sparc, the .nword directive produces native word sized value, ie. if assembling with -32 it is equivalent to .word, if assembling with -64 it is equivalent to .xword.

.proc
     This directive is ignored.  Any text following it on the same line is also ignored.

.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 #scratch, it is a scratch register, if it is #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.

.reserve
     This must be followed by a symbol name, a positive number, and "bss".  This behaves somewhat like .lcomm, but the syntax is different.

.seg
     This must be followed by "text", "data", or "data1".  It behaves like .text, .data, or .data 1.

.skip
     This is functionally identical to the .space directive.

.word
     On the Sparc, the .word directive produces 32 bit values, instead of the 16 bit values it produces on many other machines.

.xword
     On the Sparc V9 processor, the .xword directive produces 64 bit values.