Bootloader Support Utilities

Macros
#define	BOOTLOADER_SECTION   __attribute__ ((section (".bootloader")))
	Used to declare a function or variable to be placed into a new section called .bootloader. More...
#define	__COMMON_ASB   RWWSB
#define	__COMMON_ASRE   RWWSRE
#define	BLB12   5
#define	BLB11   4
#define	BLB02   3
#define	BLB01   2
#define	boot_spm_interrupt_enable()   (__SPM_REG |= (uint8_t)_BV(SPMIE))
	Enable the SPM interrupt. More...
#define	boot_spm_interrupt_disable()   (__SPM_REG &= (uint8_t)~_BV(SPMIE))
	Disable the SPM interrupt. More...
#define	boot_is_spm_interrupt()   (__SPM_REG & (uint8_t)_BV(SPMIE))
	Check if the SPM interrupt is enabled. More...
#define	boot_rww_busy()   (__SPM_REG & (uint8_t)_BV(__COMMON_ASB))
	Check if the RWW section is busy. More...
#define	boot_spm_busy()   (__SPM_REG & (uint8_t)_BV(__SPM_ENABLE))
	Check if the SPM instruction is busy. More...
#define	boot_spm_busy_wait()   do{}while(boot_spm_busy())
	Wait while the SPM instruction is busy. More...
#define	__BOOT_PAGE_ERASE   (_BV(__SPM_ENABLE) | _BV(PGERS))
#define	__BOOT_PAGE_WRITE   (_BV(__SPM_ENABLE) | _BV(PGWRT))
#define	__BOOT_PAGE_FILL   _BV(__SPM_ENABLE)
#define	__BOOT_RWW_ENABLE   (_BV(__SPM_ENABLE) | _BV(__COMMON_ASRE))
#define	__boot_page_fill_normal(address, data)
#define	__boot_page_fill_alternate(address, data)
#define	__boot_page_fill_extended(address, data)
#define	__boot_page_erase_normal(address)
#define	__boot_page_erase_alternate(address)
#define	__boot_page_erase_extended(address)
#define	__boot_page_write_normal(address)
#define	__boot_page_write_alternate(address)
#define	__boot_page_write_extended(address)
#define	__boot_rww_enable()
#define	__boot_rww_enable_alternate()
#define	__boot_lock_bits_set(lock_bits)
#define	__boot_lock_bits_set_alternate(lock_bits)
#define	GET_LOW_FUSE_BITS   (0x0000)
	address to read the low 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_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	boot_lock_fuse_bits_get(address)
	Read the lock or fuse bits at address. More...
#define	boot_signature_byte_get(addr)
	Read the Signature Row byte at address. More...
#define	__BOOT_SIGROW_READ   (_BV(__SPM_ENABLE) | _BV(SIGRD))
#define	boot_page_fill(address, data)   __boot_page_fill_normal(address, data)
	Fill the bootloader temporary page buffer for flash address with data word. More...
#define	boot_page_erase(address)   __boot_page_erase_normal(address)
	Erase the flash page that contains address. More...
#define	boot_page_write(address)   __boot_page_write_normal(address)
	Write the bootloader temporary page buffer to flash page that contains address. More...
#define	boot_rww_enable()   __boot_rww_enable()
	Enable the Read-While-Write memory section. More...
#define	boot_lock_bits_set(lock_bits)   __boot_lock_bits_set(lock_bits)
	Set the bootloader lock bits. More...
#define	boot_page_fill_safe(address, data)
	Same as boot_page_fill() except it waits for eeprom and spm operations to complete before filling the page. More...
#define	boot_page_erase_safe(address)
	Same as boot_page_erase() except it waits for eeprom and spm operations to complete before erasing the page. More...
#define	boot_page_write_safe(address)
	Same as boot_page_write() except it waits for eeprom and spm operations to complete before writing the page. More...
#define	boot_rww_enable_safe()
	Same as boot_rww_enable() except waits for eeprom and spm operations to complete before enabling the RWW mameory. More...
#define	boot_lock_bits_set_safe(lock_bits)
	Same as boot_lock_bits_set() except waits for eeprom and spm operations to complete before setting the lock bits. More...

Detailed Description

Macro Definition Documentation

__boot_lock_bits_set

#define __boot_lock_bits_set

(

lock_bits

)

Value:

(__extension__({                                           \
    uint8_t value = (uint8_t)(~(lock_bits));               \
    __asm__ __volatile__                                   \
    (                                                      \
        "ldi r30, 1\n\t"                                   \
        "ldi r31, 0\n\t"                                   \
        "mov r0, %2\n\t"                                   \
        "sts %0, %1\n\t"                                   \
        "spm\n\t"                                          \
        :                                                  \
        : "i" (_SFR_MEM_ADDR(__SPM_REG)),                  \
          "r" ((uint8_t)(__BOOT_LOCK_BITS_SET)),           \
          "r" (value)                                      \
        : "r0", "r30", "r31"                               \
    );                                                     \
}))

