Update year range in copyright notice of binutils files

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

@c Copyright (C) 2000-2021 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 arc600_norm
Assemble for ARC 600 with norm instructions.

@item arc600_mul64
Assemble for ARC 600 with mul64 instructions.

@item arc600_mul32x16
Assemble for ARC 600 with mul32x16 instructions.

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

@item arc601_norm
Assemble for ARC 601 with norm instructions.

@item arc601_mul64
Assemble for ARC 601 with mul64 instructions.

@item arc601_mul32x16
Assemble for ARC 601 with mul32x16 instructions.

@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 em
Assemble for ARC EM, identical as arcem variant.

@item em4
Assemble for ARC EM with code-density instructions.

@item em4_dmips
Assemble for ARC EM with code-density instructions.

@item em4_fpus
Assemble for ARC EM with code-density instructions.

@item em4_fpuda
Assemble for ARC EM with code-density, and double-precision assist
instructions.

@item quarkse_em
Assemble for QuarkSE-EM cpu.

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

@item hs
Assemble for ARC HS.

@item hs34
Assemble for ARC HS34.

@item hs38
Assemble for ARC HS38.

@item hs38_linux
Assemble for ARC HS38 with floating point support on.

@item nps400
@cindex @code{mnps400} command-line option, ARC
Assemble for ARC 700 with NPS-400 extended instructions.

@end table

Note: the @code{.cpu} directive (@pxref{ARC Directives}) 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.

@cindex @code{-mnps400} command-line option, ARC
@item -mnps400
Enable support for NPS-400 extended instructions.

@cindex @code{-mspfp} command-line option, ARC
@item -mspfp
Enable support for single-precision floating point instructions.

@cindex @code{-mdpfp} command-line option, ARC
@item -mdpfp
Enable support for double-precision floating point instructions.

@cindex @code{-mfpuda} command-line option, ARC
@item -mfpuda
Enable support for double-precision assist floating point instructions.
Only valid for ARC EM processors.

@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, ARC
@item .lcommon @var{symbol}, @var{length}[, @var{alignment}]
The same as @code{lcomm} directive.

@cindex @code{cpu} directive, ARC
@item .cpu @var{cpu}
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 arc600_norm
Assemble for ARC 600 with norm instructions.

@item arc600_mul64
Assemble for ARC 600 with mul64 instructions.

@item arc600_mul32x16
Assemble for ARC 600 with mul32x16 instructions.

@item arc601
Assemble for ARC 601 instruction set.

@item arc601_norm
Assemble for ARC 601 with norm instructions.

@item arc601_mul64
Assemble for ARC 601 with mul64 instructions.

@item arc601_mul32x16
Assemble for ARC 601 with mul32x16 instructions.

@item ARC700
Assemble for the ARC700 instruction set.

@item NPS400
Assemble for the NPS400 instruction set.

@item EM
Assemble for the ARC EM instruction set.

@item arcem
Assemble for ARC EM instruction set

@item em4
Assemble for ARC EM with code-density instructions.

@item em4_dmips
Assemble for ARC EM with code-density instructions.

@item em4_fpus
Assemble for ARC EM with code-density instructions.

@item em4_fpuda
Assemble for ARC EM with code-density, and double-precision assist
instructions.

@item quarkse_em
Assemble for QuarkSE-EM instruction set.

@item HS
Assemble for the ARC HS instruction set.

@item archs
Assemble for ARC HS instruction set.

@item hs
Assemble for ARC HS instruction set.

@item hs34
Assemble for ARC HS34 instruction set.

@item hs38
Assemble for ARC HS38 instruction set.

@item hs38_linux
Assemble for ARC HS38 with floating point support on.

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

@item .extAuxRegister @var{name}, @var{addr}, @var{mode}
@cindex @code{extAuxRegister} directive, ARC
Auxiliary registers can be defined in the assembler source code by
using this directive.  The first parameter, @var{name}, is the name of the
new auxiliary register.  The second parameter, @var{addr}, is
address the of the auxiliary register.  The third parameter,
@var{mode}, specifies whether the register is readable and/or writable
and is one of:
@table @code
@item r
Read only;

@item w
Write only;

@item r|w
Read and write.

@end table

For example:
@example
        .extAuxRegister mulhi, 0x12, w
@end example
specifies a write only extension auxiliary register, @var{mulhi} at
address 0x12.

@item .extCondCode @var{suffix}, @var{val}
@cindex @code{extCondCode} directive, ARC
ARC supports extensible condition codes.  This directive defines a new
condition code, to be known by the suffix, @var{suffix} and will
depend on the value, @var{val} in the condition code.

For example:
@example
        .extCondCode is_busy,0x14
        add.is_busy  r1,r2,r3
@end example
will only execute the @code{add} instruction if the condition code
value is 0x14.

