Add support for ARC instruction relaxation in the assembler.

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

@c Copyright (C) 2000-2016 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 ARC-Dependent
@chapter ARC Dependent Features
@end ifset

@ifclear GENERIC
@node Machine Dependencies
@chapter ARC Dependent Features
@end ifclear

@set ARC_CORE_DEFAULT 6

@cindex ARC support
@menu
* ARC Options::              Options
* ARC Syntax::               Syntax
* ARC Directives::           ARC Machine Directives
* ARC Modifiers::            ARC Assembler Modifiers
* ARC Symbols::              ARC Pre-defined Symbols
* ARC Opcodes::              Opcodes
@end menu

@node ARC Options
@section Options
@cindex ARC options
@cindex options for ARC

The following options control the type of CPU for which code is
assembled, and generic constraints on the code generated:

@table @code

@item -mcpu=@var{cpu}
@cindex @code{-mcpu=@var{cpu}} command line option, ARC
Set architecture type and register usage for @var{cpu}.  There are
also shortcut alias options available for backward compatibility and
convenience.  Supported values for @var{cpu} are

@table @code
@cindex @code{mA6} command line option, ARC
@cindex @code{marc600} command line option, ARC
@item arc600
Assemble for ARC 600.  Aliases: @code{-mA6}, @code{-mARC600}.

@item arc601
@cindex @code{mARC601} command line option, ARC
Assemble for ARC 601.  Alias: @code{-mARC601}.

@item arc700
@cindex @code{mA7} command line option, ARC
@cindex @code{mARC700} command line option, ARC
Assemble for ARC 700.  Aliases: @code{-mA7}, @code{-mARC700}.

@item arcem
@cindex @code{mEM} command line option, ARC
Assemble for ARC EM.  Aliases: @code{-mEM}

@item archs
@cindex @code{mHS} command line option, ARC
Assemble for ARC HS.  Aliases: @code{-mHS}, @code{-mav2hs}.

@end table

Note: the @code{.cpu} directive can to be used to select a core
variant from within assembly code.

@cindex @code{-EB} command line option, ARC
@item -EB
This option specifies that the output generated by the assembler should
be marked as being encoded for a big-endian processor.

@cindex @code{-EL} command line option, ARC
@item -EL
This option specifies that the output generated by the assembler should
be marked as being encoded for a little-endian processor - this is the
default.

@cindex @code{-mcode-density} command line option, ARC
@item -mcode-density
This option turns on Code Density instructions.  Only valid for ARC EM
processors.

@cindex @code{-mrelax} command line option, ARC
@item -mrelax
Enable support for assembly-time relaxation.  The assembler will
replace a longer version of an instruction with a shorter one,
whenever it is possible.

@end table

@node ARC Syntax
@section Syntax
@menu
* ARC-Chars::                Special Characters
* ARC-Regs::                 Register Names
@end menu

@node ARC-Chars
@subsection Special Characters

@table @code
@item %
@cindex register name prefix character, ARC
@cindex ARC register name prefix character
A register name can optionally be prefixed by a @samp{%} character.  So
register @code{%r0} is equivalent to @code{r0} in the assembly code.

@item #
@cindex line comment character, ARC
@cindex ARC line comment character
The presence of a @samp{#} character within a line (but not at the
start of a line) indicates the start of a comment that extends to the
end of the current line.

@emph{Note:} if a line starts with a @samp{#} character then it can
also be a logical line number directive (@pxref{Comments}) or a
preprocessor control command (@pxref{Preprocessing}).

@item @@
@cindex symbol prefix character, ARC
@cindex ARC symbol prefix character
Prefixing an operand with an @samp{@@} specifies that the operand is a
symbol and not a register.  This is how the assembler disambiguates
the use of an ARC register name as a symbol.  So the instruction
@example
mov r0, @@r0
@end example
moves the address of symbol @code{r0} into register @code{r0}.

@item `
@cindex line separator, ARC
@cindex statement separator, ARC
@cindex ARC line separator
The @samp{`} (backtick) character is used to separate statements on a
single line.

@cindex line
@item -
@cindex C preprocessor macro separator, ARC
@cindex ARC C preprocessor macro separator
Used as a separator to obtain a sequence of commands from a C
preprocessor macro.

@end table

@node ARC-Regs
@subsection Register Names

