avr_boot(3avr)

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

🎀 avr_boot 🎀

okay bestie, gather round, because we're talking about avr_boot — that's the <avr/boot.h> Bootloader Support Utilities, from the avr_boot(3avr) manual page, and she is iconic. this is the glow-up guide to making your AVR chip write to its own flash like a little self-sufficient main character. 💅

✨ NAME ✨

avr_boot — <avr/boot.h>: Bootloader Support Utilities. that's it, that's the name, she's simple and she knows it. 🦋

✨ SYNOPSIS ✨

Macros 🌸

this is the whole friend group, no cap:

#define BOOTLOADER_SECTION   __attribute__
    ((__section__('.bootloader')))
#define boot_spm_interrupt_enable()
#define boot_spm_interrupt_disable()
#define boot_is_spm_interrupt()
#define boot_rww_busy()
#define boot_spm_busy()
#define boot_spm_busy_wait()
#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)
#define boot_page_erase(address)
#define boot_page_write(address)
#define boot_rww_enable()
#define 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 💜

so when you pull her in:

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

the macros in this module give you a C language interface to the bootloader support functionality of certain AVR processors. and the way they're written? they're designed to work with all sizes of flash memory. versatile queen. 👑

Global interrupts are not automatically disabled for these macros. like, not even a little. it is left up to the programmer to do that — and yes, that means you, bestie. see the code example below. also go read your processor datasheet for caveats on having global interrupts enabled during writing of the Flash. fr fr, the datasheet is not a suggestion. 📖

Note 🫶 — Not all AVR processors provide bootloader support. check your processor datasheet to see if it even provides bootloader support. some of y'all's chips simply do not have the range. 💀

API Usage Example ✨

the following code shows typical usage of the boot API. this is, like, the canonical vibes:

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

void boot_program_page (uint32_t page, uint8_t *buf)
{
    // Disable interrupts.
    uint8_t sreg = SREG;
    cli();

    eeprom_busy_wait ();

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

    for (uint16_t 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()

Value:

(__SPM_REG & (uint8_t)_BV(SPMIE))

Check if the SPM interrupt is enabled. that's the whole job. she's nosy, she wants to know. 🙈

#define boot_lock_bits_set( lock_bits)

Value:

__boot_lock_bits_set(lock_bits)

Set 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. (yes, backwards, we know, it's giving "the call is coming from inside the house".) Note also that only BLBxx bits can be programmed by this command.

for example, to disallow the SPM instruction from writing to the Boot Loader memory section of flash, you would use this macro as such:

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 like, be so serious when you do this. this is not a casual decision. this is a commitment. no take-backs, periodt.

#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 waits for eeprom and spm operations to complete before setting the lock bits. she's the patient version. she waits her turn. angel behavior. 🧚

#define boot_lock_fuse_bits_get( address)

Value:

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

Read 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. pick your fighter. 🎀

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. yes, zero means programmed. we don't make the rules.

#define boot_page_erase( address)

Value:

__boot_page_erase_normal(address)

Erase the flash page that contains address. goodbye page, you were real. 👋

Note 📍 — address is a byte address in flash, not a word address. say it with me: byte address. not word address. this trips people up every single time.

#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. so considerate. 💖

#define boot_page_fill( address, data)

Value:

__boot_page_fill_normal(address, data)

Fill 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. it's giving little-endian, it's giving chaos, but it is the rules and we respect her. 💅

#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. the safe version always eats. 🫶

#define boot_page_write( address)

Value:

__boot_page_write_normal(address)

Write the bootloader temporary page buffer to flash page that contains address. that's the moment where the buffer finally gets to shine. ✨

Note 📍 — address is a byte address in flash, not a word address. (again!! byte address!!! not word address!!! i will keep saying it!!)

#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. slow and steady, absolutely slaying.

#define boot_rww_busy()

Value:

(__SPM_REG & (uint8_t)_BV(__COMMON_ASB))

Check if the RWW section is busy. she's checking if she's booked and busy. 🔥

#define boot_rww_enable()

Value:

__boot_rww_enable()

Enable the Read-While-Write memory section. reading AND writing at the same time? multitasking queen. 👑

#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, "mameory". that's what the original says and i am not correcting her, she's perfect.) 🌈

#define boot_signature_byte_get( addr)

Value:

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

Read the Signature Row byte at address. For some MCU types, this function can also retrieve the factory-stored oscillator calibration bytes. oh she knows secrets. 🔍

Parameter address can be 0-0x1f as documented by the datasheet. that range is very specific bestie, respect it.

Note 🦋 — The values are MCU type dependent. different chip, different lore.

#define boot_spm_busy()

Value:

(__SPM_REG & (uint8_t)_BV(__SPM_ENABLE))

Check if the SPM instruction is busy. is she working right now? yes or no. binary. 💀

#define boot_spm_busy_wait()

Value:

do{}while(boot_spm_busy())

Wait while the SPM instruction is busy. just sit there. patiently. until she's done. this is your whole personality now.

#define boot_spm_interrupt_disable()

Value:

(__SPM_REG &= (uint8_t)~_BV(SPMIE))

Disable the SPM interrupt. not right now, we're busy. 🙅

#define boot_spm_interrupt_enable()

Value:

(__SPM_REG |= (uint8_t)_BV(SPMIE))

Enable the SPM interrupt. okay we're listening now bestie, go off. 💅

#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. a whole section, custom-made, just for her. main character energy fr. ✨

#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. like, the robots wrote this one. and honestly? they ate. 💅

and that's the whole page, bestie!! 🫶 this was avr_boot(3avr), AVR-LibC Version 2.2.1, and you better believe every single one of these macros was documented to the last byte. ty for coming to my ted talk, go disable your global interrupts manually, and ily. 🎀✨🦋

📦 where this page comes from