avr_boot(3)

📦 version 2.2.1, in fedora 43, fedora 44, opensuse-leap 16.0

avr_boot 💖 (NAME)

okay bestie, welcome to avr_boot — the avr-libc era where you get to poke the bootloader of certain AVR chips straight from C. she's giving ✨low-level✨, she's giving memory-mapped, and she is so much fun once you know what you're doing.

SYNOPSIS 🌈

Macros

#define BOOTLOADER_SECTION   __attribute__ ((section ('.bootloader')))
#define boot_spm_interrupt_enable()   (__SPM_REG |= (uint8_t)_BV(SPMIE))
#define boot_spm_interrupt_disable()   (__SPM_REG &=
    (uint8_t)~_BV(SPMIE))
#define boot_is_spm_interrupt()   (__SPM_REG & (uint8_t)_BV(SPMIE))
#define boot_rww_busy()   (__SPM_REG & (uint8_t)_BV(__COMMON_ASB))
#define boot_spm_busy()   (__SPM_REG & (uint8_t)_BV(__SPM_ENABLE))
#define boot_spm_busy_wait()   do{}while(boot_spm_busy())
#define GET_LOW_FUSE_BITS   (0x0000)
#define GET_LOCK_BITS   (0x0001)
#define GET_EXTENDED_FUSE_BITS   (0x0002)
#define GET_HIGH_FUSE_BITS   (0x0003)
#define boot_lock_fuse_bits_get(address)
#define boot_signature_byte_get(addr)
#define boot_page_fill(address,  data)
    __boot_page_fill_normal(address, data)
#define boot_page_erase(address)   __boot_page_erase_normal(address)
#define boot_page_write(address)   __boot_page_write_normal(address)
#define boot_rww_enable()   __boot_rww_enable()
#define boot_lock_bits_set(lock_bits)   __boot_lock_bits_set(lock_bits)
#define boot_page_fill_safe(address,  data)
#define boot_page_erase_safe(address)
#define boot_page_write_safe(address)
#define boot_rww_enable_safe()
#define boot_lock_bits_set_safe(lock_bits)

Detailed Description 🦋

okay so first things first, you're gonna want these:

#include <avr/io.h>
#include <avr/boot.h>

The macros in this module are literally your C-language bestie for the bootloader support functionality on certain AVR processors, and the way they're built means they work with all sizes of flash memory — no gatekeeping, everyone eats 💅.

Now, the important part: global interrupts are NOT automatically disabled for these macros. That is a you problem, bestie, not a them problem. It's left up to the programmer to handle it, and you can peep the code example below for how. Also go read your processor datasheet for the caveats about having global interrupts enabled while writing the Flash. fr fr, read the datasheet.

Note: not every AVR processor even ships with bootloader support. Check your processor datasheet to see if it provides bootloader support before you get your hopes up 😭

Todo: straight from an email with Marek: on smaller devices (all except ATmega64/128), __SPM_REG lives in the I/O space, so it's accessible with the shorter 'in' and 'out' instructions. Since the boot loader has a limited size, this could be a pretty major optimization. some future-era glow-up pending ✨

API Usage Example 🎀

here's the typical usage of the boot API, in all her glory:

#include <inttypes.h>
#include <avr/interrupt.h>
#include <avr/pgmspace.h>

void boot_program_page (uint32_t page, uint8_t *buf)
{
    uint16_t i;
    uint8_t sreg;

    // Disable interrupts.

    sreg = SREG;
    cli();

    eeprom_busy_wait ();

    boot_page_erase (page);
    boot_spm_busy_wait ();      // Wait until the memory is erased.

    for (i=0; i<SPM_PAGESIZE; i+=2)
    {
        // Set up little-endian word.

        uint16_t w = *buf++;
        w += (*buf++) << 8;

        boot_page_fill (page + i, w);
    }

    boot_page_write (page);     // Store buffer in flash page.
    boot_spm_busy_wait();       // Wait until the memory is written.

    // Reenable RWW-section again. We need this if we want to jump back
    // to the application after bootloading.

    boot_rww_enable ();

    // Re-enable interrupts (if they were ever enabled).

    SREG = sreg;
}

Macro Definition Documentation 💜

`#define boot_is_spm_interrupt() (__SPM_REG & (uint8_t)_BV(SPMIE))`

Checks if the SPM interrupt is enabled. little vibe check on the interrupt status, yk?

`#define boot_lock_bits_set(lock_bits) __boot_lock_bits_set(lock_bits)`

Sets the bootloader lock bits. 🔒

Parameters:

lock_bits — a mask of which Boot Loader Lock Bits to set.

Note: in this context, a 'set bit' will be written to a zero value. Also note that only BLBxx bits can be programmed by this command.

so for example, if you wanted to disallow the SPM instruction from writing to the Boot Loader memory section of flash, you'd use this macro like:

boot_lock_bits_set (_BV (BLB11));

Note: like any lock bits, the Boot Loader Lock Bits, once set, cannot be cleared again except by a chip erase — which will in turn also erase the boot loader itself. so yeah. think before you commit, bestie 😭

`#define boot_lock_bits_set_safe(lock_bits)`

Value:

do {     boot_spm_busy_wait();                           eeprom_busy_wait();                             boot_lock_bits_set (lock_bits);             } while (0)

Same as boot_lock_bits_set() except it waits for eeprom and spm operations to complete before setting the lock bits. she's patient. she waits her turn 🫶

`#define boot_lock_fuse_bits_get(address)`

Value:

