Software APIs
spi_device_testutils.c
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#include "sw/device/lib/testing/spi_device_testutils.h"
6
7#include "hw/top/dt/dt_spi_device.h"
8#include "sw/device/lib/dif/dif_spi_device.h"
9#include "sw/device/lib/testing/test_framework/check.h"
10
11#define MODULE_ID MAKE_MODULE_ID('s', 'd', 't')
12
13/*
14 * The SPI device pins for which `spi_device_testutils_configure_pad_attrs()`
15 * configures the pad attributes.
16 */
17static const dt_pad_t kSpiDeviceDirectPads[4] = {
18 kDtPadSpiDeviceSd3, // sio[3]
19 kDtPadSpiDeviceSd2, // sio[2]
20 kDtPadSpiDeviceSd1, // sio[1]
21 kDtPadSpiDeviceSd0 // sio[0]
22};
23
24status_t spi_device_testutils_configure_passthrough(
25 dif_spi_device_handle_t *spi_device, uint32_t filters,
26 bool upload_write_commands) {
27 dif_spi_device_config_t spi_device_config = {
28 .tx_order = kDifSpiDeviceBitOrderMsbToLsb,
29 .rx_order = kDifSpiDeviceBitOrderMsbToLsb,
30 .device_mode = kDifSpiDeviceModePassthrough,
31 };
32 TRY(dif_spi_device_configure(spi_device, spi_device_config));
33
34 dif_spi_device_passthrough_intercept_config_t intercept_config = {
35 .status = upload_write_commands,
36 .jedec_id = false,
37 .sfdp = false,
38 .mailbox = false,
39 };
40 TRY(dif_spi_device_set_passthrough_intercept_config(spi_device,
41 intercept_config));
42
43 // Set up passthrough filter to allow all commands, initially.
44 TRY(dif_spi_device_set_all_passthrough_command_filters(spi_device,
45 kDifToggleDisabled));
46
47 dif_spi_device_flash_command_t read_commands[] = {
48 {
49 // Slot 0: ReadStatus1
50 .opcode = kSpiDeviceFlashOpReadStatus1,
51 .address_type = kDifSpiDeviceFlashAddrDisabled,
52 .dummy_cycles = 0,
53 .payload_io_type = kDifSpiDevicePayloadIoSingle,
54 .payload_dir_to_host = true,
55 },
56 {
57 // Slot 1: ReadStatus2
58 .opcode = kSpiDeviceFlashOpReadStatus2,
59 .address_type = kDifSpiDeviceFlashAddrDisabled,
60 .dummy_cycles = 0,
61 .payload_io_type = kDifSpiDevicePayloadIoSingle,
62 .payload_dir_to_host = true,
63 },
64 {
65 // Slot 2: ReadStatus3
66 .opcode = kSpiDeviceFlashOpReadStatus3,
67 .address_type = kDifSpiDeviceFlashAddrDisabled,
68 .dummy_cycles = 0,
69 .payload_io_type = kDifSpiDevicePayloadIoSingle,
70 .payload_dir_to_host = true,
71 },
72 {
73 // Slot 3: ReadJedecID
74 .opcode = kSpiDeviceFlashOpReadJedec,
75 .address_type = kDifSpiDeviceFlashAddrDisabled,
76 .dummy_cycles = 0,
77 .payload_io_type = kDifSpiDevicePayloadIoSingle,
78 .payload_dir_to_host = true,
79 },
80 {
81 // Slot 4: ReadSfdp
82 .opcode = kSpiDeviceFlashOpReadSfdp,
83 .address_type = kDifSpiDeviceFlashAddr3Byte,
84 .dummy_cycles = 8,
85 .payload_io_type = kDifSpiDevicePayloadIoSingle,
86 .payload_dir_to_host = true,
87 },
88 {
89 // Slot 5: ReadNormal
90 .opcode = kSpiDeviceFlashOpReadNormal,
91 .address_type = kDifSpiDeviceFlashAddrCfg,
92 .passthrough_swap_address = true,
93 .dummy_cycles = 0,
94 .payload_io_type = kDifSpiDevicePayloadIoSingle,
95 .payload_dir_to_host = true,
96 },
97 {
98 // Slot 6: ReadFast
99 .opcode = kSpiDeviceFlashOpReadFast,
100 .address_type = kDifSpiDeviceFlashAddrCfg,
101 .passthrough_swap_address = true,
102 .dummy_cycles = 8,
103 .payload_io_type = kDifSpiDevicePayloadIoSingle,
104 .payload_dir_to_host = true,
105 },
106 {
107 // Slot 7: ReadDual
108 .opcode = kSpiDeviceFlashOpReadDual,
109 .address_type = kDifSpiDeviceFlashAddrCfg,
110 .passthrough_swap_address = true,
111 .dummy_cycles = 8,
112 .payload_io_type = kDifSpiDevicePayloadIoDual,
113 .payload_dir_to_host = true,
114 },
115 {
116 // Slot 8: ReadQuad
117 .opcode = kSpiDeviceFlashOpReadQuad,
118 .address_type = kDifSpiDeviceFlashAddrCfg,
119 .passthrough_swap_address = true,
120 .dummy_cycles = 8,
121 .payload_io_type = kDifSpiDevicePayloadIoQuad,
122 .payload_dir_to_host = true,
123 },
124 {
125 // Slot 9: Read4b
126 .opcode = kSpiDeviceFlashOpRead4b,
127 .address_type = kDifSpiDeviceFlashAddr4Byte,
128 .passthrough_swap_address = true,
129 .dummy_cycles = 0,
130 .payload_io_type = kDifSpiDevicePayloadIoSingle,
131 .payload_dir_to_host = true,
132 },
133 {
134 // Slot 10: ReadFast4b
135 .opcode = kSpiDeviceFlashOpReadFast4b,
136 .address_type = kDifSpiDeviceFlashAddr4Byte,
137 .passthrough_swap_address = true,
138 .dummy_cycles = 8,
139 .payload_io_type = kDifSpiDevicePayloadIoSingle,
140 .payload_dir_to_host = true,
141 },
142 };
143 static_assert(ARRAYSIZE(read_commands) <= UINT8_MAX,
144 "Length of read_commands must fit in uint8_t or we must change "
145 "the type of i.");
146 for (uint8_t i = 0; i < ARRAYSIZE(read_commands); ++i) {
147 uint8_t slot = i + kSpiDeviceReadCommandSlotBase;
148 if (bitfield_bit32_read(filters, slot)) {
149 TRY(dif_spi_device_set_passthrough_command_filter(
150 spi_device, read_commands[i].opcode, kDifToggleEnabled));
151 }
152 TRY(dif_spi_device_set_flash_command_slot(
153 spi_device, slot, kDifToggleEnabled, read_commands[i]));
154 }
155 dif_spi_device_flash_command_t write_commands[] = {
156 {
157 // Slot 11: WriteStatus1
158 .opcode = kSpiDeviceFlashOpWriteStatus1,
159 .address_type = kDifSpiDeviceFlashAddrDisabled,
160 .payload_io_type = kDifSpiDevicePayloadIoSingle,
161 .payload_dir_to_host = false,
162 .upload = upload_write_commands,
163 .set_busy_status = upload_write_commands,
164 },
165 {
166 // Slot 12: WriteStatus2
167 .opcode = kSpiDeviceFlashOpWriteStatus2,
168 .address_type = kDifSpiDeviceFlashAddrDisabled,
169 .payload_io_type = kDifSpiDevicePayloadIoSingle,
170 .payload_dir_to_host = false,
171 .upload = upload_write_commands,
172 .set_busy_status = upload_write_commands,
173 },
174 {
175 // Slot 13: WriteStatus3
176 .opcode = kSpiDeviceFlashOpWriteStatus3,
177 .address_type = kDifSpiDeviceFlashAddrDisabled,
178 .payload_io_type = kDifSpiDevicePayloadIoSingle,
179 .payload_dir_to_host = false,
180 .upload = upload_write_commands,
181 .set_busy_status = upload_write_commands,
182 },
183 {
184 // Slot 14: ChipErase
185 .opcode = kSpiDeviceFlashOpChipErase,
186 .address_type = kDifSpiDeviceFlashAddrDisabled,
187 .payload_io_type = kDifSpiDevicePayloadIoNone,
188 .upload = upload_write_commands,
189 .set_busy_status = upload_write_commands,
190 },
191 {
192 // Slot 15: SectorErase
193 .opcode = kSpiDeviceFlashOpSectorErase,
194 .address_type = kDifSpiDeviceFlashAddrCfg,
195 .payload_io_type = kDifSpiDevicePayloadIoNone,
196 .upload = upload_write_commands,
197 .set_busy_status = upload_write_commands,
198 },
199 {
200 // Slot 16: BlockErase32k
201 .opcode = kSpiDeviceFlashOpBlockErase32k,
202 .address_type = kDifSpiDeviceFlashAddrCfg,
203 .payload_io_type = kDifSpiDevicePayloadIoNone,
204 .upload = upload_write_commands,
205 .set_busy_status = upload_write_commands,
206 },
207 {
208 // Slot 17: BlockErase64k
209 .opcode = kSpiDeviceFlashOpBlockErase64k,
210 .address_type = kDifSpiDeviceFlashAddrCfg,
211 .payload_io_type = kDifSpiDevicePayloadIoNone,
212 .upload = upload_write_commands,
213 .set_busy_status = upload_write_commands,
214 },
215 {
216 // Slot 18: PageProgram
217 .opcode = kSpiDeviceFlashOpPageProgram,
218 .address_type = kDifSpiDeviceFlashAddrCfg,
219 .payload_io_type = kDifSpiDevicePayloadIoSingle,
220 .payload_dir_to_host = false,
221 .upload = upload_write_commands,
222 .set_busy_status = upload_write_commands,
223 },
224 {
225 // Slot 19: SectorErase4b
226 .opcode = kSpiDeviceFlashOpSectorErase4b,
227 .address_type = kDifSpiDeviceFlashAddr4Byte,
228 .payload_io_type = kDifSpiDevicePayloadIoNone,
229 .upload = upload_write_commands,
230 .set_busy_status = upload_write_commands,
231 },
232 {
233 // Slot 20: BlockErase32k4b
234 .opcode = kSpiDeviceFlashOpBlockErase32k4b,
235 .address_type = kDifSpiDeviceFlashAddr4Byte,
236 .payload_io_type = kDifSpiDevicePayloadIoNone,
237 .upload = upload_write_commands,
238 .set_busy_status = upload_write_commands,
239 },
240 {
241 // Slot 21: BlockErase64k4b
242 .opcode = kSpiDeviceFlashOpBlockErase64k4b,
243 .address_type = kDifSpiDeviceFlashAddr4Byte,
244 .payload_io_type = kDifSpiDevicePayloadIoNone,
245 .upload = upload_write_commands,
246 .set_busy_status = upload_write_commands,
247 },
248 {
249 // Slot 22: PageProgram4b
250 .opcode = kSpiDeviceFlashOpPageProgram4b,
251 .address_type = kDifSpiDeviceFlashAddr4Byte,
252 .payload_io_type = kDifSpiDevicePayloadIoSingle,
253 .payload_dir_to_host = false,
254 .upload = upload_write_commands,
255 .set_busy_status = upload_write_commands,
256 },
257 {
258 // Slot 23: Reset
259 .opcode = kSpiDeviceFlashOpReset,
260 .address_type = kDifSpiDeviceFlashAddrDisabled,
261 .payload_io_type = kDifSpiDevicePayloadIoNone,
262 .upload = upload_write_commands,
263 .set_busy_status = upload_write_commands,
264 },
265
266 };
267 static_assert(ARRAYSIZE(write_commands) <= UINT8_MAX,
268 "Length of write_commands must fit into uint8_t");
269 for (uint8_t i = 0; i < ARRAYSIZE(write_commands); ++i) {
270 uint8_t slot = i + (uint8_t)kSpiDeviceWriteCommandSlotBase;
271 if (bitfield_bit32_read(filters, slot) || upload_write_commands) {
272 TRY(dif_spi_device_set_passthrough_command_filter(
273 spi_device, write_commands[i].opcode, kDifToggleEnabled));
274 }
275 TRY(dif_spi_device_set_flash_command_slot(
276 spi_device, slot, kDifToggleEnabled, write_commands[i]));
277 }
278 // This configuration for these commands does not guard against misbehaved
279 // hosts. The timing of any of these commands relative to an uploaded command
280 // cannot be determined.
281 TRY(dif_spi_device_configure_flash_wren_command(
282 spi_device, kDifToggleEnabled, kSpiDeviceFlashOpWriteEnable));
283 TRY(dif_spi_device_configure_flash_wrdi_command(
284 spi_device, kDifToggleEnabled, kSpiDeviceFlashOpWriteDisable));
285 TRY(dif_spi_device_configure_flash_en4b_command(
286 spi_device, kDifToggleEnabled, kSpiDeviceFlashOpEnter4bAddr));
287 TRY(dif_spi_device_configure_flash_ex4b_command(spi_device, kDifToggleEnabled,
288 kSpiDeviceFlashOpExit4bAddr));
289
290 if (upload_write_commands) {
291 TRY(dif_spi_device_set_passthrough_command_filter(
292 spi_device, kSpiDeviceFlashOpReadStatus1, kDifToggleEnabled));
293 TRY(dif_spi_device_set_passthrough_command_filter(
294 spi_device, kSpiDeviceFlashOpReadStatus2, kDifToggleEnabled));
295 TRY(dif_spi_device_set_passthrough_command_filter(
296 spi_device, kSpiDeviceFlashOpReadStatus3, kDifToggleEnabled));
297 TRY(dif_spi_device_set_passthrough_command_filter(
298 spi_device, kSpiDeviceFlashOpWriteEnable, kDifToggleEnabled));
299 TRY(dif_spi_device_set_passthrough_command_filter(
300 spi_device, kSpiDeviceFlashOpWriteDisable, kDifToggleEnabled));
301 }
302 return OK_STATUS();
303}
304
305status_t spi_device_testutils_configure_read_pipeline(
306 dif_spi_device_handle_t *spi_device,
307 dif_spi_device_read_pipeline_mode_t dual_mode,
308 dif_spi_device_read_pipeline_mode_t quad_mode) {
309 if (spi_device == NULL || dual_mode >= kDifSpiDeviceReadPipelineModeCount ||
310 quad_mode >= kDifSpiDeviceReadPipelineModeCount) {
311 return INVALID_ARGUMENT();
312 }
313
314 const dif_spi_device_flash_command_t normal_read_cmd = {
315 // Slot 5: ReadNormal
316 .opcode = kSpiDeviceFlashOpReadNormal,
317 .address_type = kDifSpiDeviceFlashAddrCfg,
318 .passthrough_swap_address = true,
319 .dummy_cycles = 0,
320 .payload_io_type = kDifSpiDevicePayloadIoSingle,
321 .payload_dir_to_host = true,
322 .read_pipeline_mode = dual_mode,
323 };
324 const dif_spi_device_flash_command_t fast_read_cmd = {
325 // Slot 6: ReadFast
326 .opcode = kSpiDeviceFlashOpReadFast,
327 .address_type = kDifSpiDeviceFlashAddrCfg,
328 .passthrough_swap_address = true,
329 .dummy_cycles = 8,
330 .payload_io_type = kDifSpiDevicePayloadIoSingle,
331 .payload_dir_to_host = true,
332 .read_pipeline_mode = dual_mode,
333 };
334 const dif_spi_device_flash_command_t dual_read_cmd = {
335 // Slot 7: ReadDual
336 .opcode = kSpiDeviceFlashOpReadDual,
337 .address_type = kDifSpiDeviceFlashAddrCfg,
338 .passthrough_swap_address = true,
339 .dummy_cycles = 8,
340 .payload_io_type = kDifSpiDevicePayloadIoDual,
341 .payload_dir_to_host = true,
342 .read_pipeline_mode = dual_mode,
343 };
344 const dif_spi_device_flash_command_t quad_read_cmd = {
345 // Slot 8: ReadQuad
346 .opcode = kSpiDeviceFlashOpReadQuad,
347 .address_type = kDifSpiDeviceFlashAddrCfg,
348 .passthrough_swap_address = true,
349 .dummy_cycles = 8,
350 .payload_io_type = kDifSpiDevicePayloadIoQuad,
351 .payload_dir_to_host = true,
352 .read_pipeline_mode = quad_mode,
353 };
354 TRY(dif_spi_device_set_flash_command_slot(
355 spi_device, /*slot=*/5, kDifToggleEnabled, normal_read_cmd));
356 TRY(dif_spi_device_set_flash_command_slot(spi_device, /*slot=*/6,
357 kDifToggleEnabled, fast_read_cmd));
358 TRY(dif_spi_device_set_flash_command_slot(spi_device, /*slot=*/7,
359 kDifToggleEnabled, dual_read_cmd));
360 TRY(dif_spi_device_set_flash_command_slot(spi_device, /*slot=*/8,
361 kDifToggleEnabled, quad_read_cmd));
362 return OK_STATUS();
363}
364
365status_t spi_device_testutils_configure_pad_attrs(dif_pinmux_t *pinmux) {
366 dif_pinmux_pad_attr_t out_attr;
367 dif_pinmux_pad_attr_t in_attr = {.slew_rate = 1, .drive_strength = 3};
368 dif_result_t res;
369 for (uint32_t i = 0; i < ARRAYSIZE(kSpiDeviceDirectPads); ++i) {
370 dt_pad_t pad = kSpiDeviceDirectPads[i];
371 res = dif_pinmux_pad_write_attrs_dt(pinmux, pad, in_attr, &out_attr);
372 if (res == kDifError) {
373 // Some target platforms may not support the specified value for slew rate
374 // and drive strength. If that's the case, use the values actually
375 // supported.
376 if (out_attr.slew_rate != in_attr.slew_rate) {
377 LOG_INFO(
378 "Specified slew rate not supported, trying supported slew rate");
379 in_attr.slew_rate = out_attr.slew_rate;
380 }
381 if (out_attr.drive_strength != in_attr.drive_strength) {
382 LOG_INFO(
383 "Specified drive strength not supported, trying supported drive "
384 "strength");
385 in_attr.drive_strength = out_attr.drive_strength;
386 }
387 TRY(dif_pinmux_pad_write_attrs_dt(pinmux, pad, in_attr, &out_attr));
388 // Note: fallthrough with the modified `in_attr` so that the same
389 // attributes are used for all pads.
390 }
391 }
392 return OK_STATUS();
393}
394
395status_t spi_device_testutils_wait_for_upload(dif_spi_device_handle_t *spid,
396 upload_info_t *info) {
397 // Wait for a SPI transaction cause an upload.
398 bool upload_pending;
399 do {
400 // The UploadCmdfifoNotEmpty interrupt status is updated after the SPI
401 // transaction completes.
402 TRY(dif_spi_device_irq_is_pending(
403 &spid->dev, kDifSpiDeviceIrqUploadCmdfifoNotEmpty, &upload_pending));
404 } while (!upload_pending);
405
406 uint8_t occupancy;
407
408 // Get the SPI opcode.
409 TRY(dif_spi_device_get_flash_command_fifo_occupancy(spid, &occupancy));
410 if (occupancy != 1) {
411 // Cannot have an uploaded command without an opcode.
412 return INTERNAL();
413 }
414 TRY(dif_spi_device_pop_flash_command_fifo(spid, &info->opcode));
415 // Get the flash_status register.
416 TRY(dif_spi_device_get_flash_status_registers(spid, &info->flash_status));
417
418 // Get the SPI address (if available).
419 TRY(dif_spi_device_get_flash_address_fifo_occupancy(spid, &occupancy));
420 if (occupancy) {
421 dif_toggle_t addr_4b;
422 TRY(dif_spi_device_get_4b_address_mode(spid, &addr_4b));
423 info->addr_4b = addr_4b;
424 TRY(dif_spi_device_pop_flash_address_fifo(spid, &info->address));
425 info->has_address = true;
426 }
427
428 // Get the SPI data payload (if available).
429 uint32_t start;
430 TRY(dif_spi_device_get_flash_payload_fifo_occupancy(spid, &info->data_len,
431 &start));
432 if (info->data_len) {
433 if (info->data_len > sizeof(info->data)) {
434 // We aren't expecting more than 256 bytes of data.
435 return INVALID_ARGUMENT();
436 }
437 TRY(dif_spi_device_read_flash_payload_buffer(spid, start, info->data_len,
438 info->data));
439 }
440
441 // Finished: ack the IRQ.
442 TRY(dif_spi_device_irq_acknowledge(&spid->dev,
443 kDifSpiDeviceIrqUploadCmdfifoNotEmpty));
444 return OK_STATUS();
445}