inline_asm(3avr)

📦
version 2.2.1 · 4 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

inline_asm — the Inline Assembler Cookbook ✨ (yep, that's this page: inline_asm(3avr) from the AVR-GCC docs)

okay bestie, this is the glow-up guide to AVR-GCC Inline Assembler. here's the whole map before we dive in 🗺️

  • About this Document
  • Building Blocks
    • The Anatomy of a GCC asm Statement
    • Special Sequences
    • Constraints
      • Constraint Modifiers
      • Instructions and Constraints
    • Print Modifiers
    • Operand Modifiers
  • Examples
    • Swapping Nibbles
    • Swapping Bytes
    • Accessing Memory
    • Accessing Bytes of wider Expressions
    • Inline Functions and __builtin_constant_p
    • Jumping and Branching
  • Binding local Variables to Registers
    • Interfacing non-ABI Functions
  • Specifying the Assembly Name of Static Objects
  • What won't work

🌸 About this Document 🌸

The GNU C/C++ compiler for AVR RISC processors offers to embed assembly language code into C/C++ programs. And like… this is the coolest feature ever, no cap 💅 you can use it to manually optimize the time-critical parts of your software, or to use specific processor instructions that the C language simply doesn't have. iconic behavior.

It's assumed that you are familiar with writing AVR assembler programs, because this is not an AVR assembler programming tutorial. It's not a C/C++ tutorial either. sorry bestie, prerequisites are prerequisites 🫶

Note that this document does not cover files written completely in assembly language, refer to AVR-LibC and Assembler Programs for this. (that's a different page, go look it up iykyk)

Copyright (C) 2001-2002 by egnite Software GmbH

Permission is granted to copy and distribute verbatim copies of this manual provided that the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

This document describes version 4.7 of the compiler or newer.

Herne, 17th of May 2002 — Harald Kipp — harald.kipp-at-egnite.de

🎀 The Anatomy of a GCC asm Statement 🎀

A GCC inline assembly statement starts with the keyword asm, __asm or __asm__, where the first one is not available in strict ANSI mode 👀 (so if you're being a strict little ANSI girlie, use the underscores).

In its simplest form, the inline assembly statement has no operands and injects just one instruction into the code stream, like in

__asm ("nop");

In its generic form, an asm statements can have one of the following three forms. let's break it down 💖

A simple asm without operands ✨

__asm (code-string);

code-string is a string literal that will be added as is into the generated assembly code. This even applies to the % character. The only replacement is that \n and \t are interpreted as newline resp. TAB character.

This type of asm statement may occur at top level, outside any function, as global asm. When its placement relative to functions is important, consider -fno-toplevel-reorder.

An asm with operands 💅

__asm volatile (code-string : output-operands : input-operands : clobbers);

This is the most widely used form of an asm statement. It must be located in a function.

output-operands, input-operands and clobbers are comma-separated lists of operands resp. clobber specifications. Any of them may be empty, for example when the asm has no outputs. At least one : (colon) must be present, otherwise it will be a simple asm without operands and without % replacements. (a colon is the whole vibe check here, don't skip it 🚨)

An asm goto statement 🦋

__asm goto (code-string : : input-operands : clobbers : labels);

Like the asm above, but labels is a comma-separated list of C/C++ code labels which would be valid in a goto statement. And output-operands must be empty, because it is impossible to generate output reloads after the code has transferred control to one of the labels.

As there are no output operands, asm goto is implicitly volatile. When volatile is specified explicitly, the goto keyword may be placed after or before the volatile.

Notes on the various parts 📝

Volatility

Keyword volatile is optional and means that the asm statement has side effects that are not expressed in terms of the operands or clobbers. The asm statement must not be optimized away or reordered with respect to other volatile statements like volatile memory accesses or other volatile asm.

Any asm statement without output-operands is implicitly volatile.

A non-volatile asm statement with output operands that are all unused may be optimized away when all output operands are unused.

Instead of volatile, __volatile or __volatile__ can be used.

code-string

A string literal that contains the code that is to be injected in the assembly code generated by the compiler. %-expressions are replaced by the string representations of the operands, and the number of lines is determined to estimate the code size of the asm.

Apart from that, the compiler does not analyze the code provided in the code template. This means that the code appears to the compiler as if it was executed in one parallel chunk, all at once. It is important to keep that in mind, in particular for cases where input and output operands may overlap. (bestie this is the part that bites people, fr fr 😭)

output-operands

input-operands

A comma-separated list of operands, which may take the following forms. In any case, the first operand can be referred to as "%0" in code-string, the second one as "%1" etc.

  • expr is a C expression that's an input or output (or both) to the asm statement. An output expression must be an lvalue, i.e. it must be valid to assign a value to it.
  • "constraints" is a string literal with constraints and constraint modifiers. For example, constraint "r" stands for general-purpose register. A simple input operand would be
"r" (value + 1)

The compiler computes value + 1 and supplies it in some general-purpose register R2...R31. In many cases, an upper d-register R16...R31 is required for instructions like LDI or ANDI. A respective output operand specification is

"=d" (result)
Notice that this operand may overlap with input operands! 👀

When an operand is written before all input operands are consumed, then in almost all cases the output operand requires an early-clobber modifier & so that it won't overlap with any input operand:

"=&d" (result)

An operand that's both an output and an input can be expressed with the + constraint modifier:

"+d" (result)

Such an operand is both output and input, and hence it won't overlap with other operands.

  • [name] — Like above. In addition, a named operand can be referred to as %[name] in code-string. This is useful in long asm statements with many operands.

clobbers

A comma-separated list of string literals like "16", "r16" or "memory".

The first two clobbers mean that the asm destroys register R16. Only the lower-case form is allowed, and register names like Z are not recognized. ⚠️

"memory" means that the asm touches memory in some way. When the asm writes to some RAM location for example, the compiler must not optimize RAM accesses across the asm because the memory may change.

Clobbering __tmp_reg__ by means of "r0" has no effect, but such a clobber may be added to indicate to the reader that the asm clobbers R0.

Clobbering __zero_reg__ by means of "r1" has no effect. When the asm destroys the zero register, for example by means of a MUL instruction, then the code must restore the register at the end by means of clr __zero_reg__

The size of an asm

The code size of an asm statement is the number of lines multiplied by 4 bytes, the maximal possible AVR instruction length. The length is needed when (conditional) jumps cross the asm statement in order to compute (upper bounds for) jump offsets of PC-relative jumps.

The number of lines is one plus the number of line breaks in code-string. These may be physical line breaks from \n characters and logical line breaks from $ characters.

Before we start with the first examples, we list all the bells and whistles that can be used to compose an inline assembly statement: special sequences, constraints, constraint modifiers, print modifiers and operand modifiers. 🎀✨

🌈 Special Sequences 🌈

There are special sequences that can be used in the assembly template. periodt.

  • __SREG__ — The I/O address of the status register SREG at 0x3F
  • __tmp_reg__ — The temporary register R0 (R16 on reduced Tiny)
  • __zero_reg__ — The zero register R1, always zero (R17 on reduced Tiny)
  • $ — A logical line separator, used to separate multiple instruction in one physical line
  • \n — A physical newline, used to separate multiple instructions
  • \t — A TAB character, can be used for better legibility of the generated asm
  • \" — A " character (double quote)
  • \\ — A \ character (backslash)
  • %% — A % charater (percent)
  • %~ — "r" or "", used to construct call or rcall by means of "%~call", depending on the architecture
  • %! — "" or "e", used to construct indirect calls like icall or eicall by means of "%!icall", depending on the architecture
  • %= — A number that's unique for the compilation unit and the respective inline asm code, used to construct unique labels

And here's the Comment / Description pairs 💬

  • ; text — A single-line assembly comment that extends to the end of the physical line
  • /* text */ — A multi-line C comment

Now the important little extras, listen up bestie 🫶

  • Moreover, the following I/O addresses are defined provided the device supports the respective SFR: __SP_L__, __SP_H__, __CCP__, __RAMPX__, __RAMPY__, __RAMPZ__, __RAMPD__.
  • Register __tmp_reg__ may be freely used by inline assembly code and need not be restored at the end of the code. 🎉
  • Register __zero_reg__ contains a value of zero. When that value is destroyed, for example by a MUL instruction, its value has to be restored at the end of the code by means of
clr __zero_reg__
  • In inline asm without operands (i.e without a single colon), a % will always insert a single %. No %-codes are available.
Sequences like __SREG__ are not evaluated as part of the inline asm, they are just copied to the asm code as they are.

At the top of each assembly file, the compiler prints definitions like

__SREG__ = 0x3f

so that they can also be used in inline assembly. 💖

✨ Constraints ✨

Okay bestie, if you want the most up-to-date and detailed tea on AVR constraints, it's all in the avr-gcc Wiki. No cap. 💅

Here's the whole vibe for registers and ranges:

  • a — Simple upper registers that support FMUL, R16 ... R23
  • b — Base pointer registers that support LDD, STD Y, Z (R28 ... R31)
  • d — Upper registers, R16 ... R31
  • e — Pointer registers that support LD, ST X, Y, Z (R26 ... R31)
  • l — Lower registers, R2 ... R15
  • r — Any register, R2 ... R31
  • w — Upper registers that support ADIW, R24 ... R31
  • x — X pointer registers, R26, R27
  • y — Y pointer registers, R28, R29
  • z — Z pointer registers, R30, R31

Now the constant constraints, periodt:

  • I — 6-bit unsigned integer constant, 0 to 63
  • J — 6-bit negative integer constant, 63 to 0
  • M — 8-bit unsigned integer constant, 0 to 255
  • n — Integer constant
  • i — Immediate value known at link-time, like the address of a variable in static storage
  • EF — Floating-point constant
  • Ynn — Fixed-point or integer constant

And the explanation constraints:

  • m — A memory location
  • X — Any valid operand
  • 0 ... 9 — Matches the respective operand number

Some rules, bestie:

  • Constraints without a modifier specify input operands.
  • Constraints with a modifier specify output operands.
  • More than one constraint like in "rn" specifies the union of the specified constraints; "r" and "n" in this case.
  • All constraints listed above are single-letter constraints, except Ynn which is a 3-letter constraint.

Constraint modifiers are:

  • = — Output-only operand. Without & it may overlap with input operands.
  • + — Output operand that's also an input.
  • =& — "Early-clobber". Register should be used for output only and won't overlap with any input operand(s).

Now, the selection of the proper constraint depends on the range of the constants or registers, which must be acceptable to the AVR instruction they are used with. The C compiler doesn't check any line of your assembler code. But it is able to check the constraint against your C expression. However, if you specify the wrong constraints, then the compiler may silently pass wrong code to the assembler. And, of course, the assembler will fail with some cryptic output or internal errors, or in the worst case wrong code may be the result. 💀

For example, if you specify the constraint "r" and you are using this register with an ORI instruction, then the compiler may select any register. This will fail if the compiler chooses R2 to R15. (It will never choose R0 or R1, because these are uses for special purposes.) That's why the correct constraint in that case is "d". On the other hand, if you use the constraint "M", the compiler will make sure that you don't pass anything else but an 8-bit unsigned integer value known at compile-time.

The following table shows all AVR assembler mnemonics which require operands, and the related constraints. Slay. 👑

  • adc — r,r
  • add — r,r
  • adiw — w,I
  • and — r,r
  • andi — d,M
  • asr — r
  • bclr — I
  • bld — r,I
  • brbc — I,label
  • brbs — I,label
  • bset — I
  • bst — r,I
  • call — i
  • cbi — I,I
  • cbr — d,I
  • clr — r
  • com — r
  • cp — r,r
  • cpc — r,r
  • cpi — d,M
  • cpse — r,r
  • dec — r
  • elpm — r,z
  • eor — r,r
  • fmul — a,a
  • fmuls — a,a
  • fmulsu — a,a
  • in — r,I
  • inc — r
  • jmp — i
  • lac — z,r
  • las — z,r
  • lat — z,r
  • ld — r,e
  • ldd — r,b
  • ldi — d,M
  • lds — r,i
  • lpm — r,z
  • lsl — r
  • lsr — r
  • mov — r,r
  • movw — r,r
  • mul — r,r
  • muls — r,r
  • mulsu — a,a
  • neg — r
  • or — r,r
  • ori — d,M
  • out — I,r
  • pop — r
  • push — r
  • rcall — i
  • rjmp — i
  • rol — r
  • ror — r
  • sbc — r,r
  • sbci — d,M
  • sbi — I,I
  • sbic — I,I
  • sbiw — w,I
  • sbr — d,M
  • sbrc — r,I
  • sbrs — r,I
  • ser — d
  • st — e,r
  • std — b,r
  • sts — i,r
  • sub — r,r
  • subi — d,M
  • swap — r
  • tst — r
  • xch — z,r

That's all. ✅

The %-operands in the inline assembly template can be adjusted by special print-modify characters. The one-letter modifier follows the % and precedes the operand number like in "%a0", or precedes the name in named operands like in "%a[address]".

  • %a0 — 1 argument. Print pointer register as address X, Y or Z, like in "LD r0, %a0+". Suitable constraints: x, y, z, b, e
  • %i0 — 1 argument. Print compile-time RAM address as I/O address, like in "OUT %i0, r0" with argument "n"(&SREG). Suitable constraints: n
  • %n0 — 1 argument. Print the negative of a compile-time integer constant. Suitable constraints: n
  • %r0 — 1 argument. Print the register number of a register, like in "CLR %r0+7" for the MSB of a 64-bit register. Suitable constraints: reg
  • %x0 — 1 argument. Print a function name without gs() modifier, like in "%~CALL %x0" with argument "s"(main). Suitable constraints: s
  • %A0 — 1 argument. Add 0 to the register number (no effect). Suitable constraints: reg
  • %B0 — 1 argument. Add 1 to the register number. Suitable constraints: reg
  • %C0 — 1 argument. Add 2 to the register number. Suitable constraints: reg
  • %D0 — 1 argument. Add 3 to the register number. Suitable constraints: reg
  • %T0%t1 — 2 arguments. Print the register that holds bit number %1 of register %0. Suitable constraints: reg + n
  • %T0%T1 — 2 arguments. Print operands suitable for BLD/BST, like in "BST %T0%T1", including the required ,. Suitable constraints: reg + n

Bestie, register constraints are: r, d, w, x, y, z, b, e, a, l. 💖

🌸 Operand Modifiers 🌸

  • lo8() — 1st Byte of a link-time constant, bits 0...7. Purpose: Getting parts of a byte-address.
  • hi8() — 2nd Byte of a link-time constant, bits 8...15.
  • hlo8() — 3rd Byte of a link-time constant, bits 16...23.
  • hhi8() — 4th Byte of a link-time constant, bits 24...31.
  • hh8() — Same like hlo8.
  • pm_lo8() — 1st Byte of a link-time constant divided by 2, bits 1...8. Purpose: Getting parts of a word-address.
  • pm_hi8() — 2nd Byte of a link-time constant divided by 2, bits 9...16.
  • pm_hh8() — 3rd Byte of a link-time constant divided by 2, bits 17...24.
  • pm() — Link-time constant divided by 2 in order to get a program memory (word) addresses, like in lo8(pm(main)). Purpose: Word-address.
  • gs() — Function address divided by 2 in order to get a (word) addresses, like in lo8(gs(main)). Generate stub (trampoline) as needed. This is required to calculate the address of a code label on devices with more than 128 KiB of program memory that's supposed to be used in EICALL. For rationale, see the GCC documentation. On devices with less program memory, gs() behaves like pm(). Purpose: Function address for [E]ICALL.

When the argument of a modifier is not computable at assembler-time, then the assembler has to encode the expression in an abstract form using RELOCs. Consequence is that only a very limited number of argument expressions is supported when they are not computable at assembler-time.

✨ Examples ✨

Some examples show the assembly code as generated by the compiler. It's the code from the .s files as generated with option -save-temps. Adding the high-level source to the generated assembly can be turned on with -fverbose-asm since GCC v8.

🦋 Swapping Nibbles 🦋

The first example uses the swap instruction to swap the nibbles of a byte. Input and output of swap are located in the same general purpose register. This means the input operand, operand 1 below, must be located in the same register(s) like operand 0, so that the right constraint for operand 1 is "0":

asm ("swap" : "=r" (value) : "0" (value));

All side effects of the code are described by the constraints and the clobbers, so that there is no need for this asm to be volatile. In particular, this asm may be optimized out when the output value is unused.

A shorter pattern to state that value is both input and output is by means of constraint modifier +

asm ("swap" : "+r" (value));

🦋 Swapping Bytes 🦋

Swapping nibbles was a piece of cake, so let's swap the bytes of a 16-bit value. In order to access the constituent bytes of the 16-bit input and output values, we use the print modifiers %A and %B.

The asm is placed in a small C test case so that we can inspect the resulting assembly code as generated by the compiler with -save-temps.

void callee (int, int);

void func (int param)
{
    int swapped;

    asm ("mov %A0, %B1" "\n\t"
         "mov %B0, %A1"
         : "=r" (swapped) : "r" (param));

    callee (param, swapped);
}

The "\n\t" sequence adds a line feed that is required between the two instructions, and a TAB to align the two instructions in the generated assembly. There is no "\n\t" after the last instruction because that would just increase the size of the asm.

The generated assembly works as expected. The compiler wraps it in #APP / #NOAPP annotations:

func:
/* #APP */
    mov r22, r25     ;  swapped, param
    mov r23, r24     ;  swapped, param
/* #NOAPP */
    jmp callee

Wrong! While the generated code above is correct, the inline asm itself is not!

We see this with a slightly adjusted test case where the arguments of callee have been swapped, but that uses the same inline asm:

void func (int param)
{
    int swapped;

    asm ("mov %A0, %B1" "\n\t"
         "mov %B0, %A1"
         : "=r" (swapped) : "r" (param));

    callee (swapped, param);
}

The result is the following assembly:

func:
    movw r22,r24
/* #APP */
    mov r24, r25     ;  swapped, param
    mov r25, r24     ;  swapped, param
/* #NOAPP */
    jmp callee

which is obviously wrong, because after the code from the inline asm, the low byte of swapped and the high byte will always have the same value of r25.

The reason is that the output operand overlaps the input, and the output is changed before all of the input operands are consumed. This is a so-called early-clobber situation. There are two possible solutions to this predicament:

  • Mark the output operand with the early-clobber constraint modifier:
asm ("mov %A0, %B1" "\n\t"
     "mov %B0, %A1"
     : "=&r" (swapped) : "r" (param));
  • Use constraints and a code sequence that expect input and output in the same registers:
asm ("eor %A0, %B0" "\n\t"
     "eor %B0, %A0" "\n\t"
     "eor %A0, %B0"
     : "=r" (swapped) : "0" (param));

🦋 Accessing Memory 🦋

Accessing memory requires that the AVR instructions that perform the memory access are provided with the appropriate memory address.

  1. The address can be provided directly, like __SREG__, 0x3f, as a symbol, or as a symbol plus a constant offset.
  2. Provide the address by means of an inline asm operand.

Approach 1 is simpler as it does not require an asm operand, while approach 2 is in many cases more powerful because macros defined per, say, #include <avr/io.h> can be used as operands, whereas such headers are not included in the assembly code as generated by the compiler.

Reading a SFR like PORTB can be performed by

asm volatile ("in %0, %1" : "=r" (result) : "I" _SFR_IO_ADDR (PORTB));

Macro _SFR_IO_ADDR is provided by avr/sfr_defs.h which is included by avr/io.h.

Since GCC v4.7, print modifier %i is supported, which prints RAM addresses like & PORTB as an I/O address:

asm volatile ("in %0, %i1" : "=r" (result) : "I" (& PORTB));

When the address is not an I/O address, then LDS or LD must be used, depending on whether the address is known at link-time or only at run-time. For example, the following macro provides the functionality to clear an SFR. The code discriminates between the possibilities that

  • The SFR address is known at compile-time and is an I/O address.
  • The SFR address is known at compile-time but is not in the I/O range.
  • The SFR address is not known at compile-time. 😩 the chaotic one. No compile-time tea to spill, so the macro falls all the way through to the "e" option:
#include <avr/io.h>

#define CLEAR_REG(sfr)                          \
do {                                            \
  if (__builtin_constant_p (& (sfr))            \
      && _SFR_IO_REG_P (sfr))                   \
    asm volatile ("out %i0, __zero_reg__"       \
                  :: "I" (& (sfr)) : "memory"); \
  else if (__builtin_constant_p (& (sfr)))      \
    asm volatile ("sts %0, __zero_reg__"        \
                  :: "n" (& (sfr)) : "memory"); \
  else                                          \
    asm volatile ("st %a0, __zero_reg__"        \
                  :: "e" (& (sfr)) : "memory"); \
} while (0)

Okay bestie, why does that last case with constraint "e" even work? ✨ It's lowkey genius: &sfr is a 16-bit value, and 16-bit values (and anything bigger, fr fr) start in even registers. So the address is gonna live in R27:R26, R29:R28 or R31:R30 — and the print modifier %a prints those as X, Y or Z, respectively. It will never end up in, like, R30:R29. Not the vibe. 💅

The test case:

void clear_3_regs (uint8_t volatile *psfr)
{
    CLEAR_REG (PORTB);
    CLEAR_REG (UDR0);
    CLEAR_REG (*psfr);
}

compiles for ATmega328 and with optimization turned on to:

clear_3_regs:
    movw r30,r24
/* #APP */
    out 0x5, __zero_reg__
    sts 198, __zero_reg__
    st Z,    __zero_reg__   ;  psfr
/* #NOAPP */
    ret

Look at that. She ate. 👑 Three different addressing modes, zero wasted effort.

Because __builtin_constant_p is what we're using to figure out whether the SFR's address is known at compile-time, you have to take extra care when you implement the functionality as an inline function instead:

static inline __attribute__((__always_inline__))
void clear_reg (uint8_t volatile *psfr)
{
  // !!! The following cast is required to make __builtin_constant_p
  // !!! work as expected in the inline function.
  uintptr_t addr = (uintptr_t) psfr;

  if (__builtin_constant_p (addr)
      && _SFR_IO_REG_P (* psfr))
    asm volatile ("out %i0, __zero_reg__"
                  :: "I" (addr) : "memory");
  else if (__builtin_constant_p (addr))
    asm volatile ("sts %0, __zero_reg__"
                  :: "n" (addr) : "memory");
  else
    asm volatile ("st %a0, __zero_reg__"
                  :: "e" (addr) : "memory");
}

void clear_3_pregs (uint8_t volatile *psfr)
{
  clear_reg (& PORTB);
  clear_reg (& UDR0);
  clear_reg (psfr);
}

So yeah — casting the address psfr to an integer type inside the inline function is required so the compiler will recognize constant addresses. No cast, no constants, no slay. 🙈

Also notice: we have to pass the address of the SFR to the inline function. Passing the SFR directly, like the marco approach does, won't work — for obvious reasons. 🫶

🌈 Accessing Bytes of wider Expressions 🌈

Finally (finally!!), an example that atomically increments a 16-bit integer. The whole thing is wrapped in IN SREG / CLI / OUT SREG to make it atomic. It reads the 16-bit value data from its absolute address, increments it, and then writes it back:

uint16_t volatile data;

void inc_data (void)
{
    uint16_t tmp;
    asm volatile ("in __tmp_reg__, __SREG__"   "\n\t"
                  "cli"                        "\n\t"
                  "lds %A[temp], %[addr]"      "\n\t"
                  "lds %B[temp], %[addr]+1"    "\n\t"
#ifdef __AVR_TINY__
                  // Reduced Tiny does not have ADIW.
                  "subi %A[temp], lo8(-1)"     "\n\t"
                  "sbci %B[temp], hi8(-1)"     "\n\t"
#else
                  "adiw %[temp], 1"            "\n\t"
#endif
                  "sts %[addr]+1, %B[temp]"    "\n\t"
                  "sts %[addr],   %A[temp]"    "\n\t"
                  "out __SREG__, __tmp_reg__"
#ifdef __AVR_TINY__
                  // No need to restrict tmp to a "w" register. And on
                  // avr-gcc v13.2 and older, "w" contains no regs.
                  : [temp] "=d" (tmp), "+m" (data)
#else
                  : [temp] "=w" (tmp), "+m" (data)
#endif
                  : [addr] "i" (& data));
}

Notice (and this is the ✨iconic✨ part) there are three different ways required to access the different bytes of the 16-bit entities involved:

  • For the 16-bit general purpose register %[temp], the print modifiers %A and %B are used. 🎀
  • For the 16-bit value data in static storage, %[addr]+1 is used to access the high byte. The resulting expression data+1 is computable at link-time and evaluated by the linker. 🦋
  • In the compilation variant for Reduced Tiny, the bytes of the 16-bit subtrahend 1 are accessed with the operand modifiers lo8 and hi8, which are evaluated by the assembler — because 1 is known at assembler-time. 💜

data is located in static storage, hence its address is known to the linker and fits constraint "i". 🫡

The sole purpose of the operand "+m" (data) is to describe the effect of the asm on data memory: it changes data. Notice there is no "memory" clobber, because that operand already describes all memory side effects — and it does it in a less intrusive way than a catch-all "memory". The operand is never used in the asm template; but in principle it would be possible to use it as an operand with LDS and STS instead of the operand [addr] "i" (& data). However, there are many situations where a memory operand constrained by "m" takes a form that cannot be used with AVR instructions — either because there are no matching print modifiers, or because it isn't known a priori what specific form the memory operand takes. In those cases you'd take the address of the operand and supply it as the address in a pointer register to the inline asm. The compiler generates the required instructions for the address computation, and the inline asm knows it can use LD and ST. 😌

💀 Jumping and Branching 💀

When an inline asm contains jumps, it also requires labels. And when the label is inside the asm, you gotta be careful that the label is unique in the compilation unit — even when the inline asm is used multiple times. Like when the code sits in an unrolled loop, or a function has multiple incarnations due to cloning, or simply because a macro or inline function containing an asm statement gets used more than once. 😭

There are two kinds of labels you can use:

  • Local labels of the form n: where n is some (small, non-negative) number. They can be targeted by means of nb or nf, depending on whether the jump direction is backwards or forwards. Such numeric labels may be present more than once. The taken label is the first one with the specified number in the respective direction:
// Loop until bit PORTB.7 is set.
asm volatile ("1: sbrs %i[sfr], %[bitno]"  "\n\t"
              "rjmp 1b"
              :: [sfr] "I" (& PORTB), [bitno] "n" (PB7));
  • Local labels that contain the sequence %=, which yields some number that's unique amongst all asm incarnations in the respective compilation unit:
// Loop until bit PORTB.7 is set.
asm volatile (".Loop.%=: sbrs %i[sfr], %[bitno]"  "\n\t"
              "rjmp .Loop.%="
              :: [sfr] "I" (& PORTB), [bitno] "n" (PB7));

Which form you use is a matter of taste, bestie. 🍓 In practice, the first variant is often preferred in short sequences, whereas the second form is usually seen in longer algorithms. Pick your fighter. 💅

For labels that are defined in the surrounding C/C++ code, asm goto has to be used. The print modifier %x0 prints panic as a raw label — not as gs(panic) like it would be the case with %0. 👀

int main (void)
{
    asm goto ("tst __zero_reg__" "\n\t"
              "brne %x0"
              :::: panic);
    /* ...Application code here... */
    return 0;
panic:
    // __zero_reg__ is supposed to contain 0, but doesn't.
    return 1;
}
⚠️ This assumes that the jump offset can be encoded in the brne instruction in all situations. When static analysis cannot prove that the jump offset fits, then a jumpity jump has to be used:
asm goto ("tst   __zero_reg__" "\n\t"
          "breq  1f"           "\n\t"
          "%~jmp %x0"          "\n"
          "1: ;; all fine"
          :::: panic);

Sequence "%~jmp" yields rjmp or jmp depending on the architecture. 🧚 And notice that a jmp can be relaxed to an rjmp with option -mrelax, provided the jump offset fits. Slay. 🔥

💖 Binding local Variables to Registers 💖

okay so one of the iconic uses of GCC's asm keyword is binding local register variables to actual hardware registers. bestie, it's giving "I choose you, specific register."

heads up tho: these bindings of local variables to registers are only guaranteed during inline asm which has these variables as operands. That's the whole deal. No operands, no promises. 🙈

🦋 Interfacing non-ABI Functions 🦋

ok so picture this: we wanna interface a non-ABI assembly function mul_8_16 that multiplies R24 with R27:R26, clobbers R0, R1 and R25, and returns the 24-bit result in R20:R19:R18. ✨

One way to do it would be to write an assembly function that does the required copying and calls mul_8_16. But bestie… that would destroy some of the performance gain obtained by using assembly for mul_8_16: additional copying back and forth, plus extra CALL and RET instructions. 💀 not the vibes.

The compiler comes to the rescue!! 🫶 We can bind local variables to the required registers:

extern void mul_8_16 (void); // Non-ABI function. Don't call in C/C++!

static inline __attribute__((__always_inline__))
__uint24 mul_8_16_gccabi (uint8_t val8, uint16_t val16)
{
    register uint8_t r24 __asm("r24") = val8;
    register __uint24 r18 __asm("r18");

    asm ("%~call %x[func]"  "\n\t"
         "clr    __zero_reg__"
         : "=r" (r18)
         : "r" (r24), "x" (val16), [func] "i" (mul_8_16)
         : "r25", "r0");

    return r18;
}
  • The 8-bit parameter is bound to R24, and the 24-bit return value is bound to R18...R20. 💅
  • The register keyword is mandatory. no skipping it, bestie.
  • The hard register is specified as a string literal for the lower case register name or register number, like "18" or "r18". Specifications like "R18", 18 or "Z" are not supported. 🙅‍♀️
  • The 16-bit parameter of mul_8_16 happens to be required in R27:R26, which is the X register for which there is register constraint "x". Therefore, no register binding is required for val16. slay, the constraint did the work.
  • As mul_8_16 clobbers the zero register R1, it has to be restored by means of
clr __zero_reg__
  • The asm is pure arithmetic and hence not volatile. (It might be advisable to make it volatile anyway, so that it won't be reordered across sei() or cli() instructions.) 👀

Let's have a look at how this performs in a test case:

void use_mul_8_16_gccabi (uint8_t val, uint8_t a, uint8_t b)
{
    if (mul_8_16_gccabi (val, a * b) >= 0x2010)
        __builtin_abort();
}

For ATmega8 we get the following assembly:

use_mul_8_16_gccabi:
    mul  r22,r20
    movw r26,r0
    clr  __zero_reg__
/* #APP */
    rcall mul_8_16
    clr   __zero_reg__
/* #NOAPP */
    cpi  r18,16
    sbci r19,32
    cpc  r20,__zero_reg__
    brlo .L1
    rcall abort
.L1:
    ret

No superfluous register moves. Great! 🔥 literally ate.

🌸 Specifying the Assembly Name of Static Objects 🌸

Sometimes, it is desirable to use a different name for an object or function rather than the (mangled) name from the C/C++ implementation. Just add an asm specifier with the desired name as a string literal at the end of the declaration. that's it, that's the trick. 🎀

For example, this is how avr/eeprom.h implements the eeprom_read_double() function:

#if __SIZEOF_DOUBLE__ == 4
double eeprom_read_double (const double*) __asm("eeprom_read_dword");
#elif __SIZEOF_DOUBLE__ == 8
double eeprom_read_double (const double*) __asm("eeprom_read_qword");
#endif
  • It uses the implementation of eeprom_read_dword for eeprom_read_double, provided double is a 32-bit type. 💖
  • It uses the implementation of eeprom_read_qword for 64-bit doubles. 💜

💀 What won't work 💀

GCC inline asm has some limitations. not everything is giving main character energy, some stuff is just a no. 😭

💔 Setting a Register on one asm and using it in a different one 💔

Sequences like the following are not supposed to work:

char var;

void set_var (char c)
{
    __asm ("inc r24");
    __asm ("sts var, r24");
}
  • There is no guarantee whatsoever that the value in R24 will survive from one asm to the next. Such code might work in many situations, but it is still wrong and the compiler may very well put instructions between the asm statements that change R24 prior to the first asm and also between the asm statements. 🫠
  • R24 is changed without noticing the compiler. When R24 contains other data, then that data will be trashed. 💀 trash. gone.

A correct code would be

__asm ("inc %0"    "\n\t"
       "sts var, %0"
       :: "r" (c) : "memory");

or

__asm ("inc %1"    "\n\t"
       "sts %0, %1"
       : "=m" (var) : "r" (c));

🚧 Letting an Operand cross the Boundaries of the Y Register 🚧

It is not possible to bind a value to a local register variable that crosses the boundaries of the Y register. For example, trying to bind a 32-bit value to R31:R28 by means of

register uint32_t r28 __asm ("28");

will result in an error message like

error: register specified for 'r28' isn't suitable for data type

Similarly, an operand described by a constraint will be located either completely below the Y register, as part of Y register, or above it. no straddling allowed, bestie. 💅

🙈 Using Matching Constraints =0"..."=9" with Output Operands" 🙈

Suppose we want an inline asm that returns the low byte of a 16-bit value val16:

asm ("" : "=1" (lo8) : "r" (val16));

The diagnostic will be:

error: matching constraint not valid in output operand

and that's the whole page, bestie!! 🎉 you made it to the end, so proud of you fr fr. 🫶 this was inline_asm(3avr) from AVR-LibC, Version 2.2.1 — go forth and write your inline asm with confidence, periodt. 👑✨

📦 where this page comes from