avr-libc  2.1.0
Standard C library for AVR-GCC

AVR Libc Home Page

 AVRs

AVR Libc Development Pages

Main Page

User Manual

Library Reference

FAQ

Example Projects
lock.h
Go to the documentation of this file.
1 /* Copyright (c) 2007, Atmel Corporation
2  All rights reserved.
3 
4  Redistribution and use in source and binary forms, with or without
5  modification, are permitted provided that the following conditions are met:
6 
7  * Redistributions of source code must retain the above copyright
8  notice, this list of conditions and the following disclaimer.
9 
10  * Redistributions in binary form must reproduce the above copyright
11  notice, this list of conditions and the following disclaimer in
12  the documentation and/or other materials provided with the
13  distribution.
14 
15  * Neither the name of the copyright holders nor the names of
16  contributors may be used to endorse or promote products derived
17  from this software without specific prior written permission.
18 
19  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
23  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29  POSSIBILITY OF SUCH DAMAGE. */
30 
31 /* $Id: lock_8h_source.html,v 1.1.1.7 2022/01/29 09:21:56 joerg_wunsch Exp $ */
32 
33 /* avr/lock.h - Lock Bits API */
34 
35 #ifndef _AVR_LOCK_H_
36 #define _AVR_LOCK_H_ 1
37 
38 
39 /** \file */
40 /** \defgroup avr_lock <avr/lock.h>: Lockbit Support
41 
42  \par Introduction
43 
44  The Lockbit API allows a user to specify the lockbit settings for the
45  specific AVR device they are compiling for. These lockbit settings will be
46  placed in a special section in the ELF output file, after linking.
47 
48  Programming tools can take advantage of the lockbit information embedded in
49  the ELF file, by extracting this information and determining if the lockbits
50  need to be programmed after programming the Flash and EEPROM memories.
51  This also allows a single ELF file to contain all the
52  information needed to program an AVR.
53 
54  To use the Lockbit API, include the <avr/io.h> header file, which in turn
55  automatically includes the individual I/O header file and the <avr/lock.h>
56  file. These other two files provides everything necessary to set the AVR
57  lockbits.
58 
59  \par Lockbit API
60 
61  Each I/O header file may define up to 3 macros that controls what kinds
62  of lockbits are available to the user.
63 
64  If __LOCK_BITS_EXIST is defined, then two lock bits are available to the
65  user and 3 mode settings are defined for these two bits.
66 
67  If __BOOT_LOCK_BITS_0_EXIST is defined, then the two BLB0 lock bits are
68  available to the user and 4 mode settings are defined for these two bits.
69 
70  If __BOOT_LOCK_BITS_1_EXIST is defined, then the two BLB1 lock bits are
71  available to the user and 4 mode settings are defined for these two bits.
72 
73  If __BOOT_LOCK_APPLICATION_TABLE_BITS_EXIST is defined then two lock bits
74  are available to set the locking mode for the Application Table Section
75  (which is used in the XMEGA family).
76 
77  If __BOOT_LOCK_APPLICATION_BITS_EXIST is defined then two lock bits are
78  available to set the locking mode for the Application Section (which is used
79  in the XMEGA family).
80 
81  If __BOOT_LOCK_BOOT_BITS_EXIST is defined then two lock bits are available
82  to set the locking mode for the Boot Loader Section (which is used in the
83  XMEGA family).
84 
85  The AVR lockbit modes have inverted values, logical 1 for an unprogrammed
86  (disabled) bit and logical 0 for a programmed (enabled) bit. The defined
87  macros for each individual lock bit represent this in their definition by a
88  bit-wise inversion of a mask. For example, the LB_MODE_3 macro is defined
89  as:
90  \code
91  #define LB_MODE_3 (0xFC)
92 ` \endcode
93 
94  To combine the lockbit mode macros together to represent a whole byte,
95  use the bitwise AND operator, like so:
96  \code
97  (LB_MODE_3 & BLB0_MODE_2)
98  \endcode
99 
100  <avr/lock.h> also defines a macro that provides a default lockbit value:
101  LOCKBITS_DEFAULT which is defined to be 0xFF.
102 
103  See the AVR device specific datasheet for more details about these
104  lock bits and the available mode settings.
105 
106  A convenience macro, LOCKMEM, is defined as a GCC attribute for a
107  custom-named section of ".lock".
108 
109  A convenience macro, LOCKBITS, is defined that declares a variable, __lock,
110  of type unsigned char with the attribute defined by LOCKMEM. This variable
111  allows the end user to easily set the lockbit data.
112 
113  \note If a device-specific I/O header file has previously defined LOCKMEM,
114  then LOCKMEM is not redefined. If a device-specific I/O header file has
115  previously defined LOCKBITS, then LOCKBITS is not redefined. LOCKBITS is
116  currently known to be defined in the I/O header files for the XMEGA devices.
117 
118  \par API Usage Example
119 
120  Putting all of this together is easy:
121 
122  \code
123  #include <avr/io.h>
124 
125  LOCKBITS = (LB_MODE_1 & BLB0_MODE_3 & BLB1_MODE_4);
126 
127  int main(void)
128  {
129  return 0;
130  }
131  \endcode
132 
133  Or:
134 
135  \code
136  #include <avr/io.h>
137 
138  unsigned char __lock __attribute__((section (".lock"))) =
139  (LB_MODE_1 & BLB0_MODE_3 & BLB1_MODE_4);
140 
141  int main(void)
142  {
143  return 0;
144  }
145  \endcode
146 
147 
148 
149  However there are a number of caveats that you need to be aware of to
150  use this API properly.
151 
152  Be sure to include <avr/io.h> to get all of the definitions for the API.
153  The LOCKBITS macro defines a global variable to store the lockbit data. This
154  variable is assigned to its own linker section. Assign the desired lockbit
155  values immediately in the variable initialization.
156 
157  The .lock section in the ELF file will get its values from the initial
158  variable assignment ONLY. This means that you can NOT assign values to
159  this variable in functions and the new values will not be put into the
160  ELF .lock section.
161 
162  The global variable is declared in the LOCKBITS macro has two leading
163  underscores, which means that it is reserved for the "implementation",
164  meaning the library, so it will not conflict with a user-named variable.
165 
166  You must initialize the lockbit variable to some meaningful value, even
167  if it is the default value. This is because the lockbits default to a
168  logical 1, meaning unprogrammed. Normal uninitialized data defaults to all
169  locgial zeros. So it is vital that all lockbits are initialized, even with
170  default data. If they are not, then the lockbits may not programmed to the
171  desired settings and can possibly put your device into an unrecoverable
172  state.
173 
174  Be sure to have the -mmcu=<em>device</em> flag in your compile command line and
175  your linker command line to have the correct device selected and to have
176  the correct I/O header file included when you include <avr/io.h>.
177 
178  You can print out the contents of the .lock section in the ELF file by
179  using this command line:
180  \code
181  avr-objdump -s -j .lock <ELF file>
182  \endcode
183 
184 */
185 
186 
187 #if !(defined(__ASSEMBLER__) || defined(__DOXYGEN__))
188 
189 #ifndef LOCKMEM
190 #define LOCKMEM __attribute__((__used__, __section__ (".lock")))
191 #endif
192 
193 #ifndef LOCKBITS
194 #define LOCKBITS unsigned char __lock LOCKMEM
195 #endif
196 
197 /* Lock Bit Modes */
198 #if defined(__LOCK_BITS_EXIST)
199 #define LB_MODE_1 (0xFF)
200 #define LB_MODE_2 (0xFE)
201 #define LB_MODE_3 (0xFC)
202 #endif
203 
204 #if defined(__BOOT_LOCK_BITS_0_EXIST)
205 #define BLB0_MODE_1 (0xFF)
206 #define BLB0_MODE_2 (0xFB)
207 #define BLB0_MODE_3 (0xF3)
208 #define BLB0_MODE_4 (0xF7)
209 #endif
210 
211 #if defined(__BOOT_LOCK_BITS_1_EXIST)
212 #define BLB1_MODE_1 (0xFF)
213 #define BLB1_MODE_2 (0xEF)
214 #define BLB1_MODE_3 (0xCF)
215 #define BLB1_MODE_4 (0xDF)
216 #endif
217 
218 #if defined(__BOOT_LOCK_APPLICATION_TABLE_BITS_EXIST)
219 #define BLBAT0 ~_BV(2)
220 #define BLBAT1 ~_BV(3)
221 #endif
222 
223 #if defined(__BOOT_LOCK_APPLICATION_BITS_EXIST)
224 #define BLBA0 ~_BV(4)
225 #define BLBA1 ~_BV(5)
226 #endif
227 
228 #if defined(__BOOT_LOCK_BOOT_BITS_EXIST)
229 #define BLBB0 ~_BV(6)
230 #define BLBB1 ~_BV(7)
231 #endif
232 
233 
234 #define LOCKBITS_DEFAULT (0xFF)
235 
236 #endif /* !(__ASSEMBLER || __DOXYGEN__) */
237 
238 
239 #endif /* _AVR_LOCK_H_ */
Generated on Sat Jan 29 2022 00:24:03 for avr-libc by   doxygen 1.8.14