__boot_lock_bits_set_alternate

#define __boot_lock_bits_set_alternate

(

lock_bits

)

Value:

(__extension__({                                           \
    uint8_t value = (uint8_t)(~(lock_bits));               \
    __asm__ __volatile__                                   \
    (                                                      \
        "ldi r30, 1\n\t"                                   \
        "ldi r31, 0\n\t"                                   \
        "mov r0, %2\n\t"                                   \
        "sts %0, %1\n\t"                                   \
        "spm\n\t"                                          \
        ".word 0xffff\n\t"                                 \
        "nop\n\t"                                          \
        :                                                  \
        : "i" (_SFR_MEM_ADDR(__SPM_REG)),                  \
          "r" ((uint8_t)(__BOOT_LOCK_BITS_SET)),           \
          "r" (value)                                      \
        : "r0", "r30", "r31"                               \
    );                                                     \
}))

__boot_page_erase_alternate

#define __boot_page_erase_alternate

(

address

)

Value:

(__extension__({                                 \
    __asm__ __volatile__                         \
    (                                            \
        "sts %0, %1\n\t"                         \
        "spm\n\t"                                \
        ".word 0xffff\n\t"                       \
        "nop\n\t"                                \
        :                                        \
        : "i" (_SFR_MEM_ADDR(__SPM_REG)),        \
          "r" ((uint8_t)(__BOOT_PAGE_ERASE)),    \
          "z" ((uint16_t)(address))              \
    );                                           \
}))

__boot_page_erase_extended

#define __boot_page_erase_extended

(

address

)

Value:

(__extension__({                                 \
    __asm__ __volatile__                         \
    (                                            \
        "movw r30, %A3\n\t"                      \
        "sts  %1, %C3\n\t"                       \
        "sts %0, %2\n\t"                         \
        "spm\n\t"                                \
        :                                        \
        : "i" (_SFR_MEM_ADDR(__SPM_REG)),        \
          "i" (_SFR_MEM_ADDR(RAMPZ)),            \
          "r" ((uint8_t)(__BOOT_PAGE_ERASE)),    \
          "r" ((uint32_t)(address))              \
        : "r30", "r31"                           \
    );                                           \
}))

__boot_page_erase_normal

#define __boot_page_erase_normal

(

address

)

Value:

(__extension__({                                 \
    __asm__ __volatile__                         \
    (                                            \
        "sts %0, %1\n\t"                         \
        "spm\n\t"                                \
        :                                        \
        : "i" (_SFR_MEM_ADDR(__SPM_REG)),        \
          "r" ((uint8_t)(__BOOT_PAGE_ERASE)),    \
          "z" ((uint16_t)(address))              \
    );                                           \
}))

__boot_page_fill_alternate

#define __boot_page_fill_alternate	(		address,
			data
	)

Value:

(__extension__({                                 \
    __asm__ __volatile__                         \
    (                                            \
        "movw  r0, %3\n\t"                       \
        "sts %0, %1\n\t"                         \
        "spm\n\t"                                \
        ".word 0xffff\n\t"                       \
        "nop\n\t"                                \
        "clr  r1\n\t"                            \
        :                                        \
        : "i" (_SFR_MEM_ADDR(__SPM_REG)),        \
          "r" ((uint8_t)(__BOOT_PAGE_FILL)),     \
          "z" ((uint16_t)(address)),             \
          "r" ((uint16_t)(data))                 \
        : "r0"                                   \
    );                                           \
}))

__boot_page_fill_extended

#define __boot_page_fill_extended	(		address,
			data
	)

Value:

(__extension__({                                 \
    __asm__ __volatile__                         \
    (                                            \
        "movw  r0, %4\n\t"                       \
        "movw r30, %A3\n\t"                      \
        "sts %1, %C3\n\t"                        \
        "sts %0, %2\n\t"                         \
        "spm\n\t"                                \
        "clr  r1\n\t"                            \
        :                                        \
        : "i" (_SFR_MEM_ADDR(__SPM_REG)),        \
          "i" (_SFR_MEM_ADDR(RAMPZ)),            \
          "r" ((uint8_t)(__BOOT_PAGE_FILL)),     \
          "r" ((uint32_t)(address)),             \
          "r" ((uint16_t)(data))                 \
        : "r0", "r30", "r31"                     \
    );                                           \
}))

__boot_page_fill_normal

#define __boot_page_fill_normal	(		address,
			data
	)

Value:

(__extension__({                                 \
    __asm__ __volatile__                         \
    (                                            \
        "movw  r0, %3\n\t"                       \
        "sts %0, %1\n\t"                         \
        "spm\n\t"                                \
        "clr  r1\n\t"                            \
        :                                        \
        : "i" (_SFR_MEM_ADDR(__SPM_REG)),        \
          "r" ((uint8_t)(__BOOT_PAGE_FILL)),     \
          "z" ((uint16_t)(address)),             \
          "r" ((uint16_t)(data))                 \
        : "r0"                                   \
    );                                           \
}))

