AVRA(1)

📦
version 1.4.2 · 3 versions
, in debian bookworm, debian trixie, ubuntu noble

💖 avra(1) — the AVR assembler, but make it a group chat 💖

okay so avra is an assembler for the AVR microcontroller family, and it hangs out in the User Commands section of your manual, bestie. pull up a chair, we're doing this together 🫶

🌸 NAME 🌸

avra — an assembler for the AVR microcontroller family. that's it, that's the whole name, short and iconic 💅

✨ SYNOPSIS ✨

avra [OPTION]... FILE

like, you give it some options, you give it a file, it does the thing. no cap. 🦋

🎀 DESCRIPTION 🎀

AVRA is an advanced macro assembler for the AVR microcontrollers, and it was literally designed as a replacement for AVRASM32. the command line options got adapted to be as close as possible to the original, bc we respect the ancestors, but AVRA also comes with a whole bunch of advanced features that AVRASM32 simply does not have. and those features? they're the ones that help you write versatile and more modular code. it's giving glow-up, fr fr. ✨

💅 OPTIONS 💅

here's the whole menu, no skipping, we list every single one bc that's the rules:

  • -d, --debugfile <filename> — name for the debug file
  • -D, --define <symbol>[=<value>] — define a symbol, optionally with a value
  • -e, --eepfile <filename> — make an EEPROM contents file
  • -f, --filetype O|M|I|G — which output file type you want
  • -I, --includepath <dir> — extra include paths (default: /usr/share/avra)
  • -l, --listfile <filename> — make a list file
  • -m, --mapfile <mapfile> — make a map file
  • -o, --outfile <filename> — name of the output file
  • -O, --overlap e|w|i — what to do about overlapping code: issue an error / warning / ignore it
  • --devices — list out all the supported devices
  • --listmac — show macro expansion in the listfile
  • --max_errors <number> — max number of errors before it dips out (default: 10)
  • --version — version information
  • -h, --help — general help
  • FILE — the file you actually want to assemble

🎀 AVRA USAGE 🎀

to compile a source file, you literally just run avra mysource.S. and boom, you end up with a compiled version of the file in Intel HEX format sitting right at mysource.S.hex. 💖

wanna control the output filename? use -o. and for even more options, peek at --help — tho fair warning bestie, not all options work. 🙈

🚨 WARNING SUPPRESSION 🚨

so there is a way to suppress certain warnings, if that's your vibe. currently only register reassignment warnings can be suppressed, and here's how:

avra -W NoRegDef

👑 USING DIRECTIVES 👑

AVRA comes with a whole set of directives that are not part of Atmel's assembler. and these directives are exactly the little helpers that let you build versatile, more modular code. we love a modular moment. 🧚

✨ Directive .define ✨

wanna define a constant? use .define. it does the exact same thing as .equ, it's just a lil more C style, that's all. and remember, AVRA is not case sensitive — keep that in mind.

⚠️ do not confuse .define with .def — .def is only for assigning registers. this split exists bc of backward compatibility with Atmel's AVRASM32, so don't come for me.

here's an example of .define in the wild:

.define network 1

now network is set to the value 1. you can also define names without values at all:

.define network

both versions are equivalent, bc AVRA will implicitly define network to be 1 in that second case. (tho, like, if you genuinely want network to be 1, use the first version, bestie, be intentional.) 💅

you might wanna assemble only a specific chunk of your code depending on a define or a switch setting. you can test your defined word on existence (.ifdef and .ifndef) as well as on the value it represents. and here's a lil trick to stop error messages from happening when you test undefined constants:

.ifndef network .define network 0 .endif

🌈 Directives .if and .else 🌈

so those three lines in the last example set the default value of network. now we can use .if and .else to test whether, like, network support should even be part of the assembly process:

.if network = 1 .include "include\tcpip.asm" .else .include "include\dummynet.asm" .endif

there's also an .elif ("else if") directive, and it does exactly what you think it does. no notes. 🔥

💜 Directive .error 💜

the .error directive lets you throw an error during the assembly process. the following example shows how we can stop the assembler if a particular value hasn't been set beforehand:

.ifndef network .error "network is not configured!" ; the assembler stops here

.endif

🎀 Directives .nolist and .list 🎀

the output to the list file can be paused and resumed with the .nolist and .list directives. the way it works: once AVRA discovers a .nolist while assembling, it stops writing output to the list file. then once a .list directive gets detected, AVRA goes right back to normal list file output. pause, resume, pause, resume — it's a whole routine and it ate. 💅

🦋 Directive .includepath 🦋

by default, any file that gets included from inside the source file has to either be a single filename or an absolute path. but with the .includepath directive you can set an additional include path. and honestly? you can set as many include paths as you want, go off. just to avoid ambiguity tho, be sure not to use the same filename in separate included directories. 🌸

