1 /* 2 * Copyright (c) 2020 - 2024 Renesas Electronics Corporation and/or its affiliates 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 /*******************************************************************************************************************//** 8 * @ingroup RENESAS_STORAGE_INTERFACES 9 * @defgroup SPI_FLASH_API SPI Flash Interface 10 * @brief Interface for accessing external SPI flash devices. 11 * 12 * @section SPI_FLASH_API_SUMMARY Summary 13 * The SPI flash API provides an interface that configures, writes, and erases sectors in SPI flash devices. 14 * @{ 15 **********************************************************************************************************************/ 16 17 #ifndef R_SPI_FLASH_API_H 18 #define R_SPI_FLASH_API_H 19 20 /*********************************************************************************************************************** 21 * Includes 22 **********************************************************************************************************************/ 23 24 /* Register definitions, common services and error codes. */ 25 #include "bsp_api.h" 26 27 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 28 FSP_HEADER 29 30 /********************************************************************************************************************** 31 * Macro definitions 32 **********************************************************************************************************************/ 33 34 #define SPI_FLASH_ERASE_SIZE_CHIP_ERASE (UINT32_MAX) 35 36 /********************************************************************************************************************** 37 * Typedef definitions 38 **********************************************************************************************************************/ 39 40 /** Read mode. */ 41 typedef enum e_spi_flash_read_mode 42 { 43 SPI_FLASH_READ_MODE_STANDARD = 0, ///< Standard Read Mode (no dummy cycles) 44 SPI_FLASH_READ_MODE_FAST_READ = 1, ///< Fast Read Mode (dummy cycles between address and data) 45 SPI_FLASH_READ_MODE_FAST_READ_DUAL_OUTPUT = 2, ///< Fast Read Dual Output Mode (data on 2 lines) 46 SPI_FLASH_READ_MODE_FAST_READ_DUAL_IO = 3, ///< Fast Read Dual I/O Mode (address and data on 2 lines) 47 SPI_FLASH_READ_MODE_FAST_READ_QUAD_OUTPUT = 4, ///< Fast Read Quad Output Mode (data on 4 lines) 48 SPI_FLASH_READ_MODE_FAST_READ_QUAD_IO = 5, ///< Fast Read Quad I/O Mode (address and data on 4 lines) 49 } spi_flash_read_mode_t; 50 51 /** SPI protocol. */ 52 typedef enum e_spi_flash_protocol 53 { 54 /** Extended SPI mode (commands on 1 line) */ 55 SPI_FLASH_PROTOCOL_EXTENDED_SPI = 0x000, 56 57 /** QPI mode (commands on 4 lines). Note that the application must ensure the device is in QPI mode. */ 58 SPI_FLASH_PROTOCOL_QPI = 0x002, 59 60 /** SOPI mode (command and data on 8 lines). Note that the application must ensure the device is in SOPI mode. */ 61 SPI_FLASH_PROTOCOL_SOPI = 0x003, 62 63 /** DOPI mode (command and data on 8 lines, dual data rate). Note that the application must ensure the device is in DOPI mode. */ 64 SPI_FLASH_PROTOCOL_DOPI = 0x004, 65 66 /** 1S-1S-1S protocol mode */ 67 SPI_FLASH_PROTOCOL_1S_1S_1S = 0x000, 68 69 /** 4S-4D-4D protocol mode */ 70 SPI_FLASH_PROTOCOL_4S_4D_4D = 0x3B2, 71 72 /** 8D-8D-8D protocol mode */ 73 SPI_FLASH_PROTOCOL_8D_8D_8D = 0x3FF, 74 75 /** 1S-2S-2S protocol mode */ 76 SPI_FLASH_PROTOCOL_1S_2S_2S = 0x048, 77 78 /** 2S-2S-2S protocol mode */ 79 SPI_FLASH_PROTOCOL_2S_2S_2S = 0x049, 80 81 /** 1S-4S-4S protocol mode */ 82 SPI_FLASH_PROTOCOL_1S_4S_4S = 0x090, 83 84 /** 4S-4S-4S protocol mode */ 85 SPI_FLASH_PROTOCOL_4S_4S_4S = 0x092 86 } spi_flash_protocol_t; 87 88 /** Number of bytes in the address. */ 89 typedef enum e_spi_flash_address_bytes 90 { 91 SPI_FLASH_ADDRESS_BYTES_3 = 2, ///< 3 address bytes 92 93 /** 4 address bytes with standard commands. If this option is selected, the application must issue the EN4B 94 * command using @ref spi_flash_api_t::directWrite() if required by the device. */ 95 SPI_FLASH_ADDRESS_BYTES_4 = 3, 96 97 /** 4 address bytes using standard 4-byte command set. */ 98 SPI_FLASH_ADDRESS_BYTES_4_4BYTE_READ_CODE = 0x13, 99 } spi_flash_address_bytes_t; 100 101 /** Number of data lines used. */ 102 typedef enum e_spi_flash_data_lines 103 { 104 SPI_FLASH_DATA_LINES_1 = 0, ///< 1 data line 105 SPI_FLASH_DATA_LINES_2 = 1, ///< 2 data lines 106 SPI_FLASH_DATA_LINES_4 = 2, ///< 4 data lines 107 } spi_flash_data_lines_t; 108 109 /** Number of dummy cycles for fast read operations. */ 110 typedef enum e_spi_flash_dummy_clocks 111 { 112 SPI_FLASH_DUMMY_CLOCKS_0 = 0, ///< 0 dummy clocks 113 SPI_FLASH_DUMMY_CLOCKS_1, ///< 1 dummy clocks 114 SPI_FLASH_DUMMY_CLOCKS_2, ///< 2 dummy clocks 115 SPI_FLASH_DUMMY_CLOCKS_3, ///< 3 dummy clocks 116 SPI_FLASH_DUMMY_CLOCKS_4, ///< 4 dummy clocks 117 SPI_FLASH_DUMMY_CLOCKS_5, ///< 5 dummy clocks 118 SPI_FLASH_DUMMY_CLOCKS_6, ///< 6 dummy clocks 119 SPI_FLASH_DUMMY_CLOCKS_7, ///< 7 dummy clocks 120 SPI_FLASH_DUMMY_CLOCKS_8, ///< 8 dummy clocks 121 SPI_FLASH_DUMMY_CLOCKS_9, ///< 9 dummy clocks 122 SPI_FLASH_DUMMY_CLOCKS_10, ///< 10 dummy clocks 123 SPI_FLASH_DUMMY_CLOCKS_11, ///< 11 dummy clocks 124 SPI_FLASH_DUMMY_CLOCKS_12, ///< 12 dummy clocks 125 SPI_FLASH_DUMMY_CLOCKS_13, ///< 13 dummy clocks 126 SPI_FLASH_DUMMY_CLOCKS_14, ///< 14 dummy clocks 127 SPI_FLASH_DUMMY_CLOCKS_15, ///< 15 dummy clocks 128 SPI_FLASH_DUMMY_CLOCKS_16, ///< 16 dummy clocks 129 SPI_FLASH_DUMMY_CLOCKS_17, ///< 17 dummy clocks 130 SPI_FLASH_DUMMY_CLOCKS_18, ///< 18 dummy clocks 131 SPI_FLASH_DUMMY_CLOCKS_19, ///< 19 dummy clocks 132 SPI_FLASH_DUMMY_CLOCKS_20, ///< 20 dummy clocks 133 SPI_FLASH_DUMMY_CLOCKS_21, ///< 21 dummy clocks 134 SPI_FLASH_DUMMY_CLOCKS_22, ///< 22 dummy clocks 135 SPI_FLASH_DUMMY_CLOCKS_23, ///< 23 dummy clocks 136 SPI_FLASH_DUMMY_CLOCKS_24, ///< 24 dummy clocks 137 SPI_FLASH_DUMMY_CLOCKS_25, ///< 25 dummy clocks 138 SPI_FLASH_DUMMY_CLOCKS_26, ///< 26 dummy clocks 139 SPI_FLASH_DUMMY_CLOCKS_27, ///< 27 dummy clocks 140 SPI_FLASH_DUMMY_CLOCKS_28, ///< 28 dummy clocks 141 SPI_FLASH_DUMMY_CLOCKS_29, ///< 29 dummy clocks 142 SPI_FLASH_DUMMY_CLOCKS_30, ///< 30 dummy clocks 143 SPI_FLASH_DUMMY_CLOCKS_31, ///< 31 dummy clocks 144 SPI_FLASH_DUMMY_CLOCKS_DEFAULT = 0xFF, 145 } spi_flash_dummy_clocks_t; 146 147 /** Direct Read and Write direction */ 148 typedef enum e_spi_flash_direct_transfer_dir_option 149 { 150 SPI_FLASH_DIRECT_TRANSFER_DIR_READ = 0x0, 151 SPI_FLASH_DIRECT_TRANSFER_DIR_WRITE = 0x1 152 } spi_flash_direct_transfer_dir_t; 153 154 /** Structure to define an erase command and associated erase size. */ 155 typedef struct st_spi_flash_erase_command 156 { 157 uint16_t command; ///< Erase command 158 uint32_t size; ///< Size of erase for associated command, set to SPI_FLASH_ERASE_SIZE_CHIP_ERASE for chip erase 159 } spi_flash_erase_command_t; 160 161 /** Structure to define a direct transfer. */ 162 typedef struct st_spi_flash_direct_transfer 163 { 164 union 165 { 166 uint64_t data_u64; ///< Data (64-bit) 167 uint32_t data; ///< Data 168 }; 169 uint32_t address; ///< Starting address 170 uint16_t command; ///< Transfer command 171 uint8_t dummy_cycles; ///< Number of dummy cycles 172 uint8_t command_length; ///< Command length 173 uint8_t address_length; ///< Address length 174 uint8_t data_length; ///< Data length 175 } spi_flash_direct_transfer_t; 176 177 /** User configuration structure used by the open function */ 178 typedef struct st_spi_flash_cfg 179 { 180 spi_flash_protocol_t spi_protocol; ///< Initial SPI protocol. SPI protocol can be changed in @ref spi_flash_api_t::spiProtocolSet. 181 spi_flash_read_mode_t read_mode; ///< Read mode 182 spi_flash_address_bytes_t address_bytes; ///< Number of bytes used to represent the address 183 spi_flash_dummy_clocks_t dummy_clocks; ///< Number of dummy clocks to use for fast read operations 184 185 /** Number of lines used to send address for page program command. This should either be 1 or match the number of lines used in 186 * the selected read mode. */ 187 spi_flash_data_lines_t page_program_address_lines; 188 uint8_t write_status_bit; ///< Which bit determines write status 189 uint8_t write_enable_bit; ///< Which bit determines write status 190 uint32_t page_size_bytes; ///< Page size in bytes (maximum number of bytes for page program). Used to specify single continuous write size (bytes) in case of OSPI RAM. 191 uint8_t page_program_command; ///< Page program command 192 uint8_t write_enable_command; ///< Command to enable write or erase, typically 0x06 193 uint8_t status_command; ///< Command to read the write status 194 uint8_t read_command; ///< Read command - OSPI SPI mode only 195 uint8_t xip_enter_command; ///< Command to enter XIP mode 196 uint8_t xip_exit_command; ///< Command to exit XIP mode 197 uint8_t erase_command_list_length; ///< Length of erase command list 198 spi_flash_erase_command_t const * p_erase_command_list; ///< List of all erase commands and associated sizes 199 void const * p_extend; ///< Pointer to implementation specific extended configurations 200 } spi_flash_cfg_t; 201 202 /** SPI flash control block. Allocate an instance specific control block to pass into the SPI flash API calls. 203 */ 204 typedef void spi_flash_ctrl_t; 205 206 /** Status. */ 207 typedef struct st_spi_flash_status 208 { 209 /** Whether or not a write is in progress. This is determined by reading the @ref spi_flash_cfg_t::write_status_bit 210 * from the @ref spi_flash_cfg_t::status_command. */ 211 bool write_in_progress; 212 } spi_flash_status_t; 213 214 /** SPI flash implementations follow this API. */ 215 typedef struct st_spi_flash_api 216 { 217 /** Open the SPI flash driver module. 218 * 219 * @param[in] p_ctrl Pointer to a driver handle 220 * @param[in] p_cfg Pointer to a configuration structure 221 **/ 222 fsp_err_t (* open)(spi_flash_ctrl_t * const p_ctrl, spi_flash_cfg_t const * const p_cfg); 223 224 /** Write raw data to the SPI flash. 225 * 226 * @param[in] p_ctrl Pointer to a driver handle 227 * @param[in] p_src Pointer to raw data to write, must include any required command/address 228 * @param[in] bytes Number of bytes to write 229 * @param[in] read_after_write If true, the slave select remains asserted and the peripheral does not return 230 * to direct communications mode. If false, the slave select is deasserted and 231 * memory mapped access is possible after this function returns if the device 232 * is not busy. 233 **/ 234 fsp_err_t (* directWrite)(spi_flash_ctrl_t * const p_ctrl, uint8_t const * const p_src, uint32_t const bytes, 235 bool const read_after_write); 236 237 /** Read raw data from the SPI flash. Must follow a call to @ref spi_flash_api_t::directWrite. 238 * 239 * @param[in] p_ctrl Pointer to a driver handle 240 * @param[out] p_dest Pointer to read raw data into 241 * @param[in] bytes Number of bytes to read 242 **/ 243 fsp_err_t (* directRead)(spi_flash_ctrl_t * const p_ctrl, uint8_t * const p_dest, uint32_t const bytes); 244 245 /** Direct Read/Write raw data to the SPI flash. 246 * 247 * @param[in] p_ctrl Pointer to a driver handle 248 * @param[in] p_data Pointer to command, address and data values and lengths 249 * @param[in] direction Direct Read/Write 250 **/ 251 fsp_err_t (* directTransfer)(spi_flash_ctrl_t * const p_ctrl, spi_flash_direct_transfer_t * const p_transfer, 252 spi_flash_direct_transfer_dir_t direction); 253 254 /** Change the SPI protocol in the driver. The application must change the SPI protocol on the device. 255 * 256 * @param[in] p_ctrl Pointer to a driver handle 257 * @param[in] spi_protocol Desired SPI protocol 258 **/ 259 fsp_err_t (* spiProtocolSet)(spi_flash_ctrl_t * const p_ctrl, spi_flash_protocol_t spi_protocol); 260 261 /** Program a page of data to the flash. 262 * 263 * @param[in] p_ctrl Pointer to a driver handle 264 * @param[in] p_src The memory address of the data to write to the flash device 265 * @param[in] p_dest The location in the flash device address space to write the data to 266 * @param[in] byte_count The number of bytes to write 267 **/ 268 fsp_err_t (* write)(spi_flash_ctrl_t * const p_ctrl, uint8_t const * const p_src, uint8_t * const p_dest, 269 uint32_t byte_count); 270 271 /** Erase a certain number of bytes of the flash. 272 * 273 * @param[in] p_ctrl Pointer to a driver handle 274 * @param[in] p_device_address The location in the flash device address space to start the erase from 275 * @param[in] byte_count The number of bytes to erase. Set to SPI_FLASH_ERASE_SIZE_CHIP_ERASE to erase entire 276 * chip. 277 **/ 278 fsp_err_t (* erase)(spi_flash_ctrl_t * const p_ctrl, uint8_t * const p_device_address, uint32_t byte_count); 279 280 /** Get the write or erase status of the flash. 281 * 282 * @param[in] p_ctrl Pointer to a driver handle 283 * @param[out] p_status Current status of the SPI flash device stored here. 284 **/ 285 fsp_err_t (* statusGet)(spi_flash_ctrl_t * const p_ctrl, spi_flash_status_t * const p_status); 286 287 /** Enter XIP mode. 288 * 289 * @param[in] p_ctrl Pointer to a driver handle 290 **/ 291 fsp_err_t (* xipEnter)(spi_flash_ctrl_t * const p_ctrl); 292 293 /** Exit XIP mode. 294 * 295 * @param[in] p_ctrl Pointer to a driver handle 296 **/ 297 fsp_err_t (* xipExit)(spi_flash_ctrl_t * const p_ctrl); 298 299 /** Select the bank to access. See implementation for details. 300 * 301 * @param[in] p_ctrl Pointer to a driver handle 302 * @param[in] bank The bank number 303 **/ 304 fsp_err_t (* bankSet)(spi_flash_ctrl_t * const p_ctrl, uint32_t bank); 305 306 /** AutoCalibrate the SPI flash driver module. Expected to be used when auto-calibrating OSPI RAM device. 307 * 308 * @param[in] p_ctrl Pointer to a driver handle 309 **/ 310 fsp_err_t (* autoCalibrate)(spi_flash_ctrl_t * const p_ctrl); 311 312 /** Close the SPI flash driver module. 313 * 314 * @param[in] p_ctrl Pointer to a driver handle 315 **/ 316 fsp_err_t (* close)(spi_flash_ctrl_t * const p_ctrl); 317 } spi_flash_api_t; 318 319 /** This structure encompasses everything that is needed to use an instance of this interface. */ 320 typedef struct st_spi_flash_instance 321 { 322 spi_flash_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 323 spi_flash_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 324 spi_flash_api_t const * p_api; ///< Pointer to the API structure for this instance 325 } spi_flash_instance_t; 326 327 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 328 FSP_FOOTER 329 330 #endif 331 332 /*******************************************************************************************************************//** 333 * @} (end defgroup SPI_FLASH_API) 334 **********************************************************************************************************************/ 335
