| 1 | @c Copyright (C) 2002-2019 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-Symbols:: Symbols |
| 20 | * CRIS-Syntax:: Syntax |
| 21 | @end menu |
| 22 | |
| 23 | @node CRIS-Opts |
| 24 | @section Command-line Options |
| 25 | |
| 26 | @cindex options, CRIS |
| 27 | @cindex CRIS options |
| 28 | The CRIS version of @code{@value{AS}} has these |
| 29 | machine-dependent command-line options. |
| 30 | |
| 31 | @cindex @option{--emulation=criself} command-line option, CRIS |
| 32 | @cindex @option{--emulation=crisaout} command-line option, CRIS |
| 33 | @cindex CRIS @option{--emulation=criself} command-line option |
| 34 | @cindex CRIS @option{--emulation=crisaout} command-line option |
| 35 | |
| 36 | The format of the generated object files can be either ELF or |
| 37 | a.out, specified by the command-line options |
| 38 | @option{--emulation=crisaout} and @option{--emulation=criself}. |
| 39 | The default is ELF (criself), unless @code{@value{AS}} has been |
| 40 | configured specifically for a.out by using the configuration |
| 41 | name @code{cris-axis-aout}. |
| 42 | |
| 43 | @cindex @option{--underscore} command-line option, CRIS |
| 44 | @cindex @option{--no-underscore} command-line option, CRIS |
| 45 | @cindex CRIS @option{--underscore} command-line option |
| 46 | @cindex CRIS @option{--no-underscore} command-line option |
| 47 | There are two different link-incompatible ELF object file |
| 48 | variants for CRIS, for use in environments where symbols are |
| 49 | expected to be prefixed by a leading @samp{_} character and for |
| 50 | environments without such a symbol prefix. The variant used for |
| 51 | GNU/Linux port has no symbol prefix. Which variant to produce |
| 52 | is specified by either of the options @option{--underscore} and |
| 53 | @option{--no-underscore}. The default is @option{--underscore}. |
| 54 | Since symbols in CRIS a.out objects are expected to have a |
| 55 | @samp{_} prefix, specifying @option{--no-underscore} when |
| 56 | generating a.out objects is an error. Besides the object format |
| 57 | difference, the effect of this option is to parse register names |
| 58 | differently (@pxref{crisnous}). The @option{--no-underscore} |
| 59 | option makes a @samp{$} register prefix mandatory. |
| 60 | |
| 61 | @cindex @option{--pic} command-line option, CRIS |
| 62 | @cindex CRIS @option{--pic} command-line option |
| 63 | @cindex Position-independent code, CRIS |
| 64 | @cindex CRIS position-independent code |
| 65 | The option @option{--pic} must be passed to @code{@value{AS}} in |
| 66 | order to recognize the symbol syntax used for ELF (SVR4 PIC) |
| 67 | position-independent-code (@pxref{crispic}). This will also |
| 68 | affect expansion of instructions. The expansion with |
| 69 | @option{--pic} will use PC-relative rather than (slightly |
| 70 | faster) absolute addresses in those expansions. This option is only |
| 71 | valid when generating ELF format object files. |
| 72 | |
| 73 | @cindex @option{--march=@var{architecture}} command-line option, CRIS |
| 74 | @cindex CRIS @option{--march=@var{architecture}} command-line option |
| 75 | @cindex Architecture variant option, CRIS |
| 76 | @cindex CRIS architecture variant option |
| 77 | The option @option{--march=@var{architecture}} |
| 78 | @anchor{march-option}specifies the recognized instruction set |
| 79 | and recognized register names. It also controls the |
| 80 | architecture type of the object file. Valid values for |
| 81 | @var{architecture} are: |
| 82 | @table @code |
| 83 | |
| 84 | @item v0_v10 |
| 85 | All instructions and register names for any architecture variant |
| 86 | in the set v0@dots{}v10 are recognized. This is the |
| 87 | default if the target is configured as cris-*. |
| 88 | |
| 89 | @item v10 |
| 90 | Only instructions and register names for CRIS v10 (as found in |
| 91 | ETRAX 100 LX) are recognized. This is the default if the target |
| 92 | is configured as crisv10-*. |
| 93 | |
| 94 | @item v32 |
| 95 | Only instructions and register names for CRIS v32 (code name |
| 96 | Guinness) are recognized. This is the default if the target is |
| 97 | configured as crisv32-*. This value implies |
| 98 | @option{--no-mul-bug-abort}. (A subsequent |
| 99 | @option{--mul-bug-abort} will turn it back on.) |
| 100 | |
| 101 | @item common_v10_v32 |
| 102 | Only instructions with register names and addressing modes with |
| 103 | opcodes common to the v10 and v32 are recognized. |
| 104 | @end table |
| 105 | |
| 106 | @cindex @option{-N} command-line option, CRIS |
| 107 | @cindex CRIS @option{-N} command-line option |
| 108 | When @option{-N} is specified, @code{@value{AS}} will emit a |
| 109 | warning when a 16-bit branch instruction is expanded into a |
| 110 | 32-bit multiple-instruction construct (@pxref{CRIS-Expand}). |
| 111 | |
| 112 | @cindex @option{--no-mul-bug-abort} command-line option, CRIS |
| 113 | @cindex @option{--mul-bug-abort} command-line option, CRIS |
| 114 | @cindex CRIS @option{--no-mul-bug-abort} command-line option |
| 115 | @cindex CRIS @option{--mul-bug-abort} command-line option |
| 116 | |
| 117 | Some versions of the CRIS v10, for example in the Etrax 100 LX, |
| 118 | contain a bug that causes destabilizing memory accesses when a |
| 119 | multiply instruction is executed with certain values in the |
| 120 | first operand just before a cache-miss. When the |
| 121 | @option{--mul-bug-abort} command-line option is active (the |
| 122 | default value), @code{@value{AS}} will refuse to assemble a file |
| 123 | containing a multiply instruction at a dangerous offset, one |
| 124 | that could be the last on a cache-line, or is in a section with |
| 125 | insufficient alignment. This placement checking does not catch |
| 126 | any case where the multiply instruction is dangerously placed |
| 127 | because it is located in a delay-slot. The |
| 128 | @option{--mul-bug-abort} command-line option turns off the |
| 129 | checking. |
| 130 | |
| 131 | @node CRIS-Expand |
| 132 | @section Instruction expansion |
| 133 | |
| 134 | @cindex instruction expansion, CRIS |
| 135 | @cindex CRIS instruction expansion |
| 136 | @code{@value{AS}} will silently choose an instruction that fits |
| 137 | the operand size for @samp{[register+constant]} operands. For |
| 138 | example, the offset @code{127} in @code{move.d [r3+127],r4} fits |
| 139 | in an instruction using a signed-byte offset. Similarly, |
| 140 | @code{move.d [r2+32767],r1} will generate an instruction using a |
| 141 | 16-bit offset. For symbolic expressions and constants that do |
| 142 | not fit in 16 bits including the sign bit, a 32-bit offset is |
| 143 | generated. |
| 144 | |
| 145 | For branches, @code{@value{AS}} will expand from a 16-bit branch |
| 146 | instruction into a sequence of instructions that can reach a |
| 147 | full 32-bit address. Since this does not correspond to a single |
| 148 | instruction, such expansions can optionally be warned about. |
| 149 | @xref{CRIS-Opts}. |
| 150 | |
| 151 | If the operand is found to fit the range, a @code{lapc} mnemonic |
| 152 | will translate to a @code{lapcq} instruction. Use @code{lapc.d} |
| 153 | to force the 32-bit @code{lapc} instruction. |
| 154 | |
| 155 | Similarly, the @code{addo} mnemonic will translate to the |
| 156 | shortest fitting instruction of @code{addoq}, @code{addo.w} and |
| 157 | @code{addo.d}, when used with a operand that is a constant known |
| 158 | at assembly time. |
| 159 | |
| 160 | @node CRIS-Symbols |
| 161 | @section Symbols |
| 162 | @cindex Symbols, built-in, CRIS |
| 163 | @cindex Symbols, CRIS, built-in |
| 164 | @cindex CRIS built-in symbols |
| 165 | @cindex Built-in symbols, CRIS |
| 166 | |
| 167 | Some symbols are defined by the assembler. They're intended to |
| 168 | be used in conditional assembly, for example: |
| 169 | @smallexample |
| 170 | .if ..asm.arch.cris.v32 |
| 171 | @var{code for CRIS v32} |
| 172 | .elseif ..asm.arch.cris.common_v10_v32 |
| 173 | @var{code common to CRIS v32 and CRIS v10} |
| 174 | .elseif ..asm.arch.cris.v10 | ..asm.arch.cris.any_v0_v10 |
| 175 | @var{code for v10} |
| 176 | .else |
| 177 | .error "Code needs to be added here." |
| 178 | .endif |
| 179 | @end smallexample |
| 180 | |
| 181 | These symbols are defined in the assembler, reflecting |
| 182 | command-line options, either when specified or the default. |
| 183 | They are always defined, to 0 or 1. |
| 184 | @table @code |
| 185 | |
| 186 | @item ..asm.arch.cris.any_v0_v10 |
| 187 | This symbol is non-zero when @option{--march=v0_v10} is specified |
| 188 | or the default. |
| 189 | |
| 190 | @item ..asm.arch.cris.common_v10_v32 |
| 191 | Set according to the option @option{--march=common_v10_v32}. |
| 192 | |
| 193 | @item ..asm.arch.cris.v10 |
| 194 | Reflects the option @option{--march=v10}. |
| 195 | |
| 196 | @item ..asm.arch.cris.v32 |
| 197 | Corresponds to @option{--march=v10}. |
| 198 | @end table |
| 199 | |
| 200 | Speaking of symbols, when a symbol is used in code, it can have |
| 201 | a suffix modifying its value for use in position-independent |
| 202 | code. @xref{CRIS-Pic}. |
| 203 | |
| 204 | @node CRIS-Syntax |
| 205 | @section Syntax |
| 206 | |
| 207 | There are different aspects of the CRIS assembly syntax. |
| 208 | |
| 209 | @menu |
| 210 | * CRIS-Chars:: Special Characters |
| 211 | * CRIS-Pic:: Position-Independent Code Symbols |
| 212 | * CRIS-Regs:: Register Names |
| 213 | * CRIS-Pseudos:: Assembler Directives |
| 214 | @end menu |
| 215 | |
| 216 | @node CRIS-Chars |
| 217 | @subsection Special Characters |
| 218 | @cindex line comment characters, CRIS |
| 219 | @cindex CRIS line comment characters |
| 220 | |
| 221 | The character @samp{#} is a line comment character. It starts a |
| 222 | comment if and only if it is placed at the beginning of a line. |
| 223 | |
| 224 | A @samp{;} character starts a comment anywhere on the line, |
| 225 | causing all characters up to the end of the line to be ignored. |
| 226 | |
| 227 | A @samp{@@} character is handled as a line separator equivalent |
| 228 | to a logical new-line character (except in a comment), so |
| 229 | separate instructions can be specified on a single line. |
| 230 | |
| 231 | @node CRIS-Pic |
| 232 | @subsection Symbols in position-independent code |
| 233 | @cindex Symbols in position-independent code, CRIS |
| 234 | @cindex CRIS symbols in position-independent code |
| 235 | @cindex Position-independent code, symbols in, CRIS |
| 236 | |
| 237 | When generating @anchor{crispic}position-independent code (SVR4 |
| 238 | PIC) for use in cris-axis-linux-gnu or crisv32-axis-linux-gnu |
| 239 | shared libraries, symbol |
| 240 | suffixes are used to specify what kind of run-time symbol lookup |
| 241 | will be used, expressed in the object as different |
| 242 | @emph{relocation types}. Usually, all absolute symbol values |
| 243 | must be located in a table, the @emph{global offset table}, |
| 244 | leaving the code position-independent; independent of values of |
| 245 | global symbols and independent of the address of the code. The |
| 246 | suffix modifies the value of the symbol, into for example an |
| 247 | index into the global offset table where the real symbol value |
| 248 | is entered, or a PC-relative value, or a value relative to the |
| 249 | start of the global offset table. All symbol suffixes start |
| 250 | with the character @samp{:} (omitted in the list below). Every |
| 251 | symbol use in code or a read-only section must therefore have a |
| 252 | PIC suffix to enable a useful shared library to be created. |
| 253 | Usually, these constructs must not be used with an additive |
| 254 | constant offset as is usually allowed, i.e.@: no 4 as in |
| 255 | @code{symbol + 4} is allowed. This restriction is checked at |
| 256 | link-time, not at assembly-time. |
| 257 | |
| 258 | @table @code |
| 259 | @item GOT |
| 260 | |
| 261 | Attaching this suffix to a symbol in an instruction causes the |
| 262 | symbol to be entered into the global offset table. The value is |
| 263 | a 32-bit index for that symbol into the global offset table. |
| 264 | The name of the corresponding relocation is |
| 265 | @samp{R_CRIS_32_GOT}. Example: @code{move.d |
| 266 | [$r0+extsym:GOT],$r9} |
| 267 | |
| 268 | @item GOT16 |
| 269 | |
| 270 | Same as for @samp{GOT}, but the value is a 16-bit index into the |
| 271 | global offset table. The corresponding relocation is |
| 272 | @samp{R_CRIS_16_GOT}. Example: @code{move.d |
| 273 | [$r0+asymbol:GOT16],$r10} |
| 274 | |
| 275 | @item PLT |
| 276 | |
| 277 | This suffix is used for function symbols. It causes a |
| 278 | @emph{procedure linkage table}, an array of code stubs, to be |
| 279 | created at the time the shared object is created or linked |
| 280 | against, together with a global offset table entry. The value |
| 281 | is a pc-relative offset to the corresponding stub code in the |
| 282 | procedure linkage table. This arrangement causes the run-time |
| 283 | symbol resolver to be called to look up and set the value of the |
| 284 | symbol the first time the function is called (at latest; |
| 285 | depending environment variables). It is only safe to leave the |
| 286 | symbol unresolved this way if all references are function calls. |
| 287 | The name of the relocation is @samp{R_CRIS_32_PLT_PCREL}. |
| 288 | Example: @code{add.d fnname:PLT,$pc} |
| 289 | |
| 290 | @item PLTG |
| 291 | |
| 292 | Like PLT, but the value is relative to the beginning of the |
| 293 | global offset table. The relocation is |
| 294 | @samp{R_CRIS_32_PLT_GOTREL}. Example: @code{move.d |
| 295 | fnname:PLTG,$r3} |
| 296 | |
| 297 | @item GOTPLT |
| 298 | |
| 299 | Similar to @samp{PLT}, but the value of the symbol is a 32-bit |
| 300 | index into the global offset table. This is somewhat of a mix |
| 301 | between the effect of the @samp{GOT} and the @samp{PLT} suffix; |
| 302 | the difference to @samp{GOT} is that there will be a procedure |
| 303 | linkage table entry created, and that the symbol is assumed to |
| 304 | be a function entry and will be resolved by the run-time |
| 305 | resolver as with @samp{PLT}. The relocation is |
| 306 | @samp{R_CRIS_32_GOTPLT}. Example: @code{jsr |
| 307 | [$r0+fnname:GOTPLT]} |
| 308 | |
| 309 | @item GOTPLT16 |
| 310 | |
| 311 | A variant of @samp{GOTPLT} giving a 16-bit value. Its |
| 312 | relocation name is @samp{R_CRIS_16_GOTPLT}. Example: @code{jsr |
| 313 | [$r0+fnname:GOTPLT16]} |
| 314 | |
| 315 | @item GOTOFF |
| 316 | |
| 317 | This suffix must only be attached to a local symbol, but may be |
| 318 | used in an expression adding an offset. The value is the |
| 319 | address of the symbol relative to the start of the global offset |
| 320 | table. The relocation name is @samp{R_CRIS_32_GOTREL}. |
| 321 | Example: @code{move.d [$r0+localsym:GOTOFF],r3} |
| 322 | @end table |
| 323 | |
| 324 | @node CRIS-Regs |
| 325 | @subsection Register names |
| 326 | @cindex register names, CRIS |
| 327 | @cindex CRIS register names |
| 328 | |
| 329 | A @samp{$} character may always prefix a general or special |
| 330 | register name in an instruction operand but is mandatory when |
| 331 | the option @option{--no-underscore} is specified or when the |
| 332 | @code{.syntax register_prefix} directive is in effect |
| 333 | (@pxref{crisnous}). Register names are case-insensitive. |
| 334 | |
| 335 | @node CRIS-Pseudos |
| 336 | @subsection Assembler Directives |
| 337 | @cindex assembler directives, CRIS |
| 338 | @cindex pseudo-ops, CRIS |
| 339 | @cindex CRIS assembler directives |
| 340 | @cindex CRIS pseudo-ops |
| 341 | |
| 342 | There are a few CRIS-specific pseudo-directives in addition to |
| 343 | the generic ones. @xref{Pseudo Ops}. Constants emitted by |
| 344 | pseudo-directives are in little-endian order for CRIS. There is |
| 345 | no support for floating-point-specific directives for CRIS. |
| 346 | |
| 347 | @table @code |
| 348 | @item .dword EXPRESSIONS |
| 349 | @cindex assembler directive .dword, CRIS |
| 350 | @cindex pseudo-op .dword, CRIS |
| 351 | @cindex CRIS assembler directive .dword |
| 352 | @cindex CRIS pseudo-op .dword |
| 353 | |
| 354 | The @code{.dword} directive is a synonym for @code{.int}, |
| 355 | expecting zero or more EXPRESSIONS, separated by commas. For |
| 356 | each expression, a 32-bit little-endian constant is emitted. |
| 357 | |
| 358 | @item .syntax ARGUMENT |
| 359 | @cindex assembler directive .syntax, CRIS |
| 360 | @cindex pseudo-op .syntax, CRIS |
| 361 | @cindex CRIS assembler directive .syntax |
| 362 | @cindex CRIS pseudo-op .syntax |
| 363 | The @code{.syntax} directive takes as @var{ARGUMENT} one of the |
| 364 | following case-sensitive choices. |
| 365 | |
| 366 | @table @code |
| 367 | @item no_register_prefix |
| 368 | |
| 369 | The @code{.syntax no_register_prefix} @anchor{crisnous}directive |
| 370 | makes a @samp{$} character prefix on all registers optional. It |
| 371 | overrides a previous setting, including the corresponding effect |
| 372 | of the option @option{--no-underscore}. If this directive is |
| 373 | used when ordinary symbols do not have a @samp{_} character |
| 374 | prefix, care must be taken to avoid ambiguities whether an |
| 375 | operand is a register or a symbol; using symbols with names the |
| 376 | same as general or special registers then invoke undefined |
| 377 | behavior. |
| 378 | |
| 379 | @item register_prefix |
| 380 | |
| 381 | This directive makes a @samp{$} character prefix on all |
| 382 | registers mandatory. It overrides a previous setting, including |
| 383 | the corresponding effect of the option @option{--underscore}. |
| 384 | |
| 385 | @item leading_underscore |
| 386 | |
| 387 | This is an assertion directive, emitting an error if the |
| 388 | @option{--no-underscore} option is in effect. |
| 389 | |
| 390 | @item no_leading_underscore |
| 391 | |
| 392 | This is the opposite of the @code{.syntax leading_underscore} |
| 393 | directive and emits an error if the option @option{--underscore} |
| 394 | is in effect. |
| 395 | @end table |
| 396 | |
| 397 | @item .arch ARGUMENT |
| 398 | @cindex assembler directive .arch, CRIS |
| 399 | @cindex pseudo-op .arch, CRIS |
| 400 | @cindex CRIS assembler directive .arch |
| 401 | @cindex CRIS pseudo-op .arch |
| 402 | This is an assertion directive, giving an error if the specified |
| 403 | @var{ARGUMENT} is not the same as the specified or default value |
| 404 | for the @option{--march=@var{architecture}} option |
| 405 | (@pxref{march-option}). |
| 406 | |
| 407 | @c If you compare with md_pseudo_table, you see that we don't |
| 408 | @c document ".file" and ".loc" here. This is because we're just |
| 409 | @c wrapping the corresponding ELF function and emitting an error for |
| 410 | @c a.out. |
| 411 | @end table |