.TH "avr_boot" 3avr "Fri Jan 1 2021" "Version 2.0.0" "avr-libc" \" -*- nroff -*-
.ad l
.nh
.SH NAME
avr_boot \- <avr/boot\&.h>: Bootloader Support Utilities
.SH SYNOPSIS
.br
.PP
.SS "Macros"

.in +1c
.ti -1c
.RI "#define \fBBOOTLOADER_SECTION\fP   \fB__attribute__\fP ((section ('\&.bootloader')))"
.br
.ti -1c
.RI "#define \fBboot_spm_interrupt_enable\fP()   (__SPM_REG |= (\fBuint8_t\fP)\fB_BV\fP(SPMIE))"
.br
.ti -1c
.RI "#define \fBboot_spm_interrupt_disable\fP()   (__SPM_REG &= (\fBuint8_t\fP)~\fB_BV\fP(SPMIE))"
.br
.ti -1c
.RI "#define \fBboot_is_spm_interrupt\fP()   (__SPM_REG & (\fBuint8_t\fP)\fB_BV\fP(SPMIE))"
.br
.ti -1c
.RI "#define \fBboot_rww_busy\fP()   (__SPM_REG & (\fBuint8_t\fP)\fB_BV\fP(__COMMON_ASB))"
.br
.ti -1c
.RI "#define \fBboot_spm_busy\fP()   (__SPM_REG & (\fBuint8_t\fP)\fB_BV\fP(__SPM_ENABLE))"
.br
.ti -1c
.RI "#define \fBboot_spm_busy_wait\fP()   do{}while(\fBboot_spm_busy\fP())"
.br
.ti -1c
.RI "#define \fBGET_LOW_FUSE_BITS\fP   (0x0000)"
.br
.ti -1c
.RI "#define \fBGET_LOCK_BITS\fP   (0x0001)"
.br
.ti -1c
.RI "#define \fBGET_EXTENDED_FUSE_BITS\fP   (0x0002)"
.br
.ti -1c
.RI "#define \fBGET_HIGH_FUSE_BITS\fP   (0x0003)"
.br
.ti -1c
.RI "#define \fBboot_lock_fuse_bits_get\fP(address)"
.br
.ti -1c
.RI "#define \fBboot_signature_byte_get\fP(addr)"
.br
.ti -1c
.RI "#define \fBboot_page_fill\fP(address,  data)   __boot_page_fill_normal(address, data)"
.br
.ti -1c
.RI "#define \fBboot_page_erase\fP(address)   __boot_page_erase_normal(address)"
.br
.ti -1c
.RI "#define \fBboot_page_write\fP(address)   __boot_page_write_normal(address)"
.br
.ti -1c
.RI "#define \fBboot_rww_enable\fP()   __boot_rww_enable()"
.br
.ti -1c
.RI "#define \fBboot_lock_bits_set\fP(lock_bits)   __boot_lock_bits_set(lock_bits)"
.br
.ti -1c
.RI "#define \fBboot_page_fill_safe\fP(address,  data)"
.br
.ti -1c
.RI "#define \fBboot_page_erase_safe\fP(address)"
.br
.ti -1c
.RI "#define \fBboot_page_write_safe\fP(address)"
.br
.ti -1c
.RI "#define \fBboot_rww_enable_safe\fP()"
.br
.ti -1c
.RI "#define \fBboot_lock_bits_set_safe\fP(lock_bits)"
.br
.in -1c
.SH "Detailed Description"
.PP 

.PP
.nf
#include <avr/io\&.h>
#include <avr/boot\&.h>

.fi
.PP
.PP
The macros in this module provide a C language interface to the bootloader support functionality of certain AVR processors\&. These macros are designed to work with all sizes of flash memory\&.
.PP
Global interrupts are not automatically disabled for these macros\&. It is left up to the programmer to do this\&. See the code example below\&. Also see the processor datasheet for caveats on having global interrupts enabled during writing of the Flash\&.
.PP
\fBNote\fP
.RS 4
Not all AVR processors provide bootloader support\&. See your processor datasheet to see if it provides bootloader support\&.
.RE
.PP
\fBTodo\fP
.RS 4
From email with Marek: On smaller devices (all except ATmega64/128), __SPM_REG is in the I/O space, accessible with the shorter 'in' and 'out' instructions - since the boot loader has a limited size, this could be an important optimization\&.
.RE
.PP
.PP
\fBAPI Usage Example\fP
.RS 4
The following code shows typical usage of the boot API\&.
.RE
.PP
.PP
.nf
#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;
}
.fi
.PP
 
.SH "Macro Definition Documentation"
.PP 
.SS "#define boot_is_spm_interrupt()   (__SPM_REG & (\fBuint8_t\fP)\fB_BV\fP(SPMIE))"
Check if the SPM interrupt is enabled\&. 
.SS "#define boot_lock_bits_set(lock_bits)   __boot_lock_bits_set(lock_bits)"
Set the bootloader lock bits\&.
.PP
\fBParameters\fP
.RS 4
\fIlock_bits\fP A mask of which Boot Loader Lock Bits to set\&.
.RE
.PP
\fBNote\fP
.RS 4
In this context, a 'set bit' will be written to a zero value\&. Note also that only BLBxx bits can be programmed by this command\&.
.RE
.PP
For example, to disallow the SPM instruction from writing to the Boot Loader memory section of flash, you would use this macro as such:
.PP
.PP
.nf
boot_lock_bits_set (_BV (BLB11));
.fi
.PP
.PP
\fBNote\fP
.RS 4
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\&. 
.RE
.PP

