1 //*****************************************************************************
2 //
3 // eeprom.h - Prototypes for the EEPROM driver.
4 //
5 // Copyright (c) 2010-2011 Texas Instruments Incorporated.  All rights reserved.
6 // Software License Agreement
7 //
8 // Texas Instruments (TI) is supplying this software for use solely and
9 // exclusively on TI's microcontroller products. The software is owned by
10 // TI and/or its suppliers, and is protected under applicable copyright
11 // laws. You may not combine this software with "viral" open-source
12 // software in order to form a larger program.
13 //
14 // THIS SOFTWARE IS PROVIDED "AS IS" AND WITH ALL FAULTS.
15 // NO WARRANTIES, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT
16 // NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
17 // A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. TI SHALL NOT, UNDER ANY
18 // CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
19 // DAMAGES, FOR ANY REASON WHATSOEVER.
20 //
21 // This is part of revision 8264 of the Stellaris Peripheral Driver Library.
22 //
23 //*****************************************************************************
24 
25 #ifndef __EEPROM_H__
26 #define __EEPROM_H__
27 
28 //*****************************************************************************
29 //
30 // If building with a C++ compiler, make all of the definitions in this header
31 // have a C binding.
32 //
33 //*****************************************************************************
34 #ifdef __cplusplus
35 extern "C"
36 {
37 #endif
38 
39 //*****************************************************************************
40 //
41 //! \addtogroup eeprom_api
42 //! @{
43 //
44 //*****************************************************************************
45 
46 //*****************************************************************************
47 //
48 // Values returned by EEPROMInit.
49 //
50 //*****************************************************************************
51 
52 //
53 //! This value may be returned from a call to EEPROMInit().  It indicates that
54 //! no previous write operations were interrupted by a reset event and that the
55 //! EEPROM peripheral is ready for use.
56 //
57 #define EEPROM_INIT_OK      0
58 
59 //
60 //! This value may be returned from a call to EEPROMInit().  It indicates that
61 //! a previous data or protection write operation was interrupted by a reset
62 //! event.  The EEPROM peripheral has recovered its state but the last write
63 //! operation may have been lost.  The application must check the validity of
64 //! data it has written and retry any writes as required.
65 //
66 #define EEPROM_INIT_RETRY   1
67 
68 //
69 //! This value may be returned from a call to EEPROMInit(). It indicates that a
70 //! previous data or protection write operation was interrupted by a reset
71 //! event and that the EEPROM peripheral was unable to clean up after the
72 //! problem.  This situation may be resolved with another reset or may be fatal
73 //! depending upon the cause of the problem.  For example, if the voltage to
74 //! the part is unstable, retrying once the voltage has stabilized may clear
75 //! the error.
76 //
77 #define EEPROM_INIT_ERROR   2
78 
79 //*****************************************************************************
80 //
81 // Error indicators returned by various EEPROM API calls.  These will be ORed
82 // together into the final return code.
83 //
84 //*****************************************************************************
85 
86 //
87 //! This return code bit indicates that the EEPROM programming state machine
88 //! failed to write a value due to the voltage level dropping below that
89 //! required for EEPROM programming.  The operation may be retried once the
90 //! voltage stabilizes.
91 //
92 #define EEPROM_RC_INVPL             0x00000100
93 
94 //
95 //! This return code bit indicates that an attempt was made to read from
96 //! the EEPROM while a write operation was in progress.
97 //
98 #define EEPROM_RC_WRBUSY            0x00000020
99 
100 //
101 //! This return code bit indicates that an attempt was made to write a
102 //! value but the destination permissions disallow write operations.  This
103 //! may be due to the destination block being locked, access protection set
104 //! to prohibit writes or an attempt to write a password when one is already
105 //! written.
106 //
107 #define EEPROM_RC_NOPERM            0x00000010
108 
109 //
110 //! This return code bit indicates that the EEPROM programming state machine
111 //! is currently copying to or from the internal copy buffer to make room for
112 //! a newly written value.  It is provided as a status indicator and does not
113 //! indicate an error.
114 //
115 #define EEPROM_RC_WKCOPY            0x00000008
116 
117 //
118 //! This return code bit indicates that the EEPROM programming state machine
119 //! is currently erasing the internal copy buffer.  It is provided as a
120 //! status indicator and does not indicate an error.
121 //
122 #define EEPROM_RC_WKERASE           0x00000004
123 
124 //
125 //! This return code bit indicates that the EEPROM programming state machine
126 //! is currently working.  No new write operations should be attempted until
127 //! this bit is clear.
128 //
129 #define EEPROM_RC_WORKING           0x00000001
130 
131 //*****************************************************************************
132 //
133 // Values that can be passed to EEPROMBlockProtectSet() in the ulProtect
134 // parameter, and returned by EEPROMBlockProtectGet().
135 //
136 //*****************************************************************************
137 
138 //
139 //! This bit may be ORed with the protection option passed to
140 //! EEPROMBlockProtectSet() or returned from EEPROMBlockProtectGet().  It
141 //! restricts EEPROM access to threads running in supervisor mode and prevents
142 //! access to an EEPROM block when the CPU is in user mode.
143 //
144 #define EEPROM_PROT_SUPERVISOR_ONLY 0x00000008
145 
146 //
147 //! This value may be passed to EEPROMBlockProtectSet() or returned from
148 //! EEPROMBlockProtectGet().  It indicates that the block should offer
149 //! read/write access when no password is set or when a password is set and
150 //! the block is unlocked, and read-only access when a password is set but
151 //! the block is locked.
152 //
153 #define EEPROM_PROT_RW_LRO_URW      0x00000000
154 
155 //
156 //! This value may be passed to EEPROMBlockProtectSet() or returned from
157 //! EEPROMBlockProtectGet().  It indicates that the block should offer neither
158 //! read nor write access unless it is protected by a password and unlocked.
159 //
160 #define EEPROM_PROT_NA_LNA_URW      0x00000001
161 
162 //
163 //! This value may be passed to EEPROMBlockProtectSet() or returned from
164 //! EEPROMBlockProtectGet().  It indicates that the block should offer
165 //! read-only access when no password is set or when a password is set and the
166 //! block is unlocked.  When a password is set and the block is locked, neither
167 //! read nor write access is permitted.
168 //
169 #define EEPROM_PROT_RO_LNA_URO      0x00000002
170 
171 //*****************************************************************************
172 //
173 //! This value may be passed to EEPROMIntEnable() and EEPROMIntDisable() and is
174 //! returned by EEPROMIntStatus() if an EEPROM interrupt is currently being
175 //! signaled.
176 //
177 //*****************************************************************************
178 #define EEPROM_INT_PROGRAM          0x00000004
179 
180 //*****************************************************************************
181 //
182 //! Returns the EEPROM block number containing a given offset address.
183 //!
184 //! \param ulAddr is the linear, byte address of the EEPROM location whose
185 //! block number is to be returned.  This is a zero-based offset from the start
186 //! of the EEPROM storage.
187 //!
188 //! This macro may be used to translate an EEPROM address offset into a
189 //! block number suitable for use in any of the driver's block protection
190 //! functions.  The address provided is expressed as a byte offset from the
191 //! base of the EEPROM.
192 //!
193 //! \return Returns the zero-based block number which contains the passed
194 //! address.
195 //
196 //*****************************************************************************
197 #define EEPROMBlockFromAddr(ulAddr) ((ulAddr) >> 6)
198 
199 //*****************************************************************************
200 //
201 //! Returns the offset address of the first word in an EEPROM block.
202 //!
203 //! \param ulBlock is the index of the EEPROM block whose first word address
204 //! is to be returned.
205 //!
206 //! This macro may be used to determine the address of the first word in a
207 //! given EEPROM block.  The address returned is expressed as a byte offset
208 //! from the base of EEPROM storage.
209 //!
210 //! \return Returns the address of the first word in the given EEPROM block.
211 //
212 //*****************************************************************************
213 #define EEPROMAddrFromBlock(ulBlock) ((ulBlock) << 6)
214 
215 //*****************************************************************************
216 //
217 // Prototypes for the APIs.
218 //
219 //*****************************************************************************
220 extern unsigned long EEPROMInit(void);
221 extern unsigned long EEPROMSizeGet(void);
222 extern unsigned long EEPROMBlockCountGet(void);
223 extern void EEPROMRead(unsigned long *pulData, unsigned long ulAddress,
224                        unsigned long ulCount);
225 extern unsigned long EEPROMProgram(unsigned long *pulData,
226                                    unsigned long ulAddress,
227                                    unsigned long ulCount);
228 extern unsigned long EEPROMProgramNonBlocking(unsigned long ulData,
229                                               unsigned long ulAddress);
230 extern unsigned long EEPROMStatusGet(void);
231 extern unsigned long EEPROMMassErase(void);
232 extern unsigned long EEPROMBlockProtectGet(unsigned long ulBlock);
233 extern unsigned long EEPROMBlockProtectSet(unsigned long ulBlock,
234                                            unsigned long ulProtect);
235 extern unsigned long EEPROMBlockPasswordSet(unsigned long ulBlock,
236                                             unsigned long *pulPassword,
237                                             unsigned long ulCount);
238 extern unsigned long EEPROMBlockLock(unsigned long ulBlock);
239 extern unsigned long EEPROMBlockUnlock(unsigned long ulBlock,
240                                        unsigned long *pulPassword,
241                                        unsigned long ulCount);
242 extern void EEPROMBlockHide(unsigned long ulBlock);
243 extern void EEPROMIntEnable(unsigned long ulIntFlags);
244 extern void EEPROMIntDisable(unsigned long ulIntFlags);
245 extern unsigned long EEPROMIntStatus(tBoolean bMasked);
246 extern void EEPROMIntClear(unsigned long ulIntFlags);
247 
248 //*****************************************************************************
249 //
250 // Close the Doxygen group.
251 //! @}
252 //
253 //*****************************************************************************
254 
255 //*****************************************************************************
256 //
257 // Mark the end of the C bindings section for C++ compilers.
258 //
259 //*****************************************************************************
260 #ifdef __cplusplus
261 }
262 #endif
263 
264 #endif // __EEPROM_H__
265