gas/doc/c-avr.texi

   1 @c Copyright (C) 2006-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
   5 @ifset GENERIC
   6 @page
   7 @node AVR-Dependent
   8 @chapter AVR Dependent Features
   9 @end ifset
  10
  11 @ifclear GENERIC
  12 @node Machine Dependencies
  13 @chapter AVR Dependent Features
  14 @end ifclear
  15
  16 @cindex AVR support
  17 @menu
  18 * AVR Options::              Options
  19 * AVR Syntax::               Syntax
  20 * AVR Opcodes::              Opcodes
  21 * AVR Pseudo Instructions::  Pseudo Instructions
  22 @end menu
  23
  24 @node AVR Options
  25 @section Options
  26 @cindex AVR options (none)
  27 @cindex options for AVR (none)
  28
  29 @table @code
  30
  31 @cindex @code{-mmcu=} command-line option, AVR
  32 @item -mmcu=@var{mcu}
  33 Specify ATMEL AVR instruction set or MCU type.
  34
  35 Instruction set avr1 is for the minimal AVR core, not supported by the C
  36 compiler, only for assembler programs (MCU types: at90s1200,
  37 attiny11, attiny12, attiny15, attiny28).
  38
  39 Instruction set avr2 (default) is for the classic AVR core with up to
  40 8K program memory space (MCU types: at90s2313, at90s2323, at90s2333, at90s2343,
  41 attiny22, attiny26, at90s4414, at90s4433, at90s4434, at90s8515, at90c8534,
  42 at90s8535).
  43
  44 Instruction set avr25 is for the classic AVR core with up to 8K program memory
  45 space plus the MOVW instruction (MCU types: attiny13, attiny13a, attiny2313,
  46 attiny2313a, attiny24, attiny24a, attiny4313, attiny44, attiny44a, attiny84,
  47 attiny84a, attiny25, attiny45, attiny85, attiny261, attiny261a, attiny461,
  48 attiny461a, attiny861, attiny861a, attiny87, attiny43u, attiny48, attiny88,
  49 attiny828, at86rf401, ata6289, ata5272).
  50
  51 Instruction set avr3 is for the classic AVR core with up to 128K program
  52 memory space (MCU types: at43usb355, at76c711).
  53
  54 Instruction set avr31 is for the classic AVR core with exactly 128K program
  55 memory space (MCU types: atmega103, at43usb320).
  56
  57 Instruction set avr35 is for classic AVR core plus MOVW, CALL, and JMP
  58 instructions (MCU types: attiny167, attiny1634, at90usb82, at90usb162,
  59 atmega8u2, atmega16u2, atmega32u2, ata5505).
  60
  61 Instruction set avr4 is for the enhanced AVR core with up to 8K program
  62 memory space (MCU types: atmega48, atmega48a, atmega48pa, atmega48p, atmega8,
  63 atmega8a, atmega88, atmega88a, atmega88p, atmega88pa, atmega8515, atmega8535,
  64 atmega8hva, at90pwm1, at90pwm2, at90pwm2b, at90pwm3, at90pwm3b, at90pwm81,
  65 ata6285, ata6286).
  66
  67 Instruction set avr5 is for the enhanced AVR core with up to 128K program
  68 memory space (MCU types: at90pwm161, atmega16, atmega16a, atmega161, atmega162,
  69 atmega163, atmega164a, atmega164p, atmega164pa, atmega165, atmega165a,
  70 atmega165p, atmega165pa, atmega168, atmega168a, atmega168p, atmega168pa,
  71 atmega169, atmega169a, atmega169p, atmega169pa, atmega32, atmega323, atmega324a,
  72 atmega324p, atmega324pa, atmega325, atmega325a, atmega32, atmega32a, atmega323,
  73 atmega324a, atmega324p, atmega324pa, atmega325, atmega325a, atmega325p,
  74 atmega325p, atmega325pa, atmega3250, atmega3250a, atmega3250p, atmega3250pa,
  75 atmega328, atmega328p, atmega329, atmega329a, atmega329p, atmega329pa,
  76 atmega3290a, atmega3290p, atmega3290pa, atmega406, atmega64, atmega64a,
  77 atmega64rfr2, atmega644rfr2, atmega640, atmega644, atmega644a, atmega644p,
  78 atmega644pa, atmega645, atmega645a, atmega645p, atmega6450, atmega6450a,
  79 atmega6450p, atmega649, atmega649a, atmega649p, atmega6490, atmega6490a,
  80 atmega6490p, atmega16hva, atmega16hva2, atmega16hvb, atmega16hvbrevb,
  81 atmega32hvb, atmega32hvbrevb, atmega64hve, at90can32, at90can64, at90pwm161,
  82 at90pwm216, at90pwm316, atmega32c1, atmega64c1, atmega16m1, atmega32m1,
  83 atmega64m1, atmega16u4, atmega32u4, atmega32u6, at90usb646, at90usb647, at94k,
  84 at90scr100, ata5790, ata5795).
  85
  86 Instruction set avr51 is for the enhanced AVR core with exactly 128K
  87 program memory space (MCU types: atmega128, atmega128a, atmega1280,
  88 atmega1281, atmega1284, atmega1284p, atmega128rfa1, atmega128rfr2,
  89 atmega1284rfr2, at90can128, at90usb1286, at90usb1287, m3000).
  90
  91 Instruction set avr6 is for the enhanced AVR core with a 3-byte PC
  92 (MCU types: atmega2560, atmega2561, atmega256rfr2, atmega2564rfr2).
  93
  94 Instruction set avrxmega2 is for the XMEGA AVR core with 8K to 64K
  95 program memory space and less than 64K data space (MCU types:
  96 atxmega16a4, atxmega16a4u, atxmega16c4, atxmega16d4, atxmega16x1,
  97 atxmega32a4, atxmega32a4u, atxmega32c4, atxmega32d4, atxmega16e5,
  98 atxmega8e5, atxmega32e5, atxmega32x1).
  99
 100 Instruction set avrxmega3 is for the XMEGA AVR core with up to 64K
 101 of combined program memory and RAM, and with program memory
 102 visible in the RAM address space (MCU types:
 103 attiny212, attiny214, attiny412, attiny414, attiny416, attiny417,
 104 attiny814, attiny816, attiny817, attiny1614, attiny1616, attiny1617,
 105 attiny3214, attiny3216, attiny3217).
 106
 107 Instruction set avrxmega4 is for the XMEGA AVR core with up to 64K
 108 program memory space and less than 64K data space (MCU types:
 109 atxmega64a3, atxmega64a3u, atxmega64a4u, atxmega64b1, atxmega64b3,
 110 atxmega64c3, atxmega64d3, atxmega64d4).
 111
 112 Instruction set avrxmega5 is for the XMEGA AVR core with up to 64K
 113 program memory space and greater than 64K data space (MCU types:
 114 atxmega64a1, atxmega64a1u).
 115
 116 Instruction set avrxmega6 is for the XMEGA AVR core with larger than
 117 64K program memory space and less than 64K data space (MCU types:
 118 atxmega128a3, atxmega128a3u, atxmega128c3, atxmega128d3, atxmega128d4,
 119 atxmega192a3, atxmega192a3u, atxmega128b1, atxmega128b3, atxmega192c3,
 120 atxmega192d3, atxmega256a3, atxmega256a3u, atxmega256a3b,
 121 atxmega256a3bu, atxmega256c3, atxmega256d3, atxmega384c3,
 122 atxmega256d3).
 123
 124 Instruction set avrxmega7 is for the XMEGA AVR core with larger than
 125 64K program memory space and greater than 64K data space (MCU types:
 126 atxmega128a1, atxmega128a1u, atxmega128a4u).
 127
 128 Instruction set avrtiny is for the ATtiny4/5/9/10/20/40
 129 microcontrollers.
 130
 131 @cindex @code{-mall-opcodes} command-line option, AVR
 132 @item -mall-opcodes
 133 Accept all AVR opcodes, even if not supported by @code{-mmcu}.
 134
 135 @cindex @code{-mno-skip-bug} command-line option, AVR
 136 @item -mno-skip-bug
 137 This option disable warnings for skipping two-word instructions.
 138
 139 @cindex @code{-mno-wrap} command-line option, AVR
 140 @item -mno-wrap
 141 This option reject @code{rjmp/rcall} instructions with 8K wrap-around.
 142
 143 @cindex @code{-mrmw} command-line option, AVR
 144 @item -mrmw
 145 Accept Read-Modify-Write (@code{XCH,LAC,LAS,LAT}) instructions.
 146
 147 @cindex @code{-mlink-relax} command-line option, AVR
 148 @item -mlink-relax
 149 Enable support for link-time relaxation.  This is now on by default
 150 and this flag no longer has any effect.
 151
 152 @cindex @code{-mno-link-relax} command-line option, AVR
 153 @item -mno-link-relax
 154 Disable support for link-time relaxation.  The assembler will resolve
 155 relocations when it can, and may be able to better compress some debug
 156 information.
 157
 158 @cindex @code{-mgcc-isr} command-line option, AVR
 159 @item -mgcc-isr
 160 Enable the @code{__gcc_isr} pseudo instruction.
 161
 162 @end table
 163
 164
 165 @node AVR Syntax
 166 @section Syntax
 167 @menu
 168 * AVR-Chars::                Special Characters
 169 * AVR-Regs::                 Register Names
 170 * AVR-Modifiers::            Relocatable Expression Modifiers
 171 @end menu
 172
 173 @node AVR-Chars
 174 @subsection Special Characters
 175
 176 @cindex line comment character, AVR
 177 @cindex AVR line comment character
 178
 179 The presence of a @samp{;} anywhere on a line indicates the start of a
 180 comment that extends to the end of that line.
 181
 182 If a @samp{#} appears as the first character of a line, the whole line
 183 is treated as a comment, but in this case the line can also be a
 184 logical line number directive (@pxref{Comments}) or a preprocessor
 185 control command (@pxref{Preprocessing}).
 186
 187 @cindex line separator, AVR
 188 @cindex statement separator, AVR
 189 @cindex AVR line separator
 190
 191 The @samp{$} character can be used instead of a newline to separate
 192 statements.
 193
 194 @node AVR-Regs
 195 @subsection Register Names
 196
 197 @cindex AVR register names
 198 @cindex register names, AVR
 199
 200 The AVR has 32 x 8-bit general purpose working registers @samp{r0},
 201 @samp{r1}, ... @samp{r31}.
 202 Six of the 32 registers can be used as three 16-bit indirect address
 203 register pointers for Data Space addressing. One of the these address
 204 pointers can also be used as an address pointer for look up tables in
 205 Flash program memory. These added function registers are the 16-bit
 206 @samp{X}, @samp{Y} and @samp{Z} - registers.
 207
 208 @smallexample
 209 X = @r{r26:r27}
 210 Y = @r{r28:r29}
 211 Z = @r{r30:r31}
 212 @end smallexample
 213
 214 @node AVR-Modifiers
 215 @subsection Relocatable Expression Modifiers
 216
 217 @cindex AVR modifiers
 218 @cindex syntax, AVR
 219
 220 The assembler supports several modifiers when using relocatable addresses
 221 in AVR instruction operands.  The general syntax is the following:
 222
 223 @smallexample
 224 modifier(relocatable-expression)
 225 @end smallexample
 226
 227 @table @code
 228 @cindex symbol modifiers
 229
 230 @item lo8
 231
 232 This modifier allows you to use bits 0 through 7 of
 233 an address expression as 8 bit relocatable expression.
 234
 235 @item hi8
 236
 237 This modifier allows you to use bits 7 through 15 of an address expression
 238 as 8 bit relocatable expression.  This is useful with, for example, the
 239 AVR @samp{ldi} instruction and @samp{lo8} modifier.
 240
 241 For example
 242
 243 @smallexample
 244 ldi r26, lo8(sym+10)
 245 ldi r27, hi8(sym+10)
 246 @end smallexample
 247
 248 @item hh8
 249
 250 This modifier allows you to use bits 16 through 23 of
 251 an address expression as 8 bit relocatable expression.
 252 Also, can be useful for loading 32 bit constants.
 253
 254 @item hlo8
 255
 256 Synonym of @samp{hh8}.
 257
 258 @item hhi8
 259
 260 This modifier allows you to use bits 24 through 31 of
 261 an expression as 8 bit expression. This is useful with, for example, the
 262 AVR @samp{ldi} instruction and @samp{lo8}, @samp{hi8}, @samp{hlo8},
 263 @samp{hhi8}, modifier.
 264
 265 For example
 266
 267 @smallexample
 268 ldi r26, lo8(285774925)
 269 ldi r27, hi8(285774925)
 270 ldi r28, hlo8(285774925)
 271 ldi r29, hhi8(285774925)
 272 ; r29,r28,r27,r26 = 285774925
 273 @end smallexample
 274
 275 @item pm_lo8
 276
 277 This modifier allows you to use bits 0 through 7 of
 278 an address expression as 8 bit relocatable expression.
 279 This modifier useful for addressing data or code from
 280 Flash/Program memory. The using of @samp{pm_lo8} similar
 281 to @samp{lo8}.
 282
 283 @item pm_hi8
 284
 285 This modifier allows you to use bits 8 through 15 of
 286 an address expression as 8 bit relocatable expression.
 287 This modifier useful for addressing data or code from
 288 Flash/Program memory.
 289
 290 @item pm_hh8
 291
 292 This modifier allows you to use bits 15 through 23 of
 293 an address expression as 8 bit relocatable expression.
 294 This modifier useful for addressing data or code from
 295 Flash/Program memory.
 296
 297 @end table
 298
 299 @node AVR Opcodes
 300 @section Opcodes
 301
 302 @cindex AVR opcode summary
 303 @cindex opcode summary, AVR
 304 @cindex mnemonics, AVR
 305 @cindex instruction summary, AVR
 306 For detailed information on the AVR machine instruction set, see
 307 @url{www.atmel.com/products/AVR}.
 308
 309 @code{@value{AS}} implements all the standard AVR opcodes.
 310 The following table summarizes the AVR opcodes, and their arguments.
 311
 312 @smallexample
 313 @i{Legend:}
 314    r   @r{any register}
 315    d   @r{`ldi' register (r16-r31)}
 316    v   @r{`movw' even register (r0, r2, ..., r28, r30)}
 317    a   @r{`fmul' register (r16-r23)}
 318    w   @r{`adiw' register (r24,r26,r28,r30)}
 319    e   @r{pointer registers (X,Y,Z)}
 320    b   @r{base pointer register and displacement ([YZ]+disp)}
 321    z   @r{Z pointer register (for [e]lpm Rd,Z[+])}
 322    M   @r{immediate value from 0 to 255}
 323    n   @r{immediate value from 0 to 255 ( n = ~M ). Relocation impossible}
 324    s   @r{immediate value from 0 to 7}
 325    P   @r{Port address value from 0 to 63. (in, out)}
 326    p   @r{Port address value from 0 to 31. (cbi, sbi, sbic, sbis)}
 327    K   @r{immediate value from 0 to 63 (used in `adiw', `sbiw')}
 328    i   @r{immediate value}
 329    l   @r{signed pc relative offset from -64 to 63}
 330    L   @r{signed pc relative offset from -2048 to 2047}
 331    h   @r{absolute code address (call, jmp)}
 332    S   @r{immediate value from 0 to 7 (S = s << 4)}
 333    ?   @r{use this opcode entry if no parameters, else use next opcode entry}
 334
 335 1001010010001000   clc
 336 1001010011011000   clh
 337 1001010011111000   cli
 338 1001010010101000   cln
 339 1001010011001000   cls
 340 1001010011101000   clt
 341 1001010010111000   clv
 342 1001010010011000   clz
 343 1001010000001000   sec
 344 1001010001011000   seh
 345 1001010001111000   sei
 346 1001010000101000   sen
 347 1001010001001000   ses
 348 1001010001101000   set
 349 1001010000111000   sev
 350 1001010000011000   sez
 351 100101001SSS1000   bclr    S
 352 100101000SSS1000   bset    S
 353 1001010100001001   icall
 354 1001010000001001   ijmp
 355 1001010111001000   lpm     ?
 356 1001000ddddd010+   lpm     r,z
 357 1001010111011000   elpm    ?
 358 1001000ddddd011+   elpm    r,z
 359 0000000000000000   nop
 360 1001010100001000   ret
 361 1001010100011000   reti
 362 1001010110001000   sleep
 363 1001010110011000   break
 364 1001010110101000   wdr
 365 1001010111101000   spm
 366 000111rdddddrrrr   adc     r,r
 367 000011rdddddrrrr   add     r,r
 368 001000rdddddrrrr   and     r,r
 369 000101rdddddrrrr   cp      r,r
 370 000001rdddddrrrr   cpc     r,r
 371 000100rdddddrrrr   cpse    r,r
 372 001001rdddddrrrr   eor     r,r
 373 001011rdddddrrrr   mov     r,r
 374 100111rdddddrrrr   mul     r,r
 375 001010rdddddrrrr   or      r,r
 376 000010rdddddrrrr   sbc     r,r
 377 000110rdddddrrrr   sub     r,r
 378 001001rdddddrrrr   clr     r
 379 000011rdddddrrrr   lsl     r
 380 000111rdddddrrrr   rol     r
 381 001000rdddddrrrr   tst     r
 382 0111KKKKddddKKKK   andi    d,M
 383 0111KKKKddddKKKK   cbr     d,n
 384 1110KKKKddddKKKK   ldi     d,M
 385 11101111dddd1111   ser     d
 386 0110KKKKddddKKKK   ori     d,M
 387 0110KKKKddddKKKK   sbr     d,M
 388 0011KKKKddddKKKK   cpi     d,M
 389 0100KKKKddddKKKK   sbci    d,M
 390 0101KKKKddddKKKK   subi    d,M
 391 1111110rrrrr0sss   sbrc    r,s
 392 1111111rrrrr0sss   sbrs    r,s
 393 1111100ddddd0sss   bld     r,s
 394 1111101ddddd0sss   bst     r,s
 395 10110PPdddddPPPP   in      r,P
 396 10111PPrrrrrPPPP   out     P,r
 397 10010110KKddKKKK   adiw    w,K
 398 10010111KKddKKKK   sbiw    w,K
 399 10011000pppppsss   cbi     p,s
 400 10011010pppppsss   sbi     p,s
 401 10011001pppppsss   sbic    p,s
 402 10011011pppppsss   sbis    p,s
 403 111101lllllll000   brcc    l
 404 111100lllllll000   brcs    l
 405 111100lllllll001   breq    l
 406 111101lllllll100   brge    l
 407 111101lllllll101   brhc    l
 408 111100lllllll101   brhs    l
 409 111101lllllll111   brid    l
 410 111100lllllll111   brie    l
 411 111100lllllll000   brlo    l
 412 111100lllllll100   brlt    l
 413 111100lllllll010   brmi    l
 414 111101lllllll001   brne    l
 415 111101lllllll010   brpl    l
 416 111101lllllll000   brsh    l
 417 111101lllllll110   brtc    l
 418 111100lllllll110   brts    l
 419 111101lllllll011   brvc    l
 420 111100lllllll011   brvs    l
 421 111101lllllllsss   brbc    s,l
 422 111100lllllllsss   brbs    s,l
 423 1101LLLLLLLLLLLL   rcall   L
 424 1100LLLLLLLLLLLL   rjmp    L
 425 1001010hhhhh111h   call    h
 426 1001010hhhhh110h   jmp     h
 427 1001010rrrrr0101   asr     r
 428 1001010rrrrr0000   com     r
 429 1001010rrrrr1010   dec     r
 430 1001010rrrrr0011   inc     r
 431 1001010rrrrr0110   lsr     r
 432 1001010rrrrr0001   neg     r
 433 1001000rrrrr1111   pop     r
 434 1001001rrrrr1111   push    r
 435 1001010rrrrr0111   ror     r
 436 1001010rrrrr0010   swap    r
 437 00000001ddddrrrr   movw    v,v
 438 00000010ddddrrrr   muls    d,d
 439 000000110ddd0rrr   mulsu   a,a
 440 000000110ddd1rrr   fmul    a,a
 441 000000111ddd0rrr   fmuls   a,a
 442 000000111ddd1rrr   fmulsu  a,a
 443 1001001ddddd0000   sts     i,r
 444 1001000ddddd0000   lds     r,i
 445 10o0oo0dddddbooo   ldd     r,b
 446 100!000dddddee-+   ld      r,e
 447 10o0oo1rrrrrbooo   std     b,r
 448 100!001rrrrree-+   st      e,r
 449 1001010100011001   eicall
 450 1001010000011001   eijmp
 451 @end smallexample
 452
 453 @node AVR Pseudo Instructions
 454 @section Pseudo Instructions
 455
 456 The only available pseudo-instruction @code{__gcc_isr} can be activated by
 457 option @option{-mgcc-isr}.
 458
 459 @table @code
 460
 461 @item __gcc_isr 1
 462 Emit code chunk to be used in avr-gcc ISR prologue.
 463 It will expand to at most six 1-word instructions, all optional:
 464 push of @code{tmp_reg}, push of @code{SREG},
 465 push and clear of @code{zero_reg}, push of @var{Reg}.
 466
 467 @item __gcc_isr 2
 468 Emit code chunk to be used in an avr-gcc ISR epilogue.
 469 It will expand to at most five 1-word instructions, all optional:
 470 pop of @var{Reg}, pop of @code{zero_reg},
 471 pop of @code{SREG}, pop of @code{tmp_reg}.
 472
 473 @item __gcc_isr 0, @var{Reg}
 474 Finish avr-gcc ISR function.  Scan code since the last prologue
 475 for usage of: @code{SREG}, @code{tmp_reg}, @code{zero_reg}.
 476 Prologue chunk and epilogue chunks will be replaced by appropriate code
 477 to save / restore @code{SREG}, @code{tmp_reg}, @code{zero_reg} and @var{Reg}.
 478
 479 @end table
 480
 481 Example input:
 482
 483 @example
 484 __vector1:
 485     __gcc_isr 1
 486     lds r24, var
 487     inc r24
 488     sts var, r24
 489     __gcc_isr 2
 490     reti
 491     __gcc_isr 0, r24
 492 @end example
 493
 494 Example output:
 495
 496 @example
 497 00000000 <__vector1>:
 498    0:   8f 93           push    r24
 499    2:   8f b7           in      r24, 0x3f
 500    4:   8f 93           push    r24
 501    6:   80 91 60 00     lds     r24, 0x0060     ; 0x800060 <var>
 502    a:   83 95           inc     r24
 503    c:   80 93 60 00     sts     0x0060, r24     ; 0x800060 <var>
 504   10:   8f 91           pop     r24
 505   12:   8f bf           out     0x3f, r24
 506   14:   8f 91           pop     r24
 507   16:   18 95           reti
 508 @end example