🌟 USING INCLUDE FILES 🌟

to avoid multiple inclusion of include files, you can use some directives, like in this example:

.ifndef _MYFILE_ASM_ ; Avoid multiple inclusion of myfile.asm
.define _MYFILE_ASM_

; Anything here will only be included once.

.endif

⭐ USING BUILD DATE META TAGS ⭐

you can use some special tags that AVRA supports to bake compiler build time and date right into your program. they're literally little time capsules:

  • %MINUTE% — gets replaced by the current minute (00-59)
  • %HOUR% — gets replaced by the current hour (00-23)
  • %DAY% — gets replaced by the current day of month (01-31)
  • %MONTH% — gets replaced by the current month (01-12)
  • %YEAR% — gets replaced by the current year (2004-9999)

for example, these tags can be used like this:

buildtime: .db "Release date %DAY%.%MONTH%.%YEAR% %HOUR%:%MINUTE%"

and this line will then be assembled by AVRA into:

buildtime: .db "Release date 10.05.2004 19:54"

as another example, you can create an automatically-updating serial number with meta tags:

.define serialnumber %DAY% + %MONTH%*31 + (%YEAR% - 2000) *31*12

and the important bit: the %TAG% is translated before any other parsing happens. the real output can be found in the list file. 👑

🦋 MACRO FEATURES 🦋

okay so sometimes you gotta deal with 16-bit-or-bigger variables that live inside 8-bit registers, and that's exactly the situation AVRA's enhanced macro support was made for, bestie. It lets you write short + flexible macros that make big-variable access feel effortless. The glow-up activates when you wrap macro parameters in square brackets [ ]. Examples below, let's go 💅

✨ Automatic Type Conversion For Macros ✨

Values bigger than 8 bits are normally chillin' in a set of byte-wide registers. To make 16-bit ops less of a whole thing, you can write words as r16:r17. In that example, r16 holds the most significant byte and r17 holds the least significant byte. Same energy for a 24-bit value spread over 3 registers — write it like r16:r17:r18 (here r16 is the most significant and r18 is the least significant). fr fr you can use up to 8 registers with this syntax. iconic.

🎀 Macro Data Types 🎀

There are 3 data types you can use in macro definitions, and you pick them by tacking one of these underscore-y codes onto the end of the macro name:

  • immediate values — _i
  • registers — _8, _16, _24, _32, _40, _48, _56, _64
  • void parameter — _v

Peep the next section for how these actually behave 👀

Inside square brackets, the two words src and dst get interpreted as YH:YL and ZH:ZL, respectively. And no worries — normal code outside of the macro parameter square brackets can still use the special key words src and dst with zero side effects. no cap.

💖 Examples For Automatic Type Conversion and Macro Overloading 💖

To keep the examples below chill, we redefine some registers:

.def a = r16        ; general purpose registers
.def b = r17
.def c = r18
.def d = r19

.def w = r20        ; working registers
.def v = r21

So if we wanna subtract the 16 bit value c:d from a:b, we'd usually be stuck writing this whole command sequence:

sub b,d
sbc a,c

But now? Macros can make 16-bit subtraction so much cuter:

.macro subs
  .message "no parameters specified"
.endm

.macro subs_16_16
  sub @1,@3
  sbc @0,@2
.endm

.macro subs_16_8
  sub  @1,@2
  sbci @0,0
.endm

and then:

; Now we can write a 16 bit minus 16 bit subtraction as:
subs [a:b,c:d]

; Or, for a 16 bit minus 8 bit subtraction:
subs [a:b,c]

not me overloading the subs macro to accept arguments of different types… literally just like you could do in C, bestie. 💅 Another example of macro overloading coming right up:

.macro load
  ; This message is shown if you use the macro within your code
  ; specifying no parameters. If your macro allows the case where
  ; no parameters are given, exchange .message with your code.
  .message "no parameters specified"
.endm

; Here we define the macro "load" for the case it is being used
; with two registers as first parameter and an immediate (constant)
; value as second parameter:

.macro load_16_i
  ldi @0,high(@2)
  ldi @1,low(@2)
.endm

; The same case, but now with a 32 bit register value as first
; parameter:

.macro load_32_i
  ldi @0,BYTE4(@4)
  ldi @1,BYTE3(@4)
  ldi @2,high(@4)
  ldi @3,low(@4)
.endm

and now these macros can be invoked like this:

load [a:b,15]       ; Uses macro load_16_i to load immediate.
load [a:b:c:d,15]   ; Uses macro load_32_i to load immediate.

🌸 More Examples 🌸

.dseg
counter: .byte 2

.cseg

.macro poke
  .message "no parameters"
.endm

.macro poke_i_16_i
  ldi    @1,high(@3)
  sts    @0+0,@1
  ldi    @2,low(@3)
  sts    @0+1,@2
.endm

.macro poke_i_i
  ldi    w,@1
  sts    @0+0,w
.endm

.macro poke_i_v_i
  ldi    w,high(@3)
  sts    @0+0,w
  ldi    w,low(@3)
  sts    @0+1,w
.endm

.macro poke_i_v_v_v_i
  ldi    w,high(@3)
  sts    @0+0,w
  ldi    w,low(@3)
  sts    @0+1,w
  ldi    w,BYTE3(@3)
  sts    @0+2,w
  ldi    w,BYTE4(@3)
  sts    @0+3,w
.endm
; This writes 9999 into the memory at 'counter' using only the working
; register for transferring the values.
poke [counter,w:w,9999]

; This works the same as above, but the transferred value 9999 is also
; kept in the pair of registers a:b.
poke [counter,a:b,9999]

; In this design 'w' is always a working register, which implies that
; it cannot be used for normal variables. The following example
; uses poke_i_i because the parameter contains two immediate values.
poke [counter,9999]      ;uses poke_i_i

; To be able to choose between a 8, 16, or 32 bit operation, you just
; add a void parameter.
poke [counter,,9999]     ;uses poke_i_v_i

; And the same for 32 bit pokes:
poke [counter,,,,9999]   ;uses poke_i_v_v_v_i

🧚 Loops Within Macros 🧚

okay so one lil problem you might've bumped into: labels defined inside macros get defined twice — for example if you call the macro two times. 😭 The fix is adorable tho: make labels for macro loops by appending "_%" to the label. The "%" symbol gets replaced by a running number. slay.

Loop Example:

; Definition of the macro
.macro write_8_8
write_%:
  st     Z+,@0
  dec    @1
  brne write_%
.endm

; Use in user code
write [a,b]
write [c,d]

; After assembling this code, the result looks like this:
write_1:
  st     Z+,a
  dec    b
  brne write_1
write_2:
  st     Z+,c
  dec    d
  brne write_2

💀 WARNINGS AND ERRORS 💀

Here are some frequently asked questions about common errors. (yes this is the "it's giving chaos" section, but we get through it together 🫶)

😭 Constant Out Of Range 😭

This warning pops up if a value exceeds the byte or word value of an assignment. Read the comment posted by Jim Galbraith:

The expression (~0x80) is a Bitwise Not operation. This operator returns the input expression with all its bits inverted. If 0x80 represents -128, then 0x7f, or +127 should be ok. If this is considered as a 32-bit expression (AVRA internal representation), then it appears to be more like oxffffffff-0x80 or 0xffffffff^0x80. The result would then be 0xffffff7f. The assembler would then have to be told or it would have to decide, based on context, how much significance to assign to the higher bits. I have also encountered such conditions with various assemblers, including AVRA. To make sure the assembler does what I really want, I use a construct like 0xff-0x80 or 0xff^0x80. This way the bit significance cannot extend beyond bit-7 and there cannot be any misunderstanding.

🚫 Can't Use .DB Directive in Data Segment 🚫

The .DB and .DW directives are only for assigning constant data in the eeprom or code space. Using them inside the data segment is forbidden — because you literally cannot set ram content at assembly time, bestie. You can only allocate memory for your variables using labels and the .byte directive:

.dseg
my_string: .byte 15

🍓 The .byte Directive 🍓

The .byte directive can only be used in the data segment (.dseg).

It can't be used in the code or eeprom regions, because it only allocates memory without assigning specific values to it. Instead, use .db or .dw for data in the code or eeprom segments. periodt.

🙈 Internal Assembler Error 🙈

If you get an "internal assembler error", please contact the project maintainer via the GitHub issue tracker: <https://github.com/Ro5bert/avra/issues>. Be sure to include a code example and a description of your working environment. (we can't fix what we can't see, bestie 💖)

👑 AUTHOR 👑

Originally written by John Anders Haugum; subsequently maintained by Tobias Weber (v0.7+), Burkhard Arenfeld (v1.2), Jerry Jacobs (v1.3) and Virgil Dupras (v1.4). This manual page has been produced by Milan Kupcevic <milan@debian.org> for the Debian project and can be used by others. See AUTHORS for complete list of contributors. 🫶

Copyright © 1998-2003, 2004, 2005, 2006, 2007, 2010, 2019, 2020 Jon Anders Haugum, Tobias Weber, Burkhard Arenfeld, Robert Russell, Jerry Jacobs et al. License GPLv2+: GNU GPL version 2 or later <http://gnu.org/licenses/gpl.html>. This is free software; you are free to change and redistribute it under certain conditions. There is NO WARRANTY to the extent permitted by law. ⚠️

⭐ SEE ALSO ⭐

and that's the whole page, bestie!! this was avra 1.4.2, dated March 2023, and the man page is AVRA(1) — go forth and assemble something iconic 💅✨

📦 where this page comes from