1 /* 2 * This file is part of the Serial Flash Universal Driver Library. 3 * 4 * Copyright (c) 2016-2018, Armink, <[email protected]> 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining 7 * a copy of this software and associated documentation files (the 8 * 'Software'), to deal in the Software without restriction, including 9 * without limitation the rights to use, copy, modify, merge, publish, 10 * distribute, sublicense, and/or sell copies of the Software, and to 11 * permit persons to whom the Software is furnished to do so, subject to 12 * the following conditions: 13 * 14 * The above copyright notice and this permission notice shall be 15 * included in all copies or substantial portions of the Software. 16 * 17 * THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, 18 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 20 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 21 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 22 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 23 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 24 * 25 * Function: It is the macro definition head file for this library. 26 * Created on: 2016-04-23 27 */ 28 29 #ifndef _SFUD_DEF_H_ 30 #define _SFUD_DEF_H_ 31 32 #include <stdio.h> 33 #include <stdlib.h> 34 #include <stdint.h> 35 #include <stdbool.h> 36 #include <sfud_cfg.h> 37 #include "sfud_flash_def.h" 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 /* debug print function. Must be implement by user. */ 44 #ifdef SFUD_DEBUG_MODE 45 #ifndef SFUD_DEBUG 46 #define SFUD_DEBUG(...) sfud_log_debug(__FILE__, __LINE__, __VA_ARGS__) 47 #endif /* SFUD_DEBUG */ 48 #else 49 #define SFUD_DEBUG(...) 50 #endif /* SFUD_DEBUG_MODE */ 51 52 #ifndef SFUD_INFO 53 #define SFUD_INFO(...) sfud_log_info(__VA_ARGS__) 54 #endif 55 56 /* assert for developer. */ 57 #ifdef SFUD_DEBUG_MODE 58 #define SFUD_ASSERT(EXPR) \ 59 if (!(EXPR)) \ 60 { \ 61 SFUD_DEBUG("(%s) has assert failed at %s.", #EXPR, __FUNCTION__); \ 62 while (1); \ 63 } 64 #else 65 #define SFUD_ASSERT(EXPR) 66 #endif 67 68 /** 69 * retry process 70 * 71 * @param delay delay function for every retry. NULL will not delay for every retry. 72 * @param retry retry counts 73 * @param result SFUD_ERR_TIMEOUT: retry timeout 74 */ 75 #define SFUD_RETRY_PROCESS(delay, retry, result) \ 76 void (*__delay_temp)(void) = (void (*)(void))delay; \ 77 if (retry == 0) {result = SFUD_ERR_TIMEOUT;break;} \ 78 else {if (__delay_temp) {__delay_temp();} retry --;} 79 80 /* software version number */ 81 #define SFUD_SW_VERSION "1.1.0" 82 /* 83 * all defined supported command 84 */ 85 #ifndef SFUD_CMD_WRITE_ENABLE 86 #define SFUD_CMD_WRITE_ENABLE 0x06 87 #endif 88 89 #ifndef SFUD_CMD_WRITE_DISABLE 90 #define SFUD_CMD_WRITE_DISABLE 0x04 91 #endif 92 93 #ifndef SFUD_CMD_READ_STATUS_REGISTER 94 #define SFUD_CMD_READ_STATUS_REGISTER 0x05 95 #endif 96 97 #ifndef SFUD_VOLATILE_SR_WRITE_ENABLE 98 #define SFUD_VOLATILE_SR_WRITE_ENABLE 0x50 99 #endif 100 101 #ifndef SFUD_CMD_WRITE_STATUS_REGISTER 102 #define SFUD_CMD_WRITE_STATUS_REGISTER 0x01 103 #endif 104 105 #ifndef SFUD_CMD_PAGE_PROGRAM 106 #define SFUD_CMD_PAGE_PROGRAM 0x02 107 #endif 108 109 #ifndef SFUD_CMD_AAI_WORD_PROGRAM 110 #define SFUD_CMD_AAI_WORD_PROGRAM 0xAD 111 #endif 112 113 #ifndef SFUD_CMD_ERASE_CHIP 114 #define SFUD_CMD_ERASE_CHIP 0xC7 115 #endif 116 117 #ifndef SFUD_CMD_READ_DATA 118 #define SFUD_CMD_READ_DATA 0x03 119 #endif 120 121 #ifndef SFUD_CMD_DUAL_OUTPUT_READ_DATA 122 #define SFUD_CMD_DUAL_OUTPUT_READ_DATA 0x3B 123 #endif 124 125 #ifndef SFUD_CMD_DUAL_IO_READ_DATA 126 #define SFUD_CMD_DUAL_IO_READ_DATA 0xBB 127 #endif 128 129 #ifndef SFUD_CMD_QUAD_IO_READ_DATA 130 #define SFUD_CMD_QUAD_IO_READ_DATA 0xEB 131 #endif 132 133 #ifndef SFUD_CMD_QUAD_OUTPUT_READ_DATA 134 #define SFUD_CMD_QUAD_OUTPUT_READ_DATA 0x6B 135 #endif 136 137 #ifndef SFUD_CMD_MANUFACTURER_DEVICE_ID 138 #define SFUD_CMD_MANUFACTURER_DEVICE_ID 0x90 139 #endif 140 141 #ifndef SFUD_CMD_JEDEC_ID 142 #define SFUD_CMD_JEDEC_ID 0x9F 143 #endif 144 145 #ifndef SFUD_CMD_READ_UNIQUE_ID 146 #define SFUD_CMD_READ_UNIQUE_ID 0x4B 147 #endif 148 149 #ifndef SFUD_CMD_READ_SFDP_REGISTER 150 #define SFUD_CMD_READ_SFDP_REGISTER 0x5A 151 #endif 152 153 #ifndef SFUD_CMD_ENABLE_RESET 154 #define SFUD_CMD_ENABLE_RESET 0x66 155 #endif 156 157 #ifndef SFUD_CMD_RESET 158 #define SFUD_CMD_RESET 0x99 159 #endif 160 161 #ifndef SFUD_CMD_ENTER_4B_ADDRESS_MODE 162 #define SFUD_CMD_ENTER_4B_ADDRESS_MODE 0xB7 163 #endif 164 165 #ifndef SFUD_CMD_EXIT_4B_ADDRESS_MODE 166 #define SFUD_CMD_EXIT_4B_ADDRESS_MODE 0xE9 167 #endif 168 169 #ifndef SFUD_WRITE_MAX_PAGE_SIZE 170 #define SFUD_WRITE_MAX_PAGE_SIZE 256 171 #endif 172 173 /* send dummy data for read data */ 174 #ifndef SFUD_DUMMY_DATA 175 #define SFUD_DUMMY_DATA 0xFF 176 #endif 177 178 /* maximum number of erase type support on JESD216 (V1.0) */ 179 #define SFUD_SFDP_ERASE_TYPE_MAX_NUM 4 180 181 /** 182 * status register bits 183 */ 184 enum { 185 SFUD_STATUS_REGISTER_BUSY = (1 << 0), /**< busing */ 186 SFUD_STATUS_REGISTER_WEL = (1 << 1), /**< write enable latch */ 187 SFUD_STATUS_REGISTER_SRP = (1 << 7), /**< status register protect */ 188 }; 189 190 /** 191 * error code 192 */ 193 typedef enum { 194 SFUD_SUCCESS = 0, /**< success */ 195 SFUD_ERR_NOT_FOUND = 1, /**< not found or not supported */ 196 SFUD_ERR_WRITE = 2, /**< write error */ 197 SFUD_ERR_READ = 3, /**< read error */ 198 SFUD_ERR_TIMEOUT = 4, /**< timeout error */ 199 SFUD_ERR_ADDR_OUT_OF_BOUND = 5, /**< address is out of flash bound */ 200 } sfud_err; 201 202 #ifdef SFUD_USING_QSPI 203 /** 204 * QSPI flash read cmd format 205 */ 206 typedef struct { 207 uint8_t instruction; 208 uint8_t instruction_lines; 209 uint8_t address_size; 210 uint8_t address_lines; 211 uint8_t alternate_bytes_lines; 212 uint8_t dummy_cycles; 213 uint8_t data_lines; 214 } sfud_qspi_read_cmd_format; 215 #endif /* SFUD_USING_QSPI */ 216 217 /* SPI bus write read data function type */ 218 typedef sfud_err (*spi_write_read_func)(const uint8_t *write_buf, size_t write_size, uint8_t *read_buf, size_t read_size); 219 220 #ifdef SFUD_USING_SFDP 221 /** 222 * the SFDP (Serial Flash Discoverable Parameters) parameter info which used on this library 223 */ 224 typedef struct { 225 bool available; /**< available when read SFDP OK */ 226 uint8_t major_rev; /**< SFDP Major Revision */ 227 uint8_t minor_rev; /**< SFDP Minor Revision */ 228 uint16_t write_gran; /**< write granularity (bytes) */ 229 uint8_t erase_4k; /**< 4 kilobyte erase is supported throughout the device */ 230 uint8_t erase_4k_cmd; /**< 4 Kilobyte erase command */ 231 bool sr_is_non_vola; /**< status register is supports non-volatile */ 232 uint8_t vola_sr_we_cmd; /**< volatile status register write enable command */ 233 bool addr_3_byte; /**< supports 3-Byte addressing */ 234 bool addr_4_byte; /**< supports 4-Byte addressing */ 235 uint32_t capacity; /**< flash capacity (bytes) */ 236 struct { 237 uint32_t size; /**< erase sector size (bytes). 0x00: not available */ 238 uint8_t cmd; /**< erase command */ 239 } eraser[SFUD_SFDP_ERASE_TYPE_MAX_NUM]; /**< supported eraser types table */ 240 //TODO lots of fast read-related stuff (like modes supported and number of wait states/dummy cycles needed in each) 241 } sfud_sfdp, *sfud_sfdp_t; 242 #endif 243 244 /** 245 * SPI device 246 */ 247 typedef struct __sfud_spi { 248 /* SPI device name */ 249 char *name; 250 /* SPI bus write read data function */ 251 sfud_err (*wr)(const struct __sfud_spi *spi, const uint8_t *write_buf, size_t write_size, uint8_t *read_buf, 252 size_t read_size); 253 #ifdef SFUD_USING_QSPI 254 /* QSPI fast read function */ 255 sfud_err (*qspi_read)(const struct __sfud_spi *spi, uint32_t addr, sfud_qspi_read_cmd_format *qspi_read_cmd_format, 256 uint8_t *read_buf, size_t read_size); 257 #endif 258 /* lock SPI bus */ 259 void (*lock)(const struct __sfud_spi *spi); 260 /* unlock SPI bus */ 261 void (*unlock)(const struct __sfud_spi *spi); 262 /* some user data */ 263 void *user_data; 264 } sfud_spi, *sfud_spi_t; 265 266 /** 267 * serial flash device 268 */ 269 typedef struct { 270 char *name; /**< serial flash name */ 271 size_t index; /**< index of flash device information table @see flash_table */ 272 sfud_flash_chip chip; /**< flash chip information */ 273 sfud_spi spi; /**< SPI device */ 274 bool init_ok; /**< initialize OK flag */ 275 bool addr_in_4_byte; /**< flash is in 4-Byte addressing */ 276 struct { 277 void (*delay)(void); /**< every retry's delay */ 278 size_t times; /**< default times for error retry */ 279 } retry; 280 void *user_data; /**< some user data */ 281 282 #ifdef SFUD_USING_QSPI 283 sfud_qspi_read_cmd_format read_cmd_format; /**< fast read cmd format */ 284 #endif 285 286 #ifdef SFUD_USING_SFDP 287 sfud_sfdp sfdp; /**< serial flash discoverable parameters by JEDEC standard */ 288 #endif 289 290 } sfud_flash, *sfud_flash_t; 291 292 #ifdef __cplusplus 293 } 294 #endif 295 296 #endif /* _SFUD_DEF_H_ */ 297