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 an head file for this library. You can see all of the functions which can be called by user. 26 * Created on: 2016-04-23 27 */ 28 29 #ifndef _SFUD_H_ 30 #define _SFUD_H_ 31 32 #include "sfud_def.h" 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /* ../src/sfup.c */ 39 /** 40 * SFUD library initialize. 41 * 42 * @return result 43 */ 44 sfud_err sfud_init(void); 45 46 /** 47 * SFUD initialize by flash device 48 * 49 * @param flash flash device 50 * 51 * @return result 52 */ 53 sfud_err sfud_device_init(sfud_flash *flash); 54 55 /** 56 * get flash device by its index which in the flash information table 57 * 58 * @param index the index which in the flash information table @see flash_table 59 * 60 * @return flash device 61 */ 62 sfud_flash *sfud_get_device(size_t index); 63 64 /** 65 * get flash device total number on flash device information table @see flash_table 66 * 67 * @return flash device total number 68 */ 69 size_t sfud_get_device_num(void); 70 71 /** 72 * get flash device information table @see flash_table 73 * 74 * @return flash device table pointer 75 */ 76 const sfud_flash *sfud_get_device_table(void); 77 78 #ifdef SFUD_USING_QSPI 79 /** 80 * Enbale the fast read mode in QSPI flash mode. Default read mode is normal SPI mode. 81 * 82 * it will find the appropriate fast-read instruction to replace the read instruction(0x03) 83 * fast-read instruction @see SFUD_FLASH_EXT_INFO_TABLE 84 * 85 * @note When Flash is in QSPI mode, the method must be called after sfud_device_init(). 86 * 87 * @param flash flash device 88 * @param data_line_width the data lines max width which QSPI bus supported, such as 1, 2, 4 89 * 90 * @return result 91 */ 92 sfud_err sfud_qspi_fast_read_enable(sfud_flash *flash, uint8_t data_line_width); 93 #endif /* SFUD_USING_QSPI */ 94 95 /** 96 * read flash data 97 * 98 * @param flash flash device 99 * @param addr start address 100 * @param size read size 101 * @param data read data pointer 102 * 103 * @return result 104 */ 105 sfud_err sfud_read(const sfud_flash *flash, uint32_t addr, size_t size, uint8_t *data); 106 107 /** 108 * erase flash data 109 * 110 * @note It will erase align by erase granularity. 111 * 112 * @param flash flash device 113 * @param addr start address 114 * @param size erase size 115 * 116 * @return result 117 */ 118 sfud_err sfud_erase(const sfud_flash *flash, uint32_t addr, size_t size); 119 120 /** 121 * write flash data (no erase operate) 122 * 123 * @param flash flash device 124 * @param addr start address 125 * @param data write data 126 * @param size write size 127 * 128 * @return result 129 */ 130 sfud_err sfud_write(const sfud_flash *flash, uint32_t addr, size_t size, const uint8_t *data); 131 132 /** 133 * erase and write flash data 134 * 135 * @param flash flash device 136 * @param addr start address 137 * @param size write size 138 * @param data write data 139 * 140 * @return result 141 */ 142 sfud_err sfud_erase_write(const sfud_flash *flash, uint32_t addr, size_t size, const uint8_t *data); 143 144 /** 145 * erase all flash data 146 * 147 * @param flash flash device 148 * 149 * @return result 150 */ 151 sfud_err sfud_chip_erase(const sfud_flash *flash); 152 153 /** 154 * read flash register status 155 * 156 * @param flash flash device 157 * @param status register status 158 * 159 * @return result 160 */ 161 sfud_err sfud_read_status(const sfud_flash *flash, uint8_t *status); 162 163 /** 164 * write status register 165 * 166 * @param flash flash device 167 * @param is_volatile true: volatile mode, false: non-volatile mode 168 * @param status register status 169 * 170 * @return result 171 */ 172 sfud_err sfud_write_status(const sfud_flash *flash, bool is_volatile, uint8_t status); 173 174 #ifdef __cplusplus 175 } 176 #endif 177 178 #endif /* _SFUD_H_ */ 179