@cindex ARC register names
@cindex register names, ARC
The ARC assembler uses the following register names for its core
registers:

@table @code
@item r0-r31
@cindex core general registers, ARC
@cindex ARC core general registers
The core general registers.  Registers @code{r26} through @code{r31}
have special functions, and are usually referred to by those synonyms.

@item gp
@cindex global pointer, ARC
@cindex ARC global pointer
The global pointer and a synonym for @code{r26}.

@item fp
@cindex frame pointer, ARC
@cindex ARC frame pointer
The frame pointer and a synonym for @code{r27}.

@item sp
@cindex stack pointer, ARC
@cindex ARC stack pointer
The stack pointer and a synonym for @code{r28}.

@item ilink1
@cindex level 1 interrupt link register, ARC
@cindex ARC level 1 interrupt link register
For ARC 600 and ARC 700, the level 1 interrupt link register and a
synonym for @code{r29}.  Not supported for ARCv2.

@item ilink
@cindex interrupt link register, ARC
@cindex ARC interrupt link register
For ARCv2, the interrupt link register and a synonym for @code{r29}.
Not supported for ARC 600 and ARC 700.

@item ilink2
@cindex level 2 interrupt link register, ARC
@cindex ARC level 2 interrupt link register
For ARC 600 and ARC 700, the level 2 interrupt link register and a
synonym for @code{r30}.  Not supported for ARC v2.

@item blink
@cindex link register, ARC
@cindex ARC link register
The link register and a synonym for @code{r31}.

@item r32-r59
@cindex extension core registers, ARC
@cindex ARC extension core registers
The extension core registers.

@item lp_count
@cindex loop counter, ARC
@cindex ARC loop counter
The loop count register.

@item pcl
@cindex word aligned program counter, ARC
@cindex ARC word aligned program counter
The word aligned program counter.

@end table

In addition the ARC processor has a large number of @emph{auxiliary
registers}.  The precise set depends on the extensions being
supported, but the following baseline set are always defined:

@table @code
@item identity
@cindex Processor Identification register, ARC
@cindex ARC Processor Identification register
Processor Identification register.  Auxiliary register address 0x4.

@item pc
@cindex Program Counter, ARC
@cindex ARC Program Counter
Program Counter.  Auxiliary register address 0x6.

@item status32
@cindex Status register, ARC
@cindex ARC Status register
Status register.  Auxiliary register address 0x0a.

@item bta
@cindex Branch Target Address, ARC
@cindex ARC Branch Target Address
Branch Target Address.  Auxiliary register address 0x412.

@item ecr
@cindex Exception Cause Register, ARC
@cindex ARC Exception Cause Register
Exception Cause Register.  Auxiliary register address 0x403.

@item int_vector_base
@cindex Interrupt Vector Base address, ARC
@cindex ARC Interrupt Vector Base address
Interrupt Vector Base address.  Auxiliary register address 0x25.

@item status32_p0
@cindex Stored STATUS32 register on entry to level P0 interrupts, ARC
@cindex ARC Stored STATUS32 register on entry to level P0 interrupts
Stored STATUS32 register on entry to level P0 interrupts.  Auxiliary
register address 0xb.

@item aux_user_sp
@cindex Saved User Stack Pointer, ARC
@cindex ARC Saved User Stack Pointer
Saved User Stack Pointer.  Auxiliary register address 0xd.

@item eret
@cindex Exception Return Address, ARC
@cindex ARC Exception Return Address
Exception Return Address.  Auxiliary register address 0x400.

@item erbta
@cindex BTA saved on exception entry, ARC
@cindex ARC BTA saved on exception entry
BTA saved on exception entry.  Auxiliary register address 0x401.

@item erstatus
@cindex STATUS32 saved on exception, ARC
@cindex ARC STATUS32 saved on exception
STATUS32 saved on exception.  Auxiliary register address 0x402.

@item bcr_ver
@cindex Build Configuration Registers Version, ARC
@cindex ARC Build Configuration Registers Version
Build Configuration Registers Version.  Auxiliary register address 0x60.

@item bta_link_build
@cindex Build configuration for: BTA Registers, ARC
@cindex ARC Build configuration for: BTA Registers
Build configuration for: BTA Registers.  Auxiliary register address 0x63.

@item vecbase_ac_build
@cindex Build configuration for: Interrupts, ARC
@cindex ARC Build configuration for: Interrupts
Build configuration for: Interrupts.  Auxiliary register address 0x68.

