CRIS Dependent Features
***********************

Command-line Options
====================

The CRIS version of AS has these machine-dependent command-line options.

The format of the generated object files can be either ELF or a.out, specified by the command-line options --emulation=crisaout and --emulation=criself. The default is ELF (criself), unless AS has been configured specifically for a.out by using the configuration name cris-axis-aout.

There are two different link-incompatible ELF object file variants for CRIS, for use in environments where symbols are expected to be prefixed by a leading _ character and for environments without such a symbol prefix.  The variant used for GNU/Linux port has no symbol prefix.  Which variant to produce is specified by either of the options --underscore and --no-underscore.  The default is --underscore. Since symbols in CRIS a.out objects are expected to have a _ prefix, specifying --no-underscore when generating a.out objects is an error.  Besides the object format difference, the effect of this option is to parse register names differently (see crisnous).  The --no-underscore option makes a $ register prefix mandatory.

The option --pic must be passed to AS in order to recognize the symbol syntax used for ELF (SVR4 PIC) position-independent-code (see crispic).  This will also affect expansion of instructions.  The expansion with --pic will use PC-relative rather than (slightly faster) absolute addresses in those expansions.  This option is only valid when generating ELF format object files.

The option --march=ARCHITECTURE specifies the recognized instruction set and recognized register names.  It also controls the architecture type of the object file.  Valid values for ARCHITECTURE are:

v0_v10
     All instructions and register names for any architecture variant in the set v0...v10 are recognized.  This is the default if the target is configured as cris-*.

v10
     Only instructions and register names for CRIS v10 (as found in ETRAX 100 LX) are recognized.  This is the default if the target is configured as crisv10-*.

v32
     Only instructions and register names for CRIS v32 (code name Guinness) are recognized.  This is the default if the target is configured as crisv32-*.  This value implies --no-mul-bug-abort.  (A subsequent --mul-bug-abort will turn it back on.)

common_v10_v32
     Only instructions with register names and addressing modes with opcodes common to the v10 and v32 are recognized.

When -N is specified, AS will emit a warning when a 16-bit branch instruction is expanded into a 32-bit multiple-instruction construct (see CRIS-Expand).

Some versions of the CRIS v10, for example in the Etrax 100 LX, contain a bug that causes destabilizing memory accesses when a multiply instruction is executed with certain values in the first operand just before a cache-miss.  When the --mul-bug-abort command-line option is active (the default value), AS will refuse to assemble a file containing a multiply instruction at a dangerous offset, one that could be the last on a cache-line, or is in a section with insufficient alignment.  This placement checking does not catch any case where the multiply instruction is dangerously placed because it is located in a delay-slot.  The --mul-bug-abort command-line option turns off the checking.

Instruction expansion
=====================

AS will silently choose an instruction that fits the operand size for [register+constant] operands.  For example, the offset 127 in move.d [r3+127],r4 fits in an instruction using a signed-byte offset.  Similarly, move.d [r2+32767],r1 will generate an instruction using a 16-bit offset.  For symbolic expressions and constants that do not fit in 16 bits including the sign bit, a 32-bit offset is generated.

For branches, AS will expand from a 16-bit branch instruction into a sequence of instructions that can reach a full 32-bit address.  Since this does not correspond to a single instruction, such expansions can optionally be warned about. See CRIS-Opts.

If the operand is found to fit the range, a lapc mnemonic will translate to a lapcq instruction.  Use lapc.d to force the 32-bit lapc instruction.

Similarly, the addo mnemonic will translate to the shortest fitting instruction of addoq, addo.w and addo.d, when used with a operand that is a constant known at assembly time.

Symbols
=======

Some symbols are defined by the assembler.  They're intended to be used in conditional assembly, for example:

      .if ..asm.arch.cris.v32
      CODE FOR CRIS V32
      .elseif ..asm.arch.cris.common_v10_v32
      CODE COMMON TO CRIS V32 AND CRIS V10
      .elseif ..asm.arch.cris.v10 | ..asm.arch.cris.any_v0_v10
      CODE FOR V10
      .else
      .error "Code needs to be added here."
      .endif

These symbols are defined in the assembler, reflecting command-line options, either when specified or the default. They are always defined, to 0 or 1.

..asm.arch.cris.any_v0_v10
     This symbol is non-zero when --march=v0_v10 is specified or the default.

..asm.arch.cris.common_v10_v32
     Set according to the option --march=common_v10_v32.

..asm.arch.cris.v10
     Reflects the option --march=v10.

..asm.arch.cris.v32
     Corresponds to --march=v10.

Speaking of symbols, when a symbol is used in code, it can have a suffix modifying its value for use in position-independent code. See CRIS-Pic.

Syntax
======

There are different aspects of the CRIS assembly syntax.

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

The character # is a line comment character.  It starts a comment if and only if it is placed at the beginning of a line.

A ; character starts a comment anywhere on the line, causing all characters up to the end of the line to be ignored.

