1 /**
2 * \file
3 *
4 * \brief SAM Non-Volatile Memory driver
5 *
6 * Copyright (C) 2012-2016 Atmel Corporation. All rights reserved.
7 *
8 * \asf_license_start
9 *
10 * \page License
11 *
12 * Redistribution and use in source and binary forms, with or without
13 * modification, are permitted provided that the following conditions are met:
14 *
15 * 1. Redistributions of source code must retain the above copyright notice,
16 * this list of conditions and the following disclaimer.
17 *
18 * 2. Redistributions in binary form must reproduce the above copyright notice,
19 * this list of conditions and the following disclaimer in the documentation
20 * and/or other materials provided with the distribution.
21 *
22 * 3. The name of Atmel may not be used to endorse or promote products derived
23 * from this software without specific prior written permission.
24 *
25 * 4. This software may only be redistributed and used in connection with an
26 * Atmel microcontroller product.
27 *
28 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
29 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
30 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
31 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
32 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
33 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
34 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
35 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
36 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
37 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
38 * POSSIBILITY OF SUCH DAMAGE.
39 *
40 * \asf_license_stop
41 *
42 */
43 /*
44 * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
45 */
46 #ifndef NVM_H_INCLUDED
47 #define NVM_H_INCLUDED
48
49 /**
50 * \defgroup asfdoc_sam0_nvm_group SAM Non-Volatile Memory (NVM) Driver
51 *
52 * This driver for Atmel® | SMART ARM®-based microcontrollers provides
53 * an interface for the configuration and management of non-volatile memories
54 * within the device, for partitioning, erasing, reading, and writing of data.
55 *
56 * The following peripheral is used by this module:
57 * - NVM (Non-Volatile Memory)
58 *
59 * The following devices can use this module:
60 * - Atmel | SMART SAM D20/D21
61 * - Atmel | SMART SAM R21
62 * - Atmel | SMART SAM D09/D10/D11
63 * - Atmel | SMART SAM L21/L22
64 * - Atmel | SMART SAM DA1
65 * - Atmel | SMART SAM C20/C21
66 * - Atmel | SMART SAM HA1
67 * - Atmel | SMART SAM R30
68 *
69 * The outline of this documentation is as follows:
70 * - \ref asfdoc_sam0_nvm_prerequisites
71 * - \ref asfdoc_sam0_nvm_module_overview
72 * - \ref asfdoc_sam0_nvm_special_considerations
73 * - \ref asfdoc_sam0_nvm_extra_info
74 * - \ref asfdoc_sam0_nvm_examples
75 * - \ref asfdoc_sam0_nvm_api_overview
76 *
77 *
78 * \section asfdoc_sam0_nvm_prerequisites Prerequisites
79 *
80 * There are no prerequisites for this module.
81 *
82 *
83 * \section asfdoc_sam0_nvm_module_overview Module Overview
84 *
85 * The Non-Volatile Memory (NVM) module provides an interface to the device's
86 * Non-Volatile Memory controller, so that memory pages can be written, read,
87 * erased, and reconfigured in a standardized manner.
88 *
89 * \subsection asfdoc_sam0_nvm_features Driver Feature Macro Definition
90 * <table>
91 * <tr>
92 * <th>Driver feature macro</th>
93 * <th>Supported devices</th>
94 * </tr>
95 * <tr>
96 * <td>FEATURE_NVM_RWWEE</td>
97 * <td>SAM L21/L22, SAM D21-64K, SAM DA1, SAM C20/C21, SAM R30</td>
98 * </tr>
99 * <tr>
100 * <td>FEATURE_BOD12</td>
101 * <td>SAM L21, SAMR30</td>
102 * </tr>
103 * </table>
104 * \note The specific features are only available in the driver when the
105 * selected device supports those features.
106 *
107 * \subsection asfdoc_sam0_nvm_module_overview_regions Memory Regions
108 * The NVM memory space of the SAM devices is divided into two sections:
109 * a Main Array section, and an Auxiliary space section. The Main Array space
110 * can be configured to have an (emulated) EEPROM and/or boot loader section.
111 * The memory layout with the EEPROM and bootloader partitions is shown in
112 * \ref asfdoc_sam0_nvm_module_mem_layout "the figure below".
113 *
114 * \anchor asfdoc_sam0_nvm_module_mem_layout
115 * \dot
116 * digraph memory_layout {
117 * size="5,5"
118 * node [shape=plaintext, fontname=arial]
119 * memory [label=<
120 * <table border="0" cellborder="1" cellspacing="0" >
121 * <tr>
122 * <td align="right" border="0"> End of NVM Memory </td>
123 * <td rowspan="3" align="center"> Reserved EEPROM Section </td>
124 * </tr>
125 * <tr>
126 * <td align="right" border="0"> </td>
127 * </tr>
128 * <tr>
129 * <td align="right" border="0"> Start of EEPROM Memory </td>
130 * </tr>
131 * <tr>
132 * <td align="right" border="0"> End of Application Memory </td>
133 * <td rowspan="3" align="center"> Application Section </td>
134 * </tr>
135 * <tr>
136 * <td height="300" align="right" border="0"> </td>
137 * </tr>
138 * <tr>
139 * <td align="right" border="0"> Start of Application Memory </td>
140 * </tr>
141 * <tr>
142 * <td align="right" border="0"> End of Bootloader Memory </td>
143 * <td rowspan="3" align="center"> BOOT Section </td>
144 * </tr>
145 * <tr>
146 * <td align="right" border="0"> </td>
147 * </tr>
148 * <tr>
149 * <td align="right" border="0"> Start of NVM Memory</td>
150 * </tr>
151 * </table>
152 * >]
153 * }
154 * \enddot
155 *
156 * The Main Array is divided into rows and pages, where each row contains four
157 * pages. The size of each page may vary from 8-1024 bytes dependent of the
158 * device. Device specific parameters such as the page size and total number of
159 * pages in the NVM memory space are available via the \ref nvm_get_parameters()
160 * function.
161 *
162 * An NVM page number and address can be computed via the following equations:
163 *
164 * \f[ PageNum = (RowNum \times 4) + PagePosInRow \f]
165 * \f[ PageAddr = PageNum \times PageSize \f]
166 *
167 * \ref asfdoc_sam0_nvm_module_row_layout "The figure below" shows an example
168 * of the memory page and address values associated with logical row 7 of the
169 * NVM memory space.
170 *
171 * \anchor asfdoc_sam0_nvm_module_row_layout
172 * \dot
173 * digraph row_layout {
174 * size="4,4"
175 * node [shape=plaintext, fontname=arial]
176 * row [label=<
177 * <table border="0" cellborder="1" cellspacing="0">
178 * <tr>
179 * <td align="right" border ="0"> Row 0x07 </td>
180 * <td > Page 0x1F </td>
181 * <td > Page 0x1E </td>
182 * <td > Page 0x1D </td>
183 * <td > Page 0x1C </td>
184 * </tr>
185 * <tr>
186 * <td align="right" border ="0"> Address </td>
187 * <td border="0"> 0x7C0 </td>
188 * <td border="0"> 0x780 </td>
189 * <td border="0"> 0x740 </td>
190 * <td border="0"> 0x700 </td>
191 * </tr>
192 * </table>
193 * >]
194 * }
195 * \enddot
196 *
197 * \subsection asfdoc_sam0_nvm_module_overview_locking_regions Region Lock Bits
198 * As mentioned in \ref asfdoc_sam0_nvm_module_overview_regions, the main
199 * block of the NVM memory is divided into a number of individually addressable
200 * pages. These pages are grouped into 16 equal sized regions, where each region
201 * can be locked separately issuing an \ref NVM_COMMAND_LOCK_REGION command or
202 * by writing the LOCK bits in the User Row. Rows reserved for the EEPROM
203 * section are not affected by the lock bits or commands.
204 *
205 * \note By using the \ref NVM_COMMAND_LOCK_REGION or
206 * \ref NVM_COMMAND_UNLOCK_REGION commands the settings will remain in
207 * effect until the next device reset. By changing the default lock
208 * setting for the regions, the auxiliary space must to be written,
209 * however the adjusted configuration will not take effect until the next
210 * device reset.
211 *
212 * \note If the \ref asfdoc_sam0_nvm_special_consideration_security_bit is
213 * set, the auxiliary space cannot be written to. Clearing of the security
214 * bit can only be performed by a full chip erase.
215 *
216 * \subsection asfdoc_sam0_nvm_module_overview_sub_rw Read/Write
217 * Reading from the NVM memory can be performed using direct addressing into the
218 * NVM memory space, or by calling the \ref nvm_read_buffer() function.
219 *
220 * Writing to the NVM memory must be performed by the \ref nvm_write_buffer()
221 * function - additionally, a manual page program command must be issued if
222 * the NVM controller is configured in manual page writing mode.
223 *
224 * Before a page can be updated, the associated NVM memory row must be erased
225 * first via the \ref nvm_erase_row() function. Writing to a non-erased page
226 * will result in corrupt data being stored in the NVM memory space.
227 *
228 * \section asfdoc_sam0_nvm_special_considerations Special Considerations
229 *
230 * \subsection asfdoc_sam0_nvm_special_consideration_pageerase Page Erasure
231 * The granularity of an erase is per row, while the granularity of a write is
232 * per page. Thus, if the user application is modifying only one page of a row,
233 * the remaining pages in the row must be buffered and the row erased, as an
234 * erase is mandatory before writing to a page.
235 *
236 * \subsection asfdoc_sam0_nvm_special_consideration_clocks Clocks
237 * The user must ensure that the driver is configured with a proper number of
238 * wait states when the CPU is running at high frequencies.
239 *
240 * \subsection asfdoc_sam0_nvm_special_consideration_security_bit Security Bit
241 * The User Row in the Auxiliary Space cannot be read or written when
242 * the Security Bit is set. The Security Bit can be set by using passing
243 * \ref NVM_COMMAND_SET_SECURITY_BIT to the \ref nvm_execute_command() function,
244 * or it will be set if one tries to access a locked region. See
245 * \ref asfdoc_sam0_nvm_module_overview_locking_regions.
246 *
247 * The Security Bit can only be cleared by performing a chip erase.
248 *
249 *
250 * \section asfdoc_sam0_nvm_extra_info Extra Information
251 *
252 * For extra information, see \ref asfdoc_sam0_nvm_extra. This includes:
253 * - \ref asfdoc_sam0_nvm_extra_acronyms
254 * - \ref asfdoc_sam0_nvm_extra_dependencies
255 * - \ref asfdoc_sam0_nvm_extra_errata
256 * - \ref asfdoc_sam0_nvm_extra_history
257 *
258 *
259 * \section asfdoc_sam0_nvm_examples Examples
260 *
261 * For a list of examples related to this driver, see
262 * \ref asfdoc_sam0_nvm_exqsg.
263 *
264 *
265 * \section asfdoc_sam0_nvm_api_overview API Overview
266 * @{
267 */
268
269 #include <compiler.h>
270 #include <status_codes.h>
271 #include <stdbool.h>
272
273 #ifdef __cplusplus
274 extern "C" {
275 #endif
276
277 /* Define SAMD21-64K devices */
278 #if defined(SAMD21E15L) || defined(SAMD21E16L) || defined(__SAMD21E15L__) || defined(__SAMD21E16L__) \
279 || defined(SAMD21E15B) || defined(SAMD21E16B) || defined(__SAMD21E15B__) || defined(__SAMD21E16B__) \
280 || defined(SAMD21E15BU) || defined(SAMD21E16BU) || defined(__SAMD21E15BU__) || defined(__SAMD21E16BU__) \
281 || defined(SAMD21G15L) || defined(SAMD21G16L) || defined(__SAMD21G15L__) || defined(__SAMD21G16L__) \
282 || defined(SAMD21G15B) || defined(SAMD21G16B) || defined(__SAMD21G15B__) || defined(__SAMD21G16B__) \
283 || defined(SAMD21J15B) || defined(SAMD21J16B) || defined(__SAMD21J15B__) || defined(__SAMD21J16B__)
284
285 # define SAMD21_64K
286
287 #endif
288
289 /**
290 * \name Driver Feature Definition
291 *
292 * Define NVM features set according to the different device families.
293 * @{
294 */
295 #if (SAML21) || (SAML22) || (SAMDA1) || (SAMC20) || (SAMC21) || (SAMR30) || defined(SAMD21_64K) || (SAMHA1) \
296 || defined(__DOXYGEN__)
297 /** Read while write EEPROM emulation feature. */
298 # define FEATURE_NVM_RWWEE
299 #endif
300 #if (SAML21) || (SAMR30) || defined(__DOXYGEN__)
301 /** Brown-out detector internal to the voltage regulator for VDDCORE. */
302 #define FEATURE_BOD12
303 #endif
304 /*@}*/
305
306 #if !defined(__DOXYGEN__)
307 /**
308 * \brief Mask for the error flags in the status register.
309 */
310 # define NVM_ERRORS_MASK (NVMCTRL_STATUS_PROGE | \
311 NVMCTRL_STATUS_LOCKE | \
312 NVMCTRL_STATUS_NVME)
313 #endif
314
315 /**
316 * \brief NVM error flags.
317 *
318 * Possible NVM controller error codes, which can be returned by the NVM
319 * controller after a command is issued.
320 */
321 enum nvm_error {
322 /** No errors */
323 NVM_ERROR_NONE = 0,
324 /** Lock error, a locked region was attempted accessed */
325 NVM_ERROR_LOCK = NVMCTRL_STATUS_NVME | NVMCTRL_STATUS_LOCKE,
326 /** Program error, invalid command was executed */
327 NVM_ERROR_PROG = NVMCTRL_STATUS_NVME | NVMCTRL_STATUS_PROGE,
328 };
329
330 /**
331 * \brief NVM controller commands.
332 */
333 enum nvm_command {
334 /** Erases the addressed memory row */
335 NVM_COMMAND_ERASE_ROW = NVMCTRL_CTRLA_CMD_ER,
336
337 /** Write the contents of the page buffer to the addressed memory page */
338 NVM_COMMAND_WRITE_PAGE = NVMCTRL_CTRLA_CMD_WP,
339
340 /** Erases the addressed auxiliary memory row.
341 *
342 * \note This command can only be given when the security bit is not set.
343 */
344 NVM_COMMAND_ERASE_AUX_ROW = NVMCTRL_CTRLA_CMD_EAR,
345
346 /** Write the contents of the page buffer to the addressed auxiliary memory
347 * row.
348 *
349 * \note This command can only be given when the security bit is not set.
350 */
351 NVM_COMMAND_WRITE_AUX_ROW = NVMCTRL_CTRLA_CMD_WAP,
352
353 /** Locks the addressed memory region, preventing further modifications
354 * until the region is unlocked or the device is erased
355 */
356 NVM_COMMAND_LOCK_REGION = NVMCTRL_CTRLA_CMD_LR,
357
358 /** Unlocks the addressed memory region, allowing the region contents to be
359 * modified
360 */
361 NVM_COMMAND_UNLOCK_REGION = NVMCTRL_CTRLA_CMD_UR,
362
363 /** Clears the page buffer of the NVM controller, resetting the contents to
364 * all zero values
365 */
366 NVM_COMMAND_PAGE_BUFFER_CLEAR = NVMCTRL_CTRLA_CMD_PBC,
367
368 /** Sets the device security bit, disallowing the changing of lock bits and
369 * auxiliary row data until a chip erase has been performed
370 */
371 NVM_COMMAND_SET_SECURITY_BIT = NVMCTRL_CTRLA_CMD_SSB,
372
373 /** Enter power reduction mode in the NVM controller to reduce the power
374 * consumption of the system
375 */
376 NVM_COMMAND_ENTER_LOW_POWER_MODE = NVMCTRL_CTRLA_CMD_SPRM,
377
378 /** Exit power reduction mode in the NVM controller to allow other NVM
379 * commands to be issued
380 */
381 NVM_COMMAND_EXIT_LOW_POWER_MODE = NVMCTRL_CTRLA_CMD_CPRM,
382 #ifdef FEATURE_NVM_RWWEE
383 /** Read while write (RWW) EEPROM area erase row */
384 NVM_COMMAND_RWWEE_ERASE_ROW = NVMCTRL_CTRLA_CMD_RWWEEER,
385 /** RWW EEPROM write page */
386 NVM_COMMAND_RWWEE_WRITE_PAGE = NVMCTRL_CTRLA_CMD_RWWEEWP,
387 #endif
388 };
389
390 /**
391 * \brief NVM controller power reduction mode configurations.
392 *
393 * Power reduction modes of the NVM controller, to conserve power while the
394 * device is in sleep.
395 */
396 enum nvm_sleep_power_mode {
397 /** NVM controller exits low-power mode on first access after sleep */
398 NVM_SLEEP_POWER_MODE_WAKEONACCESS = NVMCTRL_CTRLB_SLEEPPRM_WAKEONACCESS_Val,
399 /** NVM controller exits low-power mode when the device exits sleep mode */
400 NVM_SLEEP_POWER_MODE_WAKEUPINSTANT = NVMCTRL_CTRLB_SLEEPPRM_WAKEUPINSTANT_Val,
401 /** Power reduction mode in the NVM controller disabled */
402 NVM_SLEEP_POWER_MODE_ALWAYS_AWAKE = NVMCTRL_CTRLB_SLEEPPRM_DISABLED_Val,
403 };
404
405 /**
406 * \brief NVM controller cache readmode configuration.
407 *
408 * Control how the NVM cache prefetch data from flash.
409 *
410 */
411 enum nvm_cache_readmode {
412 /** The NVM Controller (cache system) does not insert wait states on
413 * a cache miss. Gives the best system performance.
414 */
415 NVM_CACHE_READMODE_NO_MISS_PENALTY,
416 /** Reduces power consumption of the cache system, but inserts a
417 * wait state each time there is a cache miss
418 */
419 NVM_CACHE_READMODE_LOW_POWER,
420 /** The cache system ensures that a cache hit or miss takes the same
421 * amount of time, determined by the number of programmed flash
422 * wait states
423 */
424 NVM_CACHE_READMODE_DETERMINISTIC,
425 };
426
427 /**
428 * \brief NVM controller configuration structure.
429 *
430 * Configuration structure for the NVM controller within the device.
431 */
432 struct nvm_config {
433 /** Power reduction mode during device sleep */
434 enum nvm_sleep_power_mode sleep_power_mode;
435 /** Manual write mode; if enabled, pages loaded into the NVM buffer will
436 * not be written until a separate write command is issued. If disabled,
437 * writing to the last byte in the NVM page buffer will trigger an automatic
438 * write.
439 *
440 * \note If a partial page is to be written, a manual write command must be
441 * executed in either mode.
442 */
443 bool manual_page_write;
444 /** Number of wait states to insert when reading from flash, to prevent
445 * invalid data from being read at high clock frequencies
446 */
447 uint8_t wait_states;
448
449 /**
450 * Setting this to true will disable the pre-fetch cache in front of the
451 * NVM controller
452 */
453 bool disable_cache;
454 #if (SAMC20) || (SAMC21)
455 /**
456 * Setting this to true will disable the pre-fetch RWW cache in front of the
457 * NVM controller.
458 * If RWW cache is enabled, NVM cache will also be enabled.
459 */
460 bool disable_rww_cache;
461 #endif
462 /**
463 * Select the mode for how the cache will pre-fetch data from the flash
464 */
465 enum nvm_cache_readmode cache_readmode;
466 };
467
468 /**
469 * \brief NVM memory parameter structure.
470 *
471 * Structure containing the memory layout parameters of the NVM module.
472 */
473 struct nvm_parameters {
474 /** Number of bytes per page */
475 uint8_t page_size;
476 /** Number of pages in the main array */
477 uint16_t nvm_number_of_pages;
478 /** Size of the emulated EEPROM memory section configured in the NVM
479 * auxiliary memory space */
480 uint32_t eeprom_number_of_pages;
481 /** Size of the Bootloader memory section configured in the NVM auxiliary
482 * memory space */
483 uint32_t bootloader_number_of_pages;
484 #ifdef FEATURE_NVM_RWWEE
485 /** Number of pages in read while write EEPROM (RWWEE) emulation area */
486 uint16_t rww_eeprom_number_of_pages;
487 #endif
488 };
489
490 /**
491 * \brief Bootloader size.
492 *
493 * Available bootloader protection sizes in kilobytes.
494 *
495 */
496 enum nvm_bootloader_size {
497 /** Boot Loader Size is 32768 bytes */
498 NVM_BOOTLOADER_SIZE_128,
499 /** Boot Loader Size is 16384 bytes */
500 NVM_BOOTLOADER_SIZE_64,
501 /** Boot Loader Size is 8192 bytes */
502 NVM_BOOTLOADER_SIZE_32,
503 /** Boot Loader Size is 4096 bytes */
504 NVM_BOOTLOADER_SIZE_16,
505 /** Boot Loader Size is 2048 bytes */
506 NVM_BOOTLOADER_SIZE_8,
507 /** Boot Loader Size is 1024 bytes */
508 NVM_BOOTLOADER_SIZE_4,
509 /** Boot Loader Size is 512 bytes */
510 NVM_BOOTLOADER_SIZE_2,
511 /** Boot Loader Size is 0 bytes */
512 NVM_BOOTLOADER_SIZE_0,
513 };
514
515 /**
516 * \brief EEPROM emulator size.
517 *
518 * Available space in flash dedicated for EEPROM emulator in bytes.
519 *
520 */
521 enum nvm_eeprom_emulator_size {
522 /** EEPROM Size for EEPROM emulation is 16384 bytes */
523 NVM_EEPROM_EMULATOR_SIZE_16384,
524 /** EEPROM Size for EEPROM emulation is 8192 bytes */
525 NVM_EEPROM_EMULATOR_SIZE_8192,
526 /** EEPROM Size for EEPROM emulation is 4096 bytes */
527 NVM_EEPROM_EMULATOR_SIZE_4096,
528 /** EEPROM Size for EEPROM emulation is 2048 bytes */
529 NVM_EEPROM_EMULATOR_SIZE_2048,
530 /** EEPROM Size for EEPROM emulation is 1024 bytes */
531 NVM_EEPROM_EMULATOR_SIZE_1024,
532 /** EEPROM Size for EEPROM emulation is 512 bytes */
533 NVM_EEPROM_EMULATOR_SIZE_512,
534 /** EEPROM Size for EEPROM emulation is 256 bytes */
535 NVM_EEPROM_EMULATOR_SIZE_256,
536 /** EEPROM Size for EEPROM emulation is 0 bytes */
537 NVM_EEPROM_EMULATOR_SIZE_0,
538 };
539
540 /**
541 * \brief BOD33 Action.
542 *
543 * What action should be triggered when BOD33 is detected.
544 *
545 */
546 enum nvm_bod33_action {
547 /** No action */
548 NVM_BOD33_ACTION_NONE,
549 /** The BOD33 generates a reset */
550 NVM_BOD33_ACTION_RESET,
551 /** The BOD33 generates an interrupt */
552 NVM_BOD33_ACTION_INTERRUPT,
553 };
554
555 #ifdef FEATURE_BOD12
556 /**
557 * \brief BOD12 Action.
558 *
559 * What action should be triggered when BOD12 is detected.
560 *
561 */
562 enum nvm_bod12_action {
563 /** No action */
564 NVM_BOD12_ACTION_NONE,
565 /** The BOD12 generates a reset */
566 NVM_BOD12_ACTION_RESET,
567 /** The BOD12 generates an interrupt */
568 NVM_BOD12_ACTION_INTERRUPT,
569 };
570 #endif
571
572 /**
573 * \brief WDT Window time-out period.
574 *
575 * Window mode time-out period in clock cycles.
576 *
577 */
578 enum nvm_wdt_window_timeout {
579 /** 8 clock cycles */
580 NVM_WDT_WINDOW_TIMEOUT_PERIOD_8,
581 /** 16 clock cycles */
582 NVM_WDT_WINDOW_TIMEOUT_PERIOD_16,
583 /** 32 clock cycles */
584 NVM_WDT_WINDOW_TIMEOUT_PERIOD_32,
585 /** 64 clock cycles */
586 NVM_WDT_WINDOW_TIMEOUT_PERIOD_64,
587 /** 128 clock cycles */
588 NVM_WDT_WINDOW_TIMEOUT_PERIOD_128,
589 /** 256 clock cycles */
590 NVM_WDT_WINDOW_TIMEOUT_PERIOD_256,
591 /** 512 clock cycles */
592 NVM_WDT_WINDOW_TIMEOUT_PERIOD_512,
593 /** 1024 clock cycles */
594 NVM_WDT_WINDOW_TIMEOUT_PERIOD_1024,
595 /** 2048 clock cycles */
596 NVM_WDT_WINDOW_TIMEOUT_PERIOD_2048,
597 /** 4096 clock cycles */
598 NVM_WDT_WINDOW_TIMEOUT_PERIOD_4096,
599 /** 8192 clock cycles */
600 NVM_WDT_WINDOW_TIMEOUT_PERIOD_8192,
601 /** 16384 clock cycles */
602 NVM_WDT_WINDOW_TIMEOUT_PERIOD_16384,
603 };
604
605 /**
606 * \brief WDT Early warning offset.
607 *
608 * This setting determine how many GCLK_WDT cycles before a watchdog time-out period
609 * an early warning interrupt should be triggered.
610 *
611 */
612 enum nvm_wdt_early_warning_offset {
613 /** 8 clock cycles */
614 NVM_WDT_EARLY_WARNING_OFFSET_8,
615 /** 16 clock cycles */
616 NVM_WDT_EARLY_WARNING_OFFSET_16,
617 /** 32 clock cycles */
618 NVM_WDT_EARLY_WARNING_OFFSET_32,
619 /** 64 clock cycles */
620 NVM_WDT_EARLY_WARNING_OFFSET_64,
621 /** 128 clock cycles */
622 NVM_WDT_EARLY_WARNING_OFFSET_128,
623 /** 256 clock cycles */
624 NVM_WDT_EARLY_WARNING_OFFSET_256,
625 /** 512 clock cycles */
626 NVM_WDT_EARLY_WARNING_OFFSET_512,
627 /** 1024 clock cycles */
628 NVM_WDT_EARLY_WARNING_OFFSET_1024,
629 /** 2048 clock cycles */
630 NVM_WDT_EARLY_WARNING_OFFSET_2048,
631 /** 4096 clock cycles */
632 NVM_WDT_EARLY_WARNING_OFFSET_4096,
633 /** 8192 clock cycles */
634 NVM_WDT_EARLY_WARNING_OFFSET_8192,
635 /** 16384 clock cycles */
636 NVM_WDT_EARLY_WARNING_OFFSET_16384,
637 };
638
639 /**
640 * \brief NVM user row fuse setting structure.
641 *
642 * This structure contain the layout of the first 64 bits of the user row
643 * which contain the fuse settings.
644 */
645 struct nvm_fusebits {
646 /** Bootloader size */
647 enum nvm_bootloader_size bootloader_size;
648 /** EEPROM emulation area size */
649 enum nvm_eeprom_emulator_size eeprom_size;
650 #if (SAMC20) || (SAMC21)
651 /** BODVDD Threshold level at power on */
652 uint8_t bodvdd_level;
653 /** BODVDD Enable at power on */
654 bool bodvdd_enable;
655 /** BODVDD Action at power on */
656 enum nvm_bod33_action bodvdd_action;
657 /* BODVDD Hysteresis at power on */
658 bool bodvdd_hysteresis;
659 #else
660 /** BOD33 Threshold level at power on */
661 uint8_t bod33_level;
662 /** BOD33 Enable at power on */
663 bool bod33_enable;
664 /** BOD33 Action at power on */
665 enum nvm_bod33_action bod33_action;
666 /* BOD33 Hysteresis at power on */
667 bool bod33_hysteresis;
668 #endif
669 /** WDT Enable at power on */
670 bool wdt_enable;
671 /** WDT Always-on at power on */
672 bool wdt_always_on;
673 /** WDT Period at power on */
674 uint8_t wdt_timeout_period;
675 /** WDT Window mode time-out at power on */
676 enum nvm_wdt_window_timeout wdt_window_timeout;
677 /** WDT Early warning interrupt time offset at power on */
678 enum nvm_wdt_early_warning_offset wdt_early_warning_offset;
679 /** WDT Window mode enabled at power on */
680 bool wdt_window_mode_enable_at_poweron;
681 /** NVM Lock bits */
682 uint16_t lockbits;
683 #ifdef FEATURE_BOD12
684 /** BOD12 Threshold level at power on */
685 uint8_t bod12_level;
686 /** BOD12 Enable at power on */
687 bool bod12_enable;
688 /** BOD12 Action at power on */
689 enum nvm_bod12_action bod12_action;
690 /* BOD12 Hysteresis at power on */
691 bool bod12_hysteresis;
692 #endif
693 };
694
695 /**
696 * \name Configuration and Initialization
697 * @{
698 */
699
700 /**
701 * \brief Initializes an NVM controller configuration structure to defaults.
702 *
703 * Initializes a given NVM controller configuration structure to a set of
704 * known default values. This function should be called on all new
705 * instances of these configuration structures before being modified by the
706 * user application.
707 *
708 * The default configuration is as follows:
709 * \li Power reduction mode enabled after sleep mode until first NVM access
710 * \li Automatic page write mode disabled
711 * \li Number of FLASH wait states left unchanged
712 *
713 * \param[out] config Configuration structure to initialize to default values
714 *
715 */
nvm_get_config_defaults(struct nvm_config * const config)716 static inline void nvm_get_config_defaults(
717 struct nvm_config *const config)
718 {
719 /* Sanity check the parameters */
720 Assert(config);
721
722 /* Write the default configuration for the NVM configuration */
723 config->sleep_power_mode = NVM_SLEEP_POWER_MODE_WAKEONACCESS;
724 config->manual_page_write = true;
725 config->wait_states = NVMCTRL->CTRLB.bit.RWS;
726 config->disable_cache = false;
727 #if (SAMC20) || (SAMC21)
728 config->disable_rww_cache = false;
729 #endif
730 config->cache_readmode = NVM_CACHE_READMODE_NO_MISS_PENALTY;
731 }
732
733 enum status_code nvm_set_config(
734 const struct nvm_config *const config);
735
736 /**
737 * \brief Checks if the NVM controller is ready to accept a new command.
738 *
739 * Checks the NVM controller to determine if it is currently busy execution an
740 * operation, or ready for a new command.
741 *
742 * \return Busy state of the NVM controller.
743 *
744 * \retval true If the hardware module is ready for a new command
745 * \retval false If the hardware module is busy executing a command
746 *
747 */
nvm_is_ready(void)748 static inline bool nvm_is_ready(void)
749 {
750 /* Get a pointer to the module hardware instance */
751 Nvmctrl *const nvm_module = NVMCTRL;
752
753 return nvm_module->INTFLAG.reg & NVMCTRL_INTFLAG_READY;
754 }
755
756 /** @} */
757
758 /**
759 * \name NVM Access Management
760 * @{
761 */
762
763 void nvm_get_parameters(
764 struct nvm_parameters *const parameters);
765
766 enum status_code nvm_write_buffer(
767 const uint32_t destination_address,
768 const uint8_t *buffer,
769 uint16_t length);
770
771 enum status_code nvm_read_buffer(
772 const uint32_t source_address,
773 uint8_t *const buffer,
774 uint16_t length);
775
776 enum status_code nvm_update_buffer(
777 const uint32_t destination_address,
778 uint8_t *const buffer,
779 uint16_t offset,
780 uint16_t length);
781
782 enum status_code nvm_erase_row(
783 const uint32_t row_address);
784
785 enum status_code nvm_execute_command(
786 const enum nvm_command command,
787 const uint32_t address,
788 const uint32_t parameter);
789
790 enum status_code nvm_get_fuses(struct nvm_fusebits *fusebits);
791 enum status_code nvm_set_fuses(struct nvm_fusebits *fb);
792
793 bool nvm_is_page_locked(uint16_t page_number);
794
795 /**
796 * \brief Retrieves the error code of the last issued NVM operation.
797 *
798 * Retrieves the error code from the last executed NVM operation. Once
799 * retrieved, any error state flags in the controller are cleared.
800 *
801 * \note The \ref nvm_is_ready() function is an exception. Thus, errors
802 * retrieved after running this function should be valid for the function
803 * executed before \ref nvm_is_ready().
804 *
805 * \return Error caused by the last NVM operation.
806 *
807 * \retval NVM_ERROR_NONE No error occurred in the last NVM operation
808 *
809 * \retval NVM_ERROR_LOCK The last NVM operation attempted to access a locked
810 * region
811 * \retval NVM_ERROR_PROG An invalid NVM command was issued
812 */
nvm_get_error(void)813 static inline enum nvm_error nvm_get_error(void)
814 {
815 enum nvm_error ret_val;
816
817 /* Get a pointer to the module hardware instance */
818 Nvmctrl *const nvm_module = NVMCTRL;
819
820 /* Mask out non-error bits */
821 ret_val = (enum nvm_error)(nvm_module->STATUS.reg & NVM_ERRORS_MASK);
822
823 /* Clear error flags */
824 nvm_module->STATUS.reg = NVM_ERRORS_MASK;
825
826 /* Return error code from the NVM controller */
827 return ret_val;
828 }
829
830 /** @} */
831
832 #ifdef __cplusplus
833 }
834 #endif
835
836 /** @} */
837
838 /**
839 * \page asfdoc_sam0_nvm_extra Extra Information for NVM Driver
840 *
841 * \section asfdoc_sam0_nvm_extra_acronyms Acronyms
842 * The table below presents the acronyms used in this module:
843 *
844 * <table>
845 * <tr>
846 * <th>Acronym</th>
847 * <th>Description</th>
848 * </tr>
849 * <tr>
850 * <td>NVM</td>
851 * <td>Non-Volatile Memory</td>
852 * </tr>
853 * <tr>
854 * <td>EEPROM</td>
855 * <td>Electrically Erasable Programmable Read-Only Memory</td>
856 * </tr>
857 * </table>
858 *
859 *
860 * \section asfdoc_sam0_nvm_extra_dependencies Dependencies
861 * This driver has the following dependencies:
862 *
863 * - None
864 *
865 *
866 * \section asfdoc_sam0_nvm_extra_errata Errata
867 * There are no errata related to this driver.
868 *
869 *
870 * \section asfdoc_sam0_nvm_extra_history Module History
871 * An overview of the module history is presented in the table below, with
872 * details on the enhancements and fixes made to the module since its first
873 * release. The current version of this corresponds to the newest version in
874 * the table.
875 *
876 * <table>
877 * <tr>
878 * <th>Changelog</th>
879 * </tr>
880 * <tr>
881 * <td>Removed BOD12 reference, removed nvm_set_fuses() API</td>
882 * </tr>
883 * <tr>
884 * <td>Added functions to read/write fuse settings</td>
885 * </tr>
886 * <tr>
887 * <td>Added support for NVM cache configuration</td>
888 * </tr>
889 * <tr>
890 * <td>Updated initialization function to also enable the digital interface
891 * clock to the module if it is disabled</td>
892 * </tr>
893 * <tr>
894 * <td>Initial Release</td>
895 * </tr>
896 * </table>
897 */
898
899 /**
900 * \page asfdoc_sam0_nvm_exqsg Examples for NVM Driver
901 *
902 * This is a list of the available Quick Start guides (QSGs) and example
903 * applications for \ref asfdoc_sam0_nvm_group. QSGs are simple examples with
904 * step-by-step instructions to configure and use this driver in a selection of
905 * use cases. Note that a QSG can be compiled as a standalone application or be
906 * added to the user application.
907 *
908 * - \subpage asfdoc_sam0_nvm_basic_use_case
909 *
910 * \page asfdoc_sam0_nvm_document_revision_history Document Revision History
911 *
912 * <table>
913 * <tr>
914 * <th>Doc. Rev.</th>
915 * <th>Date</th>
916 * <th>Comments</th>
917 * </tr>
918 * <tr>
919 * <td>42114E</td>
920 * <td>12/2015</td>
921 * <td>Added support for SAM L21/L22, SAM C21, SAM D09, SAMR30 and SAM DA1</td>
922 * </tr>
923 * <tr>
924 * <td>42114D</td>
925 * <td>12/2014</td>
926 * <td>Added support for SAM R21 and SAM D10/D11</td>
927 * </tr>
928 * <tr>
929 * <td>42114C</td>
930 * <td>01/2014</td>
931 * <td>Added support for SAM D21</td>
932 * </tr>
933 * <tr>
934 * <td>42114B</td>
935 * <td>06/2013</td>
936 * <td>Corrected documentation typos</td>
937 * </tr>
938 * <tr>
939 * <td>42114A</td>
940 * <td>06/2013</td>
941 * <td>Initial document release</td>
942 * </tr>
943 * </table>
944 */
945
946 #endif /* NVM_H_INCLUDED */
947