1 // Copyright 2015-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 #pragma once 16 #include "hal/spi_flash_hal.h" 17 18 /** Default configuration for the memspi (high speed version) */ 19 #define ESP_FLASH_DEFAULT_HOST_DRIVER() (spi_flash_host_driver_t) { \ 20 .dev_config = spi_flash_hal_device_config, \ 21 .common_command = spi_flash_hal_common_command, \ 22 .read_id = memspi_host_read_id_hs, \ 23 .erase_chip = spi_flash_hal_erase_chip, \ 24 .erase_sector = spi_flash_hal_erase_sector, \ 25 .erase_block = spi_flash_hal_erase_block, \ 26 .read_status = memspi_host_read_status_hs, \ 27 .set_write_protect = spi_flash_hal_set_write_protect, \ 28 .supports_direct_write = spi_flash_hal_supports_direct_write, \ 29 .supports_direct_read = spi_flash_hal_supports_direct_read, \ 30 .program_page = spi_flash_hal_program_page, \ 31 .write_data_slicer = memspi_host_write_data_slicer, \ 32 .read = spi_flash_hal_read, \ 33 .read_data_slicer = memspi_host_read_data_slicer, \ 34 .host_status = spi_flash_hal_check_status, \ 35 .configure_host_io_mode = spi_flash_hal_configure_host_io_mode, \ 36 .poll_cmd_done = spi_flash_hal_poll_cmd_done, \ 37 .flush_cache = memspi_host_flush_cache, \ 38 .check_suspend = NULL, \ 39 .resume = spi_flash_hal_resume, \ 40 .suspend = spi_flash_hal_suspend,\ 41 .sus_setup = spi_flash_hal_setup_read_suspend,\ 42 } 43 44 /// configuration for the memspi host 45 typedef spi_flash_hal_config_t memspi_host_config_t; 46 /// context for the memspi host 47 typedef spi_flash_hal_context_t memspi_host_inst_t; 48 49 /** 50 * Initialize the memory SPI host. 51 * 52 * @param host Pointer to the host structure. 53 * @param cfg Pointer to configuration structure 54 * 55 * @return always return ESP_OK 56 */ 57 esp_err_t memspi_host_init_pointers(memspi_host_inst_t *host, const memspi_host_config_t *cfg); 58 59 /******************************************************************************* 60 * NOTICE 61 * Rest part of this file are part of the HAL layer 62 * The HAL is not public api, don't use in application code. 63 * See readme.md in hal/include/hal/readme.md 64 ******************************************************************************/ 65 66 /** 67 * @brief Read the Status Register read from RDSR (05h). 68 * 69 * High speed implementation of RDID through memspi interface relying on the 70 * ``common_command``. 71 * 72 * @param host The driver context. 73 * @param id Output of the read ID from the slave. 74 * 75 * @return 76 * - ESP_OK: if success 77 * - ESP_ERR_FLASH_NO_RESPONSE: if no response from chip 78 * - or other cases from ``spi_hal_common_command`` 79 */ 80 esp_err_t memspi_host_read_id_hs(spi_flash_host_inst_t *host, uint32_t *id); 81 82 /** 83 * High speed implementation of RDSR through memspi interface relying on the 84 * ``common_command``. 85 * 86 * @param host The driver context. 87 * @param id Output of the read ID from the slave. 88 * 89 * @return 90 * - ESP_OK: if success 91 * - or other cases from ``spi_hal_common_command`` 92 */ 93 esp_err_t memspi_host_read_status_hs(spi_flash_host_inst_t *host, uint8_t *out_sr); 94 95 /** 96 * Flush the cache (if needed) after the contents are modified. 97 * 98 * @param host The driver context. 99 * @param addr Start address of the modified region 100 * @param size Size of the region modified. 101 * 102 * @return always ESP_OK. 103 */ 104 esp_err_t memspi_host_flush_cache(spi_flash_host_inst_t *host, uint32_t addr, uint32_t size); 105 106 /** 107 * Erase contents of entire chip. 108 * 109 * @param host The driver context. 110 */ 111 void memspi_host_erase_chip(spi_flash_host_inst_t *host); 112 113 /** 114 * Erase a sector starting from a given address. For 24bit address only. 115 * 116 * @param host The driver context. 117 * @param start_address Starting address of the sector. 118 */ 119 void memspi_host_erase_sector(spi_flash_host_inst_t *host, uint32_t start_address); 120 121 /** 122 * Erase a block starting from a given address. For 24bit address only. 123 * 124 * @param host The driver context. 125 * @param start_address Starting address of the block. 126 */ 127 void memspi_host_erase_block(spi_flash_host_inst_t *host, uint32_t start_address); 128 129 /** 130 * Program a page with contents of a buffer. For 24bit address only. 131 * 132 * @param host The driver context. 133 * @param buffer Buffer which contains the data to be flashed. 134 * @param address Starting address of where to flash the data. 135 * @param length The number of bytes to flash. 136 */ 137 void memspi_host_program_page(spi_flash_host_inst_t *host, const void *buffer, uint32_t address, uint32_t length); 138 139 /** 140 * Set ability to write to chip. 141 * 142 * @param host The driver context. 143 * @param wp Enable or disable write protect (true - enable, false - disable). 144 */ 145 esp_err_t memspi_host_set_write_protect(spi_flash_host_inst_t *host, bool wp); 146 147 /** 148 * Read data to buffer. 149 * 150 * @param host The driver context. 151 * @param buffer Buffer which contains the data to be read. 152 * @param address Starting address of where to read the data. 153 * @param length The number of bytes to read. 154 */ 155 esp_err_t memspi_host_read(spi_flash_host_inst_t *host, void *buffer, uint32_t address, uint32_t read_len); 156 157 /** 158 * @brief Slicer for read data used in non-encrypted regions. This slicer does nothing but 159 * limit the length to the maximum size the host supports. 160 * 161 * @param address Flash address to read 162 * @param len Length to read 163 * @param align_address Output of the address to read, should be equal to the input `address` 164 * @param page_size Physical SPI flash page size 165 * 166 * @return Length that can actually be read in one `read` call in `spi_flash_host_driver_t`. 167 */ 168 int memspi_host_read_data_slicer(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t *align_address, uint32_t page_size); 169 170 /** 171 * @brief Slicer for write data used in non-encrypted regions. This slicer limit the length to the 172 * maximum size the host supports, and truncate if the write data lie accross the page boundary 173 * (256 bytes) 174 * 175 * @param address Flash address to write 176 * @param len Length to write 177 * @param align_address Output of the address to write, should be equal to the input `address` 178 * @param page_size Physical SPI flash page size 179 * 180 * @return Length that can actually be written in one `program_page` call in `spi_flash_host_driver_t`. 181 */ 182 int memspi_host_write_data_slicer(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t *align_address, uint32_t page_size); 183