@c Copyright (C) 2006-2026 Free Software Foundation, Inc.
@c This is part of the GAS manual.
@c For copying conditions, see the file as.texinfo.

@ifset GENERIC
@page
@node AVR-Dependent
@chapter AVR Dependent Features
@end ifset

@ifclear GENERIC
@node Machine Dependencies
@chapter AVR Dependent Features
@end ifclear

@cindex AVR support
@menu
* AVR Options::              Options
* AVR Syntax::               Syntax
* AVR Opcodes::              Opcodes
* AVR Pseudo Instructions::  Pseudo Instructions
@end menu

@node AVR Options
@section Options
@cindex AVR options (none)
@cindex options for AVR (none)

@table @code

@cindex @code{-mmcu=} command-line option, AVR
@item -mmcu=@var{mcu}
Specify AVR instruction set or MCU type.

Instruction set avr1 is for the minimal AVR core, not supported by the C
compiler, only for assembler programs (MCU types: at90s1200,
attiny11, attiny12, attiny15, attiny28).

Instruction set avr2 (default) is for the classic AVR core with up to
8K program memory space (MCU types: at90s2313, at90s2323, at90s2333, at90s2343,
attiny22, attiny26, at90s4414, at90s4433, at90s4434, at90s8515, at90c8534,
at90s8535).

Instruction set avr25 is for the classic AVR core with up to 8K program memory
space plus the MOVW instruction (MCU types: attiny13, attiny13a, attiny2313,
attiny2313a, attiny24, attiny24a, attiny4313, attiny44, attiny44a, attiny84,
attiny84a, attiny25, attiny45, attiny85, attiny261, attiny261a, attiny461,
attiny461a, attiny861, attiny861a, attiny87, attiny43u, attiny48, attiny88,
attiny828, at86rf401, ata6289, ata5272).

Instruction set avr3 is for the classic AVR core with up to 128K program
memory space (MCU types: at43usb355, at76c711).

Instruction set avr31 is for the classic AVR core with exactly 128K program
memory space (MCU types: atmega103, at43usb320).

Instruction set avr35 is for classic AVR core plus MOVW, CALL, and JMP
instructions (MCU types: attiny167, attiny1634, at90usb82, at90usb162,
atmega8u2, atmega16u2, atmega32u2, ata5505).

Instruction set avr4 is for the enhanced AVR core with up to 8K program
memory space (MCU types: atmega48, atmega48a, atmega48pa, atmega48p, atmega8,
atmega8a, atmega88, atmega88a, atmega88p, atmega88pa, atmega8515, atmega8535,
atmega8hva, at90pwm1, at90pwm2, at90pwm2b, at90pwm3, at90pwm3b, at90pwm81,
ata6285, ata6286).

Instruction set avr5 is for the enhanced AVR core with up to 128K program
memory space (MCU types: at90pwm161, atmega16, atmega16a, atmega161, atmega162,
atmega163, atmega164a, atmega164p, atmega164pa, atmega165, atmega165a,
atmega165p, atmega165pa, atmega168, atmega168a, atmega168p, atmega168pa,
atmega169, atmega169a, atmega169p, atmega169pa, atmega32, atmega323, atmega324a,
atmega324p, atmega324pa, atmega325, atmega325a, atmega32, atmega32a, atmega323,
atmega324a, atmega324p, atmega324pa, atmega325, atmega325a, atmega325p,
atmega325p, atmega325pa, atmega3250, atmega3250a, atmega3250p, atmega3250pa,
atmega328, atmega328p, atmega329, atmega329a, atmega329p, atmega329pa,
atmega3290a, atmega3290p, atmega3290pa, atmega406, atmega64, atmega64a,
atmega64rfr2, atmega644rfr2, atmega640, atmega644, atmega644a, atmega644p,
atmega644pa, atmega645, atmega645a, atmega645p, atmega6450, atmega6450a,
atmega6450p, atmega649, atmega649a, atmega649p, atmega6490, atmega6490a,
atmega6490p, atmega16hva, atmega16hva2, atmega16hvb, atmega16hvbrevb,
atmega32hvb, atmega32hvbrevb, atmega64hve, at90can32, at90can64, at90pwm161,
at90pwm216, at90pwm316, atmega32c1, atmega64c1, atmega16m1, atmega32m1,
atmega64m1, atmega16u4, atmega32u4, atmega32u6, at90usb646, at90usb647, at94k,
at90scr100, ata5790, ata5795).