.SS "#define boot_lock_bits_set_safe(lock_bits)"
\fBValue:\fP
.PP
.nf
do { \
    boot_spm_busy_wait();                       \
    eeprom_busy_wait();                         \
    boot_lock_bits_set (lock_bits);             \
} while (0)
.fi
Same as \fBboot_lock_bits_set()\fP except waits for eeprom and spm operations to complete before setting the lock bits\&. 
.SS "#define boot_lock_fuse_bits_get(address)"
\fBValue:\fP
.PP
.nf
(__extension__({                                           \
    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;                                              \
}))
.fi
Read the lock or fuse bits at \fCaddress\fP\&.
.PP
Parameter \fCaddress\fP can be any of GET_LOW_FUSE_BITS, GET_LOCK_BITS, GET_EXTENDED_FUSE_BITS, or GET_HIGH_FUSE_BITS\&.
.PP
\fBNote\fP
.RS 4
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\&. 
.RE
.PP

.SS "#define boot_page_erase(address)   __boot_page_erase_normal(address)"
Erase the flash page that contains address\&.
.PP
\fBNote\fP
.RS 4
address is a byte address in flash, not a word address\&. 
.RE
.PP

.SS "#define boot_page_erase_safe(address)"
\fBValue:\fP
.PP
.nf
do { \
    boot_spm_busy_wait();                       \
    eeprom_busy_wait();                         \
    boot_page_erase (address);                  \
} while (0)
.fi
Same as \fBboot_page_erase()\fP except it waits for eeprom and spm operations to complete before erasing the page\&. 
.SS "#define boot_page_fill(address, data)   __boot_page_fill_normal(address, data)"
Fill the bootloader temporary page buffer for flash address with data word\&.
.PP
\fBNote\fP
.RS 4
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\&. 
.RE
.PP

.SS "#define boot_page_fill_safe(address, data)"
\fBValue:\fP
.PP
.nf
do { \
    boot_spm_busy_wait();                       \
    eeprom_busy_wait();                         \
    boot_page_fill(address, data);              \
} while (0)
.fi
Same as \fBboot_page_fill()\fP except it waits for eeprom and spm operations to complete before filling the page\&. 
.SS "#define boot_page_write(address)   __boot_page_write_normal(address)"
Write the bootloader temporary page buffer to flash page that contains address\&.
.PP
\fBNote\fP
.RS 4
address is a byte address in flash, not a word address\&. 
.RE
.PP

.SS "#define boot_page_write_safe(address)"
\fBValue:\fP
.PP
.nf
do { \
    boot_spm_busy_wait();                       \
    eeprom_busy_wait();                         \
    boot_page_write (address);                  \
} while (0)
.fi
Same as \fBboot_page_write()\fP except it waits for eeprom and spm operations to complete before writing the page\&. 
.SS "#define boot_rww_busy()   (__SPM_REG & (\fBuint8_t\fP)\fB_BV\fP(__COMMON_ASB))"
Check if the RWW section is busy\&. 
.SS "#define boot_rww_enable()   __boot_rww_enable()"
Enable the Read-While-Write memory section\&. 
.SS "#define boot_rww_enable_safe()"
\fBValue:\fP
.PP
.nf
do { \
    boot_spm_busy_wait();                       \
    eeprom_busy_wait();                         \
    boot_rww_enable();                          \
} while (0)
.fi
Same as \fBboot_rww_enable()\fP except waits for eeprom and spm operations to complete before enabling the RWW mameory\&. 
.SS "#define boot_signature_byte_get(addr)"
\fBValue:\fP
.PP
.nf
(__extension__({                      \
      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_SIGROW_READ)),  \
          "z" ((uint16_t)(addr))                \
      );                                        \
      __result;                                 \
}))
.fi
Read the Signature Row byte at \fCaddress\fP\&. For some MCU types, this function can also retrieve the factory-stored oscillator calibration bytes\&.
.PP
Parameter \fCaddress\fP can be 0-0x1f as documented by the datasheet\&. 
.PP
\fBNote\fP
.RS 4
The values are MCU type dependent\&. 
.RE
.PP

.SS "#define boot_spm_busy()   (__SPM_REG & (\fBuint8_t\fP)\fB_BV\fP(__SPM_ENABLE))"
Check if the SPM instruction is busy\&. 
.SS "#define boot_spm_busy_wait()   do{}while(\fBboot_spm_busy\fP())"
Wait while the SPM instruction is busy\&. 
.SS "#define boot_spm_interrupt_disable()   (__SPM_REG &= (\fBuint8_t\fP)~\fB_BV\fP(SPMIE))"
Disable the SPM interrupt\&. 
.SS "#define boot_spm_interrupt_enable()   (__SPM_REG |= (\fBuint8_t\fP)\fB_BV\fP(SPMIE))"
Enable the SPM interrupt\&. 
.SS "#define BOOTLOADER_SECTION   \fB__attribute__\fP ((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\&. 
.SS "#define GET_EXTENDED_FUSE_BITS   (0x0002)"
address to read the extended fuse bits, using boot_lock_fuse_bits_get 
.SS "#define GET_HIGH_FUSE_BITS   (0x0003)"
address to read the high fuse bits, using boot_lock_fuse_bits_get 
.SS "#define GET_LOCK_BITS   (0x0001)"
address to read the lock bits, using boot_lock_fuse_bits_get 
.SS "#define GET_LOW_FUSE_BITS   (0x0000)"
address to read the low fuse bits, using boot_lock_fuse_bits_get 
.SH "Author"
.PP 
Generated automatically by Doxygen for avr-libc from the source code\&.