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 @item nps400
  68 @cindex @code{mnps400} command line option, ARC
  69 Assemble for ARC 700 with NPS-400 extended instructions.
  70
  71 @end table
  72
  73 Note: the @code{.cpu} directive (@pxref{ARC Directives}) can
  74 to be used to select a core variant from within assembly code.
  75
  76 @cindex @code{-EB} command line option, ARC
  77 @item -EB
  78 This option specifies that the output generated by the assembler should
  79 be marked as being encoded for a big-endian processor.
  80
  81 @cindex @code{-EL} command line option, ARC
  82 @item -EL
  83 This option specifies that the output generated by the assembler should
  84 be marked as being encoded for a little-endian processor - this is the
  85 default.
  86
  87 @cindex @code{-mcode-density} command line option, ARC
  88 @item -mcode-density
  89 This option turns on Code Density instructions.  Only valid for ARC EM
  90 processors.
  91
  92 @cindex @code{-mrelax} command line option, ARC
  93 @item -mrelax
  94 Enable support for assembly-time relaxation.  The assembler will
  95 replace a longer version of an instruction with a shorter one,
  96 whenever it is possible.
  97
  98 @cindex @code{-mnps400} command line option, ARC
  99 @item -mnps400
 100 Enable support for NPS-400 extended instructions.
 101
 102 @cindex @code{-mspfp} command line option, ARC
 103 @item -mspfp
 104 Enable support for single-precision floating point instructions.
 105
 106 @cindex @code{-mdpfp} command line option, ARC
 107 @item -mdpfp
 108 Enable support for double-precision floating point instructions.
 109
 110 @cindex @code{-mfpuda} command line option, ARC
 111 @item -mfpuda
 112 Enable support for double-precision assist floating point instructions.
 113 Only valid for ARC EM processors.
 114
 115 @end table
 116
 117 @node ARC Syntax
 118 @section Syntax
 119 @menu
 120 * ARC-Chars::                Special Characters
 121 * ARC-Regs::                 Register Names
 122 @end menu
 123
 124 @node ARC-Chars
 125 @subsection Special Characters
 126
 127 @table @code
 128 @item %
 129 @cindex register name prefix character, ARC
 130 @cindex ARC register name prefix character
 131 A register name can optionally be prefixed by a @samp{%} character.  So
 132 register @code{%r0} is equivalent to @code{r0} in the assembly code.
 133
 134 @item #
 135 @cindex line comment character, ARC
 136 @cindex ARC line comment character
 137 The presence of a @samp{#} character within a line (but not at the
 138 start of a line) indicates the start of a comment that extends to the
 139 end of the current line.
 140
 141 @emph{Note:} if a line starts with a @samp{#} character then it can
 142 also be a logical line number directive (@pxref{Comments}) or a
 143 preprocessor control command (@pxref{Preprocessing}).
 144
 145 @item @@
 146 @cindex symbol prefix character, ARC
 147 @cindex ARC symbol prefix character
 148 Prefixing an operand with an @samp{@@} specifies that the operand is a
 149 symbol and not a register.  This is how the assembler disambiguates
 150 the use of an ARC register name as a symbol.  So the instruction
 151 @example
 152 mov r0, @@r0
 153 @end example
 154 moves the address of symbol @code{r0} into register @code{r0}.
 155
 156 @item `
 157 @cindex line separator, ARC
 158 @cindex statement separator, ARC
 159 @cindex ARC line separator
 160 The @samp{`} (backtick) character is used to separate statements on a
 161 single line.
 162
 163 @cindex line
 164 @item -
 165 @cindex C preprocessor macro separator, ARC
 166 @cindex ARC C preprocessor macro separator
 167 Used as a separator to obtain a sequence of commands from a C
 168 preprocessor macro.
 169
 170 @end table
 171
 172 @node ARC-Regs
 173 @subsection Register Names
 174
 175 @cindex ARC register names
 176 @cindex register names, ARC
 177 The ARC assembler uses the following register names for its core
 178 registers:
 179
 180 @table @code
 181 @item r0-r31
 182 @cindex core general registers, ARC
 183 @cindex ARC core general registers
 184 The core general registers.  Registers @code{r26} through @code{r31}
 185 have special functions, and are usually referred to by those synonyms.
 186
 187 @item gp
 188 @cindex global pointer, ARC
 189 @cindex ARC global pointer
 190 The global pointer and a synonym for @code{r26}.
 191
 192 @item fp
 193 @cindex frame pointer, ARC
 194 @cindex ARC frame pointer
 195 The frame pointer and a synonym for @code{r27}.
 196
 197 @item sp
 198 @cindex stack pointer, ARC
 199 @cindex ARC stack pointer
 200 The stack pointer and a synonym for @code{r28}.
 201
 202 @item ilink1
 203 @cindex level 1 interrupt link register, ARC
 204 @cindex ARC level 1 interrupt link register
 205 For ARC 600 and ARC 700, the level 1 interrupt link register and a
 206 synonym for @code{r29}.  Not supported for ARCv2.
 207
 208 @item ilink
 209 @cindex interrupt link register, ARC
 210 @cindex ARC interrupt link register
 211 For ARCv2, the interrupt link register and a synonym for @code{r29}.
 212 Not supported for ARC 600 and ARC 700.
 213
 214 @item ilink2
 215 @cindex level 2 interrupt link register, ARC
 216 @cindex ARC level 2 interrupt link register
 217 For ARC 600 and ARC 700, the level 2 interrupt link register and a
 218 synonym for @code{r30}.  Not supported for ARC v2.
 219
 220 @item blink
 221 @cindex link register, ARC
 222 @cindex ARC link register
 223 The link register and a synonym for @code{r31}.
 224
 225 @item r32-r59
 226 @cindex extension core registers, ARC
 227 @cindex ARC extension core registers
 228 The extension core registers.
 229
 230 @item lp_count
 231 @cindex loop counter, ARC
 232 @cindex ARC loop counter
 233 The loop count register.
 234
 235 @item pcl
 236 @cindex word aligned program counter, ARC
 237 @cindex ARC word aligned program counter
 238 The word aligned program counter.
 239
 240 @end table
 241
 242 In addition the ARC processor has a large number of @emph{auxiliary
 243 registers}.  The precise set depends on the extensions being
 244 supported, but the following baseline set are always defined:
 245
 246 @table @code
 247 @item identity
 248 @cindex Processor Identification register, ARC
 249 @cindex ARC Processor Identification register
 250 Processor Identification register.  Auxiliary register address 0x4.
 251
 252 @item pc
 253 @cindex Program Counter, ARC
 254 @cindex ARC Program Counter
 255 Program Counter.  Auxiliary register address 0x6.
 256
 257 @item status32
 258 @cindex Status register, ARC
 259 @cindex ARC Status register
 260 Status register.  Auxiliary register address 0x0a.
 261
 262 @item bta
 263 @cindex Branch Target Address, ARC
 264 @cindex ARC Branch Target Address
 265 Branch Target Address.  Auxiliary register address 0x412.
 266
 267 @item ecr
 268 @cindex Exception Cause Register, ARC
 269 @cindex ARC Exception Cause Register
 270 Exception Cause Register.  Auxiliary register address 0x403.
 271
 272 @item int_vector_base
 273 @cindex Interrupt Vector Base address, ARC
 274 @cindex ARC Interrupt Vector Base address
 275 Interrupt Vector Base address.  Auxiliary register address 0x25.
 276
 277 @item status32_p0
 278 @cindex Stored STATUS32 register on entry to level P0 interrupts, ARC
 279 @cindex ARC Stored STATUS32 register on entry to level P0 interrupts
 280 Stored STATUS32 register on entry to level P0 interrupts.  Auxiliary
 281 register address 0xb.
 282
 283 @item aux_user_sp
 284 @cindex Saved User Stack Pointer, ARC
 285 @cindex ARC Saved User Stack Pointer
 286 Saved User Stack Pointer.  Auxiliary register address 0xd.
 287
 288 @item eret
 289 @cindex Exception Return Address, ARC
 290 @cindex ARC Exception Return Address
 291 Exception Return Address.  Auxiliary register address 0x400.
 292
 293 @item erbta
 294 @cindex BTA saved on exception entry, ARC
 295 @cindex ARC BTA saved on exception entry
 296 BTA saved on exception entry.  Auxiliary register address 0x401.
 297
 298 @item erstatus
 299 @cindex STATUS32 saved on exception, ARC
 300 @cindex ARC STATUS32 saved on exception
 301 STATUS32 saved on exception.  Auxiliary register address 0x402.
 302
 303 @item bcr_ver
 304 @cindex Build Configuration Registers Version, ARC
 305 @cindex ARC Build Configuration Registers Version
 306 Build Configuration Registers Version.  Auxiliary register address 0x60.
 307
 308 @item bta_link_build
 309 @cindex Build configuration for: BTA Registers, ARC
 310 @cindex ARC Build configuration for: BTA Registers
 311 Build configuration for: BTA Registers.  Auxiliary register address 0x63.
 312
 313 @item vecbase_ac_build
 314 @cindex Build configuration for: Interrupts, ARC
 315 @cindex ARC Build configuration for: Interrupts
 316 Build configuration for: Interrupts.  Auxiliary register address 0x68.
 317
 318 @item rf_build
 319 @cindex Build configuration for: Core Registers, ARC
 320 @cindex ARC Build configuration for: Core Registers
 321 Build configuration for: Core Registers.  Auxiliary register address 0x6e.
 322
 323 @item dccm_build
 324 @cindex DCCM RAM Configuration Register, ARC
 325 @cindex ARC DCCM RAM Configuration Register
 326 DCCM RAM Configuration Register.  Auxiliary register address 0xc1.
 327
 328 @end table
 329
 330 Additional auxiliary register names are defined according to the
 331 processor architecture version and extensions selected by the options.
 332
 333 @node ARC Directives
 334 @section ARC Machine Directives
 335
 336 @cindex machine directives, ARC
 337 @cindex ARC machine directives
 338 The ARC version of @code{@value{AS}} supports the following additional
 339 machine directives:
 340
 341 @table @code
 342
 343 @cindex @code{lcomm} directive
 344 @item .lcomm @var{symbol}, @var{length}[, @var{alignment}]
 345 Reserve @var{length} (an absolute expression) bytes for a local common
 346 denoted by @var{symbol}.  The section and value of @var{symbol} are
 347 those of the new local common.  The addresses are allocated in the bss
 348 section, so that at run-time the bytes start off zeroed.  Since
 349 @var{symbol} is not declared global, it is normally not visible to
 350 @code{@value{LD}}.  The optional third parameter, @var{alignment},
 351 specifies the desired alignment of the symbol in the bss section,
 352 specified as a byte boundary (for example, an alignment of 16 means
 353 that the least significant 4 bits of the address should be zero).  The
 354 alignment must be an absolute expression, and it must be a power of
 355 two.  If no alignment is specified, as will set the alignment to the
 356 largest power of two less than or equal to the size of the symbol, up
 357 to a maximum of 16.
 358
 359 @cindex @code{lcommon} directive, ARC
 360 @item .lcommon @var{symbol}, @var{length}[, @var{alignment}]
 361 The same as @code{lcomm} directive.
 362
 363 @cindex @code{cpu} directive, ARC
 364 @item .cpu @var{cpu}
 365 The @code{.cpu} directive must be followed by the desired core
 366 version.  Permitted values for CPU are:
 367 @table @code
 368 @item ARC600
 369 Assemble for the ARC600 instruction set.
 370
 371 @item ARC700
 372 Assemble for the ARC700 instruction set.
 373
 374 @item NPS400
 375 Assemble for the NPS400 instruction set.
 376
 377 @item EM
 378 Assemble for the ARC EM instruction set.
 379
 380 @item HS
 381 Assemble for the ARC HS instruction set.
 382
 383 @end table
 384
 385 Note: the @code{.cpu} directive overrides the command line option
 386 @code{-mcpu=@var{cpu}}; a warning is emitted when the version is not
 387 consistent between the two.
 388
 389 @item .extAuxRegister @var{name}, @var{addr}, @var{mode}
 390 @cindex @code{extAuxRegister} directive, ARC
 391 Auxiliary registers can be defined in the assembler source code by
 392 using this directive.  The first parameter, @var{name}, is the name of the
 393 new auxiliary register.  The second parameter, @var{addr}, is
 394 address the of the auxiliary register.  The third parameter,
 395 @var{mode}, specifies whether the register is readable and/or writable
 396 and is one of:
 397 @table @code
 398 @item r
 399 Read only;
 400
 401 @item w
 402 Write only;
 403
 404 @item r|w
 405 Read and write.
 406
 407 @end table
 408
 409 For example:
 410 @example
 411         .extAuxRegister mulhi, 0x12, w
 412 @end example
 413 specifies a write only extension auxiliary register, @var{mulhi} at
 414 address 0x12.
 415
 416 @item .extCondCode @var{suffix}, @var{val}
 417 @cindex @code{extCondCode} directive, ARC
 418 ARC supports extensible condition codes.  This directive defines a new
 419 condition code, to be known by the suffix, @var{suffix} and will
 420 depend on the value, @var{val} in the condition code.
 421
 422 For example:
 423 @example
 424         .extCondCode is_busy,0x14
 425         add.is_busy  r1,r2,r3
 426 @end example
 427 will only execute the @code{add} instruction if the condition code
 428 value is 0x14.
 429
 430 @item .extCoreRegister @var{name}, @var{regnum}, @var{mode}, @var{shortcut}
 431 @cindex @code{extCoreRegister} directive, ARC
 432 Specifies an extension core register named @var{name} as a synonym for
 433 the register numbered @var{regnum}.  The register number must be
 434 between 32 and 59.  The third argument, @var{mode}, indicates whether
 435 the register is readable and/or writable and is one of:
 436 @table @code
 437 @item r
 438 Read only;
 439
 440 @item w
 441 Write only;
 442
 443 @item r|w
 444 Read and write.
 445
 446 @end table
 447
 448 The final parameter, @var{shortcut} indicates whether the register has
 449 a short cut in the pipeline.  The valid values are:
 450 @table @code
 451 @item can_shortcut
 452 The register has a short cut in the pipeline;
 453
 454 @item cannot_shortcut
 455 The register does not have a short cut in the pipeline.
 456 @end table
 457
 458 For example:
 459 @example
 460         .extCoreRegister mlo, 57, r , can_shortcut
 461 @end example
 462 defines a read only extension core register, @code{mlo}, which is
 463 register 57, and can short cut the pipeline.
 464
 465 @item .extInstruction @var{name}, @var{opcode}, @var{subopcode}, @var{suffixclass}, @var{syntaxclass}
 466 @cindex @code{extInstruction} directive, ARC
 467 ARC allows the user to specify extension instructions.  These
 468 extension instructions are not macros; the assembler creates encodings
 469 for use of these instructions according to the specification by the
 470 user.
 471
 472 The first argument, @var{name}, gives the name of the instruction.
 473
 474 The second argument, @var{opcode}, is the opcode to be used (bits 31:27
 475 in the encoding).
 476
 477 The third argument, @var{subopcode}, is the sub-opcode to be used, but
 478 the correct value also depends on the fifth argument,
 479 @var{syntaxclass}
 480
 481 The fourth argument, @var{suffixclass}, determines the kinds of
 482 suffixes to be allowed.  Valid values are:
 483 @table @code
 484 @item SUFFIX_NONE
 485 No suffixes are permitted;
 486
 487 @item SUFFIX_COND
 488 Conditional suffixes are permitted;
 489
 490 @item SUFFIX_FLAG
 491 Flag setting suffixes are permitted.
 492
 493 @item SUFFIX_COND|SUFFIX_FLAG
 494 Both conditional and flag setting suffices are permitted.
 495
 496 @end table
 497
 498 The fifth and final argument, @var{syntaxclass}, determines the syntax
 499 class for the instruction.  It can have the following values:
 500 @table @code
 501 @item SYNTAX_2OP
 502 Two Operand Instruction;
 503
 504 @item SYNTAX_3OP
 505 Three Operand Instruction.
 506
 507 @item SYNTAX_1OP
 508 One Operand Instruction.
 509
 510 @item SYNTAX_NOP
 511 No Operand Instruction.
 512 @end table
 513
 514 The syntax class may be followed by @samp{|} and one of the following
 515 modifiers.
 516 @table @code
 517
 518 @item OP1_MUST_BE_IMM
 519 Modifies syntax class @code{SYNTAX_3OP}, specifying that the first
 520 operand of a three-operand instruction must be an immediate (i.e., the
 521 result is discarded).  This is usually used to set the flags using
 522 specific instructions and not retain results.
 523
 524 @item OP1_IMM_IMPLIED
 525 Modifies syntax class @code{SYNTAX_20P}, specifying that there is an
 526 implied immediate destination operand which does not appear in the
 527 syntax.
 528
 529 For example, if the source code contains an instruction like:
 530 @example
 531 inst r1,r2
 532 @end example
 533 the first argument is an implied immediate (that is, the result is
 534 discarded).  This is the same as though the source code were: inst
 535 0,r1,r2.
 536
 537 @end table
 538
 539 For example, defining a 64-bit multiplier with immediate operands:
 540 @example
 541         .extInstruction  mp64, 0x07, 0x2d, SUFFIX_COND|SUFFIX_FLAG,
 542                          SYNTAX_3OP|OP1_MUST_BE_IMM
 543 @end example
 544 which specifies an extension instruction named @code{mp64} with 3
 545 operands.  It sets the flags and can be used with a condition code,
 546 for which the first operand is an immediate, i.e. equivalent to
 547 discarding the result of the operation.
 548
 549 A two operands instruction variant would be:
 550 @example
 551         .extInstruction mul64, 0x07, 0x2d, SUFFIX_COND,
 552         SYNTAX_2OP|OP1_IMM_IMPLIED
 553 @end example
 554 which describes a two operand instruction with an implicit first
 555 immediate operand.  The result of this operation would be discarded.
 556
 557 @end table
 558
 559 @node ARC Modifiers
 560 @section ARC Assembler Modifiers
 561
 562 The following additional assembler modifiers have been added for
 563 position-independent code.  These modifiers are available only with
 564 the ARC 700 and above processors and generate relocation entries,
 565 which are interpreted by the linker as follows:
 566
 567 @table @code
 568 @item @@pcl(@var{symbol})
 569 @cindex @@pcl(@var{symbol}), ARC modifier
 570 Relative distance of @var{symbol}'s from the current program counter
 571 location.
 572
 573 @item @@gotpc(@var{symbol})
 574 @cindex @@gotpc(@var{symbol}), ARC modifier
 575 Relative distance of @var{symbol}'s Global Offset Table entry from the
 576 current program counter location.
 577
 578 @item @@gotoff(@var{symbol})
 579 @cindex @@gotoff(@var{symbol}), ARC modifier
 580 Distance of @var{symbol} from the base of the Global Offset Table.
 581
 582 @item @@plt(@var{symbol})
 583 @cindex @@plt(@var{symbol}), ARC modifier
 584 Distance of @var{symbol}'s Procedure Linkage Table entry from the
 585 current program counter.  This is valid only with branch and link
 586 instructions and PC-relative calls.
 587
 588 @item @@sda(@var{symbol})
 589 @cindex @@sda(@var{symbol}), ARC modifier
 590 Relative distance of @var{symbol} from the base of the Small Data
 591 Pointer.
 592
 593 @end table
 594
 595 @node ARC Symbols
 596 @section ARC Pre-defined Symbols
 597
 598 The following assembler symbols will prove useful when developing
 599 position-independent code.  These symbols are available only with the
 600 ARC 700 and above processors.
 601
 602 @table @code
 603 @item __GLOBAL_OFFSET_TABLE__
 604 @cindex __GLOBAL_OFFSET_TABLE__, ARC pre-defined symbol
 605 Symbol referring to the base of the Global Offset Table.
 606
 607 @item __DYNAMIC__
 608 @cindex __DYNAMIC__, ARC pre-defined symbol
 609 An alias for the Global Offset Table
 610 @code{Base__GLOBAL_OFFSET_TABLE__}.  It can be used only with
 611 @code{@@gotpc} modifiers.
 612
 613 @end table
 614
 615 @node ARC Opcodes
 616 @section Opcodes
 617
 618 @cindex ARC opcodes
 619 @cindex opcodes for ARC
 620
 621 For information on the ARC instruction set, see @cite{ARC Programmers
 622 Reference Manual}, available where you download the processor IP library.