AVR Libc Home Page AVRs AVR Libc Development Pages
Main Page User Manual Library Reference FAQ Alphabetical Index Example Projects

lock.h

Go to the documentation of this file.
00001 /* Copyright (c) 2007, Atmel Corporation
00002    All rights reserved.
00003 
00004    Redistribution and use in source and binary forms, with or without
00005    modification, are permitted provided that the following conditions are met:
00006 
00007    * Redistributions of source code must retain the above copyright
00008      notice, this list of conditions and the following disclaimer.
00009 
00010    * Redistributions in binary form must reproduce the above copyright
00011      notice, this list of conditions and the following disclaimer in
00012      the documentation and/or other materials provided with the
00013      distribution.
00014 
00015    * Neither the name of the copyright holders nor the names of
00016      contributors may be used to endorse or promote products derived
00017      from this software without specific prior written permission.
00018 
00019   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00020   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00021   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00022   ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
00023   LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
00024   CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00025   SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00026   INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00027   CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
00028   ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00029   POSSIBILITY OF SUCH DAMAGE. */
00030 
00031 /* $Id: lock.h 1692 2008-04-29 18:07:36Z arcanum $ */
00032 
00033 /* avr/lock.h - Lock Bits API */
00034 
00035 #ifndef _AVR_LOCK_H_
00036 #define _AVR_LOCK_H_  1
00037 
00038 
00039 /** \file */
00040 /** \defgroup avr_lock <avr/lock.h>: Lockbit Support
00041 
00042     \par Introduction
00043 
00044     The Lockbit API allows a user to specify the lockbit settings for the 
00045     specific AVR device they are compiling for. These lockbit settings will be 
00046     placed in a special section in the ELF output file, after linking.
00047 
00048     Programming tools can take advantage of the lockbit information embedded in
00049     the ELF file, by extracting this information and determining if the lockbits
00050     need to be programmed after programming the Flash and EEPROM memories.
00051     This also allows a single ELF file to contain all the
00052     information needed to program an AVR. 
00053 
00054     To use the Lockbit API, include the <avr/io.h> header file, which in turn
00055     automatically includes the individual I/O header file and the <avr/lock.h>
00056     file. These other two files provides everything necessary to set the AVR
00057     lockbits.
00058     
00059     \par Lockbit API
00060     
00061     Each I/O header file may define up to 3 macros that controls what kinds
00062     of lockbits are available to the user.
00063     
00064     If __LOCK_BITS_EXIST is defined, then two lock bits are available to the
00065     user and 3 mode settings are defined for these two bits.
00066     
00067     If __BOOT_LOCK_BITS_0_EXIST is defined, then the two BLB0 lock bits are
00068     available to the user and 4 mode settings are defined for these two bits.
00069     
00070     If __BOOT_LOCK_BITS_1_EXIST is defined, then the two BLB1 lock bits are
00071     available to the user and 4 mode settings are defined for these two bits.
00072 
00073     If __BOOT_LOCK_APPLICATION_TABLE_BITS_EXIST is defined then two lock bits
00074     are available to set the locking mode for the Application Table Section 
00075     (which is used in the XMEGA family).
00076     
00077     If __BOOT_LOCK_APPLICATION_BITS_EXIST is defined then two lock bits are
00078     available to set the locking mode for the Application Section (which is used
00079     in the XMEGA family).
00080     
00081     If __BOOT_LOCK_BOOT_BITS_EXIST is defined then two lock bits are available
00082     to set the locking mode for the Boot Loader Section (which is used in the
00083     XMEGA family).
00084 
00085     The AVR lockbit modes have inverted values, logical 1 for an unprogrammed 
00086     (disabled) bit and logical 0 for a programmed (enabled) bit. The defined 
00087     macros for each individual lock bit represent this in their definition by a 
00088     bit-wise inversion of a mask. For example, the LB_MODE_3 macro is defined 
00089     as:
00090     \code
00091     #define LB_MODE_3  (0xFC)
00092 `   \endcode
00093     
00094     To combine the lockbit mode macros together to represent a whole byte,
00095     use the bitwise AND operator, like so:
00096     \code
00097     (LB_MODE_3 & BLB0_MODE_2)
00098     \endcode
00099     
00100     <avr/lock.h> also defines a macro that provides a default lockbit value:
00101     LOCKBITS_DEFAULT which is defined to be 0xFF.
00102 
00103     See the AVR device specific datasheet for more details about these
00104     lock bits and the available mode settings.
00105     
00106     A convenience macro, LOCKMEM, is defined as a GCC attribute for a 
00107     custom-named section of ".lock".
00108     
00109     A convenience macro, LOCKBITS, is defined that declares a variable, __lock, 
00110     of type unsigned char with the attribute defined by LOCKMEM. This variable
00111     allows the end user to easily set the lockbit data.
00112 
00113     \note If a device-specific I/O header file has previously defined LOCKMEM,
00114     then LOCKMEM is not redefined. If a device-specific I/O header file has
00115     previously defined LOCKBITS, then LOCKBITS is not redefined. LOCKBITS is
00116     currently known to be defined in the I/O header files for the XMEGA devices.
00117 
00118     \par API Usage Example
00119     
00120     Putting all of this together is easy:
00121     
00122     \code
00123     #include <avr/io.h>
00124 
00125     LOCKBITS = (LB_MODE_1 & BLB0_MODE_3 & BLB1_MODE_4);
00126 
00127     int main(void)
00128     {
00129         return 0;
00130     }
00131     \endcode
00132     
00133     Or:
00134     
00135     \code
00136     #include <avr/io.h>
00137 
00138     unsigned char __lock __attribute__((section (".lock"))) = 
00139         (LB_MODE_1 & BLB0_MODE_3 & BLB1_MODE_4);
00140 
00141     int main(void)
00142     {
00143         return 0;
00144     }
00145     \endcode
00146     
00147     
00148     
00149     However there are a number of caveats that you need to be aware of to
00150     use this API properly.
00151     
00152     Be sure to include <avr/io.h> to get all of the definitions for the API.
00153     The LOCKBITS macro defines a global variable to store the lockbit data. This 
00154     variable is assigned to its own linker section. Assign the desired lockbit 
00155     values immediately in the variable initialization.
00156     
00157     The .lock section in the ELF file will get its values from the initial 
00158     variable assignment ONLY. This means that you can NOT assign values to 
00159     this variable in functions and the new values will not be put into the
00160     ELF .lock section.
00161     
00162     The global variable is declared in the LOCKBITS macro has two leading 
00163     underscores, which means that it is reserved for the "implementation",
00164     meaning the library, so it will not conflict with a user-named variable.
00165     
00166     You must initialize the lockbit variable to some meaningful value, even
00167     if it is the default value. This is because the lockbits default to a 
00168     logical 1, meaning unprogrammed. Normal uninitialized data defaults to all 
00169     locgial zeros. So it is vital that all lockbits are initialized, even with 
00170     default data. If they are not, then the lockbits may not programmed to the 
00171     desired settings and can possibly put your device into an unrecoverable 
00172     state.
00173     
00174     Be sure to have the -mmcu=<em>device</em> flag in your compile command line and
00175     your linker command line to have the correct device selected and to have 
00176     the correct I/O header file included when you include <avr/io.h>.
00177 
00178     You can print out the contents of the .lock section in the ELF file by
00179     using this command line:
00180     \code
00181     avr-objdump -s -j .lock <ELF file>
00182     \endcode
00183 
00184 */
00185 
00186 
00187 #ifndef __ASSEMBLER__
00188 
00189 #ifndef LOCKMEM
00190 #define LOCKMEM  __attribute__((section (".lock")))
00191 #endif
00192 
00193 #ifndef LOCKBITS
00194 #define LOCKBITS unsigned char __lock LOCKMEM
00195 #endif
00196 
00197 #endif  /* !__ASSEMBLER */
00198 
00199 
00200 /* Lock Bit Modes */
00201 #if defined(__LOCK_BITS_EXIST)
00202 #define LB_MODE_1  (0xFF)
00203 #define LB_MODE_2  (0xFE)
00204 #define LB_MODE_3  (0xFC)
00205 #endif
00206 
00207 #if defined(__BOOT_LOCK_BITS_0_EXIST)
00208 #define BLB0_MODE_1  (0xFF)
00209 #define BLB0_MODE_2  (0xFB)
00210 #define BLB0_MODE_3  (0xF3)
00211 #define BLB0_MODE_4  (0xF7)
00212 #endif
00213 
00214 #if defined(__BOOT_LOCK_BITS_1_EXIST)
00215 #define BLB1_MODE_1  (0xFF)
00216 #define BLB1_MODE_2  (0xEF)
00217 #define BLB1_MODE_3  (0xCF)
00218 #define BLB1_MODE_4  (0xDF)
00219 #endif
00220 
00221 #if defined(__BOOT_LOCK_APPLICATION_TABLE_BITS_EXIST)
00222 #define BLBAT0 ~_BV(2)
00223 #define BLBAT1 ~_BV(3)
00224 #endif
00225 
00226 #if defined(__BOOT_LOCK_APPLICATION_BITS_EXIST)
00227 #define BLBA0 ~_BV(4)
00228 #define BLBA1 ~_BV(5)
00229 #endif
00230 
00231 #if defined(__BOOT_LOCK_BOOT_BITS_EXIST)
00232 #define BLBB0 ~_BV(6)
00233 #define BLBB1 ~_BV(7)
00234 #endif
00235 
00236 
00237 #define LOCKBITS_DEFAULT (0xFF)
00238 
00239 #endif /* _AVR_LOCK_H_ */

Automatically generated by Doxygen 1.7.3 on Thu May 19 2011.