AVR-LibC  2.2.0
Standard C library for AVR-GCC
 

AVR-LibC Documentation

Logo

AVR-LibC Development Pages

Main Page

User Manual

Library Reference

FAQ

Example Projects

File List

Loading...
Searching...
No Matches
eeprom.h
1/* Copyright (c) 2002, 2003, 2004, 2007 Marek Michalkiewicz
2 Copyright (c) 2005, 2006 Bjoern Haase
3 Copyright (c) 2008 Atmel Corporation
4 Copyright (c) 2008 Wouter van Gulik
5 Copyright (c) 2009 Dmitry Xmelkov
6 All rights reserved.
7
8 Redistribution and use in source and binary forms, with or without
9 modification, are permitted provided that the following conditions are met:
10
11 * Redistributions of source code must retain the above copyright
12 notice, this list of conditions and the following disclaimer.
13 * Redistributions in binary form must reproduce the above copyright
14 notice, this list of conditions and the following disclaimer in
15 the documentation and/or other materials provided with the
16 distribution.
17 * Neither the name of the copyright holders nor the names of
18 contributors may be used to endorse or promote products derived
19 from this software without specific prior written permission.
20
21 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
22 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
25 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
26 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
27 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
28 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
29 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
30 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
31 POSSIBILITY OF SUCH DAMAGE. */
32
33/* $Id$ */
34
35#ifndef _AVR_EEPROM_H_
36#define _AVR_EEPROM_H_ 1
37
38#include <avr/io.h>
39
40#if !E2END && !defined(__DOXYGEN__) && !defined(__COMPILING_AVR_LIBC__)
41# warning "Device does not have EEPROM available."
42#else
43
44#if defined (EEAR) && !defined (EEARL) && !defined (EEARH)
45#define EEARL EEAR
46#endif
47
48#ifndef __ASSEMBLER__
49
50#include <stddef.h> /* size_t */
51#include <stdint.h>
52
53/** \defgroup avr_eeprom <avr/eeprom.h>: EEPROM handling
54 \code #include <avr/eeprom.h> \endcode
55
56 This header file declares the interface to some simple library
57 routines suitable for handling the data EEPROM contained in the
58 AVR microcontrollers. The implementation uses a simple polled
59 mode interface. Applications that require interrupt-controlled
60 EEPROM access to ensure that no time will be wasted in spinloops
61 will have to deploy their own implementation.
62
63 \par Notes:
64
65 - In addition to the write functions there is a set of update ones.
66 This functions read each byte first and skip the burning if the
67 old value is the same with new. The scaning direction is from
68 high address to low, to obtain quick return in common cases.
69
70 - All of the read/write functions first make sure the EEPROM is
71 ready to be accessed. Since this may cause long delays if a
72 write operation is still pending, time-critical applications
73 should first poll the EEPROM e. g. using eeprom_is_ready() before
74 attempting any actual I/O. But this functions does not wait until
75 SELFPRGEN in SPMCSR becomes zero. Do this manually, if your
76 softwate contains the Flash burning.
77
78 - As these functions modify IO registers, they are known to be
79 non-reentrant. If any of these functions are used from both,
80 standard and interrupt context, the applications must ensure
81 proper protection (e.g. by disabling interrupts before accessing
82 them).
83
84 - All write functions force erase_and_write programming mode.
85
86 - For Xmega the EEPROM start address is 0, like other architectures.
87 The reading functions add the 0x2000 value to use EEPROM mapping into
88 data space.
89 */
90
91#ifdef __cplusplus
92extern "C" {
93#endif
94
95#ifndef __ATTR_PURE__
96# ifdef __DOXYGEN__
97# define __ATTR_PURE__
98# else
99# define __ATTR_PURE__ __attribute__((__pure__))
100# endif
101#endif
102
103/** \def EEMEM
104 \ingroup avr_eeprom
105 Attribute expression causing a variable to be allocated within the
106 .eeprom section. */
107#define EEMEM __attribute__((__section__(".eeprom")))
108
109/** \def eeprom_is_ready
110 \ingroup avr_eeprom
111 \returns 1 if EEPROM is ready for a new read/write operation, 0 if not.
112 */
113#if defined (__DOXYGEN__)
114# define eeprom_is_ready()
115#elif defined (NVM_STATUS)
116# define eeprom_is_ready() bit_is_clear (NVM_STATUS, NVM_NVMBUSY_bp)
117#elif defined (NVMCTRL_STATUS)
118# define eeprom_is_ready() bit_is_clear (NVMCTRL_STATUS, NVMCTRL_EEBUSY_bp)
119#elif defined (DEECR)
120# define eeprom_is_ready() bit_is_clear (DEECR, BSY)
121#elif defined (EEPE)
122# define eeprom_is_ready() bit_is_clear (EECR, EEPE)
123#else
124# define eeprom_is_ready() bit_is_clear (EECR, EEWE)
125#endif
126
127
128/** \def eeprom_busy_wait
129 \ingroup avr_eeprom
130 Loops until the eeprom is no longer busy.
131 \returns Nothing.
132 */
133#define eeprom_busy_wait() do {} while (!eeprom_is_ready())
134
135
136/** \ingroup avr_eeprom
137 Read one byte from EEPROM address \a __p.
138 */
139uint8_t eeprom_read_byte (const uint8_t *__p) __ATTR_PURE__;
140
141/** \ingroup avr_eeprom
142 Read one 16-bit word (little endian) from EEPROM address \a __p.
143 */
144uint16_t eeprom_read_word (const uint16_t *__p) __ATTR_PURE__;
145
146/** \ingroup avr_eeprom
147 Read one 32-bit double word (little endian) from EEPROM address \a __p.
148 */
149uint32_t eeprom_read_dword (const uint32_t *__p) __ATTR_PURE__;
150
151/** \ingroup avr_eeprom
152 Read one 64-bit quad word (little endian) from EEPROM address \a __p.
153 */
154#if defined(__DOXYGEN__) || __SIZEOF_LONG_LONG__ == 8
155uint64_t eeprom_read_qword (const uint64_t *__p) __ATTR_PURE__;
156#endif
157
158/** \ingroup avr_eeprom
159 Read one float value (little endian) from EEPROM address \a __p.
160 */
161float eeprom_read_float (const float *__p) __ATTR_PURE__;
162
163/** \ingroup avr_eeprom
164 Read one double value (little endian) from EEPROM address \a __p.
165 */
166#if defined(__DOXYGEN__)
167double eeprom_read_double (const double *__p);
168#elif __SIZEOF_DOUBLE__ == 4
169double eeprom_read_double (const double *__p) __asm("eeprom_read_dword");
170#elif __SIZEOF_DOUBLE__ == 8
171double eeprom_read_double (const double *__p) __asm("eeprom_read_qword");
172#endif
173
174/** \ingroup avr_eeprom
175 Read one long double value (little endian) from EEPROM address \a __p.
176 */
177#if defined(__DOXYGEN__)
178long double eeprom_read_long_double (const long double *__p);
179#elif __SIZEOF_LONG_DOUBLE__ == 4
180long double eeprom_read_long_double (const long double *__p) __asm("eeprom_read_dword");
181#elif __SIZEOF_LONG_DOUBLE__ == 8
182long double eeprom_read_long_double (const long double *__p) __asm("eeprom_read_qword");
183#endif
184
185/** \ingroup avr_eeprom
186 Read a block of \a __n bytes from EEPROM address \a __src to SRAM
187 \a __dst.
188 */
189void eeprom_read_block (void *__dst, const void *__src, size_t __n);
190
191
192/** \ingroup avr_eeprom
193 Write a byte \a __value to EEPROM address \a __p.
194 */
195void eeprom_write_byte (uint8_t *__p, uint8_t __value);
196
197/** \ingroup avr_eeprom
198 Write a word \a __value to EEPROM address \a __p.
199 */
200void eeprom_write_word (uint16_t *__p, uint16_t __value);
201
202/** \ingroup avr_eeprom
203 Write a 32-bit double word \a __value to EEPROM address \a __p.
204 */
205void eeprom_write_dword (uint32_t *__p, uint32_t __value);
206
207/** \ingroup avr_eeprom
208 Write a 64-bit quad word \a __value to EEPROM address \a __p.
209 */
210#if defined(__DOXYGEN__) || __SIZEOF_LONG_LONG__ == 8
211void eeprom_write_qword (uint64_t *__p, uint64_t __value);
212#endif
213
214/** \ingroup avr_eeprom
215 Write a float \a __value to EEPROM address \a __p.
216 */
217void eeprom_write_float (float *__p, float __value);
218
219/** \ingroup avr_eeprom
220 Write a double \a __value to EEPROM address \a __p.
221 */
222#if defined(__DOXYGEN__)
223void eeprom_write_double (double *__p, double __value);
224#elif __SIZEOF_DOUBLE__ == 4
225void eeprom_write_double (double *__p, double __value) __asm("eeprom_write_dword");
226#elif __SIZEOF_DOUBLE__ == 8
227void eeprom_write_double (double *__p, double __value) __asm("eeprom_write_qword");
228#endif
229
230/** \ingroup avr_eeprom
231 Write a long double \a __value to EEPROM address \a __p.
232 */
233#if defined(__DOXYGEN__)
234void eeprom_write_long_double (long double *__p, long double __value);
235#elif __SIZEOF_LONG_DOUBLE__ == 4
236void eeprom_write_long_double (long double *__p, long double __value) __asm("eeprom_write_dword");
237#elif __SIZEOF_LONG_DOUBLE__ == 8
238void eeprom_write_long_double (long double *__p, long double __value) __asm("eeprom_write_qword");
239#endif
240
241/** \ingroup avr_eeprom
242 Write a block of \a __n bytes to EEPROM address \a __dst from \a __src.
243 \note The argument order is mismatch with common functions like strcpy().
244 */
245void eeprom_write_block (const void *__src, void *__dst, size_t __n);
246
247
248/** \ingroup avr_eeprom
249 Update a byte \a __value at EEPROM address \a __p.
250 */
251void eeprom_update_byte (uint8_t *__p, uint8_t __value);
252
253/** \ingroup avr_eeprom
254 Update a word \a __value at EEPROM address \a __p.
255 */
256void eeprom_update_word (uint16_t *__p, uint16_t __value);
257
258/** \ingroup avr_eeprom
259 Update a 32-bit double word \a __value at EEPROM address \a __p.
260 */
261void eeprom_update_dword (uint32_t *__p, uint32_t __value);
262
263/** \ingroup avr_eeprom
264 Update a 64-bit quad word \a __value at EEPROM address \a __p.
265 */
266#if defined(__DOXYGEN__) || __SIZEOF_LONG_LONG__ == 8
267void eeprom_update_qword (uint64_t *__p, uint64_t __value);
268#endif
269
270/** \ingroup avr_eeprom
271 Update a float \a __value at EEPROM address \a __p.
272 */
273void eeprom_update_float (float *__p, float __value);
274
275/** \ingroup avr_eeprom
276 Update a double \a __value at EEPROM address \a __p.
277 */
278#if defined(__DOXYGEN__)
279void eeprom_update_double (double *__p, double __value);
280#elif __SIZEOF_DOUBLE__ == 4
281void eeprom_update_double (double *__p, double __value) __asm("eeprom_update_dword");
282#elif __SIZEOF_DOUBLE__ == 8
283void eeprom_update_double (double *__p, double __value) __asm("eeprom_update_qword");
284#endif
285
286/** \ingroup avr_eeprom
287 Update a long double \a __value at EEPROM address \a __p.
288 */
289#if defined(__DOXYGEN__)
290void eeprom_update_long_double (long double *__p, long double __value);
291#elif __SIZEOF_LONG_DOUBLE__ == 4
292void eeprom_update_long_double (long double *__p, long double __value) __asm("eeprom_update_dword");
293#elif __SIZEOF_LONG_DOUBLE__ == 8
294void eeprom_update_long_double (long double *__p, long double __value) __asm("eeprom_update_qword");
295#endif
296
297/** \ingroup avr_eeprom
298 Update a block of \a __n bytes at EEPROM address \a __dst from \a __src.
299 \note The argument order is mismatch with common functions like strcpy().
300 */
301void eeprom_update_block (const void *__src, void *__dst, size_t __n);
302
303
304/** \name IAR C compatibility defines */
305/**@{*/
306
307/** \def _EEPUT
308 \ingroup avr_eeprom
309 Write a byte to EEPROM. Compatibility define for IAR C. */
310#define _EEPUT(addr, val) eeprom_write_byte ((uint8_t *)(addr), (uint8_t)(val))
311
312/** \def __EEPUT
313 \ingroup avr_eeprom
314 Write a byte to EEPROM. Compatibility define for IAR C. */
315#define __EEPUT(addr, val) eeprom_write_byte ((uint8_t *)(addr), (uint8_t)(val))
316
317/** \def _EEGET
318 \ingroup avr_eeprom
319 Read a byte from EEPROM. Compatibility define for IAR C. */
320#define _EEGET(var, addr) (var) = eeprom_read_byte ((const uint8_t *)(addr))
321
322/** \def __EEGET
323 \ingroup avr_eeprom
324 Read a byte from EEPROM. Compatibility define for IAR C. */
325#define __EEGET(var, addr) (var) = eeprom_read_byte ((const uint8_t *)(addr))
326
327/**@}*/
328
329#ifdef __cplusplus
330}
331#endif
332
333#endif /* !__ASSEMBLER__ */
334#endif /* E2END || defined(__DOXYGEN__) || defined(__COMPILING_AVR_LIBC__) */
335#endif /* !_AVR_EEPROM_H_ */
void eeprom_write_dword(uint32_t *__p, uint32_t __value)
void eeprom_read_block(void *__dst, const void *__src, size_t __n)
void eeprom_update_float(float *__p, float __value)
void eeprom_update_word(uint16_t *__p, uint16_t __value)
void eeprom_write_long_double(long double *__p, long double __value)
void eeprom_write_word(uint16_t *__p, uint16_t __value)
uint8_t eeprom_read_byte(const uint8_t *__p)
double eeprom_read_double(const double *__p)
long double eeprom_read_long_double(const long double *__p)
uint16_t eeprom_read_word(const uint16_t *__p)
void eeprom_update_byte(uint8_t *__p, uint8_t __value)
void eeprom_write_byte(uint8_t *__p, uint8_t __value)
void eeprom_update_double(double *__p, double __value)
void eeprom_update_long_double(long double *__p, long double __value)
void eeprom_update_qword(uint64_t *__p, uint64_t __value)
void eeprom_update_block(const void *__src, void *__dst, size_t __n)
void eeprom_update_dword(uint32_t *__p, uint32_t __value)
void eeprom_write_qword(uint64_t *__p, uint64_t __value)
float eeprom_read_float(const float *__p)
void eeprom_write_block(const void *__src, void *__dst, size_t __n)
void eeprom_write_float(float *__p, float __value)
void eeprom_write_double(double *__p, double __value)
uint64_t eeprom_read_qword(const uint64_t *__p)
uint32_t eeprom_read_dword(const uint32_t *__p)
unsigned int uint16_t
Definition: stdint.h:93
unsigned long int uint32_t
Definition: stdint.h:103
unsigned char uint8_t
Definition: stdint.h:83
unsigned long long int uint64_t
Definition: stdint.h:117