1 /* 2 * Copyright (C) 2015-2017 Alibaba Group Holding Limited. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef HAL_FLASH_H 17 #define HAL_FLASH_H 18 19 #include <stdint.h> 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 #define PAR_OPT_READ_POS (0) 26 #define PAR_OPT_WRITE_POS (1) 27 28 #define PAR_OPT_READ_MASK (0x1u << PAR_OPT_READ_POS) 29 #define PAR_OPT_WRITE_MASK (0x1u << PAR_OPT_WRITE_POS) 30 31 #define PAR_OPT_READ_DIS (0x0u << PAR_OPT_READ_POS) 32 #define PAR_OPT_READ_EN (0x1u << PAR_OPT_READ_POS) 33 #define PAR_OPT_WRITE_DIS (0x0u << PAR_OPT_WRITE_POS) 34 #define PAR_OPT_WRITE_EN (0x1u << PAR_OPT_WRITE_POS) 35 36 typedef enum { 37 HAL_PARTITION_ERROR = -1, 38 HAL_PARTITION_BOOTLOADER, 39 HAL_PARTITION_APPLICATION, 40 HAL_PARTITION_ATE, 41 HAL_PARTITION_OTA_TEMP, 42 HAL_PARTITION_RF_FIRMWARE, 43 HAL_PARTITION_PARAMETER_1, 44 HAL_PARTITION_PARAMETER_2, 45 HAL_PARTITION_PARAMETER_3, 46 HAL_PARTITION_PARAMETER_4, 47 HAL_PARTITION_BT_FIRMWARE, 48 HAL_PARTITION_SPIFFS, 49 HAL_PARTITION_CUSTOM_1, 50 HAL_PARTITION_CUSTOM_2, 51 HAL_PARTITION_RECOVERY, 52 HAL_PARTITION_OTA_MCU, 53 HAL_PARTITION_OTA_PARA, 54 HAL_PARTITION_OTA_HEAD_PARA, 55 HAL_PARTITION_RECOVERY_BACK_PARA, 56 HAL_PARTITION_MBINS_APP, 57 HAL_PARTITION_MBINS_KERNEL, 58 HAL_PARTITION_MAX, 59 HAL_PARTITION_NONE, 60 } hal_partition_t; 61 62 typedef enum { 63 HAL_FLASH_EMBEDDED, 64 HAL_FLASH_SPI, 65 HAL_FLASH_QSPI, 66 HAL_FLASH_MAX, 67 HAL_FLASH_NONE, 68 } hal_flash_t; 69 70 typedef struct { 71 hal_flash_t partition_owner; 72 const char *partition_description; 73 uint32_t partition_start_addr; 74 uint32_t partition_length; 75 uint32_t partition_options; 76 } hal_logic_partition_t; 77 78 /** 79 * Get the infomation of the specified flash area 80 * 81 * @param[in] in_partition The target flash logical partition 82 * 83 * @return HAL_logi_partition struct 84 */ 85 hal_logic_partition_t *hal_flash_get_info(hal_partition_t in_partition); 86 87 /** 88 * Erase an area on a Flash logical partition 89 * 90 * @note Erase on an address will erase all data on a sector that the 91 * address is belonged to, this function does not save data that 92 * beyond the address area but in the affected sector, the data 93 * will be lost. 94 * 95 * @param[in] in_partition The target flash logical partition which should be erased 96 * @param[in] off_set Start address of the erased flash area 97 * @param[in] size Size of the erased flash area 98 * 99 * @return 0 : On success, EIO : If an error occurred with any step 100 */ 101 int32_t hal_flash_erase(hal_partition_t in_partition, uint32_t off_set, uint32_t size); 102 103 /** 104 * Write data to an area on a flash logical partition without erase 105 * 106 * @param[in] in_partition The target flash logical partition which should be read which should be written 107 * @param[in] off_set Point to the start address that the data is written to, and 108 * point to the last unwritten address after this function is 109 * returned, so you can call this function serval times without 110 * update this start address. 111 * @param[in] inBuffer point to the data buffer that will be written to flash 112 * @param[in] inBufferLength The length of the buffer 113 * 114 * @return 0 : On success, EIO : If an error occurred with any step 115 */ 116 int32_t hal_flash_write(hal_partition_t in_partition, uint32_t *off_set, 117 const void *in_buf, uint32_t in_buf_len); 118 119 int32_t hal_flash_write_saved(hal_partition_t in_partition, uint32_t *off_set, 120 const void *in_buf, uint32_t in_buf_len); 121 /** 122 * Write data to an area on a flash logical partition with erase first 123 * 124 * @param[in] in_partition The target flash logical partition which should be read which should be written 125 * @param[in] off_set Point to the start address that the data is written to, and 126 * point to the last unwritten address after this function is 127 * returned, so you can call this function serval times without 128 * update this start address. 129 * @param[in] inBuffer point to the data buffer that will be written to flash 130 * @param[in] inBufferLength The length of the buffer 131 * 132 * @return 0 : On success, EIO : If an error occurred with any step 133 */ 134 int32_t hal_flash_erase_write(hal_partition_t in_partition, uint32_t *off_set, 135 const void *in_buf, uint32_t in_buf_len); 136 137 /** 138 * Read data from an area on a Flash to data buffer in RAM 139 * 140 * @param[in] in_partition The target flash logical partition which should be read 141 * @param[in] off_set Point to the start address that the data is read, and 142 * point to the last unread address after this function is 143 * returned, so you can call this function serval times without 144 * update this start address. 145 * @param[in] outBuffer Point to the data buffer that stores the data read from flash 146 * @param[in] inBufferLength The length of the buffer 147 * 148 * @return 0 : On success, EIO : If an error occurred with any step 149 */ 150 int32_t hal_flash_read(hal_partition_t in_partition, uint32_t *off_set, 151 void *out_buf, uint32_t in_buf_len); 152 153 /** 154 * Set security options on a logical partition 155 * 156 * @param[in] partition The target flash logical partition 157 * @param[in] offset Point to the start address that the data is read, and 158 * point to the last unread address after this function is 159 * returned, so you can call this function serval times without 160 * update this start address. 161 * @param[in] size Size of enabled flash area 162 * 163 * @return 0 : On success, EIO : If an error occurred with any step 164 */ 165 int32_t hal_flash_enable_secure(hal_partition_t partition, uint32_t off_set, uint32_t size); 166 167 /** 168 * Disable security options on a logical partition 169 * 170 * @param[in] partition The target flash logical partition 171 * @param[in] offset Point to the start address that the data is read, and 172 * point to the last unread address after this function is 173 * returned, so you can call this function serval times without 174 * update this start address. 175 * @param[in] size Size of disabled flash area 176 * 177 * @return 0 : On success, EIO : If an error occurred with any step 178 */ 179 int32_t hal_flash_dis_secure(hal_partition_t partition, uint32_t off_set, uint32_t size); 180 181 /** 182 * Convert physical address to logic partition id and offset in partition 183 * 184 * @param[out] in_partition Point to the logic partition id 185 * @param[out] off_set Point to the offset in logic partition 186 * @param[in] addr The physical address 187 * 188 * @return 0 : On success, EIO : If an error occurred with any step 189 */ 190 int32_t hal_flash_addr2offset(hal_partition_t *in_partition, uint32_t *off_set, uint32_t addr); 191 192 #ifdef __cplusplus 193 } 194 #endif /* __cplusplus */ 195 196 #endif /* HAL_FLASH_H */ 197