diff options
Diffstat (limited to 'cpukit/score/cpu/avr/avr/boot.h')
| -rw-r--r-- | cpukit/score/cpu/avr/avr/boot.h | 231 |
1 files changed, 121 insertions, 110 deletions
diff --git a/cpukit/score/cpu/avr/avr/boot.h b/cpukit/score/cpu/avr/avr/boot.h index 96453b5bfd..863143b226 100644 --- a/cpukit/score/cpu/avr/avr/boot.h +++ b/cpukit/score/cpu/avr/avr/boot.h @@ -1,104 +1,114 @@ -/* Copyright (c) 2002,2003,2004,2005,2006,2007,2008,2009 Eric B. Weddington - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of the copyright holders nor the names of - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE - LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. */ +/** + * @file + * + * @brief Bootloader Support Utilities + * + * 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. + * + * 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; + * } + */ + +/* + * Copyright (c) 2002,2003,2004,2005,2006,2007,2008,2009 Eric B. Weddington + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * * Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * * Neither the name of the copyright holders nor the names of + * contributors may be used to endorse or promote products derived + * from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ #ifndef _AVR_BOOT_H_ #define _AVR_BOOT_H_ 1 -/** \file */ -/** \defgroup avr_boot <avr/boot.h>: Bootloader Support Utilities - \code - #include <avr/io.h> - #include <avr/boot.h> - \endcode - - 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. - - \par API Usage Example - The following code shows typical usage of the boot API. - - \code - #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; - }\endcode */ +/** + * @defgroup avr_boot Bootloader Support Utilities + * + * @ingroup avr + */ +/**@{*/ #include <avr/eeprom.h> #include <avr/io.h> @@ -382,11 +392,11 @@ If bits 5..2 in R0 are cleared (zero), the corresponding Boot Lock bit will be programmed if an SPM instruction is executed within four cycles - after BLBSET and SPMEN (or SELFPRGEN) are set in SPMCR. The Z-pointer is - don't care during this operation, but for future compatibility it is - recommended to load the Z-pointer with $0001 (same as used for reading the - Lock bits). For future compatibility It is also recommended to set bits 7, - 6, 1, and 0 in R0 to 1 when writing the Lock bits. When programming the + after BLBSET and SPMEN (or SELFPRGEN) are set in SPMCR. The Z-pointer is + don't care during this operation, but for future compatibility it is + recommended to load the Z-pointer with $0001 (same as used for reading the + Lock bits). For future compatibility It is also recommended to set bits 7, + 6, 1, and 0 in R0 to 1 when writing the Lock bits. When programming the Lock bits the entire Flash can be read during the operation. */ #define __boot_lock_bits_set(lock_bits) \ @@ -430,8 +440,8 @@ /* Reading lock and fuse bits: - Similarly to writing the lock bits above, set BLBSET and SPMEN (or - SELFPRGEN) bits in __SPMREG, and then (within four clock cycles) issue an + Similarly to writing the lock bits above, set BLBSET and SPMEN (or + SELFPRGEN) bits in __SPMREG, and then (within four clock cycles) issue an LPM instruction. Z address: contents: @@ -525,13 +535,13 @@ /** \ingroup avr_boot \def boot_page_fill(address, data) - Fill the bootloader temporary page buffer for flash - address with data word. + 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 + \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 + 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.*/ /** \ingroup avr_boot @@ -544,9 +554,9 @@ /** \ingroup avr_boot \def boot_page_write(address) - Write the bootloader temporary page buffer + Write the bootloader temporary page buffer to flash page that contains address. - + \note address is a byte address in flash, not a word address. */ /** \ingroup avr_boot @@ -581,7 +591,7 @@ instruction sequences after LPM. FLASHEND is defined in the ioXXXX.h file. - USHRT_MAX is defined in <limits.h>. */ + USHRT_MAX is defined in <limits.h>. */ #if defined(__AVR_ATmega161__) || defined(__AVR_ATmega163__) \ || defined(__AVR_ATmega323__) @@ -673,4 +683,5 @@ do { \ boot_lock_bits_set (lock_bits); \ } while (0) +/**@}*/ #endif /* _AVR_BOOT_H_ */ |