(__extension__({                                               uint8_t __result;                                          __asm__ __volatile__                                       (                                                              "sts %1, %2"                                           "lpm %0, Z"                                            : "=r" (__result)                                          : "i" (_SFR_MEM_ADDR(__SPM_REG)),                            "r" ((uint8_t)(__BOOT_LOCK_BITS_SET)),                     "z" ((uint16_t)(address))                            );                                                         __result;                                              }))

Reads the lock or fuse bits at address.

Parameter address can be any of GET_LOW_FUSE_BITS, GET_LOCK_BITS, GET_EXTENDED_FUSE_BITS, or GET_HIGH_FUSE_BITS.

Note: the lock and fuse bits returned are the physical values, i.e. a bit returned as 0 means the corresponding fuse or lock bit is programmed. backwards from what your brain wants, ik ik.

`#define boot_page_erase(address) __boot_page_erase_normal(address)`

Erases the flash page that contains address. poof, gone 💨

Note: address is a byte address in flash, not a word address.

`#define boot_page_erase_safe(address)`

Value:

do {     boot_spm_busy_wait();                           eeprom_busy_wait();                             boot_page_erase (address);                  } while (0)

Same as boot_page_erase() except it waits for eeprom and spm operations to complete before erasing the page. so polite.

`#define boot_page_fill(address, data) __boot_page_fill_normal(address, data)`

Fills the bootloader temporary page buffer for flash address with data word.

Note: the address is a byte address. The data is a word. The AVR writes data to the buffer a word at a time, but addresses the buffer per byte! So, increment your address by 2 between calls, and send 2 data bytes in a word format! The LSB of the data is written to the lower address; the MSB of the data is written to the higher address. little-endian girlies rise 🙈

`#define boot_page_fill_safe(address, data)`

Value:

do {     boot_spm_busy_wait();                           eeprom_busy_wait();                             boot_page_fill(address, data);              } while (0)

Same as boot_page_fill() except it waits for eeprom and spm operations to complete before filling the page.

`#define boot_page_write(address) __boot_page_write_normal(address)`

Writes the bootloader temporary page buffer to the flash page that contains address. this is the moment where the buffer becomes real, main character energy 👑

Note: address is a byte address in flash, not a word address.

`#define boot_page_write_safe(address)`

Value:

do {     boot_spm_busy_wait();                           eeprom_busy_wait();                             boot_page_write (address);                  } while (0)

Same as boot_page_write() except it waits for eeprom and spm operations to complete before writing the page.

`#define boot_rww_busy() (__SPM_REG & (uint8_t)_BV(__COMMON_ASB))`

Checks if the RWW section is busy. busy busy busy 💀

`#define boot_rww_enable() __boot_rww_enable()`

Enables the Read-While-Write memory section.

`#define boot_rww_enable_safe()`

Value:

do {     boot_spm_busy_wait();                           eeprom_busy_wait();                             boot_rww_enable();                          } while (0)

Same as boot_rww_enable() except waits for eeprom and spm operations to complete before enabling the RWW mameory. (yes, the typo "mameory" is canon, I don't make the rules 🍓)

`#define boot_signature_byte_get(addr)`

Value:

(__extension__({                            uint8_t __result;                               __asm__ __volatile__                            (                                                 "sts %1, %2"                                "lpm %0, Z" ""                              : "=r" (__result)                               : "i" (_SFR_MEM_ADDR(__SPM_REG)),                 "r" ((uint8_t)(__BOOT_SIGROW_READ)),            "z" ((uint16_t)(addr))                      );                                              __result;                                 }))

Reads the Signature Row byte at address. For some MCU types, this function can also retrieve the factory-stored oscillator calibration bytes. factory secrets, unlocked ✨

Parameter address can be 0-0x1f as documented by the datasheet.

Note: the values are MCU type dependent.

`#define boot_spm_busy() (__SPM_REG & (uint8_t)_BV(__SPM_ENABLE))`

Checks if the SPM instruction is busy.

`#define boot_spm_busy_wait() do{}while(boot_spm_busy())`

Waits while the SPM instruction is busy. she'll just sit there. patiently. forever if she has to 🧚

`#define boot_spm_interrupt_disable() (__SPM_REG &= (uint8_t)~_BV(SPMIE))`

Disables the SPM interrupt.

`#define boot_spm_interrupt_enable() (__SPM_REG |= (uint8_t)_BV(SPMIE))`

Enables the SPM interrupt.

`#define BOOTLOADER_SECTION attribute ((section ('.bootloader')))`

Used to declare a function or variable to be placed into a new section called .bootloader. This section and its contents can then be relocated to any address (such as the bootloader NRWW area) at link-time. it's giving ✨movable✨

`#define GET_EXTENDED_FUSE_BITS (0x0002)`

address to read the extended fuse bits, using boot_lock_fuse_bits_get.

`#define GET_HIGH_FUSE_BITS (0x0003)`

address to read the high fuse bits, using boot_lock_fuse_bits_get.

`#define GET_LOCK_BITS (0x0001)`

address to read the lock bits, using boot_lock_fuse_bits_get.

`#define GET_LOW_FUSE_BITS (0x0000)`

address to read the low fuse bits, using boot_lock_fuse_bits_get.

Author 🌟

Generated automatically by Doxygen for avr-libc from the source code. (so technically Doxygen wrote this, I just gave it a makeover 💅)

and that's the whole page, bestie!! 🫶 this is Version 2.1.0, dated Sat Jan 29 2022, from your friends over in avr-libc land — go forth and bootload responsibly, no cap 🎀💖

📦 where this page comes from

fedora 43: avr-libc 2.2.1-3.fc43 · BSD-3-Clause
fedora 44: avr-libc 2.2.1-5.fc44 · BSD-3-Clause
opensuse-leap 16.0: avr-libc 2.1.0-bp160.1.33 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms