gas/doc/c-arc.texi

   1 @c Copyright (C) 2000-2016 Free Software Foundation, Inc.
   2 @c This is part of the GAS manual.
   3 @c For copying conditions, see the file as.texinfo.
   4
   5 @ifset GENERIC
   6 @page
   7 @node ARC-Dependent
   8 @chapter ARC Dependent Features
   9 @end ifset
  10
  11 @ifclear GENERIC
  12 @node Machine Dependencies
  13 @chapter ARC Dependent Features
  14 @end ifclear
  15
  16 @set ARC_CORE_DEFAULT 6
  17
  18 @cindex ARC support
  19 @menu
  20 * ARC Options::              Options
  21 * ARC Syntax::               Syntax
  22 * ARC Directives::           ARC Machine Directives
  23 * ARC Modifiers::            ARC Assembler Modifiers
  24 * ARC Symbols::              ARC Pre-defined Symbols
  25 * ARC Opcodes::              Opcodes
  26 @end menu
  27
  28 @node ARC Options
  29 @section Options
  30 @cindex ARC options
  31 @cindex options for ARC
  32
  33 The following options control the type of CPU for which code is
  34 assembled, and generic constraints on the code generated:
  35
  36 @table @code
  37
  38 @item -mcpu=@var{cpu}
  39 @cindex @code{-mcpu=@var{cpu}} command line option, ARC
  40 Set architecture type and register usage for @var{cpu}.  There are
  41 also shortcut alias options available for backward compatibility and
  42 convenience.  Supported values for @var{cpu} are
  43
  44 @table @code
  45 @cindex @code{mA6} command line option, ARC
  46 @cindex @code{marc600} command line option, ARC
  47 @item arc600
  48 Assemble for ARC 600.  Aliases: @code{-mA6}, @code{-mARC600}.
  49
  50 @item arc601
  51 @cindex @code{mARC601} command line option, ARC
  52 Assemble for ARC 601.  Alias: @code{-mARC601}.
  53
  54 @item arc700
  55 @cindex @code{mA7} command line option, ARC
  56 @cindex @code{mARC700} command line option, ARC
  57 Assemble for ARC 700.  Aliases: @code{-mA7}, @code{-mARC700}.
  58
  59 @item arcem
  60 @cindex @code{mEM} command line option, ARC
  61 Assemble for ARC EM.  Aliases: @code{-mEM}
  62
  63 @item archs
  64 @cindex @code{mHS} command line option, ARC
  65 Assemble for ARC HS.  Aliases: @code{-mHS}, @code{-mav2hs}.
  66
  67 @end table
  68
  69 Note: the @code{.cpu} directive can to be used to select a core
  70 variant from within assembly code.
  71
  72 @cindex @code{-EB} command line option, ARC
  73 @item -EB
  74 This option specifies that the output generated by the assembler should
  75 be marked as being encoded for a big-endian processor.
  76
  77 @cindex @code{-EL} command line option, ARC
  78 @item -EL
  79 This option specifies that the output generated by the assembler should
  80 be marked as being encoded for a little-endian processor - this is the
  81 default.
  82
  83 @cindex @code{-mcode-density} command line option, ARC
  84 @item -mcode-density
  85 This option turns on Code Density instructions.  Only valid for ARC EM
  86 processors.
  87
  88 @cindex @code{-mrelax} command line option, ARC
  89 @item -mrelax
  90 Enable support for assembly-time relaxation.  The assembler will
  91 replace a longer version of an instruction with a shorter one,
  92 whenever it is possible.
  93
  94 @end table
  95
  96 @node ARC Syntax
  97 @section Syntax
  98 @menu
  99 * ARC-Chars::                Special Characters
 100 * ARC-Regs::                 Register Names
 101 @end menu
 102
 103 @node ARC-Chars
 104 @subsection Special Characters
 105
 106 @table @code
 107 @item %
 108 @cindex register name prefix character, ARC
 109 @cindex ARC register name prefix character
 110 A register name can optionally be prefixed by a @samp{%} character.  So
 111 register @code{%r0} is equivalent to @code{r0} in the assembly code.
 112
 113 @item #
 114 @cindex line comment character, ARC
 115 @cindex ARC line comment character
 116 The presence of a @samp{#} character within a line (but not at the
 117 start of a line) indicates the start of a comment that extends to the
 118 end of the current line.
 119
 120 @emph{Note:} if a line starts with a @samp{#} character then it can
 121 also be a logical line number directive (@pxref{Comments}) or a
 122 preprocessor control command (@pxref{Preprocessing}).
 123
 124 @item @@
 125 @cindex symbol prefix character, ARC
 126 @cindex ARC symbol prefix character
 127 Prefixing an operand with an @samp{@@} specifies that the operand is a
 128 symbol and not a register.  This is how the assembler disambiguates
 129 the use of an ARC register name as a symbol.  So the instruction
 130 @example
 131 mov r0, @@r0
 132 @end example
 133 moves the address of symbol @code{r0} into register @code{r0}.
 134
 135 @item `
 136 @cindex line separator, ARC
 137 @cindex statement separator, ARC
 138 @cindex ARC line separator
 139 The @samp{`} (backtick) character is used to separate statements on a
 140 single line.
 141
 142 @cindex line
 143 @item -
 144 @cindex C preprocessor macro separator, ARC
 145 @cindex ARC C preprocessor macro separator
 146 Used as a separator to obtain a sequence of commands from a C
 147 preprocessor macro.
 148
 149 @end table
 150
 151 @node ARC-Regs
 152 @subsection Register Names
 153
 154 @cindex ARC register names
 155 @cindex register names, ARC
 156 The ARC assembler uses the following register names for its core
 157 registers:
 158
 159 @table @code
 160 @item r0-r31
 161 @cindex core general registers, ARC
 162 @cindex ARC core general registers
 163 The core general registers.  Registers @code{r26} through @code{r31}
 164 have special functions, and are usually referred to by those synonyms.
 165
 166 @item gp
 167 @cindex global pointer, ARC
 168 @cindex ARC global pointer
 169 The global pointer and a synonym for @code{r26}.
 170
 171 @item fp
 172 @cindex frame pointer, ARC
 173 @cindex ARC frame pointer
 174 The frame pointer and a synonym for @code{r27}.
 175
 176 @item sp
 177 @cindex stack pointer, ARC
 178 @cindex ARC stack pointer
 179 The stack pointer and a synonym for @code{r28}.
 180
 181 @item ilink1
 182 @cindex level 1 interrupt link register, ARC
 183 @cindex ARC level 1 interrupt link register
 184 For ARC 600 and ARC 700, the level 1 interrupt link register and a
 185 synonym for @code{r29}.  Not supported for ARCv2.
 186
 187 @item ilink
 188 @cindex interrupt link register, ARC
 189 @cindex ARC interrupt link register
 190 For ARCv2, the interrupt link register and a synonym for @code{r29}.
 191 Not supported for ARC 600 and ARC 700.
 192
 193 @item ilink2
 194 @cindex level 2 interrupt link register, ARC
 195 @cindex ARC level 2 interrupt link register
 196 For ARC 600 and ARC 700, the level 2 interrupt link register and a
 197 synonym for @code{r30}.  Not supported for ARC v2.
 198
 199 @item blink
 200 @cindex link register, ARC
 201 @cindex ARC link register
 202 The link register and a synonym for @code{r31}.
 203
 204 @item r32-r59
 205 @cindex extension core registers, ARC
 206 @cindex ARC extension core registers
 207 The extension core registers.
 208
 209 @item lp_count
 210 @cindex loop counter, ARC
 211 @cindex ARC loop counter
 212 The loop count register.
 213
 214 @item pcl
 215 @cindex word aligned program counter, ARC
 216 @cindex ARC word aligned program counter
 217 The word aligned program counter.
 218
 219 @end table
 220
 221 In addition the ARC processor has a large number of @emph{auxiliary
 222 registers}.  The precise set depends on the extensions being
 223 supported, but the following baseline set are always defined:
 224
 225 @table @code
 226 @item identity
 227 @cindex Processor Identification register, ARC
 228 @cindex ARC Processor Identification register
 229 Processor Identification register.  Auxiliary register address 0x4.
 230
 231 @item pc
 232 @cindex Program Counter, ARC
 233 @cindex ARC Program Counter
 234 Program Counter.  Auxiliary register address 0x6.
 235
 236 @item status32
 237 @cindex Status register, ARC
 238 @cindex ARC Status register
 239 Status register.  Auxiliary register address 0x0a.
 240
 241 @item bta
 242 @cindex Branch Target Address, ARC
 243 @cindex ARC Branch Target Address
 244 Branch Target Address.  Auxiliary register address 0x412.
 245
 246 @item ecr
 247 @cindex Exception Cause Register, ARC
 248 @cindex ARC Exception Cause Register
 249 Exception Cause Register.  Auxiliary register address 0x403.
 250
 251 @item int_vector_base
 252 @cindex Interrupt Vector Base address, ARC
 253 @cindex ARC Interrupt Vector Base address
 254 Interrupt Vector Base address.  Auxiliary register address 0x25.
 255
 256 @item status32_p0
 257 @cindex Stored STATUS32 register on entry to level P0 interrupts, ARC
 258 @cindex ARC Stored STATUS32 register on entry to level P0 interrupts
 259 Stored STATUS32 register on entry to level P0 interrupts.  Auxiliary
 260 register address 0xb.
 261
 262 @item aux_user_sp
 263 @cindex Saved User Stack Pointer, ARC
 264 @cindex ARC Saved User Stack Pointer
 265 Saved User Stack Pointer.  Auxiliary register address 0xd.
 266
 267 @item eret
 268 @cindex Exception Return Address, ARC
 269 @cindex ARC Exception Return Address
 270 Exception Return Address.  Auxiliary register address 0x400.
 271
 272 @item erbta
 273 @cindex BTA saved on exception entry, ARC
 274 @cindex ARC BTA saved on exception entry
 275 BTA saved on exception entry.  Auxiliary register address 0x401.
 276
 277 @item erstatus
 278 @cindex STATUS32 saved on exception, ARC
 279 @cindex ARC STATUS32 saved on exception
 280 STATUS32 saved on exception.  Auxiliary register address 0x402.
 281
 282 @item bcr_ver
 283 @cindex Build Configuration Registers Version, ARC
 284 @cindex ARC Build Configuration Registers Version
 285 Build Configuration Registers Version.  Auxiliary register address 0x60.
 286
 287 @item bta_link_build
 288 @cindex Build configuration for: BTA Registers, ARC
 289 @cindex ARC Build configuration for: BTA Registers
 290 Build configuration for: BTA Registers.  Auxiliary register address 0x63.
 291
 292 @item vecbase_ac_build
 293 @cindex Build configuration for: Interrupts, ARC
 294 @cindex ARC Build configuration for: Interrupts
 295 Build configuration for: Interrupts.  Auxiliary register address 0x68.
 296
 297 @item rf_build
 298 @cindex Build configuration for: Core Registers, ARC
 299 @cindex ARC Build configuration for: Core Registers
 300 Build configuration for: Core Registers.  Auxiliary register address 0x6e.
 301
 302 @item dccm_build
 303 @cindex DCCM RAM Configuration Register, ARC
 304 @cindex ARC DCCM RAM Configuration Register
 305 DCCM RAM Configuration Register.  Auxiliary register address 0xc1.
 306
 307 @end table
 308
 309 Additional auxiliary register names are defined according to the
 310 processor architecture version and extensions selected by the options.
 311
 312 @node ARC Directives
 313 @section ARC Machine Directives
 314
 315 @cindex machine directives, ARC
 316 @cindex ARC machine directives
 317 The ARC version of @code{@value{AS}} supports the following additional
 318 machine directives:
 319
 320 @table @code
 321
 322 @cindex @code{lcomm} directive
 323 @item .lcomm @var{symbol}, @var{length}[, @var{alignment}]
 324 Reserve @var{length} (an absolute expression) bytes for a local common
 325 denoted by @var{symbol}.  The section and value of @var{symbol} are
 326 those of the new local common.  The addresses are allocated in the bss
 327 section, so that at run-time the bytes start off zeroed.  Since
 328 @var{symbol} is not declared global, it is normally not visible to
 329 @code{@value{LD}}.  The optional third parameter, @var{alignment},
 330 specifies the desired alignment of the symbol in the bss section,
 331 specified as a byte boundary (for example, an alignment of 16 means
 332 that the least significant 4 bits of the address should be zero).  The
 333 alignment must be an absolute expression, and it must be a power of
 334 two.  If no alignment is specified, as will set the alignment to the
 335 largest power of two less than or equal to the size of the symbol, up
 336 to a maximum of 16.
 337
 338 @cindex @code{lcommon} directive
 339 @item .lcommon @var{symbol}, @var{length}[, @var{alignment}]
 340 The same as @code{lcomm} directive.
 341
 342 @cindex @code{cpu} directive
 343 @item .cpu @var{cpu}
 344 The @code{.cpu} directive must be followed by the desired core
 345 version.  Permitted values for CPU are:
 346 @table @code
 347 @item ARC600
 348 Assemble for the ARC600 instruction set.
 349
 350 @item ARC700
 351 Assemble for the ARC700 instruction set.
 352
 353 @item EM
 354 Assemble for the ARC EM instruction set.
 355
 356 @item HS
 357 Assemble for the ARC HS instruction set.
 358
 359 @end table
 360
 361 Note: the @code{.cpu} directive overrides the command line option
 362 @code{-mcpu=@var{cpu}}; a warning is emitted when the version is not
 363 consistent between the two.
 364
 365 @item .extInstruction @var{name}, @var{opcode}, @var{subopcode}, @var{suffixclass}, @var{syntaxclass}
 366 @cindex @code{extInstruction} directive
 367 ARC allows the user to specify extension instructions.  These
 368 extension instructions are not macros; the assembler creates encodings
 369 for use of these instructions according to the specification by the
 370 user.
 371
 372 The first argument, @var{name}, gives the name of the instruction.
 373
 374 The second argument, @var{opcode}, is the opcode to be used (bits 31:27
 375 in the encoding).
 376
 377 The third argument, @var{subopcode}, is the sub-opcode to be used, but
 378 the correct value also depends on the fifth argument,
 379 @var{syntaxclass}
 380
 381 The fourth argument, @var{suffixclass}, determines the kinds of
 382 suffixes to be allowed.  Valid values are:
 383 @table @code
 384 @item SUFFIX_NONE
 385 No suffixes are permitted;
 386
 387 @item SUFFIX_COND
 388 Conditional suffixes are permitted;
 389
 390 @item SUFFIX_FLAG
 391 Flag setting suffixes are permitted.
 392
 393 @item SUFFIX_COND|SUFFIX_FLAG
 394 Both conditional and flag setting suffices are permitted.
 395
 396 @end table
 397
 398 The fifth and final argument, @var{syntaxclass}, determines the syntax
 399 class for the instruction.  It can have the following values:
 400 @table @code
 401 @item SYNTAX_2OP
 402 Two Operand Instruction;
 403
 404 @item SYNTAX_3OP
 405 Three Operand Instruction.
 406 @end table
 407
 408 The syntax class may be followed by @samp{|} and one of the following
 409 modifiers.
 410 @table @code
 411
 412 @item OP1_MUST_BE_IMM
 413 Modifies syntax class @code{SYNTAX_3OP}, specifying that the first
 414 operand of a three-operand instruction must be an immediate (i.e., the
 415 result is discarded).  This is usually used to set the flags using
 416 specific instructions and not retain results.
 417
 418 @item OP1_IMM_IMPLIED
 419 Modifies syntax class @code{SYNTAX_20P}, specifying that there is an
 420 implied immediate destination operand which does not appear in the
 421 syntax.
 422
 423 For example, if the source code contains an instruction like:
 424 @example
 425 inst r1,r2
 426 @end example
 427 the first argument is an implied immediate (that is, the result is
 428 discarded).  This is the same as though the source code were: inst
 429 0,r1,r2.
 430
 431 @end table
 432
 433 For example, defining a 64-bit multiplier with immediate operands:
 434 @example
 435         .extInstruction  mp64, 0x07, 0x2d, SUFFIX_COND|SUFFIX_FLAG,
 436                          SYNTAX_3OP|OP1_MUST_BE_IMM
 437 @end example
 438 which specifies an extension instruction named @code{mp64} with 3
 439 operands.  It sets the flags and can be used with a condition code,
 440 for which the first operand is an immediate, i.e. equivalent to
 441 discarding the result of the operation.
 442
 443 A two operands instruction variant would be:
 444 @example
 445         .extInstruction mul64, 0x07, 0x2d, SUFFIX_COND,
 446         SYNTAX_2OP|OP1_IMM_IMPLIED
 447 @end example
 448 which describes a two operand instruction with an implicit first
 449 immediate operand.  The result of this operation would be discarded.
 450
 451 @end table
 452
 453 @node ARC Modifiers
 454 @section ARC Assembler Modifiers
 455
 456 The following additional assembler modifiers have been added for
 457 position-independent code.  These modifiers are available only with
 458 the ARC 700 and above processors and generate relocation entries,
 459 which are interpreted by the linker as follows:
 460
 461 @table @code
 462 @item @@pcl(@var{symbol})
 463 @cindex @@pcl(@var{symbol}), ARC modifier
 464 Relative distance of @var{symbol}'s from the current program counter
 465 location.
 466
 467 @item @@gotpc(@var{symbol})
 468 @cindex @@gotpc(@var{symbol}), ARC modifier
 469 Relative distance of @var{symbol}'s Global Offset Table entry from the
 470 current program counter location.
 471
 472 @item @@gotoff(@var{symbol})
 473 @cindex @@gotoff(@var{symbol}), ARC modifier
 474 Distance of @var{symbol} from the base of the Global Offset Table.
 475
 476 @item @@plt(@var{symbol})
 477 @cindex @@plt(@var{symbol}), ARC modifier
 478 Distance of @var{symbol}'s Procedure Linkage Table entry from the
 479 current program counter.  This is valid only with branch and link
 480 instructions and PC-relative calls.
 481
 482 @item @@sda(@var{symbol})
 483 @cindex @@sda(@var{symbol}), ARC modifier
 484 Relative distance of @var{symbol} from the base of the Small Data
 485 Pointer.
 486
 487 @end table
 488
 489 @node ARC Symbols
 490 @section ARC Pre-defined Symbols
 491
 492 The following assembler symbols will prove useful when developing
 493 position-independent code.  These symbols are available only with the
 494 ARC 700 and above processors.
 495
 496 @table @code
 497 @item __GLOBAL_OFFSET_TABLE__
 498 @cindex __GLOBAL_OFFSET_TABLE__, ARC pre-defined symbol
 499 Symbol referring to the base of the Global Offset Table.
 500
 501 @item __DYNAMIC__
 502 @cindex __DYNAMIC__, ARC pre-defined symbol
 503 An alias for the Global Offset Table
 504 @code{Base__GLOBAL_OFFSET_TABLE__}.  It can be used only with
 505 @code{@@gotpc} modifiers.
 506
 507 @end table
 508
 509 @node ARC Opcodes
 510 @section Opcodes
 511
 512 @cindex ARC opcodes
 513 @cindex opcodes for ARC
 514
 515 For information on the ARC instruction set, see @cite{ARC Programmers
 516 Reference Manual}, available where you download the processor IP library.