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.

#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.3 on 8 Oct 2003.