1 /*
2 * Copyright (c) 2019 - 2020, Nordic Semiconductor ASA
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
7 *
8 * 1. Redistributions of source code must retain the above copyright notice, this
9 * list of conditions and the following disclaimer.
10 *
11 * 2. Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 *
15 * 3. Neither the name of the copyright holder nor the names of its
16 * contributors may be used to endorse or promote products derived from this
17 * software without specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
23 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29 * POSSIBILITY OF SUCH DAMAGE.
30 */
31
32 #ifndef NRFX_NVMC_H__
33 #define NRFX_NVMC_H__
34
35 #include <nrfx.h>
36 #include <hal/nrf_nvmc.h>
37 #include <hal/nrf_ficr.h>
38
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42
43 /**
44 * @defgroup nrfx_nvmc NVMC driver
45 * @{
46 * @ingroup nrf_nvmc
47 * @brief Non-Volatile Memory Controller (NVMC) peripheral driver.
48 */
49
50 /**
51 * @brief Function for erasing a page in flash.
52 *
53 * This function blocks until the erase operation finishes.
54 *
55 * @note Depending on the source of the code being executed,
56 * the CPU may be halted during the operation.
57 * Refer to the Product Specification for more information.
58 *
59 * @param address Address of the first word in the page to erase.
60 *
61 * @retval NRFX_SUCCESS Page erase complete.
62 * @retval NRFX_ERROR_INVALID_ADDR Address is not aligned to the size of the page.
63 */
64 nrfx_err_t nrfx_nvmc_page_erase(uint32_t address);
65
66 /**
67 * @brief Function for erasing the user information configuration register (UICR).
68 *
69 * @note Depending on the source of the code being executed,
70 * the CPU may be halted during the operation.
71 * Refer to the Product Specification for more information.
72 *
73 * @retval NRFX_SUCCESS UICR has been successfully erased.
74 * @retval NRFX_ERROR_NOT_SUPPORTED UICR erase is not supported.
75 */
76 nrfx_err_t nrfx_nvmc_uicr_erase(void);
77
78 /**
79 * @brief Function for erasing the whole flash memory.
80 *
81 * @note All user code and UICR will be erased.
82 */
83 void nrfx_nvmc_all_erase(void);
84
85 #if defined(NRF_NVMC_PARTIAL_ERASE_PRESENT)
86 /**
87 * @brief Function for initiating a complete page erase split into parts (also known as partial erase).
88 *
89 * This function initiates a partial erase with the specified duration.
90 * To execute each part of the partial erase, use @ref nrfx_nvmc_page_partial_erase_continue.
91 *
92 * @param address Address of the first word in the page to erase.
93 * @param duration_ms Time in milliseconds that each partial erase will take.
94 *
95 * @retval NRFX_SUCCESS Partial erase started.
96 * @retval NRFX_ERROR_INVALID_ADDR Address is not aligned to the size of the page.
97 *
98 * @sa nrfx_nvmc_page_partial_erase_continue()
99 */
100 nrfx_err_t nrfx_nvmc_page_partial_erase_init(uint32_t address, uint32_t duration_ms);
101
102 /**
103 * @brief Function for performing a part of the complete page erase (also known as partial erase).
104 *
105 * This function must be called several times to erase the whole page, once for each erase part.
106 *
107 * @note The actual time needed to perform each part of the page erase is longer than the partial
108 * erase duration specified in the call to @ref nrfx_nvmc_page_partial_erase_init,
109 * since the NVMC peripheral needs certain additional amount of time to handle the process.
110 * For details regarding this additional time, see the "Electrical specification" section
111 * for the NVMC peripheral in the Product Specification.
112 *
113 * @note Using a page that was not completely erased leads to undefined behavior.
114 * Depending on the source of the code being executed,
115 * the CPU may be halted during the operation.
116 * Refer to the Product Specification for more information.
117 *
118 * @retval true Partial erase finished.
119 * @retval false Partial erase not finished.
120 * Call the function again to process the next part.
121 */
122 bool nrfx_nvmc_page_partial_erase_continue(void);
123
124 #endif // defined(NRF_NVMC_PARTIAL_ERASE_PRESENT)
125
126 /**
127 * @brief Function for checking whether a byte is writable at the specified address.
128 *
129 * The NVMC is only able to write '0' to bits in the flash that are erased (set to '1').
130 * It cannot rewrite a bit back to '1'. This function checks if the value currently
131 * residing at the specified address can be transformed to the desired value
132 * without any '0' to '1' transitions.
133 *
134 * @param address Address to be checked.
135 * @param value Value to be checked.
136 *
137 * @retval true Byte can be written at the specified address.
138 * @retval false Byte cannot be written at the specified address.
139 * Erase the page or change the address.
140 */
141 bool nrfx_nvmc_byte_writable_check(uint32_t address, uint8_t value);
142
143 /**
144 * @brief Function for writing a single byte to flash.
145 *
146 * To determine if the flash write has been completed, use @ref nrfx_nvmc_write_done_check().
147 *
148 * @note Depending on the source of the code being executed,
149 * the CPU may be halted during the operation.
150 * Refer to the Product Specification for more information.
151 *
152 * @param address Address to write to.
153 * @param value Value to write.
154 */
155 void nrfx_nvmc_byte_write(uint32_t address, uint8_t value);
156
157 /**
158 * @brief Function for checking whether a halfword is writable at the specified address.
159 *
160 * The NVMC is only able to write '0' to bits in the Flash that are erased (set to '1').
161 * It cannot rewrite a bit back to '1'. This function checks if the value currently
162 * residing at the specified address can be transformed to the desired value
163 * without any '0' to '1' transitions.
164 *
165 * @param address Address to be checked. Must be halfword-aligned.
166 * @param value Value to be checked.
167 *
168 * @retval true Halfword can be written at the specified address.
169 * @retval false Halfword cannot be written at the specified address.
170 * Erase page or change address.
171 */
172 bool nrfx_nvmc_halfword_writable_check(uint32_t address, uint16_t value);
173
174 /**
175 * @brief Function for writing a 16-bit halfword to flash.
176 *
177 * To determine if the flash write has been completed, use @ref nrfx_nvmc_write_done_check().
178 *
179 * @note Depending on the source of the code being executed,
180 * the CPU may be halted during the operation.
181 * Refer to the Product Specification for more information.
182 *
183 * @param address Address to write to. Must be halfword-aligned.
184 * @param value Value to write.
185 */
186 void nrfx_nvmc_halfword_write(uint32_t address, uint16_t value);
187
188 /**
189 * @brief Function for checking whether a word is writable at the specified address.
190 *
191 * The NVMC is only able to write '0' to bits in the Flash that are erased (set to '1').
192 * It cannot rewrite a bit back to '1'. This function checks if the value currently
193 * residing at the specified address can be transformed to the desired value
194 * without any '0' to '1' transitions.
195 *
196 * @param address Address to be checked. Must be word-aligned.
197 * @param value Value to be checked.
198 *
199 * @retval true Word can be written at the specified address.
200 * @retval false Word cannot be written at the specified address.
201 * Erase page or change address.
202 */
203 bool nrfx_nvmc_word_writable_check(uint32_t address, uint32_t value);
204
205 /**
206 * @brief Function for writing a 32-bit word to flash.
207 *
208 * To determine if the flash write has been completed, use @ref nrfx_nvmc_write_done_check().
209 *
210 * @note Depending on the source of the code being executed,
211 * the CPU may be halted during the operation.
212 * Refer to the Product Specification for more information.
213 *
214 * @param address Address to write to. Must be word-aligned.
215 * @param value Value to write.
216 */
217 void nrfx_nvmc_word_write(uint32_t address, uint32_t value);
218
219 /**
220 * @brief Function for writing consecutive bytes to flash.
221 *
222 * To determine if the last flash write has been completed, use @ref nrfx_nvmc_write_done_check().
223 *
224 * @note Depending on the source of the code being executed,
225 * the CPU may be halted during the operation.
226 * Refer to the Product Specification for more information.
227 *
228 * @param address Address to write to.
229 * @param src Pointer to the data to copy from.
230 * @param num_bytes Number of bytes to write.
231 */
232 void nrfx_nvmc_bytes_write(uint32_t address, void const * src, uint32_t num_bytes);
233
234 /**
235 * @brief Function for writing consecutive words to flash.
236 *
237 * To determine if the last flash write has been completed, use @ref nrfx_nvmc_write_done_check().
238 *
239 * @note Depending on the source of the code being executed,
240 * the CPU may be halted during the operation.
241 * Refer to the Product Specification for more information.
242 *
243 * @param address Address to write to. Must be word-aligned.
244 * @param src Pointer to data to copy from. Must be word-aligned.
245 * @param num_words Number of words to write.
246 */
247 void nrfx_nvmc_words_write(uint32_t address, void const * src, uint32_t num_words);
248
249 /**
250 * @brief Function for reading a 16-bit aligned halfword from the OTP (UICR)
251 *
252 * OTP is a region of the UICR present in some chips. This function must be used
253 * to read halfword data from this region since unaligned accesses are not
254 * available on the OTP flash area.
255 *
256 * @param address Address to read from. Must be halfword-aligned.
257 *
258 * @retval The contents at @p address.
259 */
260 uint16_t nrfx_nvmc_otp_halfword_read(uint32_t address);
261
262 /**
263 * @brief Function for getting the total flash size in bytes.
264 *
265 * @return Flash total size in bytes.
266 */
267 uint32_t nrfx_nvmc_flash_size_get(void);
268
269 /**
270 * @brief Function for getting the flash page size in bytes.
271 *
272 * @return Flash page size in bytes.
273 */
274 uint32_t nrfx_nvmc_flash_page_size_get(void);
275
276 /**
277 * @brief Function for getting the flash page count.
278 *
279 * @return Flash page count.
280 */
281 uint32_t nrfx_nvmc_flash_page_count_get(void);
282
283 /**
284 * @brief Function for checking if the last flash write has been completed.
285 *
286 * @retval true Last write completed successfully.
287 * @retval false Last write is still in progress.
288 */
289 NRFX_STATIC_INLINE bool nrfx_nvmc_write_done_check(void);
290
291 #if defined(NVMC_FEATURE_CACHE_PRESENT)
292 /**
293 * @brief Function for enabling the Instruction Cache (ICache).
294 *
295 * Enabling ICache reduces the amount of accesses to flash memory,
296 * which can boost performance and lower power consumption.
297 */
298 NRFX_STATIC_INLINE void nrfx_nvmc_icache_enable(void);
299
300 /** @brief Function for disabling ICache. */
301 NRFX_STATIC_INLINE void nrfx_nvmc_icache_disable(void);
302
303 #endif // defined(NVMC_FEATURE_CACHE_PRESENT)
304
305 #ifndef NRFX_DECLARE_ONLY
nrfx_nvmc_write_done_check(void)306 NRFX_STATIC_INLINE bool nrfx_nvmc_write_done_check(void)
307 {
308 return nrf_nvmc_ready_check(NRF_NVMC);
309 }
310
311 #if defined(NVMC_FEATURE_CACHE_PRESENT)
nrfx_nvmc_icache_enable(void)312 NRFX_STATIC_INLINE void nrfx_nvmc_icache_enable(void)
313 {
314 nrf_nvmc_icache_config_set(NRF_NVMC, NRF_NVMC_ICACHE_ENABLE_WITH_PROFILING);
315 }
316
nrfx_nvmc_icache_disable(void)317 NRFX_STATIC_INLINE void nrfx_nvmc_icache_disable(void)
318 {
319 nrf_nvmc_icache_config_set(NRF_NVMC, NRF_NVMC_ICACHE_DISABLE);
320 }
321 #endif // defined(NVMC_FEATURE_CACHE_PRESENT)
322 #endif // NRFX_DECLARE_ONLY
323
324 /** @} */
325
326 #ifdef __cplusplus
327 }
328 #endif
329
330 #endif // NRF_NVMC_H__
331