avr-libc  2.0.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

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: eeprom_8h_source.html,v 1.1.1.6 2016/02/09 07:13:47 joerg_wunsch Exp $ */
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 are 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
92 extern "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 (__AVR_XMEGA__) && __AVR_XMEGA__
116 # define eeprom_is_ready() bit_is_clear (NVM_STATUS, NVM_NVMBUSY_bp)
117 #elif defined (DEECR)
118 # define eeprom_is_ready() bit_is_clear (DEECR, BSY)
119 #elif defined (EEPE)
120 # define eeprom_is_ready() bit_is_clear (EECR, EEPE)
121 #else
122 # define eeprom_is_ready() bit_is_clear (EECR, EEWE)
123 #endif
124 
125 
126 /** \def eeprom_busy_wait
127  \ingroup avr_eeprom
128  Loops until the eeprom is no longer busy.
129  \returns Nothing.
130  */
131 #define eeprom_busy_wait() do {} while (!eeprom_is_ready())
132 
133 
134 /** \ingroup avr_eeprom
135  Read one byte from EEPROM address \a __p.
136  */
137 uint8_t eeprom_read_byte (const uint8_t *__p) __ATTR_PURE__;
138 
139 /** \ingroup avr_eeprom
140  Read one 16-bit word (little endian) from EEPROM address \a __p.
141  */
142 uint16_t eeprom_read_word (const uint16_t *__p) __ATTR_PURE__;
143 
144 /** \ingroup avr_eeprom
145  Read one 32-bit double word (little endian) from EEPROM address \a __p.
146  */
147 uint32_t eeprom_read_dword (const uint32_t *__p) __ATTR_PURE__;
148 
149 /** \ingroup avr_eeprom
150  Read one float value (little endian) from EEPROM address \a __p.
151  */
152 float eeprom_read_float (const float *__p) __ATTR_PURE__;
153 
154 /** \ingroup avr_eeprom
155  Read a block of \a __n bytes from EEPROM address \a __src to SRAM
156  \a __dst.
157  */
158 void eeprom_read_block (void *__dst, const void *__src, size_t __n);
159 
160 
161 /** \ingroup avr_eeprom
162  Write a byte \a __value to EEPROM address \a __p.
163  */
164 void eeprom_write_byte (uint8_t *__p, uint8_t __value);
165 
166 /** \ingroup avr_eeprom
167  Write a word \a __value to EEPROM address \a __p.
168  */
169 void eeprom_write_word (uint16_t *__p, uint16_t __value);
170 
171 /** \ingroup avr_eeprom
172  Write a 32-bit double word \a __value to EEPROM address \a __p.
173  */
174 void eeprom_write_dword (uint32_t *__p, uint32_t __value);
175 
176 /** \ingroup avr_eeprom
177  Write a float \a __value to EEPROM address \a __p.
178  */
179 void eeprom_write_float (float *__p, float __value);
180 
181 /** \ingroup avr_eeprom
182  Write a block of \a __n bytes to EEPROM address \a __dst from \a __src.
183  \note The argument order is mismatch with common functions like strcpy().
184  */
185 void eeprom_write_block (const void *__src, void *__dst, size_t __n);
186 
187 
188 /** \ingroup avr_eeprom
189  Update a byte \a __value to EEPROM address \a __p.
190  */
191 void eeprom_update_byte (uint8_t *__p, uint8_t __value);
192 
193 /** \ingroup avr_eeprom
194  Update a word \a __value to EEPROM address \a __p.
195  */
196 void eeprom_update_word (uint16_t *__p, uint16_t __value);
197 
198 /** \ingroup avr_eeprom
199  Update a 32-bit double word \a __value to EEPROM address \a __p.
200  */
201 void eeprom_update_dword (uint32_t *__p, uint32_t __value);
202 
203 /** \ingroup avr_eeprom
204  Update a float \a __value to EEPROM address \a __p.
205  */
206 void eeprom_update_float (float *__p, float __value);
207 
208 /** \ingroup avr_eeprom
209  Update a block of \a __n bytes to EEPROM address \a __dst from \a __src.
210  \note The argument order is mismatch with common functions like strcpy().
211  */
212 void eeprom_update_block (const void *__src, void *__dst, size_t __n);
213 
214 
215 /** \name IAR C compatibility defines */
216 /*@{*/
217 
218 /** \def _EEPUT
219  \ingroup avr_eeprom
220  Write a byte to EEPROM. Compatibility define for IAR C. */
221 #define _EEPUT(addr, val) eeprom_write_byte ((uint8_t *)(addr), (uint8_t)(val))
222 
223 /** \def __EEPUT
224  \ingroup avr_eeprom
225  Write a byte to EEPROM. Compatibility define for IAR C. */
226 #define __EEPUT(addr, val) eeprom_write_byte ((uint8_t *)(addr), (uint8_t)(val))
227 
228 /** \def _EEGET
229  \ingroup avr_eeprom
230  Read a byte from EEPROM. Compatibility define for IAR C. */
231 #define _EEGET(var, addr) (var) = eeprom_read_byte ((const uint8_t *)(addr))
232 
233 /** \def __EEGET
234  \ingroup avr_eeprom
235  Read a byte from EEPROM. Compatibility define for IAR C. */
236 #define __EEGET(var, addr) (var) = eeprom_read_byte ((const uint8_t *)(addr))
237 
238 /*@}*/
239 
240 #ifdef __cplusplus
241 }
242 #endif
243 
244 #endif /* !__ASSEMBLER__ */
245 #endif /* E2END || defined(__DOXYGEN__) || defined(__COMPILING_AVR_LIBC__) */
246 #endif /* !_AVR_EEPROM_H_ */
void eeprom_update_block(const void *__src, void *__dst, size_t __n)
void eeprom_write_block(const void *__src, void *__dst, size_t __n)
void eeprom_update_word(uint16_t *__p, uint16_t __value)
void eeprom_write_byte(uint8_t *__p, uint8_t __value)
void eeprom_read_block(void *__dst, const void *__src, size_t __n)
void eeprom_write_dword(uint32_t *__p, uint32_t __value)
float eeprom_read_float(const float *__p) __ATTR_PURE__
void eeprom_update_dword(uint32_t *__p, uint32_t __value)
void eeprom_write_float(float *__p, float __value)
void eeprom_update_byte(uint8_t *__p, uint8_t __value)
unsigned char uint8_t
Definition: stdint.h:83
unsigned long int uint32_t
Definition: stdint.h:103
uint32_t eeprom_read_dword(const uint32_t *__p) __ATTR_PURE__
void eeprom_write_word(uint16_t *__p, uint16_t __value)
void eeprom_update_float(float *__p, float __value)
uint8_t eeprom_read_byte(const uint8_t *__p) __ATTR_PURE__
uint16_t eeprom_read_word(const uint16_t *__p) __ATTR_PURE__
unsigned int uint16_t
Definition: stdint.h:93