Software APIs
nvm_testutils.h
1// Copyright lowRISC contributors (OpenTitan project).
2// Licensed under the Apache License, Version 2.0, see LICENSE for details.
3// SPDX-License-Identifier: Apache-2.0
4
5#ifndef OPENTITAN_SW_DEVICE_LIB_TESTING_NVM_TESTUTILS_H_
6#define OPENTITAN_SW_DEVICE_LIB_TESTING_NVM_TESTUTILS_H_
7
8#include <stddef.h>
9#include <stdint.h>
10
11#include "sw/device/lib/base/status.h"
12#include "sw/device/silicon_creator/lib/nvm_ctrl.h"
13
14// nvm_page_perms_t, nvm_page_cfg_t, and nvm_info_page_t are defined in
15// nvm_ctrl.h (included
16// above). The semantics for nvm_testutils functions are:
17// - nvm_testutils_info_page_setup: `true` enables, `false` disables.
18
19/** Read-only: read selected, write and erase not selected. */
20extern const nvm_page_perms_t kPageReadOnly;
21/** Read-write: read, write, and erase all selected. */
22extern const nvm_page_perms_t kPageReadWrite;
23/** Write-only: read not selected, write and erase selected. */
24extern const nvm_page_perms_t kPageWriteOnly;
25
26/** Scrambled: scrambling and ECC selected, high-endurance not selected. */
27extern const nvm_page_cfg_t kPageScrambleCfg;
28/** Plain: scrambling not selected, ECC selected, high-endurance not selected.
29 */
30extern const nvm_page_cfg_t kPagePlainCfg;
31/** Raw: scrambling not selected, ECC not selected, high-endurance not selected.
32 * Use for pages written without ECC encoding (e.g. AST calibration data).
33 */
34extern const nvm_page_cfg_t kPageRawCfg;
35
36/**
37 * Wait for the flash controller to finish its initialization sequence.
38 *
39 * Must be called before any flash operations when running from SRAM (e.g. in
40 * SRAM provisioning programs) to ensure the controller is ready.
41 *
42 * @return The result of the operation.
43 */
44OT_WARN_UNUSED_RESULT
45status_t nvm_testutils_wait_for_init(void);
46
47/**
48 * Set all access permissions and configuration flags for an NVM info page.
49 *
50 * Writes all fields unconditionally: `true` → enabled, `false` → disabled.
51 *
52 * @param page Logical info page identifier.
53 * @param perms Permission values to apply to all fields.
54 * @param cfg Configuration values to apply to all fields.
55 * @return The result of the operation.
56 */
57OT_WARN_UNUSED_RESULT
58status_t nvm_testutils_info_page_setup(nvm_info_page_t page,
59 nvm_page_perms_t perms,
60 nvm_page_cfg_t cfg);
61
62/**
63 * Write data to a logical NVM info page.
64 *
65 * The caller must call nvm_testutils_info_page_setup() before this function to
66 * configure the region properties (scrambling, ECC, permissions).
67 *
68 * When `erase_before_write` is true the page is erased first and a readback
69 * is performed to verify the write.
70 *
71 * @param page Logical info page identifier.
72 * @param byte_offset Byte offset from the start of the page.
73 * @param data Data words to write.
74 * @param word_count Number of 32-bit words to write (max 64).
75 * @param erase_before_write Erase the page before writing.
76 * @param readback Read back and verify data after writing.
77 * Set false for pages not readable in the current LC
78 * state (e.g. WaferAuthSecret in TEST_UNLOCKED).
79 * @return The result of the operation.
80 */
81OT_WARN_UNUSED_RESULT
82status_t nvm_testutils_write_info_page(nvm_info_page_t page,
83 uint32_t byte_offset,
84 const uint32_t *data, size_t word_count,
85 bool erase_before_write, bool readback);
86
87/**
88 * Read data from a logical NVM info page.
89 *
90 * The caller must call nvm_testutils_info_page_setup() before this function to
91 * configure the region properties (scrambling, ECC, permissions).
92 *
93 * @param page Logical info page identifier.
94 * @param byte_offset Byte offset from the start of the page.
95 * @param[out] data Output buffer for the read data.
96 * @param word_count Number of 32-bit words to read.
97 * @return The result of the operation.
98 */
99OT_WARN_UNUSED_RESULT
100status_t nvm_testutils_read_info_page(nvm_info_page_t page,
101 uint32_t byte_offset, uint32_t *data,
102 size_t word_count);
103
104/**
105 * Initialize the NVM controller at ROM/boot time.
106 *
107 * Starts the flash and/or RRAM controller, waits for initialization to
108 * complete, optionally applies default region scrambling/ECC config read
109 * from OTP, and enables NVM access and instruction fetch. Call this once
110 * from test ROM before any other NVM operation.
111 *
112 * Unlike flash, RRAM cannot simply be read once its PHY is ready. The
113 * controller must be initialized before the RRAM can be read/written via
114 * software.
115 *
116 * @param otp_nvm_default_cfg CREATOR_SW_CFG_NVM_DATA_DEFAULT_CFG OTP word;
117 * pass 0 when HAS_OTP_CTRL is not available or the field reads as zero.
118 * Applied to both flash and RRAM default region scrambling/ECC config; the
119 * high-endurance field is ignored for RRAM, which has no such concept.
120 * @return The result of the operation.
121 */
122OT_WARN_UNUSED_RESULT
123status_t nvm_testutils_rom_init(uint32_t otp_nvm_default_cfg);
124
125/**
126 * Lock the region configuration for an NVM info page.
127 *
128 * Once locked the region properties cannot be changed until the device is
129 * reset. Passing `lock = false` is a no-op and always returns OK_STATUS.
130 *
131 * @param page Logical info page identifier.
132 * @param lock If true, lock the region configuration; if false, do nothing.
133 * @return The result of the operation.
134 */
135OT_WARN_UNUSED_RESULT
136status_t nvm_testutils_info_page_lock(nvm_info_page_t page, bool lock);
137
138/**
139 * Log the current access permissions, configuration, and lock state of an
140 * NVM info page.
141 *
142 * Unlike the other nvm_testutils_info_page_* functions, this reads back
143 * whatever the page's properties currently are, rather than setting them.
144 * On flash the printed line has six enable fields (RD-WR-ER-SC-EC-HE); RRAM
145 * has no separate erase or high-endurance concept, so its line only has four
146 * (RD-WR-SC-EC).
147 *
148 * @param page Logical info page identifier.
149 * @return The result of the operation.
150 */
151OT_WARN_UNUSED_RESULT
152status_t nvm_testutils_info_page_print(nvm_info_page_t page);
153
154/**
155 * Set properties for an NVM data region and enable it.
156 *
157 * Configures the base page, size, access permissions, and memory properties
158 * for a data region, then enables it. Writes all fields unconditionally.
159 *
160 * @param region Data region index.
161 * @param base Base page index of the region.
162 * @param size Size of the region in pages.
163 * @param perms Permission values to apply (read, write, erase).
164 * @param cfg Configuration values to apply (scrambling, ECC, HE).
165 * @return The result of the operation.
166 */
167OT_WARN_UNUSED_RESULT
168status_t nvm_testutils_data_region_setup(uint32_t region, uint32_t base,
169 uint32_t size, nvm_page_perms_t perms,
170 nvm_page_cfg_t cfg);
171
172/**
173 * Lock the region configuration for an NVM data region.
174 *
175 * Once locked the region properties cannot be changed until the device is
176 * reset. Passing `lock = false` is a no-op and always returns OK_STATUS.
177 *
178 * @param region Data region index.
179 * @param lock If true, lock the region configuration; if false, do nothing.
180 * @return The result of the operation.
181 */
182OT_WARN_UNUSED_RESULT
183status_t nvm_testutils_data_region_lock(uint32_t region, bool lock);
184
185/**
186 * Write data to an NVM data-partition address.
187 *
188 * @param byte_address The byte address to write to.
189 * @param data The data to write.
190 * @param word_count The number of uint32_t words to write.
191 * @param erase_before_write Whether to erase the containing page before
192 * writing. Required on flash, which cannot program a bit back to `1` without
193 * an erase; ignored on RRAM, which supports direct overwrite.
194 * @return The result of the operation.
195 */
196OT_WARN_UNUSED_RESULT
197status_t nvm_testutils_data_write(uint32_t byte_address, const uint32_t *data,
198 size_t word_count, bool erase_before_write);
199
200/**
201 * Enable or disable code execution from the NVM data partition.
202 *
203 * @param enable Whether execution should be enabled.
204 * @return The result of the operation.
205 */
206OT_WARN_UNUSED_RESULT
207status_t nvm_testutils_set_exec_enablement(bool enable);
208
209/**
210 * Log any outstanding flash controller fault status registers.
211 *
212 * Initialises the NVM controller internally, reads the fault status registers
213 * via flash_ctrl_testutils_show_faults, and logs any faults. Useful at the
214 * start of a test to confirm the controller is in a clean state.
215 *
216 * @return The result of the operation.
217 */
218OT_WARN_UNUSED_RESULT
219status_t nvm_testutils_show_faults(void);
220
221/**
222 * Set the NVM controller default data region properties.
223 *
224 * Writes all fields of the default region unconditionally using the same
225 * bool-to-MultiBitBool4 semantics as nvm_testutils_info_page_setup.
226 * Hardware register state persists, so subsequent NVM operations will observe
227 * these settings.
228 *
229 * @param perms Permission values to apply (read, write, erase).
230 * @param cfg Configuration values to apply (scrambling, ECC, HE).
231 * @return The result of the operation.
232 */
233OT_WARN_UNUSED_RESULT
234status_t nvm_testutils_default_region_setup(nvm_page_perms_t perms,
235 nvm_page_cfg_t cfg);
236/**
237 * Get the NVM controller's current default data region properties.
238 *
239 * RRAM has no separate erase permission or high-endurance concept; on RRAM
240 * `perms->erase` and `cfg->he` are always reported as `kMultiBitBool4False`.
241 *
242 * @param[out] perms Current permission values (read, write, erase). May be
243 * NULL if not needed.
244 * @param[out] cfg Current configuration values (scrambling, ECC, HE). May
245 * be NULL if not needed.
246 * @return The result of the operation.
247 */
248OT_WARN_UNUSED_RESULT
249status_t nvm_testutils_default_region_get(nvm_page_perms_t *perms,
250 nvm_page_cfg_t *cfg);
251
252#endif // OPENTITAN_SW_DEVICE_LIB_TESTING_NVM_TESTUTILS_H_