gas/doc/c-cris.texi

   1 @c Copyright 2002 Free Software Foundation, Inc.
   2 @c This is part of the GAS manual.
   3 @c For copying conditions, see the file as.texinfo.
   4 @c CRIS description contributed by Axis Communications.
   5 @ifset GENERIC
   6 @page
   7 @node CRIS-Dependent
   8 @chapter CRIS Dependent Features
   9 @end ifset
  10 @ifclear GENERIC
  11 @node Machine Dependencies
  12 @chapter CRIS Dependent Features
  13 @end ifclear
  14
  15 @cindex CRIS support
  16 @menu
  17 * CRIS-Opts::              Command-line Options
  18 * CRIS-Expand::            Instruction expansion
  19 * CRIS-Syntax::            Syntax
  20 @end menu
  21
  22 @node CRIS-Opts
  23 @section Command-line Options
  24
  25 @cindex options, CRIS
  26 @cindex CRIS options
  27 The CRIS version of @code{@value{AS}} has these
  28 machine-dependent command-line options.
  29
  30 @cindex @option{--emulation=criself} command line option, CRIS
  31 @cindex @option{--emulation=crisaout} command line option, CRIS
  32 @cindex CRIS @option{--emulation=criself} command line option
  33 @cindex CRIS @option{--emulation=crisaout} command line option
  34
  35 The format of the generated object files can be either ELF or
  36 a.out, specified by the command-line options
  37 @option{--emulation=crisaout} and @option{--emulation=criself}.
  38 The default is ELF (criself), unless @code{@value{AS}} has been
  39 configured specifically for a.out by using the configuration
  40 name @code{cris-axis-aout}.
  41
  42 @cindex @option{--underscore} command line option, CRIS
  43 @cindex @option{--no-underscore} command line option, CRIS
  44 @cindex CRIS @option{--underscore} command line option
  45 @cindex CRIS @option{--no-underscore} command line option
  46 There are two different link-incompatible ELF object file
  47 variants for CRIS, for use in environments where symbols are
  48 expected to be prefixed by a leading @samp{_} character and for
  49 environments without such a symbol prefix.  The variant used for
  50 GNU/Linux port has no symbol prefix.  Which variant to produce
  51 is specified by either of the options @option{--underscore} and
  52 @option{--no-underscore}.  The default is @option{--underscore}.
  53 Since symbols in CRIS a.out objects are expected to have a
  54 @samp{_} prefix, specifying @option{--no-underscore} when
  55 generating a.out objects is an error.  Besides the object format
  56 difference, the effect of this option is to parse register names
  57 differently (@pxref{crisnous}).  The @option{--no-underscore}
  58 option makes a @samp{$} register prefix mandatory.
  59
  60 @cindex @option{--pic} command line option, CRIS
  61 @cindex CRIS @option{--pic} command line option
  62 @cindex Position-independent code, CRIS
  63 @cindex CRIS position-independent code
  64 The option @option{--pic} must be passed to @code{@value{AS}} in
  65 order to recognize the symbol syntax used for ELF (SVR4 PIC)
  66 position-independent-code (@pxref{crispic}).  This will also
  67 affect expansion of instructions.  The expansion with
  68 @option{--pic} will use PC-relative rather than (slightly
  69 faster) absolute addresses in those expansions.
  70
  71 @cindex @option{-N} command line option, CRIS
  72 @cindex CRIS @option{-N} command line option
  73 When @option{-N} is specified, @code{@value{AS}} will emit a
  74 warning when a 16-bit branch instruction is expanded into a
  75 32-bit multiple-instruction construct (@pxref{CRIS-Expand}).
  76
  77 @cindex @option{--no-mul-bug-abort} command line option, CRIS
  78 @cindex @option{--mul-bug-abort} command line option, CRIS
  79 @cindex CRIS @option{--no-mul-bug-abort} command line option
  80 @cindex CRIS @option{--mul-bug-abort} command line option
  81
  82 Some versions of the CRIS v10, for example in the Etrax 100 LX,
  83 contain a bug that causes destabilizing memory accesses when a
  84 multiply instruction is executed with certain values in the
  85 first operand just before a cache-miss.  When the
  86 @option{--mul-bug-abort} command line option is active (the
  87 default value), @code{@value{AS}} will refuse to assemble a file
  88 containing a multiply instruction at a dangerous offset, one
  89 that could be the last on a cache-line, or is in a section with
  90 insufficient alignment.  This placement checking does not catch
  91 any case where the multiply instruction is dangerously placed
  92 because it is located in a delay-slot.  The
  93 @option{--mul-bug-abort} command line option turns off the
  94 checking.
  95
  96 @node CRIS-Expand
  97 @section Instruction expansion
  98
  99 @cindex instruction expansion, CRIS
 100 @cindex CRIS instruction expansion
 101 @code{@value{AS}} will silently choose an instruction that fits
 102 the operand size for @samp{[register+constant]} operands.  For
 103 example, the offset @code{127} in @code{move.d [r3+127],r4} fits
 104 in an instruction using a signed-byte offset.  Similarly,
 105 @code{move.d [r2+32767],r1} will generate an instruction using a
 106 16-bit offset.  For symbolic expressions and constants that do
 107 not fit in 16 bits including the sign bit, a 32-bit offset is
 108 generated.
 109
 110 For branches, @code{@value{AS}} will expand from a 16-bit branch
 111 instruction into a sequence of instructions that can reach a
 112 full 32-bit address.  Since this does not correspond to a single
 113 instruction, such expansions can optionally be warned about.
 114 @xref{CRIS-Opts}.
 115
 116 @node CRIS-Syntax
 117 @section Syntax
 118
 119 There are different aspects of the CRIS assembly syntax.
 120
 121 @menu
 122 * CRIS-Chars::                  Special Characters
 123 * CRIS-Pic::                    Position-Independent Code Symbols
 124 * CRIS-Regs::                   Register Names
 125 * CRIS-Pseudos::                Assembler Directives
 126 @end menu
 127
 128 @node CRIS-Chars
 129 @subsection Special Characters
 130 @cindex line comment characters, CRIS
 131 @cindex CRIS line comment characters
 132
 133 The character @samp{#} is a line comment character.  It starts a
 134 comment if and only if it is placed at the beginning of a line.
 135
 136 A @samp{;} character starts a comment anywhere on the line,
 137 causing all characters up to the end of the line to be ignored.
 138
 139 A @samp{@@} character is handled as a line separator equivalent
 140 to a logical new-line character (except in a comment), so
 141 separate instructions can be specified on a single line.
 142
 143 @node CRIS-Pic
 144 @subsection Symbols in position-independent code
 145 @cindex Symbols in position-independent code, CRIS
 146 @cindex CRIS symbols in position-independent code
 147 @cindex Position-independent code, symbols in, CRIS
 148
 149 When generating @anchor{crispic}position-independent code (SVR4
 150 PIC) for use in cris-axis-linux-gnu shared libraries, symbol
 151 suffixes are used to specify what kind of run-time symbol lookup
 152 will be used, expressed in the object as different
 153 @emph{relocation types}.  Usually, all absolute symbol values
 154 must be located in a table, the @emph{global offset table},
 155 leaving the code position-independent; independent of values of
 156 global symbols and independent of the address of the code.  The
 157 suffix modifies the value of the symbol, into for example an
 158 index into the global offset table where the real symbol value
 159 is entered, or a PC-relative value, or a value relative to the
 160 start of the global offset table.  All symbol suffixes start
 161 with the character @samp{:} (omitted in the list below).  Every
 162 symbol use in code or a read-only section must therefore have a
 163 PIC suffix to enable a useful shared library to be created.
 164 Usually, these constructs must not be used with an additive
 165 constant offset as is usually allowed, i.e.@: no 4 as in
 166 @code{symbol + 4} is allowed.  This restriction is checked at
 167 link-time, not at assembly-time.
 168
 169 @table @code
 170 @item GOT
 171
 172 Attaching this suffix to a symbol in an instruction causes the
 173 symbol to be entered into the global offset table.  The value is
 174 a 32-bit index for that symbol into the global offset table.
 175 The name of the corresponding relocation is
 176 @samp{R_CRIS_32_GOT}.  Example: @code{move.d
 177 [$r0+extsym:GOT],$r9}
 178
 179 @item GOT16
 180
 181 Same as for @samp{GOT}, but the value is a 16-bit index into the
 182 global offset table.  The corresponding relocation is
 183 @samp{R_CRIS_16_GOT}.  Example: @code{move.d
 184 [$r0+asymbol:GOT16],$r10}
 185
 186 @item PLT
 187
 188 This suffix is used for function symbols.  It causes a
 189 @emph{procedure linkage table}, an array of code stubs, to be
 190 created at the time the shared object is created or linked
 191 against, together with a global offset table entry.  The value
 192 is a pc-relative offset to the corresponding stub code in the
 193 procedure linkage table.  This arrangement causes the run-time
 194 symbol resolver to be called to look up and set the value of the
 195 symbol the first time the function is called (at latest;
 196 depending environment variables).  It is only safe to leave the
 197 symbol unresolved this way if all references are function calls.
 198 The name of the relocation is @samp{R_CRIS_32_PLT_PCREL}.
 199 Example: @code{add.d fnname:PLT,$pc}
 200
 201 @item PLTG
 202
 203 Like PLT, but the value is relative to the beginning of the
 204 global offset table.  The relocation is
 205 @samp{R_CRIS_32_PLT_GOTREL}.  Example: @code{move.d
 206 fnname:PLTG,$r3}
 207
 208 @item GOTPLT
 209
 210 Similar to @samp{PLT}, but the value of the symbol is a 32-bit
 211 index into the global offset table.  This is somewhat of a mix
 212 between the effect of the @samp{GOT} and the @samp{PLT} suffix;
 213 the difference to @samp{GOT} is that there will be a procedure
 214 linkage table entry created, and that the symbol is assumed to
 215 be a function entry and will be resolved by the run-time
 216 resolver as with @samp{PLT}.  The relocation is
 217 @samp{R_CRIS_32_GOTPLT}.  Example: @code{jsr
 218 [$r0+fnname:GOTPLT]}
 219
 220 @item GOTPLT16
 221
 222 A variant of @samp{GOTPLT} giving a 16-bit value.  Its
 223 relocation name is @samp{R_CRIS_16_GOTPLT}.  Example: @code{jsr
 224 [$r0+fnname:GOTPLT16]}
 225
 226 @item GOTOFF
 227
 228 This suffix must only be attached to a local symbol, but may be
 229 used in an expression adding an offset.  The value is the
 230 address of the symbol relative to the start of the global offset
 231 table.  The relocation name is @samp{R_CRIS_32_GOTREL}.
 232 Example: @code{move.d [$r0+localsym:GOTOFF],r3}
 233 @end table
 234
 235 @node CRIS-Regs
 236 @subsection Register names
 237 @cindex register names, CRIS
 238 @cindex CRIS register names
 239
 240 A @samp{$} character may always prefix a general or special
 241 register name in an instruction operand but is mandatory when
 242 the option @option{--no-underscore} is specified or when the
 243 @code{.syntax register_prefix} directive is in effect
 244 (@pxref{crisnous}).  Register names are case-insensitive.
 245
 246 @node CRIS-Pseudos
 247 @subsection Assembler Directives
 248 @cindex assembler directives, CRIS
 249 @cindex pseudo-ops, CRIS
 250 @cindex CRIS assembler directives
 251 @cindex CRIS pseudo-ops
 252
 253 There are a few CRIS-specific pseudo-directives in addition to
 254 the generic ones.  @xref{Pseudo Ops}.  Constants emitted by
 255 pseudo-directives are in little-endian order for CRIS.  There is
 256 no support for floating-point-specific directives for CRIS.
 257
 258 @table @code
 259 @item .dword EXPRESSIONS
 260 @cindex assembler directive .dword, CRIS
 261 @cindex pseudo-op .dword, CRIS
 262 @cindex CRIS assembler directive .dword
 263 @cindex CRIS pseudo-op .dword
 264
 265 The @code{.dword} directive is a synonym for @code{.int},
 266 expecting zero or more EXPRESSIONS, separated by commas.  For
 267 each expression, a 32-bit little-endian constant is emitted.
 268
 269 @item .syntax ARGUMENT
 270 @cindex assembler directive .syntax, CRIS
 271 @cindex pseudo-op .syntax, CRIS
 272 @cindex CRIS assembler directive .syntax
 273 @cindex CRIS pseudo-op .syntax
 274 The @code{.syntax} directive takes as ARGUMENT one of the
 275 following case-sensitive choices.
 276
 277 @table @code
 278 @item no_register_prefix
 279
 280 The @code{.syntax no_register_prefix} @anchor{crisnous}directive
 281 makes a @samp{$} character prefix on all registers optional.  It
 282 overrides a previous setting, including the corresponding effect
 283 of the option @option{--no-underscore}.  If this directive is
 284 used when ordinary symbols do not have a @samp{_} character
 285 prefix, care must be taken to avoid ambiguities whether an
 286 operand is a register or a symbol; using symbols with names the
 287 same as general or special registers then invoke undefined
 288 behavior.
 289
 290 @item register_prefix
 291
 292 This directive makes a @samp{$} character prefix on all
 293 registers mandatory.  It overrides a previous setting, including
 294 the corresponding effect of the option @option{--underscore}.
 295
 296 @item leading_underscore
 297
 298 This is an assertion directive, emitting an error if the
 299 @option{--no-underscore} option is in effect.
 300
 301 @item no_leading_underscore
 302
 303 This is the opposite of the @code{.syntax leading_underscore}
 304 directive and emits an error if the option @option{--underscore}
 305 is in effect.
 306 @end table
 307
 308 @c If you compare with md_pseudo_table, you see that we don't
 309 @c document ".file" and ".loc" here.  This is because we're just
 310 @c wrapping the corresponding ELF function and emitting an error for
 311 @c a.out.
 312 @end table