Man Linux: Main Page and Category List

NAME

       <avr/boot.h>: Bootloader Support Utilities -

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

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

       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.

       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 <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;
           }

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

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

   #define boot_lock_fuse_bits_get(address) Value:
       (__extension__({                                               uint8_t __result;                                          __asm__ __volatile__                                       (                                                              'sts %1, %2'                                           'lpm %0, Z'                                            : '=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.

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

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

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

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

   #define boot_signature_byte_get(addr) Value:
       (__extension__({                            uint8_t __result;                               __asm__ __volatile__                            (                                                 'sts %1, %2'                                '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.

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

       Note:
           The values are MCU type dependent.

   #define boot_spm_busy()   (__SPM_REG & (uint8_t)_BV(__SPM_ENABLE)) 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.
   #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.

Version 1.6.8                   T<avr/boot.h>:0Bootloader Support Utilities(3)