This chapter documents the backend for the Atari Jaguar GPU/DSP RISC processor.

@section Legal

    This module is written in 2014-2017,2020,2021,2024-2026 by Frank Wille and
    is covered by the vasm copyright without modifications.


@section Additional options for this module

This module provides the following additional options:

@table @option
    @item -big
        Output big-endian code and data (default).

    @item -little
        Output little-endian code and data.

    @item -many
        Generate code for GPU or DSP RISC. All instructions are accepted
        (default).

    @item -mdsp
    @itemx -mjerry
        Generate code for the DSP RISC (part of Jerry).

    @item -mgpu
    @itemx -mtom
        Generate code for the GPU RISC (part of Tom).

    @item -no-opt
        Disable all standard optimizations which do not cause any
        side effects.

    @item -opt-jr=<n>
        Enable automatic translation of @code{JR} instructions with an
        out-of-range destination into @code{MOVEI dest,Rn} followed by
        @code{JUMP cc,(Rn)}, where @code{Rn} is always the selected
        temporary register.
        Note, that this optimization also works with the aligned pseudo
        instructions @code{AJR} and @code{AJUMP}.
@end table


@section General

This backend accepts RISC instructions for the GPU or DSP in Atari's
Jaguar custom chip set according to the "Jaguar Technical Reference Manual
for Tom & Jerry", Revision 8. Documentation bugs were fixed by using
various sources on the net.

The target address type is 32 bits.

Default alignment for instructions is 2 bytes.
Data is aligned to its natural alignment by default.


@section Optimizations

This backend performs the following optimizations and translations for
the GPU/DSP RISC instruction set:

@itemize @minus

@item @code{load (Rn+0),Rm} is optimized to @code{load (Rn),Rm}.

@item @code{store Rn,(Rm+0)} is optimized to @code{store Rn,(Rm)}.

@item @code{movei #x,Rn} is optimized to @code{moveq #x,Rn} when @code{x}
  is a constant from 0 to 31.

@item @code{jr cc,label} is translated to @code{movei label,Rn} plus
  @code{jump cc,(Rn)}, when enabled by option @option{-opt-jr=<n>}.

@end itemize


@section Extensions

This backend extends the selected syntax module by the following
directives (note that a leading dot is optional):

@table @code
@item <symbol> ccdef <expression>
      Allows defining a symbol for the condition codes used in @code{jump}
      and @code{jr} instructions. Must be constant number in the range of
      0 to 31 or another condition code symbol.

@item ccundef <symbol>
      Undefine a condition code symbol previously defined via @code{ccdef}.

@item dsp
      Select DSP instruction set.

@item <symbol> equr <Rn>
      Define a new symbol named <symbol> and assign the address register
      @code{Rn} to it. <Rn> may also be another register symbol.
      Note that a register symbol must be defined before it can be used.

@item equrundef <symbol>
      Undefine a register symbol previously defined via @code{equr}.

@item gpu
      Select GPU instruction set.

@item <symbol> regequ <Rn>
      Equivalent to @code{equr}.

@item regundef <symbol>
      Undefine a register symbol previously defined via @code{regequ}.

@end table      

All directives may be optionally preceded by a dot (@code{.}), for
compatibility with various syntax modules.

Additionally the backend supports these pseudo instructions for running
code in the Jaguar's main memory:

@table @code

@item ajr [<cc>],<lab>
    Same as the official @code{jr} instruction, but ensures that the opcode
    is 32-bit aligned. Inserts a @code{nop} instruction when needed.

@item ajump [<cc>],(<Rn>)
    Same as the official @code{jump} instruction, but ensures that the opcode
    is 32-bit aligned. Inserts a @code{nop} instruction when needed.

@end table      


@section Known Problems

    Some known problems of this module at the moment:

@itemize @minus

@item Encoding of @code{MOVEI} instruction in little-endian mode is unknown.
@item Some rare relocations are not perfectly supported. For example
      @code{LOAD Rn+x} or @code{ADDQ #x,Rn}, when external symbol @code{x}
      becomes 32.

@end itemize

@section Error Messages

This module has the following error messages:

@itemize @minus

@item 2001: data size %d not supported
@item 2002: value from %d to %d required
@item 2003: register expected

@end itemize
