Go to the documentation of this file.
01 1 Copyright (c) 2007, Atmel Corporation
022All rights reserved.
033
044Redistribution and use in source and binary forms, with or without
055modification, are permitted provided that the following conditions are met:
066
077* Redistributions of source code must retain the above copyright
088notice, this list of conditions and the following disclaimer.
099
1010* Redistributions in binary form must reproduce the above copyright
1111notice, this list of conditions and the following disclaimer in
1212the documentation and/or other materials provided with the
1313distribution.
1414
1515* Neither the name of the copyright holders nor the names of
1616contributors may be used to endorse or promote products derived
1717from this software without specific prior written permission.
1818
1919THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
2020AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
2121IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
2222ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
2323LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
2424CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
2525SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
2626INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
2727CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
2828ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
2929POSSIBILITY OF SUCH DAMAGE. */
3030
3131/* $Id: lock.h 2503 2016-02-07 22:59:47Z joerg_wunsch $ */
3232
3333/* avr/lock.h - Lock Bits API */
3434
3535#ifndef _AVR_LOCK_H_
3636#define _AVR_LOCK_H_ 1
3737
3838
3939/** \file */
4040/** \defgroup avr_lock <avr/lock.h>: Lockbit Support
4141
4242\par Introduction
4343
4444The Lockbit API allows a user to specify the lockbit settings for the
4545specific AVR device they are compiling for. These lockbit settings will be
4646placed in a special section in the ELF output file, after linking.
4747
4848Programming tools can take advantage of the lockbit information embedded in
4949the ELF file, by extracting this information and determining if the lockbits
5050need to be programmed after programming the Flash and EEPROM memories.
5151This also allows a single ELF file to contain all the
5252information needed to program an AVR.
5353
5454To use the Lockbit API, include the <avr/io.h> header file, which in turn
5555automatically includes the individual I/O header file and the <avr/lock.h>
5656file. These other two files provides everything necessary to set the AVR
5757lockbits.
58585959\par Lockbit API
60606161Each I/O header file may define up to 3 macros that controls what kinds
6262of lockbits are available to the user.
63636464If __LOCK_BITS_EXIST is defined, then two lock bits are available to the
6565user and 3 mode settings are defined for these two bits.
66666767If __BOOT_LOCK_BITS_0_EXIST is defined, then the two BLB0 lock bits are
6868available to the user and 4 mode settings are defined for these two bits.
69697070If __BOOT_LOCK_BITS_1_EXIST is defined, then the two BLB1 lock bits are
7171available to the user and 4 mode settings are defined for these two bits.
7272
7373If __BOOT_LOCK_APPLICATION_TABLE_BITS_EXIST is defined then two lock bits
7474are available to set the locking mode for the Application Table Section
7575(which is used in the XMEGA family).
76767777If __BOOT_LOCK_APPLICATION_BITS_EXIST is defined then two lock bits are
7878available to set the locking mode for the Application Section (which is used
7979in the XMEGA family).
80808181If __BOOT_LOCK_BOOT_BITS_EXIST is defined then two lock bits are available
8282to set the locking mode for the Boot Loader Section (which is used in the
8383XMEGA family).
8484
8585The AVR lockbit modes have inverted values, logical 1 for an unprogrammed
8686(disabled) bit and logical 0 for a programmed (enabled) bit. The defined
8787macros for each individual lock bit represent this in their definition by a
8888bit-wise inversion of a mask. For example, the LB_MODE_3 macro is defined
8989as:
9090\code
9191#define LB_MODE_3 (0xFC)
9292` \endcode
93939494To combine the lockbit mode macros together to represent a whole byte,
9595use the bitwise AND operator, like so:
9696\code
9797(LB_MODE_3 & BLB0_MODE_2)
9898\endcode
9999100100<avr/lock.h> also defines a macro that provides a default lockbit value:
101101LOCKBITS_DEFAULT which is defined to be 0xFF.
102102
103103See the AVR device specific datasheet for more details about these
104104lock bits and the available mode settings.
105105106106A convenience macro, LOCKMEM, is defined as a GCC attribute for a
107107custom-named section of ".lock".
108108109109A convenience macro, LOCKBITS, is defined that declares a variable, __lock,
110110of type unsigned char with the attribute defined by LOCKMEM. This variable
111111allows the end user to easily set the lockbit data.
112112
113113\note If a device-specific I/O header file has previously defined LOCKMEM,
114114then LOCKMEM is not redefined. If a device-specific I/O header file has
115115previously defined LOCKBITS, then LOCKBITS is not redefined. LOCKBITS is
116116currently known to be defined in the I/O header files for the XMEGA devices.
117117
118118\par API Usage Example
119119120120Putting all of this together is easy:
121121122122\code
123123#include <avr/io.h>
124124
125125LOCKBITS = (LB_MODE_1 & BLB0_MODE_3 & BLB1_MODE_4);
126126
127127int main(void)
128128{
129129return 0;
130130}
131131\endcode
132132133133Or:
134134135135\code
136136#include <avr/io.h>
137137
138138unsigned char __lock __attribute__((section (".lock"))) =
139139(LB_MODE_1 & BLB0_MODE_3 & BLB1_MODE_4);
140140
141141int main(void)
142142{
143143return 0;
144144}
145145\endcode
146146147147148148149149However there are a number of caveats that you need to be aware of to
150150use this API properly.
151151152152Be sure to include <avr/io.h> to get all of the definitions for the API.
153153The LOCKBITS macro defines a global variable to store the lockbit data. This
154154variable is assigned to its own linker section. Assign the desired lockbit
155155values immediately in the variable initialization.
156156157157The .lock section in the ELF file will get its values from the initial
158158variable assignment ONLY. This means that you can NOT assign values to
159159this variable in functions and the new values will not be put into the
160160ELF .lock section.
161161162162The global variable is declared in the LOCKBITS macro has two leading
163163underscores, which means that it is reserved for the "implementation",
164164meaning the library, so it will not conflict with a user-named variable.
165165166166You must initialize the lockbit variable to some meaningful value, even
167167if it is the default value. This is because the lockbits default to a
168168logical 1, meaning unprogrammed. Normal uninitialized data defaults to all
169169locgial zeros. So it is vital that all lockbits are initialized, even with
170170default data. If they are not, then the lockbits may not programmed to the
171171desired settings and can possibly put your device into an unrecoverable
172172state.
173173174174Be sure to have the -mmcu=<em>device</em> flag in your compile command line and
175175your linker command line to have the correct device selected and to have
176176the correct I/O header file included when you include <avr/io.h>.
177177
178178You can print out the contents of the .lock section in the ELF file by
179179using this command line:
180180\code
181181avr-objdump -s -j .lock <ELF file>
182182\endcode
183183
184184*/
185185
186186
187187#if !(defined(__ASSEMBLER__) || defined(__DOXYGEN__))
188188
189189#ifndef LOCKMEM
190190#define LOCKMEM __attribute__((__used__, __section__ (".lock")))
191191#endif
192192
193193#ifndef LOCKBITS
194194#define LOCKBITS unsigned char __lock LOCKMEM
195195#endif
196196
197197/* Lock Bit Modes */
198198#if defined(__LOCK_BITS_EXIST)
199199#define LB_MODE_1 (0xFF)
200200#define LB_MODE_2 (0xFE)
201201#define LB_MODE_3 (0xFC)
202202#endif
203203
204204#if defined(__BOOT_LOCK_BITS_0_EXIST)
205205#define BLB0_MODE_1 (0xFF)
206206#define BLB0_MODE_2 (0xFB)
207207#define BLB0_MODE_3 (0xF3)
208208#define BLB0_MODE_4 (0xF7)
209209#endif
210210
211211#if defined(__BOOT_LOCK_BITS_1_EXIST)
212212#define BLB1_MODE_1 (0xFF)
213213#define BLB1_MODE_2 (0xEF)
214214#define BLB1_MODE_3 (0xCF)
215215#define BLB1_MODE_4 (0xDF)
216216#endif
217217
218218#if defined(__BOOT_LOCK_APPLICATION_TABLE_BITS_EXIST)
219219#define BLBAT0 ~_BV(2)
220220#define BLBAT1 ~_BV(3)
221221#endif
222222
223223#if defined(__BOOT_LOCK_APPLICATION_BITS_EXIST)
224224#define BLBA0 ~_BV(4)
225225#define BLBA1 ~_BV(5)
226226#endif
227227
228228#if defined(__BOOT_LOCK_BOOT_BITS_EXIST)
229229#define BLBB0 ~_BV(6)
230230#define BLBB1 ~_BV(7)
231231#endif
232232
233233
234234#define LOCKBITS_DEFAULT (0xFF)
235235
236236#endif /* !(__ASSEMBLER || __DOXYGEN__) */
237237
238238
239239#endif /* _AVR_LOCK_H_ */