Instruction set avr51 is for the enhanced AVR core with exactly 128K
program memory space (MCU types: atmega128, atmega128a, atmega1280,
atmega1281, atmega1284, atmega1284p, atmega128rfa1, atmega128rfr2,
atmega1284rfr2, at90can128, at90usb1286, at90usb1287, m3000).

Instruction set avr6 is for the enhanced AVR core with a 3-byte PC
(MCU types: atmega2560, atmega2561, atmega256rfr2, atmega2564rfr2).

Instruction set avrxmega2 is for the XMEGA AVR core with 8K to 64K
program memory space and less than 64K data space (MCU types:
atxmega16a4, atxmega16a4u, atxmega16c4, atxmega16d4, atxmega16x1,
atxmega32a4, atxmega32a4u, atxmega32c4, atxmega32d4, atxmega16e5,
atxmega8e5, atxmega32e5, atxmega32x1).

Instruction set avrxmega3 is for the XMEGA AVR core with up to 64K
of combined program memory and RAM, and with program memory
visible in the RAM address space (MCU types:
attiny212, attiny214, attiny412, attiny414, attiny416, attiny417,
attiny814, attiny816, attiny817, attiny1614, attiny1616, attiny1617,
attiny3214, attiny3216, attiny3217).

Instruction set avrxmega4 is for the XMEGA AVR core with up to 64K
program memory space and less than 64K data space (MCU types:
atxmega64a3, atxmega64a3u, atxmega64a4u, atxmega64b1, atxmega64b3,
atxmega64c3, atxmega64d3, atxmega64d4).

Instruction set avrxmega5 is for the XMEGA AVR core with up to 64K
program memory space and greater than 64K data space (MCU types:
atxmega64a1, atxmega64a1u).

Instruction set avrxmega6 is for the XMEGA AVR core with larger than
64K program memory space and less than 64K data space (MCU types:
atxmega128a3, atxmega128a3u, atxmega128c3, atxmega128d3, atxmega128d4,
atxmega192a3, atxmega192a3u, atxmega128b1, atxmega128b3, atxmega192c3,
atxmega192d3, atxmega256a3, atxmega256a3u, atxmega256a3b,
atxmega256a3bu, atxmega256c3, atxmega256d3, atxmega384c3,
atxmega256d3).

Instruction set avrxmega7 is for the XMEGA AVR core with larger than
64K program memory space and greater than 64K data space (MCU types:
atxmega128a1, atxmega128a1u, atxmega128a4u).

Instruction set avrtiny is for the ATtiny4/5/9/10/20/40
microcontrollers.

@cindex @code{-mall-opcodes} command-line option, AVR
@item -mall-opcodes
Accept all AVR opcodes, even if not supported by @code{-mmcu}.

@cindex @code{-mno-skip-bug} command-line option, AVR
@item -mno-skip-bug
This option disable warnings for skipping two-word instructions.

@cindex @code{-mno-wrap} command-line option, AVR
@item -mno-wrap
This option reject @code{rjmp/rcall} instructions with 8K wrap-around.

@cindex @code{-mrmw} command-line option, AVR
@item -mrmw
Accept Read-Modify-Write (@code{XCH,LAC,LAS,LAT}) instructions.

@cindex @code{-mlink-relax} command-line option, AVR
@item -mlink-relax
Enable support for link-time relaxation.  This is now on by default
and this flag no longer has any effect.

@cindex @code{-mno-link-relax} command-line option, AVR
@item -mno-link-relax
Disable support for link-time relaxation.  The assembler will resolve
relocations when it can, and may be able to better compress some debug
information.

