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// - nvm_testutils_info_page_set: `true` enables, `false` leaves unchanged.
19// - nvm_testutils_info_page_clear: `true` disables, `false` leaves unchanged.
20
21/** Read-only: read selected, write and erase not selected. */
22extern const nvm_page_perms_t kPageReadOnly;
23/** Read-write: read, write, and erase all selected. */
24extern const nvm_page_perms_t kPageReadWrite;
25/** Write-only: read not selected, write and erase selected. */
26extern const nvm_page_perms_t kPageWriteOnly;
27
28/** Scrambled: scrambling and ECC selected, high-endurance not selected. */
29extern const nvm_page_cfg_t kPageScrambleCfg;
30/** Plain: scrambling not selected, ECC selected, high-endurance not selected.
31 */
32extern const nvm_page_cfg_t kPagePlainCfg;
33/** Raw: scrambling not selected, ECC not selected, high-endurance not selected.
34 * Use for pages written without ECC encoding (e.g. AST calibration data).
35 */
36extern const nvm_page_cfg_t kPageRawCfg;
37
38/**
39 * Wait for the flash controller to finish its initialization sequence.
40 *
41 * Must be called before any flash operations when running from SRAM (e.g. in
42 * SRAM provisioning programs) to ensure the controller is ready.
43 *
44 * @return The result of the operation.
45 */
46OT_WARN_UNUSED_RESULT
47status_t nvm_testutils_wait_for_init(void);
48
49/**
50 * Set all access permissions and configuration flags for an NVM info page.
51 *
52 * Writes all fields unconditionally: `true` → enabled, `false` → disabled.
53 *
54 * @param page Logical info page identifier.
55 * @param perms Permission values to apply to all fields.
56 * @param cfg Configuration values to apply to all fields.
57 * @return The result of the operation.
58 */
59OT_WARN_UNUSED_RESULT
60status_t nvm_testutils_info_page_setup(nvm_info_page_t page,
61 nvm_page_perms_t perms,
62 nvm_page_cfg_t cfg);
63
64/**
65 * Enable selected permission and configuration bits, leaving others unchanged.
66 *
67 * For each field set to `true` in `perms`/`cfg`, the corresponding bit is
68 * enabled (kMultiBitBool4True). Fields set to `false` are not modified.
69 *
70 * @param page Logical info page identifier.
71 * @param perms Bitmask of permissions to enable.
72 * @param cfg Bitmask of configuration bits to enable.
73 * @return The result of the operation.
74 */
75OT_WARN_UNUSED_RESULT
76status_t nvm_testutils_info_page_set(nvm_info_page_t page,
77 nvm_page_perms_t perms,
78 nvm_page_cfg_t cfg);
79
80/**
81 * Disable selected permission and configuration bits, leaving others unchanged.
82 *
83 * For each field set to `true` in `perms`/`cfg`, the corresponding bit is
84 * disabled (kMultiBitBool4False). Fields set to `false` are not modified.
85 *
86 * @param page Logical info page identifier.
87 * @param perms Bitmask of permissions to disable.
88 * @param cfg Bitmask of configuration bits to disable.
89 * @return The result of the operation.
90 */
91OT_WARN_UNUSED_RESULT
92status_t nvm_testutils_info_page_clear(nvm_info_page_t page,
93 nvm_page_perms_t perms,
94 nvm_page_cfg_t cfg);
95
96/**
97 * Write data to a logical NVM info page.
98 *
99 * The caller must call nvm_testutils_info_page_setup() before this function to
100 * configure the region properties (scrambling, ECC, permissions).
101 *
102 * When `erase_before_write` is true the page is erased first and a readback
103 * is performed to verify the write.
104 *
105 * @param page Logical info page identifier.
106 * @param byte_offset Byte offset from the start of the page.
107 * @param data Data words to write.
108 * @param word_count Number of 32-bit words to write (max 64).
109 * @param erase_before_write Erase the page before writing.
110 * @param readback Read back and verify data after writing.
111 * Set false for pages not readable in the current LC
112 * state (e.g. WaferAuthSecret in TEST_UNLOCKED).
113 * @return The result of the operation.
114 */
115OT_WARN_UNUSED_RESULT
116status_t nvm_testutils_write_info_page(nvm_info_page_t page,
117 uint32_t byte_offset,
118 const uint32_t *data, size_t word_count,
119 bool erase_before_write, bool readback);
120
121/**
122 * Read data from a logical NVM info page.
123 *
124 * The caller must call nvm_testutils_info_page_setup() before this function to
125 * configure the region properties (scrambling, ECC, permissions).
126 *
127 * @param page Logical info page identifier.
128 * @param byte_offset Byte offset from the start of the page.
129 * @param[out] data Output buffer for the read data.
130 * @param word_count Number of 32-bit words to read.
131 * @return The result of the operation.
132 */
133OT_WARN_UNUSED_RESULT
134status_t nvm_testutils_read_info_page(nvm_info_page_t page,
135 uint32_t byte_offset, uint32_t *data,
136 size_t word_count);
137
138/**
139 * Initialize the NVM controller at ROM/boot time.
140 *
141 * Starts the flash controller, waits for initialization to complete,
142 * optionally applies default region properties read from OTP, and enables
143 * flash access and instruction fetch. Call this once from test ROM before any
144 * other NVM operation.
145 *
146 * @param otp_flash_default_cfg CREATOR_SW_CFG_FLASH_DATA_DEFAULT_CFG OTP word;
147 * pass 0 when HAS_OTP_CTRL is not available or the field reads as zero.
148 * @return The result of the operation.
149 */
150OT_WARN_UNUSED_RESULT
151status_t nvm_testutils_rom_init(uint32_t otp_flash_default_cfg);
152
153/**
154 * Lock the region configuration for an NVM info page.
155 *
156 * Once locked the region properties cannot be changed until the device is
157 * reset. Passing `lock = false` is a no-op and always returns OK_STATUS.
158 *
159 * @param page Logical info page identifier.
160 * @param lock If true, lock the region configuration; if false, do nothing.
161 * @return The result of the operation.
162 */
163OT_WARN_UNUSED_RESULT
164status_t nvm_testutils_info_page_lock(nvm_info_page_t page, bool lock);
165
166/**
167 * Set properties for an NVM data region and enable it.
168 *
169 * Configures the base page, size, access permissions, and memory properties
170 * for a data region, then enables it. Writes all fields unconditionally.
171 *
172 * @param region Data region index.
173 * @param base Base page index of the region.
174 * @param size Size of the region in pages.
175 * @param perms Permission values to apply (read, write, erase).
176 * @param cfg Configuration values to apply (scrambling, ECC, HE).
177 * @return The result of the operation.
178 */
179OT_WARN_UNUSED_RESULT
180status_t nvm_testutils_data_region_setup(uint32_t region, uint32_t base,
181 uint32_t size, nvm_page_perms_t perms,
182 nvm_page_cfg_t cfg);
183
184/**
185 * Lock the region configuration for an NVM data region.
186 *
187 * Once locked the region properties cannot be changed until the device is
188 * reset. Passing `lock = false` is a no-op and always returns OK_STATUS.
189 *
190 * @param region Data region index.
191 * @param lock If true, lock the region configuration; if false, do nothing.
192 * @return The result of the operation.
193 */
194OT_WARN_UNUSED_RESULT
195status_t nvm_testutils_data_region_lock(uint32_t region, bool lock);
196
197/**
198 * Log any outstanding flash controller fault status registers.
199 *
200 * Initialises the NVM controller internally, reads the fault status registers
201 * via flash_ctrl_testutils_show_faults, and logs any faults. Useful at the
202 * start of a test to confirm the controller is in a clean state.
203 *
204 * @return The result of the operation.
205 */
206OT_WARN_UNUSED_RESULT
207status_t nvm_testutils_show_faults(void);
208
209/**
210 * Set the NVM controller default data region properties.
211 *
212 * Writes all fields of the default region unconditionally using the same
213 * bool-to-MultiBitBool4 semantics as nvm_testutils_info_page_setup.
214 * Hardware register state persists, so subsequent NVM operations will observe
215 * these settings.
216 *
217 * @param perms Permission values to apply (read, write, erase).
218 * @param cfg Configuration values to apply (scrambling, ECC, HE).
219 * @return The result of the operation.
220 */
221OT_WARN_UNUSED_RESULT
222status_t nvm_testutils_default_region_setup(nvm_page_perms_t perms,
223 nvm_page_cfg_t cfg);
224
225#endif // OPENTITAN_SW_DEVICE_LIB_TESTING_NVM_TESTUTILS_H_