1 /* 2 * Copyright (C) 2015-2017 Alibaba Group Holding Limited 3 */ 4 5 #ifndef HAL_FLASH_H 6 #define HAL_FLASH_H 7 8 #ifdef __cplusplus 9 extern "C" { 10 #endif 11 12 #include <stdint.h> 13 14 #define PAR_OPT_READ_POS ( 0 ) 15 #define PAR_OPT_WRITE_POS ( 1 ) 16 17 #define PAR_OPT_READ_MASK ( 0x1u << PAR_OPT_READ_POS ) 18 #define PAR_OPT_WRITE_MASK ( 0x1u << PAR_OPT_WRITE_POS ) 19 20 #define PAR_OPT_READ_DIS ( 0x0u << PAR_OPT_READ_POS ) 21 #define PAR_OPT_READ_EN ( 0x1u << PAR_OPT_READ_POS ) 22 #define PAR_OPT_WRITE_DIS ( 0x0u << PAR_OPT_WRITE_POS ) 23 #define PAR_OPT_WRITE_EN ( 0x1u << PAR_OPT_WRITE_POS ) 24 25 typedef enum { 26 HAL_PARTITION_ERROR = -1, 27 HAL_PARTITION_BOOTLOADER, 28 HAL_PARTITION_APPLICATION, 29 HAL_PARTITION_ATE, 30 HAL_PARTITION_OTA_TEMP, 31 HAL_PARTITION_RF_FIRMWARE, 32 HAL_PARTITION_PARAMETER_1, 33 HAL_PARTITION_PARAMETER_2, 34 HAL_PARTITION_PARAMETER_3, 35 HAL_PARTITION_PARAMETER_4, 36 HAL_PARTITION_BT_FIRMWARE, 37 HAL_PARTITION_SPIFFS, 38 HAL_PARTITION_LITTLEFS, 39 HAL_PARTITION_LITTLEFS2, 40 HAL_PARTITION_LITTLEFS3, 41 HAL_PARTITION_CUSTOM_1, 42 HAL_PARTITION_CUSTOM_2, 43 HAL_PARTITION_2ND_BOOT, 44 HAL_PARTITION_MBINS_APP, 45 HAL_PARTITION_MBINS_KERNEL, 46 HAL_PARTITION_GPT, 47 HAL_PARTITION_ENV, 48 HAL_PARTITION_ENV_REDUND, 49 HAL_PARTITION_RTOSA, 50 HAL_PARTITION_RTOSB, 51 HAL_PARTITION_BOOT1, 52 HAL_PARTITION_BOOT1_REDUND, 53 HAL_PARTITION_FTL, 54 HAL_PARTITION_MAX, 55 HAL_PARTITION_NONE, 56 } hal_partition_t; 57 58 typedef enum { 59 HAL_FLASH_EMBEDDED, 60 HAL_FLASH_SPI, 61 HAL_FLASH_QSPI, 62 HAL_FLASH_MAX, 63 HAL_FLASH_NONE, 64 } hal_flash_t; 65 66 typedef enum { 67 HAL_FLASH_ERR_OK, /* operation success */ 68 HAL_FLASH_ERR_NAND_BAD, /* Bad block */ 69 HAL_FLASH_ERR_NAND_READ, /* Read fail, can't correct */ 70 HAL_FLASH_ERR_NAND_WRITE, /* Write fail */ 71 HAL_FLASH_ERR_NAND_ERASE, /* Erase fail */ 72 HAL_FLASH_ERR_NAND_FLIPS, /* Too many bitflips, uncorrected */ 73 /* add more hereafter */ 74 } hal_flash_err_t; 75 76 typedef struct { 77 hal_flash_t partition_owner; 78 const char *partition_description; 79 uint32_t partition_start_addr; 80 uint32_t partition_length; 81 uint32_t partition_options; 82 } hal_logic_partition_t; 83 84 typedef struct { 85 hal_partition_t p; // partition index 86 char *descr; // partition description 87 uint32_t offset; // start address, in byte unit 88 uint32_t siz; // parition size, in byte uint 89 uint32_t ssiz; // sector size, in byte unit. Set it to page size for NAND 90 uint32_t bsiz; // block size, in byte unit. 91 } hal_mtdpart_info_t; 92 93 /** 94 * init flash partition 95 * 96 * @param[in] in_partition The target flash logical partition 97 * 98 * @return 0: On success， otherwise is error 99 */ 100 int32_t hal_flash_init(hal_partition_t in_partition); 101 102 /** 103 * Get the information of the specified flash area 104 * 105 * @param[in] in_partition The target flash logical partition 106 * @param[in] partition The buffer to store partition info 107 * 108 * @return 0: On success， otherwise is error 109 */ 110 int32_t hal_flash_info_get(hal_partition_t in_partition, hal_logic_partition_t *partition); 111 112 /** 113 * Get the information of all the flash partitions 114 * 115 * @param[in/out] result_errar The pointer to the array of MTD partition info 116 * @param[in/out] cnt The count of the items in the result array 117 * 118 * @return 0 on success, otherwise failure. 119 * 120 * @note Caller is responsible to free the result array memory. 121 */ 122 int32_t hal_flash_mtdpart_info_get(hal_mtdpart_info_t **result_array, int *cnt); 123 124 /** 125 * Erase an area on a Flash logical partition 126 * 127 * @note Erase on an address will erase all data on a sector that the 128 * address is belonged to, this function does not save data that 129 * beyond the address area but in the affected sector, the data 130 * will be lost. 131 * 132 * @param[in] in_partition The target flash logical partition which should be erased 133 * @param[in] off_set Start address of the erased flash area 134 * @param[in] size Size of the erased flash area 135 * 136 * @return 0 : On success, EIO : If an error occurred with any step 137 */ 138 int32_t hal_flash_erase(hal_partition_t in_partition, uint32_t off_set, uint32_t size); 139 140 /** 141 * Write data to an area on a flash logical partition without erase 142 * 143 * @param[in] in_partition The target flash logical partition which should be read which should be written 144 * @param[in] off_set Point to the start address that the data is written to, and 145 * point to the last unwritten address after this function is 146 * returned, so you can call this function serval times without 147 * update this start address. 148 * @param[in] inBuffer point to the data buffer that will be written to flash 149 * @param[in] inBufferLength The length of the buffer 150 * 151 * @return 0 : On success, EIO : If an error occurred with any step 152 */ 153 int32_t hal_flash_write(hal_partition_t in_partition, uint32_t *off_set, 154 const void *in_buf, uint32_t in_buf_len); 155 156 /** 157 * Write data to an area on a flash logical partition with erase first 158 * 159 * @param[in] in_partition The target flash logical partition which should be read which should be written 160 * @param[in] off_set Point to the start address that the data is written to, and 161 * point to the last unwritten address after this function is 162 * returned, so you can call this function serval times without 163 * update this start address. 164 * @param[in] inBuffer point to the data buffer that will be written to flash 165 * @param[in] inBufferLength The length of the buffer 166 * 167 * @return 0 : On success, EIO : If an error occurred with any step 168 */ 169 int32_t hal_flash_erase_write(hal_partition_t in_partition, uint32_t *off_set, 170 const void *in_buf, uint32_t in_buf_len); 171 172 /** 173 * Read data from an area on a Flash to data buffer in RAM 174 * 175 * @param[in] in_partition The target flash logical partition which should be read 176 * @param[in] off_set Point to the start address that the data is read, and 177 * point to the last unread address after this function is 178 * returned, so you can call this function serval times without 179 * update this start address. 180 * @param[in] outBuffer Point to the data buffer that stores the data read from flash 181 * @param[in] inBufferLength The length of the buffer 182 * 183 * @return 0 : On success, EIO : If an error occurred with any step 184 */ 185 int32_t hal_flash_read(hal_partition_t in_partition, uint32_t *off_set, 186 void *out_buf, uint32_t in_buf_len); 187 188 /** 189 * Set security options on a logical partition 190 * 191 * @param[in] partition The target flash logical partition 192 * @param[in] offset Point to the start address that the data is read, and 193 * point to the last unread address after this function is 194 * returned, so you can call this function serval times without 195 * update this start address. 196 * @param[in] size Size of enabled flash area 197 * 198 * @return 0 : On success, EIO : If an error occurred with any step 199 */ 200 int32_t hal_flash_enable_secure(hal_partition_t partition, uint32_t off_set, uint32_t size); 201 202 /** 203 * Disable security options on a logical partition 204 * 205 * @param[in] partition The target flash logical partition 206 * @param[in] offset Point to the start address that the data is read, and 207 * point to the last unread address after this function is 208 * returned, so you can call this function serval times without 209 * update this start address. 210 * @param[in] size Size of disabled flash area 211 * 212 * @return 0 : On success, EIO : If an error occurred with any step 213 */ 214 int32_t hal_flash_dis_secure(hal_partition_t partition, uint32_t off_set, uint32_t size); 215 216 /** 217 * Convert physical address to logic partition id and offset in partition 218 * 219 * @param[out] in_partition Point to the logic partition id 220 * @param[out] off_set Point to the offset in logic partition 221 * @param[in] addr The physical address 222 * 223 * @return 0 : On success, EIO : If an error occurred with any step 224 */ 225 int32_t hal_flash_addr2offset(hal_partition_t *in_partition, uint32_t *off_set, uint32_t addr); 226 227 #ifdef __cplusplus 228 } 229 #endif 230 231 #endif /* HAL_FLASH_H */ 232 233