@cindex @code{-mgcc-isr} command-line option, AVR
@item -mgcc-isr
Enable the @code{__gcc_isr} pseudo instruction.

@cindex @code{-mno-dollar-line-separator} command line option, AVR
@item -mno-dollar-line-separator
Do not treat the @code{$} character as a line separator character.
This is for languages where @code{$} is valid in symbol names.

@end table


@node AVR Syntax
@section Syntax
@menu
* AVR-Chars::                Special Characters
* AVR-Regs::                 Register Names
* AVR-Modifiers::            Relocatable Expression Modifiers
@end menu

@node AVR-Chars
@subsection Special Characters

@cindex line comment character, AVR
@cindex AVR line comment character
@cindex ;, AVR

The presence of a @samp{;} anywhere on a line indicates the start of a
comment that extends to the end of that line.

If a @samp{#} appears as the first character of a line, the whole line
is treated as a comment, but in this case the line can also be a
logical line number directive (@pxref{Comments}) or a preprocessor
control command (@pxref{Preprocessing}).

@cindex line separator, AVR
@cindex statement separator, AVR
@cindex AVR line separator
@cindex $, AVR

The @samp{$} character can be used instead of a newline to separate statements.
A @samp{$} does not terminate a @samp{;} single-line comment.

@node AVR-Regs
@subsection Register Names

@cindex AVR register names
@cindex register names, AVR

The AVR has 32 x 8-bit general purpose working registers @samp{r0},
@samp{r1}, ... @samp{r31} (@samp{r16}, ... @samp{r31} on the Reduced Core).
Six of these registers can be used as three 16-bit address registers for
data addressing.  One of the these address
registers can also be used as an address pointer for lookup tables in
Flash memory. These added function registers are the 16-bit
@samp{X}, @samp{Y} and @samp{Z} registers.

@smallexample
X = @r{r26:r27}
Y = @r{r28:r29}
Z = @r{r30:r31}
@end smallexample

@itemize
@item The low part of the @code{X} register, @code{r26}, can be written
as @samp{XL}. The high part can be written as @samp{XH}.  Similar notations
exist for the parts of the @code{Y} and @code{Z} registers.

@item Registers can be accessed by their register number and without
the @samp{r} register prefix.  For example, @samp{20+1} denotes @code{r21}.

@item Both lowercase and uppercase register names are recognized.
@end itemize

@node AVR-Modifiers
@subsection Relocatable Expression Modifiers

@cindex AVR modifiers
@cindex syntax, AVR

The assembler supports several modifiers when using relocatable addresses
in AVR instruction operands.  The general syntax is the following:

@smallexample
modifier(relocatable-expression)
@end smallexample

When the argument of a modifier is not computable at assemble time,
then the assembler has to encode the expression in an abstract form
using some target-specific @emph{reloc}. The consequence is that only
a very limited number of argument expressions is supported when they
are not computable at assemble time.

@cindex symbol modifiers, AVR
@table @code

@cindex lo8, AVR
@item lo8
Bits 0 through 7 of an expression as an 8-bit relocatable expression.

@cindex hi8, AVR
@item hi8
Bits 8 through 15 of an expression as an 8-bit relocatable expression.
This is useful with instructions that have an immediate operand, for example:

@smallexample
;; my_array is an array of 8-bit values in RAM.
;; Load the N-th element to R24 where the 16-bit
;; value N is provided in the Z register (r30 and r31).
subi r30, lo8(-(my_array))
sbci r31, hi8(-(my_array))
ld   r24, Z
@end smallexample

@cindex hlo8, AVR
@cindex hh8, AVR
@item hlo8
@itemx hh8
Bits 16 through 23 of an expression as an 8-bit relocatable expression.

@cindex hhi8, AVR
@item hhi8
Bits 24 through 31 of an expression as an 8-bit relocatable expression.

@cindex gs, AVR
@item gs
A function address divided by 2 in order to get a word address.
@b{G}enerate a @b{s}tub (linker trampoline) as needed.
This is required to handle function pointers on devices with more
than 128 KiB of program memory without the need for function pointers
wider than 16 bits. For the rationale, see the
@uref{https://gcc.gnu.org/onlinedocs/gcc/AVR-Options.html#eind,,GCC documentation}.

On devices with less program memory, @code{gs()} behaves like @code{pm()}.

The following example loads a 16-bit address related to @samp{func} and
calls it:

@smallexample
;; Invoke func by means of an indirect call.
ldi r30, lo8(gs(func))
ldi r31, hi8(gs(func))
#idef __AVR_HAVE_EIJMP_EICALL__
   eicall
#else
   icall
#endif
@end smallexample

This will always be a 16-bit address, even on devices with a 3-byte PC.
With a 3-byte PC and when the target address is not reachable by an
@code{EICALL}, the linker will @b{g}enerate a @b{s}tub with a single
@samp{JMP func} instruction that @emph{is} reachable by @code{EIND}.
@code{gs()} evaluates to the lower 16 bits of the word address of that stub.

Notice that @code{EIND} is set by the
@uref{https://github.com/avrdudes/avr-libc/blob/main/crt1/gcrt1.S,,startup code}
and never read or changed by the compiler.  The default linker script locates
the stubs such that they are in the reach of @code{EIND} as set by the
startup code, so that the code above works in all situations and without the
need to touch @code{EIND}.

@cindex pm, AVR
@cindex pm_lo8, AVR
@item pm_lo8
Bits 1 through 8 of an expression as an 8-bit relocatable expression.
This modifier is useful for accessing code from @b{p}rogram @b{m}emory
with a word address.

@cindex pm_hi8, AVR
@item pm_hi8
Bits 9 through 16 of an expression as an 8-bit relocatable expression.
This modifier is useful for accessing code from @b{p}rogram @b{m}emory
with a word address.

@cindex pm_hh8, AVR
@item pm_hh8
Bits 17 through 24 of an expression as an 8-bit relocatable expression.
This modifier is useful for accessing code from @b{p}rogram @b{m}emory
with a word address.

The code below performs an indirect call by hand to function @samp{func}
using the following steps:

@enumerate
@item
Put the word address of the @samp{1:} label on the stack.
This is the return address.
@item
Put the word address of @samp{func} on the stack.
@item
Invoke @samp{func} by means of a @code{RET} instruction.
@item
The @code{RET} instruction at the end of @samp{func} will
jump to the @samp{1:} label.
@end enumerate

@smallexample
;; Push the word address of the return location.
ldi r24, pm_lo8(1f)  $  push r24
ldi r24, pm_hi8(1f)  $  push r24
#ifdef __AVR_3_BYTE_PC__
ldi r24, pm_hh8(1f)  $  push r24
#endif

;; Push the word address of func using alternative syntax.
ldi r24, lo8(pm(func))  $  push r24
ldi r24, hi8(pm(func))  $  push r24
#ifdef __AVR_3_BYTE_PC__
ldi r24, hh8(pm(func))  $  push r24
#endif

;; Indirect jump to the word address on the stack
ret

;; The location to which func will return.
1:
@end smallexample

@end table

@node AVR Opcodes
@section Opcodes

@cindex AVR opcode summary
@cindex opcode summary, AVR
@cindex mnemonics, AVR
@cindex instruction summary, AVR
For detailed information on the AVR machine instruction set, see
@url{www.atmel.com/products/AVR}
(@uref{https://ww1.microchip.com/downloads/en/DeviceDoc/AVR-InstructionSet-Manual-DS40002198.pdf,,pdf}).

The GNU assembler implements all the standard AVR opcodes.
The following table summarizes the AVR opcodes and their arguments.

@smallexample
@i{Legend:}
   r   @r{any register}
   d   @r{`ldi' register (r16-r31)}
   v   @r{`movw' even register (r0, r2, ..., r28, r30)}
   a   @r{`fmul' register (r16-r23)}
   w   @r{`adiw' register (r24, r26, r28, r30)}
   e   @r{pointer registers (X, Y, Z)}
   b   @r{base-pointer register and displacement ([YZ]+disp)}
   z   @r{Z pointer register}
   M   @r{immediate value from 0 to 255}
   n   @r{immediate value from 0 to 255 (n = ~M). Relocation impossible}
   N   @r{immediate value from 0 to 255. Relocation impossible}
   s   @r{immediate value from 0 to 7}
   P   @r{port address from 0 to 63 (in, out)}
   p   @r{port address from 0 to 31 (cbi, sbi, sbic, sbis)}
   K   @r{immediate value from 0 to 63 (adiw, sbiw)}
   i   @r{immediate value}
   j   @r{7-bit immediate value from 0x40 to 0xBF (16-bit lds, sts)}
   l   @r{PC-relative offset from -64 to 63}
   L   @r{PC-relative offset from -2048 to 2047}
   h   @r{absolute code address (call, jmp)}
   S   @r{immediate value from 0 to 7 (S = s << 4)}
   E   @r{immediate value from 0 to 15, shifted left by 4 (des)}
   ?   @r{use this opcode entry if no parameters, else use next opcode entry}

1001010010001000   clc
1001010011011000   clh
1001010011111000   cli
1001010010101000   cln
1001010011001000   cls
1001010011101000   clt
1001010010111000   clv
1001010010011000   clz
1001010000001000   sec
1001010001011000   seh
1001010001111000   sei
1001010000101000   sen
1001010001001000   ses
1001010001101000   set
1001010000111000   sev
1001010000011000   sez
100101001SSS1000   bclr    S
100101000SSS1000   bset    S
1001010100001001   icall
1001010000001001   ijmp
1001010111001000   lpm     ?
1001000ddddd010+   lpm     r,z
1001010111011000   elpm    ?
1001000ddddd011+   elpm    r,z
0000000000000000   nop
1001010100001000   ret
1001010100011000   reti
1001010110001000   sleep
1001010110011000   break
1001010110101000   wdr
1001010111101000   spm     ?
10010101111+1000   spm     z
000111rdddddrrrr   adc     r,r
000011rdddddrrrr   add     r,r
001000rdddddrrrr   and     r,r
000101rdddddrrrr   cp      r,r
000001rdddddrrrr   cpc     r,r
000100rdddddrrrr   cpse    r,r
001001rdddddrrrr   eor     r,r
001011rdddddrrrr   mov     r,r
100111rdddddrrrr   mul     r,r
001010rdddddrrrr   or      r,r
000010rdddddrrrr   sbc     r,r
000110rdddddrrrr   sub     r,r
001001rdddddrrrr   clr     r
000011rdddddrrrr   lsl     r
000111rdddddrrrr   rol     r
001000rdddddrrrr   tst     r
0111KKKKddddKKKK   andi    d,M
0111KKKKddddKKKK   cbr     d,n
1110KKKKddddKKKK   ldi     d,M
11101111dddd1111   ser     d
0110KKKKddddKKKK   ori     d,M
0110KKKKddddKKKK   sbr     d,M
0011KKKKddddKKKK   cpi     d,M
0100KKKKddddKKKK   sbci    d,M
0101KKKKddddKKKK   subi    d,M
1111110rrrrr0sss   sbrc    r,s
1111111rrrrr0sss   sbrs    r,s
1111100ddddd0sss   bld     r,s
1111101ddddd0sss   bst     r,s
10110PPdddddPPPP   in      r,P
10111PPrrrrrPPPP   out     P,r
10010110KKddKKKK   adiw    w,K
10010111KKddKKKK   sbiw    w,K
10011000pppppsss   cbi     p,s
10011010pppppsss   sbi     p,s
10011001pppppsss   sbic    p,s
10011011pppppsss   sbis    p,s
111101lllllll000   brcc    l
111100lllllll000   brcs    l
111100lllllll001   breq    l
111101lllllll100   brge    l
111101lllllll101   brhc    l
111100lllllll101   brhs    l
111101lllllll111   brid    l
111100lllllll111   brie    l
111100lllllll000   brlo    l
111100lllllll100   brlt    l
111100lllllll010   brmi    l
111101lllllll001   brne    l
111101lllllll010   brpl    l
111101lllllll000   brsh    l
111101lllllll110   brtc    l
111100lllllll110   brts    l
111101lllllll011   brvc    l
111100lllllll011   brvs    l
111101lllllllsss   brbc    s,l
111100lllllllsss   brbs    s,l
1101LLLLLLLLLLLL   rcall   L
1100LLLLLLLLLLLL   rjmp    L
1001010hhhhh111h   call    h
1001010hhhhh110h   jmp     h
1001010rrrrr0101   asr     r
1001010rrrrr0000   com     r
1001010rrrrr1010   dec     r
1001010rrrrr0011   inc     r
1001010rrrrr0110   lsr     r
1001010rrrrr0001   neg     r
1001000rrrrr1111   pop     r
1001001rrrrr1111   push    r
1001010rrrrr0111   ror     r
1001010rrrrr0010   swap    r
1001001rrrrr0100   xch     z,r
1001001rrrrr0101   las     z,r
1001001rrrrr0110   lac     z,r
1001001rrrrr0111   lat     z,r
00000001ddddrrrr   movw    v,v
00000010ddddrrrr   muls    d,d
000000110ddd0rrr   mulsu   a,a
000000110ddd1rrr   fmul    a,a
000000111ddd0rrr   fmuls   a,a
000000111ddd1rrr   fmulsu  a,a
1001001ddddd0000   sts     i,r   32-bit opcode
1001000ddddd0000   lds     r,i   32-bit opcode
10101kkkddddkkkk   sts     j,d   16-bit AVRrc opcode
10100kkkddddkkkk   lds     d,j   16-bit AVRrc opcode
10o0oo0dddddbooo   ldd     r,b
100!000dddddee-+   ld      r,e
10o0oo1rrrrrbooo   std     b,r
100!001rrrrree-+   st      e,r
1001010100011001   eicall
1001010000011001   eijmp
10010100EEEE1011   des     E
@end smallexample

@node AVR Pseudo Instructions
@section Pseudo Instructions

The only available pseudo-instruction @code{__gcc_isr} can be activated by
option @option{-mgcc-isr}.

@table @code

@item __gcc_isr 1
Emit code chunk to be used in avr-gcc ISR prologue.
It will expand to at most six 1-word instructions, all optional:
push of @code{tmp_reg}, push of @code{SREG},
push and clear of @code{zero_reg}, push of @var{Reg}.

@item __gcc_isr 2
Emit code chunk to be used in an avr-gcc ISR epilogue.
It will expand to at most five 1-word instructions, all optional:
pop of @var{Reg}, pop of @code{zero_reg},
pop of @code{SREG}, pop of @code{tmp_reg}.

@item __gcc_isr 0, @var{Reg}
Finish avr-gcc ISR function.  Scan code since the last prologue
for usage of: @code{SREG}, @code{tmp_reg}, @code{zero_reg}.
Prologue chunk and epilogue chunks will be replaced by appropriate code
to save / restore @code{SREG}, @code{tmp_reg}, @code{zero_reg} and @var{Reg}.

@end table

Example input:

@example
__vector1:
    __gcc_isr 1
    lds r24, var
    inc r24
    sts var, r24
    __gcc_isr 2
    reti
    __gcc_isr 0, r24
@end example

Example output:

@example
00000000 <__vector1>:
   0:   8f 93           push    r24
   2:   8f b7           in      r24, 0x3f
   4:   8f 93           push    r24
   6:   80 91 60 00     lds     r24, 0x0060     ; 0x800060 <var>
   a:   83 95           inc     r24
   c:   80 93 60 00     sts     0x0060, r24     ; 0x800060 <var>
  10:   8f 91           pop     r24
  12:   8f bf           out     0x3f, r24
  14:   8f 91           pop     r24
  16:   18 95           reti
@end example
