components/sfud/sfud.h

   1 /*
   2  * This file is part of the Serial Flash Universal Driver Library.
   3  *
   4  * Copyright (c) 2016-2018, Armink, <armink.ztl@gmail.com>
   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_ */