__boot_page_write_alternate

#define __boot_page_write_alternate

(

address

)

Value:

(__extension__({                                 \
    __asm__ __volatile__                         \
    (                                            \
        "sts %0, %1\n\t"                         \
        "spm\n\t"                                \
        ".word 0xffff\n\t"                       \
        "nop\n\t"                                \
        :                                        \
        : "i" (_SFR_MEM_ADDR(__SPM_REG)),        \
          "r" ((uint8_t)(__BOOT_PAGE_WRITE)),    \
          "z" ((uint16_t)(address))              \
    );                                           \
}))

__boot_page_write_extended

#define __boot_page_write_extended

(

address

)

Value:

(__extension__({                                 \
    __asm__ __volatile__                         \
    (                                            \
        "movw r30, %A3\n\t"                      \
        "sts %1, %C3\n\t"                        \
        "sts %0, %2\n\t"                         \
        "spm\n\t"                                \
        :                                        \
        : "i" (_SFR_MEM_ADDR(__SPM_REG)),        \
          "i" (_SFR_MEM_ADDR(RAMPZ)),            \
          "r" ((uint8_t)(__BOOT_PAGE_WRITE)),    \
          "r" ((uint32_t)(address))              \
        : "r30", "r31"                           \
    );                                           \
}))

__boot_page_write_normal

#define __boot_page_write_normal

(

address

)

Value:

(__extension__({                                 \
    __asm__ __volatile__                         \
    (                                            \
        "sts %0, %1\n\t"                         \
        "spm\n\t"                                \
        :                                        \
        : "i" (_SFR_MEM_ADDR(__SPM_REG)),        \
          "r" ((uint8_t)(__BOOT_PAGE_WRITE)),    \
          "z" ((uint16_t)(address))              \
    );                                           \
}))

__boot_rww_enable

#define __boot_rww_enable

(

)

Value:

(__extension__({                                 \
    __asm__ __volatile__                         \
    (                                            \
        "sts %0, %1\n\t"                         \
        "spm\n\t"                                \
        :                                        \
        : "i" (_SFR_MEM_ADDR(__SPM_REG)),        \
          "r" ((uint8_t)(__BOOT_RWW_ENABLE))     \
    );                                           \
}))

__boot_rww_enable_alternate

#define __boot_rww_enable_alternate

(

)

Value:

(__extension__({                                 \
    __asm__ __volatile__                         \
    (                                            \
        "sts %0, %1\n\t"                         \
        "spm\n\t"                                \
        ".word 0xffff\n\t"                       \
        "nop\n\t"                                \
        :                                        \
        : "i" (_SFR_MEM_ADDR(__SPM_REG)),        \
          "r" ((uint8_t)(__BOOT_RWW_ENABLE))     \
    );                                           \
}))

boot_is_spm_interrupt

#define boot_is_spm_interrupt

(

)

(__SPM_REG & (uint8_t)_BV(SPMIE))

Check if the SPM interrupt is enabled.

boot_lock_bits_set

#define boot_lock_bits_set

(

lock_bits

)

__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. 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.

boot_lock_bits_set_safe

#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.

boot_lock_fuse_bits_get

#define boot_lock_fuse_bits_get

(

address

)

Value:

(__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;                                              \
}))

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.

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.

boot_page_erase

#define boot_page_erase

(

address

)

__boot_page_erase_normal(address)

Erase the flash page that contains address.

Note

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

boot_page_erase_safe

#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.

boot_page_fill

#define boot_page_fill	(		address,
			data
	)		__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.

boot_page_fill_safe

#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.

boot_page_write

#define boot_page_write

(

address

)

__boot_page_write_normal(address)

Write the bootloader temporary page buffer to flash page that contains address.

Note

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

boot_page_write_safe

#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.

boot_rww_busy

#define boot_rww_busy

(

)

(__SPM_REG & (uint8_t)_BV(__COMMON_ASB))

Check if the RWW section is busy.

boot_rww_enable

#define boot_rww_enable

(

)

__boot_rww_enable()

Enable the Read-While-Write memory section.

boot_rww_enable_safe

#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.

boot_signature_byte_get

#define boot_signature_byte_get

(

addr

)

Value:

(__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;                                 \
}))

Read the Signature Row byte at address.

For some MCU types, this function can also retrieve the factory-stored oscillator calibration bytes.

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

Note

The values are MCU type dependent.

boot_spm_busy

#define boot_spm_busy

(

)

(__SPM_REG & (uint8_t)_BV(__SPM_ENABLE))

Check if the SPM instruction is busy.

boot_spm_busy_wait

#define boot_spm_busy_wait

(

)

do{}while(boot_spm_busy())

Wait while the SPM instruction is busy.

boot_spm_interrupt_disable

#define boot_spm_interrupt_disable

(

)

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

Disable the SPM interrupt.

boot_spm_interrupt_enable

#define boot_spm_interrupt_enable

(

)

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

Enable the SPM interrupt.

BOOTLOADER_SECTION

#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.