@item .extCoreRegister @var{name}, @var{regnum}, @var{mode}, @var{shortcut}
@cindex @code{extCoreRegister} directive, ARC
Specifies an extension core register named @var{name} as a synonym for
the register numbered @var{regnum}.  The register number must be
between 32 and 59.  The third argument, @var{mode}, indicates whether
the register is readable and/or writable and is one of:
@table @code
@item r
Read only;

@item w
Write only;

@item r|w
Read and write.

@end table

The final parameter, @var{shortcut} indicates whether the register has
a short cut in the pipeline.  The valid values are:
@table @code
@item can_shortcut
The register has a short cut in the pipeline;

@item cannot_shortcut
The register does not have a short cut in the pipeline.
@end table

For example:
@example
        .extCoreRegister mlo, 57, r , can_shortcut
@end example
defines a read only extension core register, @code{mlo}, which is
register 57, and can short cut the pipeline.

@item .extInstruction @var{name}, @var{opcode}, @var{subopcode}, @var{suffixclass}, @var{syntaxclass}
@cindex @code{extInstruction} directive, ARC
ARC allows the user to specify extension instructions.  These
extension instructions are not macros; the assembler creates encodings
for use of these instructions according to the specification by the
user.

The first argument, @var{name}, gives the name of the instruction.

The second argument, @var{opcode}, is the opcode to be used (bits 31:27
in the encoding).

The third argument, @var{subopcode}, is the sub-opcode to be used, but
the correct value also depends on the fifth argument,
@var{syntaxclass}

The fourth argument, @var{suffixclass}, determines the kinds of
suffixes to be allowed.  Valid values are:
@table @code
@item SUFFIX_NONE
No suffixes are permitted;

@item SUFFIX_COND
Conditional suffixes are permitted;

@item SUFFIX_FLAG
Flag setting suffixes are permitted.

@item SUFFIX_COND|SUFFIX_FLAG
Both conditional and flag setting suffices are permitted.

@end table

The fifth and final argument, @var{syntaxclass}, determines the syntax
class for the instruction.  It can have the following values:
@table @code
@item SYNTAX_2OP
Two Operand Instruction;

@item SYNTAX_3OP
Three Operand Instruction.

@item SYNTAX_1OP
One Operand Instruction.

@item SYNTAX_NOP
No Operand Instruction.
@end table

The syntax class may be followed by @samp{|} and one of the following
modifiers.
@table @code

@item OP1_MUST_BE_IMM
Modifies syntax class @code{SYNTAX_3OP}, specifying that the first
operand of a three-operand instruction must be an immediate (i.e., the
result is discarded).  This is usually used to set the flags using
specific instructions and not retain results.

@item OP1_IMM_IMPLIED
Modifies syntax class @code{SYNTAX_20P}, specifying that there is an
implied immediate destination operand which does not appear in the
syntax.

For example, if the source code contains an instruction like:
@example
inst r1,r2
@end example
the first argument is an implied immediate (that is, the result is
discarded).  This is the same as though the source code were: inst
0,r1,r2.

@end table

For example, defining a 64-bit multiplier with immediate operands:
@example
        .extInstruction  mp64, 0x07, 0x2d, SUFFIX_COND|SUFFIX_FLAG,
                         SYNTAX_3OP|OP1_MUST_BE_IMM
@end example
which specifies an extension instruction named @code{mp64} with 3
operands.  It sets the flags and can be used with a condition code,
for which the first operand is an immediate, i.e. equivalent to
discarding the result of the operation.

A two operands instruction variant would be:
@example
        .extInstruction mul64, 0x07, 0x2d, SUFFIX_COND,
        SYNTAX_2OP|OP1_IMM_IMPLIED
@end example
which describes a two operand instruction with an implicit first
immediate operand.  The result of this operation would be discarded.

@cindex @code{.arc_attribute} directive, ARC
@item .arc_attribute @var{tag}, @var{value}
Set the ARC object attribute @var{tag} to @var{value}.

The @var{tag} is either an attribute number, or one of the following:
@code{Tag_ARC_PCS_config}, @code{Tag_ARC_CPU_base},
@code{Tag_ARC_CPU_variation}, @code{Tag_ARC_CPU_name},
@code{Tag_ARC_ABI_rf16}, @code{Tag_ARC_ABI_osver}, @code{Tag_ARC_ABI_sda},
@code{Tag_ARC_ABI_pic}, @code{Tag_ARC_ABI_tls}, @code{Tag_ARC_ABI_enumsize},
@code{Tag_ARC_ABI_exceptions}, @code{Tag_ARC_ABI_double_size},
@code{Tag_ARC_ISA_config}, @code{Tag_ARC_ISA_apex},
@code{Tag_ARC_ISA_mpy_option}

The @var{value} is either a @code{number}, @code{"string"}, or
@code{number, "string"} depending on the tag.

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