Software APIs
flash_ctrl_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_FLASH_CTRL_TESTUTILS_H_
6#define OPENTITAN_SW_DEVICE_LIB_TESTING_FLASH_CTRL_TESTUTILS_H_
7
8#include <stdint.h>
9
10#include "sw/device/lib/base/status.h"
12
13/**
14 * Wait for the flash_ctrl to initialize.
15 *
16 * @param flash_state A flash_ctrl state handle.
17 */
19status_t flash_ctrl_testutils_wait_for_init(
20 dif_flash_ctrl_state_t *flash_state);
21
22/**
23 * Wait for a flash_ctrl operation to end.
24 *
25 * Calls dif_flash_ctrl_end in a loop and waits for a dif_result of Ok. If at
26 * any time the result is BadArg or Error this will fail.
27 * Clears any error codes and returns the value of operation_error.
28 *
29 * @param flash_state A flash_ctrl state handle.
30 * @return The result of the operation.
31 */
33status_t flash_ctrl_testutils_wait_transaction_end(
34 dif_flash_ctrl_state_t *flash_state);
35
36/**
37 * Setup and enable for a data region taking region properties as a parameter.
38 *
39 * @param flash_state A flash_ctrl state handle.
40 * @param base_page_index The region base page index.
41 * @param data_region The region index.
42 * @param region_size The region size (in number of pages).
43 * @param region_properties The properties for the data region.
44 * @param region_properties The properties for the data region.
45 * @param[out] offset The byte address offset of the region.
46 * @return The result of the operation.
47 */
49status_t flash_ctrl_testutils_data_region_setup_properties(
50 dif_flash_ctrl_state_t *flash_state, uint32_t base_page_index,
51 uint32_t data_region, uint32_t region_size,
52 dif_flash_ctrl_region_properties_t region_properties, uint32_t *offset);
53
54/**
55 * Setup and enable for a data region with scrambling disabled.
56 *
57 * @param flash_state A flash_ctrl state handle.
58 * @param base_page_index The region base page index.
59 * @param data_region The region index.
60 * @param region_size The region size (in number of pages).
61 * @param[out] offset The byte address offset of the region.
62 * @return The result of the operation.
63 */
65status_t flash_ctrl_testutils_data_region_setup(
66 dif_flash_ctrl_state_t *flash_state, uint32_t base_page_index,
67 uint32_t data_region, uint32_t region_size, uint32_t *offset);
68
69/**
70 * Setup and enable for a data region with scrambling enabled.
71 *
72 * @param flash_state A flash_ctrl state handle.
73 * @param base_page_index The region base page index.
74 * @param data_region The region index.
75 * @param region_size The region size (in number of pages).
76 * @param[out] offset The byte address offset of the region.
77 * @return The result of the operation.
78 */
80status_t flash_ctrl_testutils_data_region_scrambled_setup(
81 dif_flash_ctrl_state_t *flash_state, uint32_t base_page_index,
82 uint32_t data_region, uint32_t region_size, uint32_t *offset);
83
84/**
85 * Setup and enable for an info region taking region properties as a parameter.
86 *
87 * @param flash_state A flash_ctrl state handle.
88 * @param page_id Region page index.
89 * @param bank The required bank.
90 * @param partition_id The partition index.
91 * @param region_properties The properties for the info region.
92 * @param[out] offset The byte address offset of the region.
93 * @return The result of the operation.
94 */
96status_t flash_ctrl_testutils_info_region_setup_properties(
97 dif_flash_ctrl_state_t *flash_state, uint32_t page_id, uint32_t bank,
98 uint32_t partition_id, dif_flash_ctrl_region_properties_t region_properties,
99 uint32_t *offset);
100
101/**
102 * Setup and enable for an info region with scrambling disabled.
103 *
104 * @param flash_state A flash_ctrl state handle.
105 * @param page_id Region page index.
106 * @param bank The required bank.
107 * @param partition_id The partition index.
108 * @param[out] offset The byte address offset of the region.
109 * @return The result of the operation.
110 */
112status_t flash_ctrl_testutils_info_region_setup(
113 dif_flash_ctrl_state_t *flash_state, uint32_t page_id, uint32_t bank,
114 uint32_t partition_id, uint32_t *offset);
115
116/**
117 * Setup and enable for an info region with scrambling enabled.
118 *
119 * @param flash_state A flash_ctrl state handle.
120 * @param page_id Region page index.
121 * @param bank The required bank.
122 * @param partition_id The partition index.
123 * @param[out] offset The byte address offset of the region.
124 * @return The result of the operation.
125 */
127status_t flash_ctrl_testutils_info_region_scrambled_setup(
128 dif_flash_ctrl_state_t *flash_state, uint32_t page_id, uint32_t bank,
129 uint32_t partition_id, uint32_t *offset);
130
131/**
132 * Erases the page at byte_address.
133 * Returns the result of transaction_end.
134 *
135 * @param flash_state A flash_ctrl state handle.
136 * @param byte_address The byte address of the page to erase.
137 * @param partition_id The partition index.
138 * @param partition_type The partition type, data or info.
139 * @return The result of the operation.
140 */
142status_t flash_ctrl_testutils_erase_page(
143 dif_flash_ctrl_state_t *flash_state, uint32_t byte_address,
144 uint32_t partition_id, dif_flash_ctrl_partition_type_t partition_type);
145
146/**
147 * Programs the flash starting from byte_address.
148 * The write is broken into as many transactions as required for the supplied
149 * word_count such that the program resolution is not exceeded in any
150 * transaction.
151 * Returns the result of transaction_end.
152 *
153 * @param flash_state A flash_ctrl state handle.
154 * @param byte_address The byte address of the page to program.
155 * @param partition_id The partition index.
156 * @param data The data to program.
157 * @param partition_type The partition type, data or info.
158 * @param word_count The number of uint32_t words to program.
159 * @return The result of the operation.
160 */
162status_t flash_ctrl_testutils_write(
163 dif_flash_ctrl_state_t *flash_state, uint32_t byte_address,
164 uint32_t partition_id, const uint32_t *data,
165 dif_flash_ctrl_partition_type_t partition_type, uint32_t word_count);
166
167/**
168 * Erases and Programs the page at byte_address.
169 * Calls the erase and write functions in turn.
170 * Returns the combined result of the transaction_ends.
171 *
172 * @param flash_state A flash_ctrl state handle.
173 * @param byte_address The byte address of the page to erase and program.
174 * @param partition_id The partition index.
175 * @param data The data to program.
176 * @param partition_type The partition type, data or info.
177 * @param word_count The number of uint32_t words to program.
178 * @return The result of the operation.
179 */
181status_t flash_ctrl_testutils_erase_and_write_page(
182 dif_flash_ctrl_state_t *flash_state, uint32_t byte_address,
183 uint32_t partition_id, const uint32_t *data,
184 dif_flash_ctrl_partition_type_t partition_type, uint32_t word_count);
185
186/**
187 * Reads data starting from byte_address.
188 * Returns the result of transaction_end.
189 *
190 * @param flash_state A flash_ctrl state handle.
191 * @param byte_address The byte address of the page to erase and program.
192 * @param partition_id The partition index.
193 * @param data_out The data read from the page.
194 * @param partition_type The partition type, data or info.
195 * @param word_count The number of uint32_t words to read.
196 * @param delay_micros Optional delay (in us) for read FIFO fill testing.
197 * @return The result of the operation.
198 */
200status_t flash_ctrl_testutils_read(
201 dif_flash_ctrl_state_t *flash_state, uint32_t byte_address,
202 uint32_t partition_id, uint32_t *data_out,
203 dif_flash_ctrl_partition_type_t partition_type, uint32_t word_count,
204 uint32_t delay);
205
206/**
207 * Sets the flash default configuration.
208 *
209 * @param flash_state A flash_ctrl state handle.
210 * @param rd_en Default read enable.
211 * @param prog_en Default program enable.
212 * @param erase_en Default page erase enable.
213 * @param scramble_en Default scramble enable.
214 * @param ecc_en Default ECC enable.
215 * @param high_endurance_en Default high endurance enable
216 */
218status_t flash_ctrl_testutils_default_region_access(
219 dif_flash_ctrl_state_t *flash_state, bool rd_en, bool prog_en,
220 bool erase_en, bool scramble_en, bool ecc_en, bool high_endurance_en);
221
222/**
223 * Enables erase for the provided bank, erases the bank, then disables bank
224 * erase.
225 *
226 * @param flash_state A flash_ctrl state handle.
227 * @param bank The bank ID.
228 * @param data_only True to only erase the data partitions. False to erase
229 * everything.
230 * @return The result of the operation.
231 */
233status_t flash_ctrl_testutils_bank_erase(dif_flash_ctrl_state_t *flash_state,
234 uint32_t bank, bool data_only);
235
236enum {
237 kFlashCtrlTestUtilsCounterMaxCount = 256,
238};
239
240/**
241 * Write to log any faults set in the status register.
242 *
243 * @param flash_state A flash_ctrl state handle.
244 */
246status_t flash_ctrl_testutils_show_faults(
247 const dif_flash_ctrl_state_t *flash_state);
248#endif // OPENTITAN_SW_DEVICE_LIB_TESTING_FLASH_CTRL_TESTUTILS_H_