Software APIs
spi_device_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_SPI_DEVICE_TESTUTILS_H_
6 #define OPENTITAN_SW_DEVICE_LIB_TESTING_SPI_DEVICE_TESTUTILS_H_
7 
8 #include <assert.h>
9 #include <stdint.h>
10 
11 #include "sw/device/lib/base/status.h"
12 #include "sw/device/lib/dif/dif_pinmux.h"
13 #include "sw/device/lib/dif/dif_spi_device.h"
14 #include "sw/device/lib/testing/json/spi_passthru.h"
15 
16 /**
17  * A set of typical opcodes for named flash commands.
18  */
19 typedef enum spi_device_flash_opcode {
20  kSpiDeviceFlashOpReadJedec = 0x9f,
21  kSpiDeviceFlashOpReadSfdp = 0x5a,
22  kSpiDeviceFlashOpReadNormal = 0x03,
23  kSpiDeviceFlashOpRead4b = 0x13,
24  kSpiDeviceFlashOpReadFast = 0x0b,
25  kSpiDeviceFlashOpReadFast4b = 0x0c,
26  kSpiDeviceFlashOpReadDual = 0x3b,
27  kSpiDeviceFlashOpReadQuad = 0x6b,
28  kSpiDeviceFlashOpWriteEnable = 0x06,
29  kSpiDeviceFlashOpWriteDisable = 0x04,
30  kSpiDeviceFlashOpReadStatus1 = 0x05,
31  kSpiDeviceFlashOpReadStatus2 = 0x35,
32  kSpiDeviceFlashOpReadStatus3 = 0x15,
33  kSpiDeviceFlashOpWriteStatus1 = 0x01,
34  kSpiDeviceFlashOpWriteStatus2 = 0x31,
35  kSpiDeviceFlashOpWriteStatus3 = 0x11,
36  kSpiDeviceFlashOpChipErase = 0xc7,
37  kSpiDeviceFlashOpSectorErase = 0x20,
38  kSpiDeviceFlashOpBlockErase32k = 0x52,
39  kSpiDeviceFlashOpBlockErase64k = 0xd8,
40  kSpiDeviceFlashOpPageProgram = 0x02,
41  kSpiDeviceFlashOpEnter4bAddr = 0xb7,
42  kSpiDeviceFlashOpExit4bAddr = 0xe9,
43  kSpiDeviceFlashOpResetEnable = 0x66,
44  kSpiDeviceFlashOpReset = 0x99,
45  kSpiDeviceFlashOpSectorErase4b = 0x21,
46  kSpiDeviceFlashOpBlockErase32k4b = 0x5c,
47  kSpiDeviceFlashOpBlockErase64k4b = 0xdc,
48  kSpiDeviceFlashOpPageProgram4b = 0x12,
49 } spi_device_flash_opcode_t;
50 
51 /**
52  * The index where read and write commands begin in the command slots.
53  */
54 enum spi_device_command_slot {
55  kSpiDeviceReadCommandSlotBase = 0,
56  kSpiDeviceWriteCommandSlotBase = 11,
57 };
58 
59 /**
60  * Configure the SPI device in passthrough mode, allowing the following
61  * commands to pass through:
62  * - ReadJedec
63  * - ReadSfdp
64  * - ReadNormal
65  * - Read4b
66  * - ReadFast
67  * - ReadFast4b
68  * - ReadDual
69  * - ReadQuad
70  * - WriteEnable
71  * - WriteDisable
72  * - ReadStatus1
73  * - ReadStatus2
74  * - ReadStatus3
75  * - WriteStatus1
76  * - WriteStatus2
77  * - WriteStatus3
78  * - ChipErase
79  * - SectorErase
80  * - BlockErase32k
81  * - BlockErase64k
82  * - PageProgram
83  * - SectorErase4b
84  * - BlockErase32k4b
85  * - BlockErase64k4b
86  * - PageProgram4b
87  * - Reset
88  * - Enter4bAddr
89  * - Exit4bAddr
90  *
91  * @param spi_device A spi_device DIF handle.
92  * @param filters A bitmap of command slots to enable passthrough filters for.
93  * @param upload_write_commands Whether to upload write commands.
94  */
95 OT_WARN_UNUSED_RESULT
96 status_t spi_device_testutils_configure_passthrough(
97  dif_spi_device_handle_t *spi_device, uint32_t filters,
98  bool upload_write_commands);
99 
100 /**
101  * Configure the read pipeline setting of the read command slots.
102  *
103  * Note that these settings can be overwritten by any other function that writes
104  * the command slots. As such, this configuration should come after any function
105  * calls that would affect dual read and quad read commands.
106  *
107  * @param spi_device A spi_device DIF handle.
108  * @param dual_mode Desired read pipeline mode for the dual read command.
109  * @param quad_mode Desired read pipeline mode for the quad read command.
110  */
111 status_t spi_device_testutils_configure_read_pipeline(
112  dif_spi_device_handle_t *spi_device,
113  dif_spi_device_read_pipeline_mode_t dual_mode,
114  dif_spi_device_read_pipeline_mode_t quad_mode);
115 
116 /**
117  * Configure the SPI device pad attributes.
118  *
119  * @return A status_t indicating success or failure configuring the pad
120  * attributes.
121  */
122 OT_WARN_UNUSED_RESULT
123 status_t spi_device_testutils_configure_pad_attrs(dif_pinmux_t *pinmux);
124 
125 /**
126  * Wait for a spi command upload.
127  *
128  * Upon detecting a spi command upload, the `info` block will be populated
129  * with the opcode, address and data phases of the uploaded command.
130  *
131  * @param spid A spid_device DIF handle.
132  * @param info Pointer to an upload_info_t.
133  * @return A status_t indicating success or failure in receving the uploaded
134  * command.
135  */
136 OT_WARN_UNUSED_RESULT
137 status_t spi_device_testutils_wait_for_upload(dif_spi_device_handle_t *spid,
138  upload_info_t *info);
139 
140 #endif // OPENTITAN_SW_DEVICE_LIB_TESTING_SPI_DEVICE_TESTUTILS_H_
Return to OpenTitan Documentation