AVR Libc Home Page | AVR Libc Development Pages | ||||
Main Page | User Manual | Library Reference | FAQ | Alphabetical Index | Example Projects |
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_ */