fuse.8h
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: fuse.h 2503 2016-02-07 22:59:47Z joerg_wunsch $ */
3232
3333/* avr/fuse.h - Fuse API */
3434
3535#ifndef _AVR_FUSE_H_
3636#define _AVR_FUSE_H_ 1
3737
3838/* This file must be explicitly included by <avr/io.h>. */
3939#if !defined(_AVR_IO_H_)
4040#error "You must #include <avr/io.h> and not <avr/fuse.h> by itself."
4141#endif
4242
4343
4444/** \file */
4545/** \defgroup avr_fuse <avr/fuse.h>: Fuse Support
4646
4747\par Introduction
4848
4949The Fuse API allows a user to specify the fuse settings for the specific
5050AVR device they are compiling for. These fuse settings will be placed
5151in a special section in the ELF output file, after linking.
5252
5353Programming tools can take advantage of the fuse information embedded in
5454the ELF file, by extracting this information and determining if the fuses
5555need to be programmed before programming the Flash and EEPROM memories.
5656This also allows a single ELF file to contain all the
5757information needed to program an AVR.
5858
5959To use the Fuse API, include the <avr/io.h> header file, which in turn
6060automatically includes the individual I/O header file and the <avr/fuse.h>
6161file. These other two files provides everything necessary to set the AVR
6262fuses.
63636464\par Fuse API
65656666Each I/O header file must define the FUSE_MEMORY_SIZE macro which is
6767defined to the number of fuse bytes that exist in the AVR device.
68686969A new type, __fuse_t, is defined as a structure. The number of fields in
7070this structure are determined by the number of fuse bytes in the
7171FUSE_MEMORY_SIZE macro.
72727373If FUSE_MEMORY_SIZE == 1, there is only a single field: byte, of type
7474unsigned char.
75757676If FUSE_MEMORY_SIZE == 2, there are two fields: low, and high, of type
7777unsigned char.
78787979If FUSE_MEMORY_SIZE == 3, there are three fields: low, high, and extended,
8080of type unsigned char.
81818282If FUSE_MEMORY_SIZE >> 3, there is a single field: byte, which is an array
8383of unsigned char with the size of the array being FUSE_MEMORY_SIZE.
84848585A convenience macro, FUSEMEM, is defined as a GCC attribute for a
8686custom-named section of ".fuse".
87878888A convenience macro, FUSES, is defined that declares a variable, __fuse, of
8989type __fuse_t with the attribute defined by FUSEMEM. This variable
9090allows the end user to easily set the fuse data.
9191
9292\note If a device-specific I/O header file has previously defined FUSEMEM,
9393then FUSEMEM is not redefined. If a device-specific I/O header file has
9494previously defined FUSES, then FUSES is not redefined.
9595
9696Each AVR device I/O header file has a set of defined macros which specify the
9797actual fuse bits available on that device. The AVR fuses have inverted
9898values, logical 1 for an unprogrammed (disabled) bit and logical 0 for a
9999programmed (enabled) bit. The defined macros for each individual fuse
100100bit represent this in their definition by a bit-wise inversion of a mask.
101101For example, the FUSE_EESAVE fuse in the ATmega128 is defined as:
102102\code
103103#define FUSE_EESAVE ~_BV(3)
104104\endcode
105105\note The _BV macro creates a bit mask from a bit number. It is then
106106inverted to represent logical values for a fuse memory byte.
107107108108To combine the fuse bits macros together to represent a whole fuse byte,
109109use the bitwise AND operator, like so:
110110\code
111111(FUSE_BOOTSZ0 & FUSE_BOOTSZ1 & FUSE_EESAVE & FUSE_SPIEN & FUSE_JTAGEN)
112112\endcode
113113114114Each device I/O header file also defines macros that provide default values
115115for each fuse byte that is available. LFUSE_DEFAULT is defined for a Low
116116Fuse byte. HFUSE_DEFAULT is defined for a High Fuse byte. EFUSE_DEFAULT
117117is defined for an Extended Fuse byte.
118118119119If FUSE_MEMORY_SIZE >> 3, then the I/O header file defines macros that
120120provide default values for each fuse byte like so:
121121FUSE0_DEFAULT
122122FUSE1_DEFAULT
123123FUSE2_DEFAULT
124124FUSE3_DEFAULT
125125FUSE4_DEFAULT
126126....
127127128128\par API Usage Example
129129130130Putting all of this together is easy. Using C99's designated initializers:
131131132132\code
133133#include <avr/io.h>
134134
135135FUSES =
136136{
137137.low = LFUSE_DEFAULT,
138138.high = (FUSE_BOOTSZ0 & FUSE_BOOTSZ1 & FUSE_EESAVE & FUSE_SPIEN & FUSE_JTAGEN),
139139.extended = EFUSE_DEFAULT,
140140};
141141
142142int main(void)
143143{
144144return 0;
145145}
146146\endcode
147147148148Or, using the variable directly instead of the FUSES macro,
149149150150\code
151151#include <avr/io.h>
152152
153153__fuse_t __fuse __attribute__((section (".fuse"))) =
154154{
155155.low = LFUSE_DEFAULT,
156156.high = (FUSE_BOOTSZ0 & FUSE_BOOTSZ1 & FUSE_EESAVE & FUSE_SPIEN & FUSE_JTAGEN),
157157.extended = EFUSE_DEFAULT,
158158};
159159
160160int main(void)
161161{
162162return 0;
163163}
164164\endcode
165165166166If you are compiling in C++, you cannot use the designated intializers so
167167you must do:
168168
169169\code
170170#include <avr/io.h>
171171
172172FUSES =
173173{
174174LFUSE_DEFAULT, // .low
175175(FUSE_BOOTSZ0 & FUSE_BOOTSZ1 & FUSE_EESAVE & FUSE_SPIEN & FUSE_JTAGEN), // .high
176176EFUSE_DEFAULT, // .extended
177177};
178178
179179int main(void)
180180{
181181return 0;
182182}
183183\endcode
184184185185186186However there are a number of caveats that you need to be aware of to
187187use this API properly.
188188189189Be sure to include <avr/io.h> to get all of the definitions for the API.
190190The FUSES macro defines a global variable to store the fuse data. This
191191variable is assigned to its own linker section. Assign the desired fuse
192192values immediately in the variable initialization.
193193194194The .fuse section in the ELF file will get its values from the initial
195195variable assignment ONLY. This means that you can NOT assign values to
196196this variable in functions and the new values will not be put into the
197197ELF .fuse section.
198198199199The global variable is declared in the FUSES macro has two leading
200200underscores, which means that it is reserved for the "implementation",
201201meaning the library, so it will not conflict with a user-named variable.
202202203203You must initialize ALL fields in the __fuse_t structure. This is because
204204the fuse bits in all bytes default to a logical 1, meaning unprogrammed.
205205Normal uninitialized data defaults to all locgial zeros. So it is vital that
206206all fuse bytes are initialized, even with default data. If they are not,
207207then the fuse bits may not programmed to the desired settings.
208208209209Be sure to have the -mmcu=<em>device</em> flag in your compile command line and
210210your linker command line to have the correct device selected and to have
211211the correct I/O header file included when you include <avr/io.h>.
212212
213213You can print out the contents of the .fuse section in the ELF file by
214214using this command line:
215215\code
216216avr-objdump -s -j .fuse <ELF file>
217217\endcode
218218The section contents shows the address on the left, then the data going from
219219lower address to a higher address, left to right.
220220
221221*/
222222
223223#if !(defined(__ASSEMBLER__) || defined(__DOXYGEN__))
224224
225225#ifndef FUSEMEM
226226#define FUSEMEM __attribute__((__used__, __section__ (".fuse")))
227227#endif
228228
229229#if FUSE_MEMORY_SIZE >> 3
230230
231231typedef struct
232232{
233233unsigned char byte[FUSE_MEMORY_SIZE];
234234} __fuse_t;
235235
236236
237237#elif FUSE_MEMORY_SIZE == 3
238238
239239typedef struct
240240{
241241unsigned char low;
242242unsigned char high;
243243unsigned char extended;
244244} __fuse_t;
245245
246246#elif FUSE_MEMORY_SIZE == 2
247247
248248typedef struct
249249{
250250unsigned char low;
251251unsigned char high;
252252} __fuse_t;
253253
254254#elif FUSE_MEMORY_SIZE == 1
255255
256256typedef struct
257257{
258258unsigned char byte;
259259} __fuse_t;
260260
261261#endif
262262
263263#if !defined(FUSES)
264264#if defined(__AVR_XMEGA__)
265265#define FUSES NVM_FUSES_t __fuse FUSEMEM
266266#else
267267#define FUSES __fuse_t __fuse FUSEMEM
268268#endif
269269#endif
270270
271271
272272#endif /* !(__ASSEMBLER__ || __DOXYGEN__) */
273273
274274#endif /* _AVR_FUSE_H_ */
