Bootloader Support Utilities


Detailed Description

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

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.

Note:
Not all AVR processors provide bootloader support. See your processor datasheet to see if it provides bootloader support.

Todo:
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.
API Usage Example
The following code shows typical usage of the boot API.
#include <avr/interrupt.h> #include <avr/pgmspace.h> #define ADDRESS 0x1C000UL void boot_test(void) { unsigned char buffer[8]; cli(); // Erase page. boot_page_erase((unsigned long)ADDRESS); while(boot_rww_busy()) { boot_rww_enable(); } // Write data to buffer a word at a time. Note incrementing address // by 2. SPM_PAGESIZE is defined in the microprocessor IO header file. for(unsigned long i = ADDRESS; i < ADDRESS + SPM_PAGESIZE; i += 2) { boot_page_fill(i, (i-ADDRESS) + ((i-ADDRESS+1) << 8)); } // Write page. boot_page_write((unsigned long)ADDRESS); while(boot_rww_busy()) { boot_rww_enable(); } sei(); // Read back the values and display. // (The show() function is undefined and is used here as an example // only.) for(unsigned long i = ADDRESS; i < ADDRESS + 256; i++) { show(utoa(pgm_read_byte(i), buffer, 16)); } return; }


Defines

#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(SPMEN))
#define boot_spm_busy_wait()   do{}while(boot_spm_busy())
#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 Documentation

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

Check if the SPM interrupt is enabled.

#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.
For example, to disallow the SPM instruction from writing to the Boot Loader memory section of flash, you would do this macro as such:

boot_lock_bits_set (_BV (BLB12));

And to remove any SPM restrictions, you would do this:

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

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

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

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

Check if the RWW section is busy.

 
#define boot_rww_enable  )     __boot_rww_enable()
 

Enable the Read-While-Write memory section.

 
#define boot_spm_busy  )     (__SPM_REG & (uint8_t)_BV(SPMEN))
 

Check if the SPM instruction is busy.

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

Wait while the SPM instruction is busy.

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

Disable the SPM interrupt.

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

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


Automatically generated by Doxygen 1.3.6 on 21 Jan 2005.