gas/doc/c-avr.texi

   1 @c Copyright (C) 2006-2017 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 8K to 64K
 101 program memory space and greater than 64K data space (MCU types:
 102 none).
 103
 104 Instruction set avrxmega4 is for the XMEGA AVR core with up to 64K
 105 program memory space and less than 64K data space (MCU types:
 106 atxmega64a3, atxmega64a3u, atxmega64a4u, atxmega64b1, atxmega64b3,
 107 atxmega64c3, atxmega64d3, atxmega64d4).
 108
 109 Instruction set avrxmega5 is for the XMEGA AVR core with up to 64K
 110 program memory space and greater than 64K data space (MCU types:
 111 atxmega64a1, atxmega64a1u).
 112
 113 Instruction set avrxmega6 is for the XMEGA AVR core with larger than
 114 64K program memory space and less than 64K data space (MCU types:
 115 atxmega128a3, atxmega128a3u, atxmega128c3, atxmega128d3, atxmega128d4,
 116 atxmega192a3, atxmega192a3u, atxmega128b1, atxmega128b3, atxmega192c3,
 117 atxmega192d3, atxmega256a3, atxmega256a3u, atxmega256a3b,
 118 atxmega256a3bu, atxmega256c3, atxmega256d3, atxmega384c3,
 119 atxmega256d3).
 120
 121 Instruction set avrxmega7 is for the XMEGA AVR core with larger than
 122 64K program memory space and greater than 64K data space (MCU types:
 123 atxmega128a1, atxmega128a1u, atxmega128a4u).
 124
 125 Instruction set avrtiny is for the ATtiny4/5/9/10/20/40
 126 microcontrollers.
 127
 128 @cindex @code{-mall-opcodes} command line option, AVR
 129 @item -mall-opcodes
 130 Accept all AVR opcodes, even if not supported by @code{-mmcu}.
 131
 132 @cindex @code{-mno-skip-bug} command line option, AVR
 133 @item -mno-skip-bug
 134 This option disable warnings for skipping two-word instructions.
 135
 136 @cindex @code{-mno-wrap} command line option, AVR
 137 @item -mno-wrap
 138 This option reject @code{rjmp/rcall} instructions with 8K wrap-around.
 139
 140 @cindex @code{-mrmw} command line option, AVR
 141 @item -mrmw
 142 Accept Read-Modify-Write (@code{XCH,LAC,LAS,LAT}) instructions.
 143
 144 @cindex @code{-mlink-relax} command line option, AVR
 145 @item -mlink-relax
 146 Enable support for link-time relaxation.  This is now on by default
 147 and this flag no longer has any effect.
 148
 149 @cindex @code{-mno-link-relax} command line option, AVR
 150 @item -mno-link-relax
 151 Disable support for link-time relaxation.  The assembler will resolve
 152 relocations when it can, and may be able to better compress some debug
 153 information.
 154
 155 @cindex @code{-mgcc-isr} command line option, AVR
 156 @item -mgcc-isr
 157 Enable the @code{__gcc_isr} pseudo instruction.
 158
 159 @end table
 160
 161
 162 @node AVR Syntax
 163 @section Syntax
 164 @menu
 165 * AVR-Chars::                Special Characters
 166 * AVR-Regs::                 Register Names
 167 * AVR-Modifiers::            Relocatable Expression Modifiers
 168 @end menu
 169
 170 @node AVR-Chars
 171 @subsection Special Characters
 172
 173 @cindex line comment character, AVR
 174 @cindex AVR line comment character
 175
 176 The presence of a @samp{;} anywhere on a line indicates the start of a
 177 comment that extends to the end of that line.
 178
 179 If a @samp{#} appears as the first character of a line, the whole line
 180 is treated as a comment, but in this case the line can also be a
 181 logical line number directive (@pxref{Comments}) or a preprocessor
 182 control command (@pxref{Preprocessing}).
 183
 184 @cindex line separator, AVR
 185 @cindex statement separator, AVR
 186 @cindex AVR line separator
 187
 188 The @samp{$} character can be used instead of a newline to separate
 189 statements.
 190
 191 @node AVR-Regs
 192 @subsection Register Names
 193
 194 @cindex AVR register names
 195 @cindex register names, AVR
 196
 197 The AVR has 32 x 8-bit general purpose working registers @samp{r0},
 198 @samp{r1}, ... @samp{r31}.
 199 Six of the 32 registers can be used as three 16-bit indirect address
 200 register pointers for Data Space addressing. One of the these address
 201 pointers can also be used as an address pointer for look up tables in
 202 Flash program memory. These added function registers are the 16-bit
 203 @samp{X}, @samp{Y} and @samp{Z} - registers.
 204
 205 @smallexample
 206 X = @r{r26:r27}
 207 Y = @r{r28:r29}
 208 Z = @r{r30:r31}
 209 @end smallexample
 210
 211 @node AVR-Modifiers
 212 @subsection Relocatable Expression Modifiers
 213
 214 @cindex AVR modifiers
 215 @cindex syntax, AVR
 216
 217 The assembler supports several modifiers when using relocatable addresses
 218 in AVR instruction operands.  The general syntax is the following:
 219
 220 @smallexample
 221 modifier(relocatable-expression)
 222 @end smallexample
 223
 224 @table @code
 225 @cindex symbol modifiers
 226
 227 @item lo8
 228
 229 This modifier allows you to use bits 0 through 7 of
 230 an address expression as 8 bit relocatable expression.
 231
 232 @item hi8
 233
 234 This modifier allows you to use bits 7 through 15 of an address expression
 235 as 8 bit relocatable expression.  This is useful with, for example, the
 236 AVR @samp{ldi} instruction and @samp{lo8} modifier.
 237
 238 For example
 239
 240 @smallexample
 241 ldi r26, lo8(sym+10)
 242 ldi r27, hi8(sym+10)
 243 @end smallexample
 244
 245 @item hh8
 246
 247 This modifier allows you to use bits 16 through 23 of
 248 an address expression as 8 bit relocatable expression.
 249 Also, can be useful for loading 32 bit constants.
 250
 251 @item hlo8
 252
 253 Synonym of @samp{hh8}.
 254
 255 @item hhi8
 256
 257 This modifier allows you to use bits 24 through 31 of
 258 an expression as 8 bit expression. This is useful with, for example, the
 259 AVR @samp{ldi} instruction and @samp{lo8}, @samp{hi8}, @samp{hlo8},
 260 @samp{hhi8}, modifier.
 261
 262 For example
 263
 264 @smallexample
 265 ldi r26, lo8(285774925)
 266 ldi r27, hi8(285774925)
 267 ldi r28, hlo8(285774925)
 268 ldi r29, hhi8(285774925)
 269 ; r29,r28,r27,r26 = 285774925
 270 @end smallexample
 271
 272 @item pm_lo8
 273
 274 This modifier allows you to use bits 0 through 7 of
 275 an address expression as 8 bit relocatable expression.
 276 This modifier useful for addressing data or code from
 277 Flash/Program memory. The using of @samp{pm_lo8} similar
 278 to @samp{lo8}.
 279
 280 @item pm_hi8
 281
 282 This modifier allows you to use bits 8 through 15 of
 283 an address expression as 8 bit relocatable expression.
 284 This modifier useful for addressing data or code from
 285 Flash/Program memory.
 286
 287 @item pm_hh8
 288
 289 This modifier allows you to use bits 15 through 23 of
 290 an address expression as 8 bit relocatable expression.
 291 This modifier useful for addressing data or code from
 292 Flash/Program memory.
 293
 294 @end table
 295
 296 @node AVR Opcodes
 297 @section Opcodes
 298
 299 @cindex AVR opcode summary
 300 @cindex opcode summary, AVR
 301 @cindex mnemonics, AVR
 302 @cindex instruction summary, AVR
 303 For detailed information on the AVR machine instruction set, see
 304 @url{www.atmel.com/products/AVR}.
 305
 306 @code{@value{AS}} implements all the standard AVR opcodes.
 307 The following table summarizes the AVR opcodes, and their arguments.
 308
 309 @smallexample
 310 @i{Legend:}
 311    r   @r{any register}
 312    d   @r{`ldi' register (r16-r31)}
 313    v   @r{`movw' even register (r0, r2, ..., r28, r30)}
 314    a   @r{`fmul' register (r16-r23)}
 315    w   @r{`adiw' register (r24,r26,r28,r30)}
 316    e   @r{pointer registers (X,Y,Z)}
 317    b   @r{base pointer register and displacement ([YZ]+disp)}
 318    z   @r{Z pointer register (for [e]lpm Rd,Z[+])}
 319    M   @r{immediate value from 0 to 255}
 320    n   @r{immediate value from 0 to 255 ( n = ~M ). Relocation impossible}
 321    s   @r{immediate value from 0 to 7}
 322    P   @r{Port address value from 0 to 63. (in, out)}
 323    p   @r{Port address value from 0 to 31. (cbi, sbi, sbic, sbis)}
 324    K   @r{immediate value from 0 to 63 (used in `adiw', `sbiw')}
 325    i   @r{immediate value}
 326    l   @r{signed pc relative offset from -64 to 63}
 327    L   @r{signed pc relative offset from -2048 to 2047}
 328    h   @r{absolute code address (call, jmp)}
 329    S   @r{immediate value from 0 to 7 (S = s << 4)}
 330    ?   @r{use this opcode entry if no parameters, else use next opcode entry}
 331
 332 1001010010001000   clc
 333 1001010011011000   clh
 334 1001010011111000   cli
 335 1001010010101000   cln
 336 1001010011001000   cls
 337 1001010011101000   clt
 338 1001010010111000   clv
 339 1001010010011000   clz
 340 1001010000001000   sec
 341 1001010001011000   seh
 342 1001010001111000   sei
 343 1001010000101000   sen
 344 1001010001001000   ses
 345 1001010001101000   set
 346 1001010000111000   sev
 347 1001010000011000   sez
 348 100101001SSS1000   bclr    S
 349 100101000SSS1000   bset    S
 350 1001010100001001   icall
 351 1001010000001001   ijmp
 352 1001010111001000   lpm     ?
 353 1001000ddddd010+   lpm     r,z
 354 1001010111011000   elpm    ?
 355 1001000ddddd011+   elpm    r,z
 356 0000000000000000   nop
 357 1001010100001000   ret
 358 1001010100011000   reti
 359 1001010110001000   sleep
 360 1001010110011000   break
 361 1001010110101000   wdr
 362 1001010111101000   spm
 363 000111rdddddrrrr   adc     r,r
 364 000011rdddddrrrr   add     r,r
 365 001000rdddddrrrr   and     r,r
 366 000101rdddddrrrr   cp      r,r
 367 000001rdddddrrrr   cpc     r,r
 368 000100rdddddrrrr   cpse    r,r
 369 001001rdddddrrrr   eor     r,r
 370 001011rdddddrrrr   mov     r,r
 371 100111rdddddrrrr   mul     r,r
 372 001010rdddddrrrr   or      r,r
 373 000010rdddddrrrr   sbc     r,r
 374 000110rdddddrrrr   sub     r,r
 375 001001rdddddrrrr   clr     r
 376 000011rdddddrrrr   lsl     r
 377 000111rdddddrrrr   rol     r
 378 001000rdddddrrrr   tst     r
 379 0111KKKKddddKKKK   andi    d,M
 380 0111KKKKddddKKKK   cbr     d,n
 381 1110KKKKddddKKKK   ldi     d,M
 382 11101111dddd1111   ser     d
 383 0110KKKKddddKKKK   ori     d,M
 384 0110KKKKddddKKKK   sbr     d,M
 385 0011KKKKddddKKKK   cpi     d,M
 386 0100KKKKddddKKKK   sbci    d,M
 387 0101KKKKddddKKKK   subi    d,M
 388 1111110rrrrr0sss   sbrc    r,s
 389 1111111rrrrr0sss   sbrs    r,s
 390 1111100ddddd0sss   bld     r,s
 391 1111101ddddd0sss   bst     r,s
 392 10110PPdddddPPPP   in      r,P
 393 10111PPrrrrrPPPP   out     P,r
 394 10010110KKddKKKK   adiw    w,K
 395 10010111KKddKKKK   sbiw    w,K
 396 10011000pppppsss   cbi     p,s
 397 10011010pppppsss   sbi     p,s
 398 10011001pppppsss   sbic    p,s
 399 10011011pppppsss   sbis    p,s
 400 111101lllllll000   brcc    l
 401 111100lllllll000   brcs    l
 402 111100lllllll001   breq    l
 403 111101lllllll100   brge    l
 404 111101lllllll101   brhc    l
 405 111100lllllll101   brhs    l
 406 111101lllllll111   brid    l
 407 111100lllllll111   brie    l
 408 111100lllllll000   brlo    l
 409 111100lllllll100   brlt    l
 410 111100lllllll010   brmi    l
 411 111101lllllll001   brne    l
 412 111101lllllll010   brpl    l
 413 111101lllllll000   brsh    l
 414 111101lllllll110   brtc    l
 415 111100lllllll110   brts    l
 416 111101lllllll011   brvc    l
 417 111100lllllll011   brvs    l
 418 111101lllllllsss   brbc    s,l
 419 111100lllllllsss   brbs    s,l
 420 1101LLLLLLLLLLLL   rcall   L
 421 1100LLLLLLLLLLLL   rjmp    L
 422 1001010hhhhh111h   call    h
 423 1001010hhhhh110h   jmp     h
 424 1001010rrrrr0101   asr     r
 425 1001010rrrrr0000   com     r
 426 1001010rrrrr1010   dec     r
 427 1001010rrrrr0011   inc     r
 428 1001010rrrrr0110   lsr     r
 429 1001010rrrrr0001   neg     r
 430 1001000rrrrr1111   pop     r
 431 1001001rrrrr1111   push    r
 432 1001010rrrrr0111   ror     r
 433 1001010rrrrr0010   swap    r
 434 00000001ddddrrrr   movw    v,v
 435 00000010ddddrrrr   muls    d,d
 436 000000110ddd0rrr   mulsu   a,a
 437 000000110ddd1rrr   fmul    a,a
 438 000000111ddd0rrr   fmuls   a,a
 439 000000111ddd1rrr   fmulsu  a,a
 440 1001001ddddd0000   sts     i,r
 441 1001000ddddd0000   lds     r,i
 442 10o0oo0dddddbooo   ldd     r,b
 443 100!000dddddee-+   ld      r,e
 444 10o0oo1rrrrrbooo   std     b,r
 445 100!001rrrrree-+   st      e,r
 446 1001010100011001   eicall
 447 1001010000011001   eijmp
 448 @end smallexample
 449
 450 @node AVR Pseudo Instructions
 451 @section Pseudo Instructions
 452
 453 The only available pseudo-instruction @code{__gcc_isr} can be activated by
 454 option @option{-mgcc-isr}.
 455
 456 @table @code
 457
 458 @item __gcc_isr 1
 459 Emit code chunk to be used in avr-gcc ISR prologue.
 460 It will expand to at most six 1-word instructions, all optional:
 461 push of @code{tmp_reg}, push of @code{SREG},
 462 push and clear of @code{zero_reg}, push of @var{Reg}.
 463
 464 @item __gcc_isr 2
 465 Emit code chunk to be used in an avr-gcc ISR epilogue.
 466 It will expand to at most five 1-word instructions, all optional:
 467 pop of @var{Reg}, pop of @code{zero_reg},
 468 pop of @code{SREG}, pop of @code{tmp_reg}.
 469
 470 @item __gcc_isr 0, @var{Reg}
 471 Finish avr-gcc ISR function.  Scan code since the last prologue
 472 for usage of: @code{SREG}, @code{tmp_reg}, @code{zero_reg}.
 473 Prologue chunk and epilogue chunks will be replaced by appropriate code
 474 to save / restore @code{SREG}, @code{tmp_reg}, @code{zero_reg} and @var{Reg}.
 475
 476 @end table
 477
 478 Example input:
 479
 480 @example
 481 __vector1:
 482     __gcc_isr 1
 483     lds r24, var
 484     inc r24
 485     sts var, r24
 486     __gcc_isr 2
 487     reti
 488     __gcc_isr 0, r24
 489 @end example
 490
 491 Example output:
 492
 493 @example
 494 00000000 <__vector1>:
 495    0:   8f 93           push    r24
 496    2:   8f b7           in      r24, 0x3f
 497    4:   8f 93           push    r24
 498    6:   80 91 60 00     lds     r24, 0x0060     ; 0x800060 <var>
 499    a:   83 95           inc     r24
 500    c:   80 93 60 00     sts     0x0060, r24     ; 0x800060 <var>
 501   10:   8f 91           pop     r24
 502   12:   8f bf           out     0x3f, r24
 503   14:   8f 91           pop     r24
 504   16:   18 95           reti
 505 @end example