@item rf_build
@cindex Build configuration for: Core Registers, ARC
@cindex ARC Build configuration for: Core Registers
Build configuration for: Core Registers.  Auxiliary register address 0x6e.

@item dccm_build
@cindex DCCM RAM Configuration Register, ARC
@cindex ARC DCCM RAM Configuration Register
DCCM RAM Configuration Register.  Auxiliary register address 0xc1.

@end table

Additional auxiliary register names are defined according to the
processor architecture version and extensions selected by the options.

@node ARC Directives
@section ARC Machine Directives

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

@table @code

@cindex @code{lcomm} directive
@item .lcomm @var{symbol} , @var{length}[, @var{alignment}]
Reserve @var{length} (an absolute expression) bytes for a local common
denoted by @var{symbol}.  The section and value of @var{symbol} are
those of the new local common.  The addresses are allocated in the bss
section, so that at run-time the bytes start off zeroed.  Since
@var{symbol} is not declared global, it is normally not visible to
@code{@value{LD}}.  The optional third parameter, @var{alignment},
specifies the desired alignment of the symbol in the bss section,
specified as a byte boundary (for example, an alignment of 16 means
that the least significant 4 bits of the address should be zero).  The
alignment must be an absolute expression, and it must be a power of
two.  If no alignment is specified, as will set the alignment to the
largest power of two less than or equal to the size of the symbol, up
to a maximum of 16.

@cindex @code{lcommon} directive
@item .lcommon @var{symbol} , @var{length}[, @var{alignment}]
The same as @code{lcomm} directive.

@cindex @code{cpu} directive, ARC
@cindex @code{cpu} directive, ARC
The @code{.cpu} directive must be followed by the desired core
version.  Permitted values for CPU are:
@table @code
@item ARC600
Assemble for the ARC600 instruction set.

@item ARC700
Assemble for the ARC700 instruction set.

@item EM
Assemble for the ARC EM instruction set.

@item HS
Assemble for the ARC HS instruction set.

@end table

Note: the @code{.cpu} directive overrides the command line option
@code{-mcpu=@var{cpu}}; a warning is emitted when the version is not
consistent between the two.
@end table

@node ARC Modifiers
@section ARC Assembler Modifiers

The following additional assembler modifiers have been added for
position-independent code.  These modifiers are available only with
the ARC 700 and above processors and generate relocation entries,
which are interpreted by the linker as follows:

@table @code
@item @@pcl(@var{symbol})
@cindex @@pcl(@var{symbol}), ARC modifier
Relative distance of @var{symbol}'s from the current program counter
location.

@item @@gotpc(@var{symbol})
@cindex @@gotpc(@var{symbol}), ARC modifier
Relative distance of @var{symbol}'s Global Offset Table entry from the
current program counter location.

@item @@gotoff(@var{symbol})
@cindex @@gotoff(@var{symbol}), ARC modifier
Distance of @var{symbol} from the base of the Global Offset Table.

@item @@plt(@var{symbol})
@cindex @@plt(@var{symbol}), ARC modifier
Distance of @var{symbol}'s Procedure Linkage Table entry from the
current program counter.  This is valid only with branch and link
instructions and PC-relative calls.

@item @@sda(@var{symbol})
@cindex @@sda(@var{symbol}), ARC modifier
Relative distance of @var{symbol} from the base of the Small Data
Pointer.

@end table

@node ARC Symbols
@section ARC Pre-defined Symbols

The following assembler symbols will prove useful when developing
position-independent code.  These symbols are available only with the
ARC 700 and above processors.

@table @code
@item __GLOBAL_OFFSET_TABLE__
@cindex __GLOBAL_OFFSET_TABLE__, ARC pre-defined symbol
Symbol referring to the base of the Global Offset Table.

@item __DYNAMIC__
@cindex __DYNAMIC__, ARC pre-defined symbol
An alias for the Global Offset Table
@code{Base__GLOBAL_OFFSET_TABLE__}.  It can be used only with
@code{@@gotpc} modifiers.

@end table

@node ARC Opcodes
@section Opcodes

@cindex ARC opcodes
@cindex opcodes for ARC

For information on the ARC instruction set, see @cite{ARC Programmers
Reference Manual}, available where you download the processor IP library.