1 // Copyright 2010-2019 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 /******************************************************************************* 16 * NOTICE 17 * The HAL is not public api, don't use in application code. 18 * See readme.md in hal/include/hal/readme.md 19 ******************************************************************************/ 20 21 // The HAL layer for SPI Flash (common part) 22 23 #pragma once 24 25 #include "hal/spi_flash_ll.h" 26 #include "hal/spi_types.h" 27 #include "hal/spi_flash_types.h" 28 #include "soc/soc_memory_layout.h" 29 30 /* Hardware host-specific constants */ 31 #define SPI_FLASH_HAL_MAX_WRITE_BYTES 64 32 #define SPI_FLASH_HAL_MAX_READ_BYTES 64 33 34 /** 35 * Generic driver context structure for all chips using the SPI peripheral. 36 * Include this into the HEAD of the driver data for other driver 37 * implementations that also use the SPI peripheral. 38 */ 39 typedef struct { 40 spi_flash_host_inst_t inst; ///< Host instance, containing host data and function pointer table. May update with the host (hardware version). 41 spi_dev_t *spi; ///< Pointer to SPI peripheral registers (SP1, SPI2 or SPI3). Set before initialisation. 42 int cs_num; ///< Which cs pin is used, 0-2. 43 struct { 44 uint8_t extra_dummy; ///< Pre-calculated extra dummy used for compensation 45 uint8_t cs_setup; ///< (cycles-1) of prepare phase by spi clock. 46 uint8_t cs_hold; ///< CS hold time config used by the host 47 uint8_t reserved2; ///< Reserved, set to 0. 48 }; 49 spi_flash_ll_clock_reg_t clock_conf; ///< Pre-calculated clock configuration value 50 esp_flash_io_mode_t base_io_mode; ///< Default IO mode mask for common commands 51 uint32_t flags; ///< Flags for configurations with one set of driver code. (e.g. QPI mode, auto-suspend mode, 64-bit address mode, etc.) 52 #define SPI_FLASH_HOST_CONTEXT_FLAG_AUTO_SUSPEND BIT(0) ///< When the auto-suspend is setup in configuration. 53 #define SPI_FLASH_HOST_CONTEXT_FLAG_AUTO_RESUME BIT(1) ///< Setup auto-resume feature. 54 spi_flash_sus_cmd_conf sus_cfg; ///< To store suspend command/mask information. 55 } spi_flash_hal_context_t; 56 _Static_assert(sizeof(spi_flash_hal_context_t) == 36, "size of spi_flash_hal_context_t incorrect. Please check data compatibility with the ROM"); 57 58 /// Configuration structure for the SPI driver. 59 typedef struct { 60 spi_host_device_t host_id; ///< SPI peripheral ID. 61 int cs_num; ///< Which cs pin is used, 0-(SOC_SPI_PERIPH_CS_NUM-1). 62 bool iomux; ///< Whether the IOMUX is used, used for timing compensation. 63 int input_delay_ns; ///< Input delay on the MISO pin after the launch clock, used for timing compensation. 64 esp_flash_speed_t speed;///< SPI flash clock speed to work at. 65 uint32_t cs_hold; ///< CS hold time config used by the host 66 uint8_t cs_setup; ///< (cycles-1) of prepare phase by spi clock 67 bool auto_sus_en; ///< Auto suspend feature enable bit 1: enable, 0: disable. 68 } spi_flash_hal_config_t; 69 70 /** 71 * Configure SPI flash hal settings. 72 * 73 * @param data Buffer to hold configured data, the buffer should be in DRAM to be available when cache disabled 74 * @param cfg Configurations to set 75 * 76 * @return 77 * - ESP_OK: success 78 * - ESP_ERR_INVALID_ARG: the data buffer is not in the DRAM. 79 */ 80 esp_err_t spi_flash_hal_init(spi_flash_hal_context_t *data_out, const spi_flash_hal_config_t *cfg); 81 82 /** 83 * Configure the device-related register before transactions. 84 * 85 * @param host The driver context. 86 * 87 * @return always return ESP_OK. 88 */ 89 esp_err_t spi_flash_hal_device_config(spi_flash_host_inst_t *host); 90 91 /** 92 * Send an user-defined spi transaction to the device. 93 * 94 * @note This is usually used when the memspi interface doesn't support some 95 * particular commands. Since this function supports timing compensation, it is 96 * also used to receive some data when the frequency is high. 97 * 98 * @param host The driver context. 99 * @param trans The transaction to send, also holds the received data. 100 * 101 * @return always return ESP_OK. 102 */ 103 esp_err_t spi_flash_hal_common_command(spi_flash_host_inst_t *host, spi_flash_trans_t *trans); 104 105 /** 106 * Erase whole flash chip by using the erase chip (C7h) command. 107 * 108 * @param host The driver context. 109 */ 110 void spi_flash_hal_erase_chip(spi_flash_host_inst_t *host); 111 112 /** 113 * Erase a specific sector by its start address through the sector erase (20h) 114 * command. For 24bit address only. 115 * 116 * @param host The driver context. 117 * @param start_address Start address of the sector to erase. 118 */ 119 void spi_flash_hal_erase_sector(spi_flash_host_inst_t *host, uint32_t start_address); 120 121 /** 122 * Erase a specific 64KB block by its start address through the 64KB block 123 * erase (D8h) command. For 24bit address only. 124 * 125 * @param host The driver context. 126 * @param start_address Start address of the block to erase. 127 */ 128 void spi_flash_hal_erase_block(spi_flash_host_inst_t *host, uint32_t start_address); 129 130 /** 131 * Program a page of the flash using the page program (02h) command. For 24bit address only. 132 * 133 * @param host The driver context. 134 * @param address Address of the page to program 135 * @param buffer Data to program 136 * @param length Size of the buffer in bytes, no larger than ``SPI_FLASH_HAL_MAX_WRITE_BYTES`` (64) bytes. 137 */ 138 void spi_flash_hal_program_page(spi_flash_host_inst_t *host, const void *buffer, uint32_t address, uint32_t length); 139 140 /** 141 * Read from the flash. Call ``spi_flash_hal_configure_host_read_mode`` to 142 * configure the read command before calling this function. 143 * 144 * @param host The driver context. 145 * @param buffer Buffer to store the read data 146 * @param address Address to read 147 * @param length Length to read, no larger than ``SPI_FLASH_HAL_MAX_READ_BYTES`` (64) bytes. 148 * 149 * @return always return ESP_OK. 150 */ 151 esp_err_t spi_flash_hal_read(spi_flash_host_inst_t *host, void *buffer, uint32_t address, uint32_t read_len); 152 153 /** 154 * @brief Send the write enable (06h) or write disable (04h) command to the flash chip. 155 * 156 * @param driver The driver context. 157 * @param wp true to enable the write protection, otherwise false. 158 * 159 * @return always return ESP_OK. 160 */ 161 esp_err_t spi_flash_hal_set_write_protect(spi_flash_host_inst_t *host, bool wp); 162 163 /** 164 * Check whether the SPI host is idle and can perform other operations. 165 * 166 * @param host The driver context. 167 * 168 * @return 0:busy, 1:idle, 2:suspended. 169 */ 170 uint32_t spi_flash_hal_check_status(spi_flash_host_inst_t *host); 171 172 /** 173 * @brief Configure the SPI host hardware registers for the specified io mode. 174 * 175 * Note that calling this configures SPI host registers, so if running any 176 * other commands as part of set_io_mode() then these must be run before 177 * calling this function. 178 * 179 * The command value, address length and dummy cycles are configured according 180 * to the format of read commands: 181 * 182 * - command: 8 bits, value set. 183 * - address: 24 bits 184 * - dummy: cycles to compensate the input delay 185 * - out & in data: 0 bits. 186 * 187 * The following commands still need to: 188 * 189 * - Read data: set address value and data (length and contents), no need 190 * to touch command and dummy phases. 191 * - Common read: set command value, address value (or length to 0 if not used) 192 * - Common write: set command value, address value (or length to 0 if not 193 * used), disable dummy phase, and set output data. 194 * 195 * @param host The driver context 196 * @param io_mode The HW read mode to use 197 * @param addr_bitlen Length of the address phase, in bits 198 * @param dummy_cyclelen_base Base cycles of the dummy phase, some extra dummy cycles may be appended to compensate the timing. 199 * @param command Actual reading command to send to flash chip on the bus. 200 * 201 * @return always return ESP_OK. 202 */ 203 esp_err_t spi_flash_hal_configure_host_io_mode(spi_flash_host_inst_t *host, uint32_t command, uint32_t addr_bitlen, 204 int dummy_cyclelen_base, esp_flash_io_mode_t io_mode); 205 206 /** 207 * Poll until the last operation is done. 208 * 209 * @param host The driver context. 210 */ 211 void spi_flash_hal_poll_cmd_done(spi_flash_host_inst_t *host); 212 213 /** 214 * Check whether the given buffer can be used as the write buffer directly. If 'chip' is connected to the main SPI bus, we can only write directly from 215 * regions that are accessible ith cache disabled. * 216 * 217 * @param host The driver context 218 * @param p The buffer holding data to send. 219 * 220 * @return True if the buffer can be used to send data, otherwise false. 221 */ 222 bool spi_flash_hal_supports_direct_write(spi_flash_host_inst_t *host, const void *p); 223 224 /** 225 * Check whether the given buffer can be used as the read buffer directly. If 'chip' is connected to the main SPI bus, we can only read directly from 226 * regions that are accessible ith cache disabled. * 227 * 228 * @param host The driver context 229 * @param p The buffer to hold the received data. 230 * 231 * @return True if the buffer can be used to receive data, otherwise false. 232 */ 233 bool spi_flash_hal_supports_direct_read(spi_flash_host_inst_t *host, const void *p); 234 235 /** 236 * @brief Resume flash chip status from suspend. 237 * 238 * @param host The driver context. 239 * 240 */ 241 void spi_flash_hal_resume(spi_flash_host_inst_t *host); 242 243 /** 244 * @brief Set the flash into suspend status manually. 245 * 246 * @param host The driver context. 247 * 248 */ 249 void spi_flash_hal_suspend(spi_flash_host_inst_t *host); 250 251 /** 252 * To setup for reading flash suspend status register 253 * 254 * @param host The driver context. 255 * @param sus_conf Flash chip suspend feature configuration, mainly for command config, may vary from chip to chip. 256 * 257 * @return Always ESP_OK 258 */ 259 esp_err_t spi_flash_hal_setup_read_suspend(spi_flash_host_inst_t *host, const spi_flash_sus_cmd_conf *sus_conf); 260