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 */
19typedef 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 */
54enum 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 */
95OT_WARN_UNUSED_RESULT
96status_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 */
111status_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 */
122OT_WARN_UNUSED_RESULT
123status_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 */
136OT_WARN_UNUSED_RESULT
137status_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_