1 /**

2 * @file xmc1_flash.h
3 * @date 2015-06-20
4 *
5 * @cond
6
*************************************************************************************
********************************
7 * XMClib v2.0.0 - XMC Peripheral Driver Library
8 *
9 * Copyright (c) 2015, Infineon Technologies AG
10 * All rights reserved.
11 *
12 * Redistribution and use in source and binary forms, with or without
modification,are permitted provided that the
13 * following conditions are met:
14 *
15 * Redistributions of source code must retain the above copyright notice, this list
of conditions and the following
16 * disclaimer.
17 *
18 * Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following
19 * disclaimer in the documentation and/or other materials provided with the
distribution.
20 *
21 * Neither the name of the copyright holders nor the names of its contributors may be
used to endorse or promote
22 * products derived from this software without specific prior written
permission.
23 *
24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES,
25 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE
26 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL,
27 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR
28 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
AND ON ANY THEORY OF LIABILITY,
29 * WHETHER IN CONTRACT, STRICT LIABILITY,OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE
30 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
31 *
32 * To improve the quality of the software, users are encouraged to share
modifications, enhancements or bug fixes with
33 * Infineon Technologies AG
dave@infineon.com).
34
*************************************************************************************
********************************
35 *
36 * Change History
37 * --------------
38 *
39 * 2014-12-10:
40 * - Initial <br>
41 * 2015-02-20:
42 * - Updated for Documentation related changes<br>
43 * 2015-06-20:
44 * - Removed version macros and declaration of GetDriverVersion API
45 * @endcond
46 *
47 */
48
49 #ifndef XMC1_FLASH_H
50 #define XMC1_FLASH_H
51
52 /*************************************************************************************
********************************
53 * HEADER FILES
 54
*************************************************************************************
*******************************/
55
56 #include "xmc_common.h"
57
58 #if UC_FAMILY == XMC1
59
60 #include <XMC1000_RomFunctionTable.h>
61
62 /**
63 * @addtogroup XMClib XMC Peripheral Library
64 * @{
65 */
66
67 /**
68 * @addtogroup FLASH
69 * @{
70 */
71
72 /*************************************************************************************
********************************
73 * MACROS
74
*************************************************************************************
*******************************/
75
76 #define XMC_FLASH_PAGES_PER_SECTOR (16U) /**< Number of pages in a sector. A page
consists of 16 blocks.*/
77 #define XMC_FLASH_BLOCKS_PER_PAGE (16U) /**< Number of blocks in a page. A block
consists of 4 words(16 bytes).*/
78
79 #define XMC_FLASH_BYTES_PER_SECTOR (4096U) /**< Number of bytes in a sector. (16
pages * 256 bytes = 4096 bytes)*/
80 #define XMC_FLASH_BYTES_PER_PAGE (256U) /**< Number of bytes in a page. (16
blocks * 16 bytes = 256 bytes)*/
81 #define XMC_FLASH_BYTES_PER_BLOCK (16U) /**< Number of bytes in a block. (128
bits = 16 bytes)*/
82
83 #define XMC_FLASH_WORDS_PER_SECTOR (1024U) /**< Number of words in a sector. (16
pages * 64 words = 1024 words)*/
84 #define XMC_FLASH_WORDS_PER_PAGE (64U) /**< Number of words in a page. (16
blocks * 4 words = 64 words) */
85 #define XMC_FLASH_WORDS_PER_BLOCK (4U) /**< Number of words in a block. (128 bit
/ 32 bit = 4 words) */
86
87 #define FLASH_BLOCK_ADDR_MASK (15U) /* Bitwise AND with block address is
done to check the address alignment.
88 Applicable to
XMC_FLASH_WriteBlocks() and
XMC_FLASH_VerifyBlocks()
89 APIs.*/
90 #define FLASH_PAGE_ADDR_MASK (255U) /* Bitwise AND with page address is
done to check the address alignment.
91 Applicable to XMC_FLASH_ErasePages()
API.*/
92 #define FLASH_SECTOR_ADDR_MASK (4095U) /* Bitwise AND with sector address is
done to check the address alignment.
93 Applicable to XMC_FLASH_EraseSector
API.*/
94
95 #define XMC_FLASH_BASE (0x10001000U) /**< Starting address of flash for
XMC1 family of microcontrollers*/
96
97 /*************************************************************************************
********************************
98 * ENUMS
99
*************************************************************************************
*******************************/
100 /**
101 * Defines the status of flash, to verify the flash related API calls. Use type \a
XMC_FLASH_STATUS_t for this enum.
102 * The members defines the respective masked status bits of \a NVMSTATUS register.
103 */
104 typedef enum XMC_FLASH_STATUS
105 {
106 XMC_FLASH_STATUS_OK = 0U, /**< Flash
related operation was successfully
107
completed*/
108 XMC_FLASH_STATUS_BUSY = NVM_NVMSTATUS_BUSY_Msk , /**< Cannot
execute the flash request because
109 another
operation is in progress*/
110 XMC_FLASH_STATUS_SLEEP_MODE = NVM_NVMSTATUS_SLEEP_Msk , /**< Flash is
in sleep mode*/
111 XMC_FLASH_STATUS_VERIFY_ERROR = NVM_NVMSTATUS_VERR_Msk , /**< Flash
reported a verification failure*/
112 XMC_FLASH_STATUS_ECC1_READ_ERROR = NVM_NVMSTATUS_ECC1READ_Msk, /**< Flash
reports a single bit failure, and it
113 is
automatically corrected.*/
114 XMC_FLASH_STATUS_ECC2_READ_ERROR = NVM_NVMSTATUS_ECC2READ_Msk, /**< Flash
reported at least two bit failure*/
115 XMC_FLASH_STATUS_WRITE_PROTOCOL_ERROR = NVM_NVMSTATUS_WRPERR_Msk , /**< Write
/Verify operation on a block is
116 failed
due to protocol violations or write
117 protected
sectors*/
118 } XMC_FLASH_STATUS_t;
119
120 /**
121 * Defines NVM ready interrupt event. Use type \a XMC_FLASH_EVENT_t for this enum.
122 */
123 typedef enum XMC_FLASH_EVENT
124 {
125 XMC_FLASH_EVENT_READY = NVM_NVMCONF_INT_ON_Msk /**< Generates the NVM ready
interrupts on flash sequence completion*/
126 } XMC_FLASH_EVENT_t;
127
128 /**
129 * Defines hard read levels for strict data verification. Use type \a
XMC_FLASH_HARDREAD_LEVEL_t for this enum.
130 * These \a hardread levels provide some margin to ensure that the data is really
programmed with suitably distinct
131 * levels for written and erased bits.
132 */
133 typedef enum XMC_FLASH_HARDREAD_LEVEL
134 {
135 XMC_FLASH_HARDREAD_LEVEL_NORMAL = (uint16_t)0x0, /**< No \a hardread level
verification enabled (Normal read)*/
136 XMC_FLASH_HARDREAD_LEVEL_WRITTEN = (uint16_t)0x1, /**< Enables strict margin
compare for written data cells*/
137 XMC_FLASH_HARDREAD_LEVEL_ERASED = (uint16_t)0x2 /**< Enables strict margin
compare for erased data cells*/
138 } XMC_FLASH_HARDREAD_LEVEL_t;
139
140 /*************************************************************************************
*********************************
141 * API PROTOTYPES
142
*************************************************************************************
********************************/
143
144 #ifdef __cplusplus
145 extern "C" {
146 #endif
147
148 /**
149 *
150 * @param address Pointer to the starting address of the flash page from where the
erase starts
151 * @param num_pages Number of pages to be erased.<BR> Range: [1 to (flash size / 256)]
152 *
153 * @return None
154 *
155 * \par<b>Description:</b><BR>
156 * Erases a set of flash memory pages.<BR><BR>
157 * Erase starts from the specified \a address.
158 * It erases a maximum number of \a num_pages flash pages. The maximum erasable pages
are limited to
159 * microcontroller flash size. It sets NVMPROG register to continuous page erase mode
before erase and resets
160 * it action back to normal state on completion. Call XMC_FLASH_GetStatus() after
calling this API to verify the erase
161 * operation.\n
162 *
163 * \par<b>Note:</b><BR>
164 * Flash will be in busy state during erase operation. Hence no operations on flash
are allowed until it completes.\n
165 *
166 * \par<b>Related APIs:</b><BR>
167 * XMC_FLASH_EraseSector(), XMC_FLASH_ErasePage() \n\n\n
168 *
169 * \par<b>Related APIs:</b><BR>
170 * None
171 *
172 */
173 void XMC_FLASH_ErasePages(uint32_t *address, uint32_t num_pages);
174
175 /**
176 *
177 * @param address Pointer to the starting address of flash block from where the
write starts.
178 * @param data Pointer to the source address where targeted data blocks are
located.
179 * @param num_blocks Maximum number of flash block writes needed.<BR> Range: [1 to
(flash size / 16)]
180 * @param verify If \a true, hardware verification after block write is enabled
else disabled.
181 *
182 * @return None
183 *
184 * \par<b>Description:</b><br>
185 * Writes a set of data blocks into the flash.\n\n Minimum possible writable area is
16 byte block. It sets the NVMPROG
186 * register to continuous block write mode before write and resets it action back to
normal state on completion.
187 * Call XMC_FLASH_GetStatus() API after calling this API to verify the erase
operation.
188 *
189 * \par<b>Note</b><br>
190 * Flash will be busy state during write is ongoing, hence no operations allowed
until it completes.
191 *
192 * \par<b>Related APIs:</b><BR>
193 * None
194 *
195 */
196 void XMC_FLASH_WriteBlocks(uint32_t *address, const uint32_t *data, uint32_t
num_blocks, bool verify);
197
198 /**
199 *
200 * @param address Pointer to the starting address of flash block from where the
verification starts.
201 * @param data Pointer to the source address where targeted data blocks are
located.
202 * @param num_blocks Maximum number of flash blocks writes needed.<BR> Range: [1 to
(flash size / 16)]
203 *
204 * @return None
205 *
206 * \par<b>Description:</b><br>
207 * Performs verification of written data blocks.\n\n After calling
XMC_FLASH_WriteBlocks() API, calling this API will
208 * verify the correctness of written blocks. It sets the \a NVMPROG register into
 continuous block write mode before
209 * write and resets it action back to normal state on completion. It reads back the
written data blocks from the flash
210 * and verify the values against the internal buffer values. Calling
XMC_FLASH_GetStatus() API after calling this API
211 * validates the result of verification.
212 *
213 * \par<b>Related APIs:</b><BR>
214 * None
215 *
216 */
217 void XMC_FLASH_VerifyBlocks(uint32_t *address, const uint32_t *data, uint32_t
num_blocks);
218
219
220 /**
221 *
222 * @param address Pointer to the starting address of flash block from where the
read starts.
223 * @param data Pointer to the destination address, where the read data blocks
to be stored.
224 * @param num_blocks Number of blocks to be read.<BR> Range: [1 to (flash size /
16)]
225 *
226 * @return None
227 *
228 * \par<b>Description:</b><br>
229 * Reads multiple blocks from flash in one shot, starting from the \a address
specified.\n\n The read blocks are stored
230 * into the locations starting from the \a data address. Calling
XMC_FLASH_GetStatus() API after calling this API
231 * verifies the read operation.
232 *
233 * \par<b>Related APIs:</b><BR>
234 * None
235 *
236 */
237 void XMC_FLASH_ReadBlocks(uint32_t *address, uint32_t *data, uint32_t num_blocks);
238
239
240 /**
241 *
242 * @param address Pointer to the flash word address from where the read is expected
243 *
244 * @return <BR>
245 * a 32bit data word stored in the specified \a address.
246 *
247 * \par<b>Description:</b><br>
248 * Reads a single word from the specified flash\a address.\n\n Calling
XMC_FLASH_GetStatus() API after calling this
249 * API returns the read status.
250 *
251 * \par<b>Related APIs:</b><BR>
252 * XMC_FLASH_ReadBlocks()
253 *
254 */
255 __STATIC_INLINE uint32_t XMC_FLASH_ReadWord(const uint32_t *const address)
256 {
257 return *address;
258 }
259
260 /**
261 *
262 * @param address Pointer to the starting address of the page to be erased
263 *
264 * @return None
265 *
266 * \par<b>Description:</b><br>
267 * Erases a single flash page associated to the specified \a address.\n\n XMC1000
Flash can be erased with granularity
268 * of one page = 16 blocks of 16 Bytes = 256 Bytes using this API. It internally
calls the Flash Firmware routine
269 * \a XMC1000_NvmErasePage(unsigned long pageAddr) to perform the erase operation.
 Refer XMC1000 reference manual
270 * for more details on flash firmware routines (Section 25.3). Call
XMC_FLASH_GetStatus() API after calling this API,
271 * to verify the erase operation.\n
272 *
273 * \par<b>Related APIs:</b><BR>
274 * XMC_FLASH_ErasePages() \n\n\n
275 */
276 void XMC_FLASH_ErasePage(uint32_t *address);
277
278 /**
279 *
280 * @param address Pointer to the starting address of flash page from where the
programming starts.
281 * @param data Pointer to the source address where targeted data blocks are
located.
282 *
283 * @return None
284 *
285 * \par<b>Description:</b><br>
286 * Erases, programs and verifies a single flash page starting from the \a address
specified.\n\n XMC1000 Flash can be
287 * programmed with granularity of one page = 16 blocks of 16 Bytes = 256 Bytes using
this API. It internally calls the
288 * Flash Firmware routine \a XMC1000_NvmProgVerify(unsigned long pageAddr) to perform
the programming. Refer XMC1000
289 * reference manual of for more details on flash firmware routines (Section 25.3).
Call XMC_FLASH_GetStatus() API after
290 * calling this API, to verify the erase operation.
291 *
292 * \par<b>Related APIs:</b><BR>
293 * None
294 *
295 */
296 void XMC_FLASH_ProgramVerifyPage(uint32_t *address, const uint32_t *data);
297
298 /**
299 *
300 * @param None
301 *
302 * @return None
303 *
304 * \par<b>Description:</b><br>
305 * Enables the flash to enter into sleep mode by resetting the NVMCONF register
NVM_ON bit.\n\n Flash can wake up from
306 * sleep mode on any flash operation completion ready event trigger. To disable the
sleep mode any time during execution
307 * call the API XMC_FLASH_ExitSleepMode().\n
308 *
309 * \par<b>Related APIs:</b><BR>
310 * XMC_FLASH_ExitSleepMode()\n\n\n
311 *
312 */
313 __STATIC_INLINE void XMC_FLASH_EnterSleepMode(void)
314 {
315 NVM->NVMCONF &= (uint16_t)(~(uint32_t)NVM_NVMCONF_NVM_ON_Msk);
316 }
317
318 /**
319 *
320 * @param None
321 *
322 * @return None
323 *
324 * \par<b>Description:</b><br>
325 * Enables the flash to exit from sleep mode by setting the NVMCONF register NVM_ON
bit.\n\n Calling the API
326 * XMC_FLASH_EnterSleepMode() allows the flash to renter into sleep mode.\n
327 *
328 * \par<b>Related APIs:</b><BR>
329 * XMC_FLASH_EnterSleepMode()\n\n\n
330 *
331 */
332 __STATIC_INLINE void XMC_FLASH_ExitSleepMode(void)
333 {
334 NVM->NVMCONF |= (uint16_t)NVM_NVMCONF_NVM_ON_Msk;
335 }
336
337
338 /**
339 *
340 * @param sector Flash sector number for which the address extraction is needed<BR>
Range: [0 to 51]
341 *
342 * @return uint32_t Starting address of the sector specified<BR> Range: [0x10001000
to 0x10032000]
343 *
344 * \par<b>Description:</b><br>
345 * Finds the starting address of the specified \a sector number.\n\n
346 *
347 * \par<b>Related APIs:</b><BR>
348 * None
349 *
350 */
351 __STATIC_INLINE uint32_t XMC_FLASH_GetSectorAddress(uint32_t sector)
352 {
353 return (XMC_FLASH_BASE + (XMC_FLASH_BYTES_PER_SECTOR * sector));
354 }
355
356
357 /**
358 *
359 * @param num_sectors Number of sectors to be protected<BR> Range: [0 to 51]
360 *
361 * @return None
362 *
363 * \par<b>Description:</b><br>
364 * Protect the flash sectors starting from 0th sector to the specified \a
num_sectors.\n\n It sets the NVMCONF register
365 * SECPROT field with the value specified in \a num_sectors. Changing the protection
limit can be achieved by calling
366 * this API at runtime with a different value of \a num_sectors.\n\n
367 *
368 * \par<b>Related APIs:</b><BR>
369 * None
370 *
371 */
372 __STATIC_INLINE void XMC_FLASH_SetSectorProtection(uint32_t num_sectors)
373 {
374 NVM->NVMCONF &= (~(uint16_t)NVM_NVMCONF_SECPROT_Msk);
375 NVM->NVMCONF |= (uint16_t)((uint16_t)num_sectors << NVM_NVMCONF_SECPROT_Pos);
376 }
377
378
379 /**
380 *
381 * @param level Hard read levels specified in \a XMC_FLASH_HARDREAD_LEVEL_t.
382 *
383 * @return None
384 *
385 * \par<b>Description:</b><br>
386 * Sets the hard read level for verification process.\n\n It insists the flash to do
a strict margin compare
387 * with the written/erased data against the internal buffer. Sets the NVMCONF
register HRLEV field with \a level
388 * value. This hardread level is used until the end of the verification sequence and,
may not be changed in between.\n\n
389 *
390 * \par<b>Related APIs:</b><BR>
391 * None
392 *
393 */
394 __STATIC_INLINE void XMC_FLASH_SetHardReadLevel(XMC_FLASH_HARDREAD_LEVEL_t level)
395 {
396 NVM->NVMCONF &= (uint16_t)(~(uint16_t)NVM_NVMCONF_HRLEV_Msk);
397 NVM->NVMCONF |= (uint16_t)(level<< (uint16_t)NVM_NVMCONF_HRLEV_Pos);
398 }
399
400 #ifdef __cplusplus
401 }
402 #endif
403
404 /**
405 * @}
406 */
407
408 /**
409 * @}
410 */
411
412 #endif
413
414 #endif /* FLASH_H */
415