gas/doc/c-avr.texi

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