1 /*
2  * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  *
6  * This is a STUB FILE HEADER used when compiling ESP-IDF to run tests on the host system.
7  * The header file used normally for ESP-IDF has the same name but is located elsewhere.
8  */
9 #pragma once
10 
11 #ifdef __cplusplus
12 extern "C" {
13 #endif
14 
15 /** Definition of a common transaction. Also holds the return value. */
16 typedef struct {
17     uint8_t command;            ///< Command to send, always 8bits
18     uint8_t mosi_len;           ///< Output data length, in bytes
19     uint8_t miso_len;           ///< Input data length, in bytes
20     uint8_t address_bitlen;     ///< Length of address in bits, set to 0 if command does not need an address
21     uint32_t address;           ///< Address to perform operation on
22     const uint8_t *mosi_data;   ///< Output data to salve
23     uint8_t *miso_data;         ///< [out] Input data from slave, little endian
24 } spi_flash_trans_t;
25 
26 /** @brief Mode used for reading from SPI flash */
27 typedef enum {
28     SPI_FLASH_SLOWRD = 0, ///< Data read using single I/O, some limits on speed
29     SPI_FLASH_FASTRD, ///< Data read using single I/O, no limit on speed
30     SPI_FLASH_DOUT,   ///< Data read using dual I/O
31     SPI_FLASH_DIO,    ///< Both address & data transferred using dual I/O
32     SPI_FLASH_QOUT,   ///< Data read using quad I/O
33     SPI_FLASH_QIO,    ///< Both address & data transferred using quad I/O
34 
35     SPI_FLASH_READ_MODE_MAX,    ///< The fastest io mode supported by the host is ``ESP_FLASH_READ_MODE_MAX-1``.
36 } esp_flash_io_mode_t;
37 
38 /**
39  * Configuration structure for the flash chip suspend feature.
40  */
41 typedef struct spi_flash_sus_cmd_conf_dummy spi_flash_sus_cmd_conf;
42 
43 struct spi_flash_host_driver_s;
44 typedef struct spi_flash_host_driver_s spi_flash_host_driver_t;
45 
46 /** SPI Flash Host driver instance */
47 typedef struct {
48     const struct spi_flash_host_driver_s* driver;  ///< Pointer to the implementation function table
49     // Implementations can wrap this structure into their own ones, and append other data here
50 } spi_flash_host_inst_t ;
51 
52 /** Host driver configuration and context structure. */
53 struct spi_flash_host_driver_s {
54     /**
55      * Configure the device-related register before transactions. This saves
56      * some time to re-configure those registers when we send continuously
57      */
58     esp_err_t (*dev_config)(spi_flash_host_inst_t *host);
59     /**
60      * Send an user-defined spi transaction to the device.
61      */
62     esp_err_t (*common_command)(spi_flash_host_inst_t *host, spi_flash_trans_t *t);
63     /**
64      * Read flash ID.
65      */
66     esp_err_t (*read_id)(spi_flash_host_inst_t *host, uint32_t *id);
67     /**
68      * Erase whole flash chip.
69      */
70     void (*erase_chip)(spi_flash_host_inst_t *host);
71     /**
72      * Erase a specific sector by its start address.
73      */
74     void (*erase_sector)(spi_flash_host_inst_t *host, uint32_t start_address);
75     /**
76      * Erase a specific block by its start address.
77      */
78     void (*erase_block)(spi_flash_host_inst_t *host, uint32_t start_address);
79     /**
80      * Read the status of the flash chip.
81      */
82     esp_err_t (*read_status)(spi_flash_host_inst_t *host, uint8_t *out_sr);
83     /**
84      * Disable write protection.
85      */
86     esp_err_t (*set_write_protect)(spi_flash_host_inst_t *host, bool wp);
87     /**
88      * Program a page of the flash. Check ``max_write_bytes`` for the maximum allowed writing length.
89      */
90     void (*program_page)(spi_flash_host_inst_t *host, const void *buffer, uint32_t address, uint32_t length);
91     /** Check whether given buffer can be directly used to write */
92     bool (*supports_direct_write)(spi_flash_host_inst_t *host, const void *p);
93     /**
94      * Slicer for write data. The `program_page` should be called iteratively with the return value
95      * of this function.
96      *
97      * @param address Beginning flash address to write
98      * @param len Length request to write
99      * @param align_addr Output of the aligned address to write to
100      * @param page_size Physical page size of the flash chip
101      * @return Length that can be actually written in one `program_page` call
102      */
103     int (*write_data_slicer)(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t *align_addr,
104                              uint32_t page_size);
105     /**
106      * Read data from the flash. Check ``max_read_bytes`` for the maximum allowed reading length.
107      */
108     esp_err_t (*read)(spi_flash_host_inst_t *host, void *buffer, uint32_t address, uint32_t read_len);
109     /** Check whether given buffer can be directly used to read */
110     bool (*supports_direct_read)(spi_flash_host_inst_t *host, const void *p);
111     /**
112      * Slicer for read data. The `read` should be called iteratively with the return value
113      * of this function.
114      *
115      * @param address Beginning flash address to read
116      * @param len Length request to read
117      * @param align_addr Output of the aligned address to read
118      * @param page_size Physical page size of the flash chip
119      * @return Length that can be actually read in one `read` call
120      */
121     int (*read_data_slicer)(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t *align_addr, uint32_t page_size);
122     /**
123      * Check the host status, 0:busy, 1:idle, 2:suspended.
124      */
125     uint32_t (*host_status)(spi_flash_host_inst_t *host);
126     /**
127      * Configure the host to work at different read mode. Responsible to compensate the timing and set IO mode.
128      */
129     esp_err_t (*configure_host_io_mode)(spi_flash_host_inst_t *host, uint32_t command,
130                                         uint32_t addr_bitlen, int dummy_bitlen_base,
131                                         esp_flash_io_mode_t io_mode);
132     /**
133      *  Internal use, poll the HW until the last operation is done.
134      */
135     void (*poll_cmd_done)(spi_flash_host_inst_t *host);
136     /**
137      * For some host (SPI1), they are shared with a cache. When the data is
138      * modified, the cache needs to be flushed. Left NULL if not supported.
139      */
140     esp_err_t (*flush_cache)(spi_flash_host_inst_t* host, uint32_t addr, uint32_t size);
141 
142     /**
143      * Resume flash from suspend manually
144      */
145     void (*resume)(spi_flash_host_inst_t *host);
146 
147     /**
148      * Set flash in suspend status manually
149      */
150     void (*suspend)(spi_flash_host_inst_t *host);
151 
152     /**
153      * Suspend feature setup for setting cmd and status register mask.
154      */
155     esp_err_t (*sus_setup)(spi_flash_host_inst_t *host, const spi_flash_sus_cmd_conf *sus_conf);
156 };
157 ///Slowest io mode supported by ESP32, currently SlowRd
158 #define SPI_FLASH_READ_MODE_MIN SPI_FLASH_SLOWRD
159 
160 #ifdef __cplusplus
161 }
162 #endif
163