A @ character is handled as a line separator equivalent to a logical new-line character (except in a comment), so separate instructions can be specified on a single line.

Symbols in position-independent code
------------------------------------

When generating position-independent code (SVR4 PIC) for use in cris-axis-linux-gnu or crisv32-axis-linux-gnu shared libraries, symbol suffixes are used to specify what kind of run-time symbol lookup will be used, expressed in the object as different relocation types.  Usually, all absolute symbol values must be located in a table, the global offset table, leaving the code position-independent; independent of values of global symbols and independent of the address of the code.  The suffix modifies the value of the symbol, into for example an index into the global offset table where the real symbol value is entered, or a PC-relative value, or a value relative to the start of the global offset table.  All symbol suffixes start with the character : (omitted in the list below).  Every symbol use in code or a read-only section must therefore have a PIC suffix to enable a useful shared library to be created. Usually, these constructs must not be used with an additive constant offset as is usually allowed, i.e. no 4 as in symbol + 4 is allowed.  This restriction is checked at link-time, not at assembly-time.

GOT

     Attaching this suffix to a symbol in an instruction causes the symbol to be entered into the global offset table.  The value is a 32-bit index for that symbol into the global offset table. The name of the corresponding relocation is R_CRIS_32_GOT.  Example: move.d [$r0+extsym:GOT],$r9

GOT16

     Same as for GOT, but the value is a 16-bit index into the global offset table.  The corresponding relocation is R_CRIS_16_GOT.  Example: move.d [$r0+asymbol:GOT16],$r10

PLT

     This suffix is used for function symbols.  It causes a procedure linkage table, an array of code stubs, to be created at the time the shared object is created or linked against, together with a global offset table entry.  The value is a pc-relative offset to the corresponding stub code in the procedure linkage table.  This arrangement causes the run-time symbol resolver to be called to look up and set the value of the symbol the first time the function is called (at latest; depending environment variables).  It is only safe to leave the symbol unresolved this way if all references are function calls. The name of the relocation is R_CRIS_32_PLT_PCREL. Example: add.d fnname:PLT,$pc

PLTG

     Like PLT, but the value is relative to the beginning of the global offset table.  The relocation is R_CRIS_32_PLT_GOTREL.  Example: move.d fnname:PLTG,$r3

GOTPLT

     Similar to PLT, but the value of the symbol is a 32-bit index into the global offset table.  This is somewhat of a mix between the effect of the GOT and the PLT suffix; the difference to GOT is that there will be a procedure linkage table entry created, and that the symbol is assumed to be a function entry and will be resolved by the run-time resolver as with PLT.  The relocation is R_CRIS_32_GOTPLT.  Example: jsr [$r0+fnname:GOTPLT]

GOTPLT16

     A variant of GOTPLT giving a 16-bit value.  Its relocation name is R_CRIS_16_GOTPLT.  Example: jsr [$r0+fnname:GOTPLT16]

GOTOFF

     This suffix must only be attached to a local symbol, but may be used in an expression adding an offset.  The value is the address of the symbol relative to the start of the global offset table.  The relocation name is R_CRIS_32_GOTREL. Example: move.d [$r0+localsym:GOTOFF],r3

Register names
--------------

A $ character may always prefix a general or special register name in an instruction operand but is mandatory when the option --no-underscore is specified or when the .syntax register_prefix directive is in effect (see crisnous).  Register names are case-insensitive.

Assembler Directives
--------------------

There are a few CRIS-specific pseudo-directives in addition to the generic ones.  See Pseudo Ops.  Constants emitted by pseudo-directives are in little-endian order for CRIS.  There is no support for floating-point-specific directives for CRIS.

.dword EXPRESSIONS

     The .dword directive is a synonym for .int, expecting zero or more EXPRESSIONS, separated by commas.  For each expression, a 32-bit little-endian constant is emitted.

.syntax ARGUMENT
     The .syntax directive takes as ARGUMENT one of the following case-sensitive choices.

     no_register_prefix

          The .syntax no_register_prefix directive makes a $ character prefix on all registers optional.  It overrides a previous setting, including the corresponding effect of the option --no-underscore.  If this directive is used when ordinary symbols do not have a _ character prefix, care must be taken to avoid ambiguities whether an operand is a register or a symbol; using symbols with names the same as general or special registers then invoke undefined behavior.

     register_prefix

          This directive makes a $ character prefix on all registers mandatory.  It overrides a previous setting, including the corresponding effect of the option --underscore.

     leading_underscore

          This is an assertion directive, emitting an error if the --no-underscore option is in effect.

     no_leading_underscore

          This is the opposite of the .syntax leading_underscore directive and emits an error if the option --underscore is in effect.

.arch ARGUMENT
     This is an assertion directive, giving an error if the specified ARGUMENT is not the same as the specified or default value for the --march=ARCHITECTURE option (see march-option).