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_types.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 #define SPI_FLASH_HOST_CONTEXT_FLAG_OCTAL_MODE BIT(2) ///< Flash works under octal spi mode. 55 spi_flash_sus_cmd_conf sus_cfg; ///< To store suspend command/mask information. 56 uint32_t slicer_flags; /// Slicer flags for configuring how to slice data correctly while reading or writing. 57 #define SPI_FLASH_HOST_CONTEXT_SLICER_FLAG_DTR BIT(0) ///< Slice data according to DTR mode, the address and length must be even (A0=0). 58 } spi_flash_hal_context_t; 59 _Static_assert(sizeof(spi_flash_hal_context_t) == 40, "size of spi_flash_hal_context_t incorrect. Please check data compatibility with the ROM"); 60 61 /// This struct provide MSPI Flash necessary timing related config, should be consistent with that in union in `spi_flash_hal_config_t`. 62 typedef struct { 63 uint32_t extra_dummy; 64 uint32_t cs_hold; 65 uint8_t cs_setup; 66 spi_flash_ll_clock_reg_t clock_config; 67 } spi_flash_hal_timing_config_t; 68 69 /// Configuration structure for the SPI driver. 70 typedef struct { 71 union { 72 struct { 73 uint32_t extra_dummy; ///< extra dummy for timing compensation. 74 uint32_t cs_hold; ///< CS hold time config used by the host 75 uint8_t cs_setup; ///< (cycles-1) of prepare phase by spi clock 76 spi_flash_ll_clock_reg_t clock_config; ///< (optional) Clock configuration for Octal flash. 77 }; 78 spi_flash_hal_timing_config_t timing_reg; ///< Reconfigure timing tuning regs. 79 }; 80 bool iomux; ///< Whether the IOMUX is used, used for timing compensation. 81 int input_delay_ns; ///< Input delay on the MISO pin after the launch clock, used for timing compensation. 82 esp_flash_speed_t speed;///< SPI flash clock speed to work at. 83 spi_host_device_t host_id; ///< SPI peripheral ID. 84 int cs_num; ///< Which cs pin is used, 0-(SOC_SPI_PERIPH_CS_NUM-1). 85 bool auto_sus_en; ///< Auto suspend feature enable bit 1: enable, 0: disable. 86 bool octal_mode_en; ///< Octal spi flash mode enable bit 1: enable, 0: disable. 87 bool using_timing_tuning; ///< System exist SPI0/1 timing tuning, using value from system directely if set to 1. 88 esp_flash_io_mode_t default_io_mode; ///< Default flash io mode. 89 } spi_flash_hal_config_t; 90 91 /** 92 * Configure SPI flash hal settings. 93 * 94 * @param data Buffer to hold configured data, the buffer should be in DRAM to be available when cache disabled 95 * @param cfg Configurations to set 96 * 97 * @return 98 * - ESP_OK: success 99 * - ESP_ERR_INVALID_ARG: the data buffer is not in the DRAM. 100 */ 101 esp_err_t spi_flash_hal_init(spi_flash_hal_context_t *data_out, const spi_flash_hal_config_t *cfg); 102 103 /** 104 * Configure the device-related register before transactions. 105 * 106 * @param host The driver context. 107 * 108 * @return always return ESP_OK. 109 */ 110 esp_err_t spi_flash_hal_device_config(spi_flash_host_inst_t *host); 111 112 /** 113 * Send an user-defined spi transaction to the device. 114 * 115 * @note This is usually used when the memspi interface doesn't support some 116 * particular commands. Since this function supports timing compensation, it is 117 * also used to receive some data when the frequency is high. 118 * 119 * @param host The driver context. 120 * @param trans The transaction to send, also holds the received data. 121 * 122 * @return always return ESP_OK. 123 */ 124 esp_err_t spi_flash_hal_common_command(spi_flash_host_inst_t *host, spi_flash_trans_t *trans); 125 126 /** 127 * Erase whole flash chip by using the erase chip (C7h) command. 128 * 129 * @param host The driver context. 130 */ 131 void spi_flash_hal_erase_chip(spi_flash_host_inst_t *host); 132 133 /** 134 * Erase a specific sector by its start address through the sector erase (20h) 135 * command. For 24bit address only. 136 * 137 * @param host The driver context. 138 * @param start_address Start address of the sector to erase. 139 */ 140 void spi_flash_hal_erase_sector(spi_flash_host_inst_t *host, uint32_t start_address); 141 142 /** 143 * Erase a specific 64KB block by its start address through the 64KB block 144 * erase (D8h) command. For 24bit address only. 145 * 146 * @param host The driver context. 147 * @param start_address Start address of the block to erase. 148 */ 149 void spi_flash_hal_erase_block(spi_flash_host_inst_t *host, uint32_t start_address); 150 151 /** 152 * Program a page of the flash using the page program (02h) command. For 24bit address only. 153 * 154 * @param host The driver context. 155 * @param address Address of the page to program 156 * @param buffer Data to program 157 * @param length Size of the buffer in bytes, no larger than ``SPI_FLASH_HAL_MAX_WRITE_BYTES`` (64) bytes. 158 */ 159 void spi_flash_hal_program_page(spi_flash_host_inst_t *host, const void *buffer, uint32_t address, uint32_t length); 160 161 /** 162 * Read from the flash. Call ``spi_flash_hal_configure_host_read_mode`` to 163 * configure the read command before calling this function. 164 * 165 * @param host The driver context. 166 * @param buffer Buffer to store the read data 167 * @param address Address to read 168 * @param length Length to read, no larger than ``SPI_FLASH_HAL_MAX_READ_BYTES`` (64) bytes. 169 * 170 * @return always return ESP_OK. 171 */ 172 esp_err_t spi_flash_hal_read(spi_flash_host_inst_t *host, void *buffer, uint32_t address, uint32_t read_len); 173 174 /** 175 * @brief Send the write enable (06h) or write disable (04h) command to the flash chip. 176 * 177 * @param driver The driver context. 178 * @param wp true to enable the write protection, otherwise false. 179 * 180 * @return always return ESP_OK. 181 */ 182 esp_err_t spi_flash_hal_set_write_protect(spi_flash_host_inst_t *host, bool wp); 183 184 /** 185 * Check whether the SPI host is idle and can perform other operations. 186 * 187 * @param host The driver context. 188 * 189 * @return 0:busy, 1:idle, 2:suspended. 190 */ 191 uint32_t spi_flash_hal_check_status(spi_flash_host_inst_t *host); 192 193 /** 194 * @brief Configure the SPI host hardware registers for the specified io mode. 195 * 196 * Note that calling this configures SPI host registers, so if running any 197 * other commands as part of set_io_mode() then these must be run before 198 * calling this function. 199 * 200 * The command value, address length and dummy cycles are configured according 201 * to the format of read commands: 202 * 203 * - command: 8 bits, value set. 204 * - address: 24 bits 205 * - dummy: cycles to compensate the input delay 206 * - out & in data: 0 bits. 207 * 208 * The following commands still need to: 209 * 210 * - Read data: set address value and data (length and contents), no need 211 * to touch command and dummy phases. 212 * - Common read: set command value, address value (or length to 0 if not used) 213 * - Common write: set command value, address value (or length to 0 if not 214 * used), disable dummy phase, and set output data. 215 * 216 * @param host The driver context 217 * @param io_mode The HW read mode to use 218 * @param addr_bitlen Length of the address phase, in bits 219 * @param dummy_cyclelen_base Base cycles of the dummy phase, some extra dummy cycles may be appended to compensate the timing. 220 * @param command Actual reading command to send to flash chip on the bus. 221 * 222 * @return always return ESP_OK. 223 */ 224 esp_err_t spi_flash_hal_configure_host_io_mode(spi_flash_host_inst_t *host, uint32_t command, uint32_t addr_bitlen, 225 int dummy_cyclelen_base, esp_flash_io_mode_t io_mode); 226 227 /** 228 * Poll until the last operation is done. 229 * 230 * @param host The driver context. 231 */ 232 void spi_flash_hal_poll_cmd_done(spi_flash_host_inst_t *host); 233 234 /** 235 * 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 236 * regions that are accessible ith cache disabled. * 237 * 238 * @param host The driver context 239 * @param p The buffer holding data to send. 240 * 241 * @return True if the buffer can be used to send data, otherwise false. 242 */ 243 bool spi_flash_hal_supports_direct_write(spi_flash_host_inst_t *host, const void *p); 244 245 /** 246 * 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 247 * regions that are accessible ith cache disabled. * 248 * 249 * @param host The driver context 250 * @param p The buffer to hold the received data. 251 * 252 * @return True if the buffer can be used to receive data, otherwise false. 253 */ 254 bool spi_flash_hal_supports_direct_read(spi_flash_host_inst_t *host, const void *p); 255 256 /** 257 * @brief Resume flash chip status from suspend. 258 * 259 * @param host The driver context. 260 * 261 */ 262 void spi_flash_hal_resume(spi_flash_host_inst_t *host); 263 264 /** 265 * @brief Set the flash into suspend status manually. 266 * 267 * @param host The driver context. 268 * 269 */ 270 void spi_flash_hal_suspend(spi_flash_host_inst_t *host); 271 272 /** 273 * To setup for reading flash suspend status register 274 * 275 * @param host The driver context. 276 * @param sus_conf Flash chip suspend feature configuration, mainly for command config, may vary from chip to chip. 277 * 278 * @return Always ESP_OK 279 */ 280 esp_err_t spi_flash_hal_setup_read_suspend(spi_flash_host_inst_t *host, const spi_flash_sus_cmd_conf *sus_conf); 281
