1 /** mbed Microcontroller Library 2 ****************************************************************************** 3 * @file flash_api.h 4 * @author 5 * @version V1.0.0 6 * @brief This file provides mbed FLASH API 7 ****************************************************************************** 8 * @attention 9 * 10 * Copyright (c) 2015, Realtek Semiconductor Corp. 11 * All rights reserved. 12 * 13 * This module is a confidential and proprietary property of RealTek and 14 * possession or use of this module requires written permission of RealTek. 15 ****************************************************************************** 16 */ 17 18 #ifndef MBED_EXT_FLASH_API_EXT_H 19 #define MBED_EXT_FLASH_API_EXT_H 20 21 #include "device.h" 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /** @addtogroup flash FLASH 28 * @ingroup hal 29 * @brief flash functions 30 * @{ 31 */ 32 33 ///@name Ameba Common 34 ///@{ 35 36 typedef struct flash_s flash_t; 37 38 /** 39 * @brief Erase flash sector 40 * @param obj: Flash object define in application software. 41 * @param address: Specifies the starting address to be erased. 42 * @retval none 43 */ 44 void flash_erase_sector(flash_t *obj, uint32_t address); 45 46 /** 47 * @brief Erase flash block(64KB) 48 * @param obj: Flash object define in application software. 49 * @param address: Specifies the starting address to be erased.LSB 16bits will be masked. 50 * @retval none 51 */ 52 void flash_erase_block(flash_t * obj, uint32_t address); 53 54 /** 55 * @brief Read a word from specified address 56 * @param obj: Flash object define in application software. 57 * @param address: Specifies the address to read from. 58 * @param data: Specified the address to save the readback data. 59 * @retval 1: Success 60 * @note auto mode read is ok, because we have flash cache 61 */ 62 int flash_read_word(flash_t *obj, uint32_t address, uint32_t * data); 63 64 /** 65 * @brief Write a word to specified address 66 * @param obj: Flash object define in application software. 67 * @param address: Specifies the address to be programmed to. 68 * @param data: Specified the data to be programmed. 69 * @retval 1: Success 70 * @note user mode write used 71 */ 72 int flash_write_word(flash_t *obj, uint32_t address, uint32_t data); 73 74 /** 75 * @brief Read a stream of data from specified address 76 * @param obj: Flash object define in application software. 77 * @param address: Specifies the starting address to read from. 78 * @param len: Specifies the length of the data to read. 79 * @param data: Specified the address to save the readback data. 80 * @retval 1: Success 81 * @note auto mode is ok, because we have flash cache 82 */ 83 int flash_stream_read(flash_t *obj, uint32_t address, uint32_t len, uint8_t * data); 84 85 /** 86 * @brief Write a stream of data to specified address 87 * @param obj: Flash object define in application software. 88 * @param address: Specifies the starting address to write to. 89 * @param len: Specifies the length of the data to write. 90 * @param data: Pointer to a byte array that is to be written. 91 * @retval 1: Success 92 */ 93 int flash_stream_write(flash_t *obj, uint32_t address, uint32_t len, uint8_t * data); 94 95 /** 96 * @brief Control the flash chip write protect enable/disable. 97 * @param obj: Flash object define in application software. 98 * @param protect: This parameter can be 1 or 0. 99 * @arg 1: Protect the whole chip from being programmed/erased. 100 * @arg 0: Unprotect the whole chip from being programmed/erased. 101 * @retval none 102 */ 103 void flash_write_protect(flash_t *obj, uint32_t protect); 104 105 /** 106 * @brief Get the value of status register1 107 * @param obj: Flash object define in application software. 108 * @retval : The value of status register1. 109 */ 110 int flash_get_status(flash_t * obj); 111 112 /** 113 * @brief Set Status register to enable desired operation 114 * @param obj: Specifies the parameter of flash object. 115 * @param data: Specifies which bit users like to set. 116 * ex: if users want to set the third bit, data = 0x8. 117 * @retval 1: Success 118 * @note Please refer to the datatsheet of flash for more details of the content of status register. 119 * The block protected area and the corresponding control bits are provided in the flash datasheet. 120 */ 121 int flash_set_status(flash_t * obj, uint32_t data); 122 123 /** 124 * @brief This function aims to reset the status register, please make sure the operation is appropriate. 125 * @param obj: Specifies the parameter of flash object. 126 * @retval none 127 */ 128 void flash_reset_status(flash_t * obj); 129 130 /** 131 * @brief It is the same with flash_stream_write function which is used to write a stream of data to specified address. 132 * @param obj: Flash object define in application software. 133 * @param address: Specifies the starting address to write to. 134 * @param len: Specifies the length of the data to write. 135 * @param data: Pointer to a byte array that is to be written. 136 * @retval 1: Success 137 */ 138 int flash_burst_write(flash_t * obj, uint32_t address, uint32_t Length, uint8_t * data); 139 140 /** 141 * @brief It is the same with flash_stream_read function which is used to read a stream of data from specified address 142 * @param obj: Flash object define in application software. 143 * @param address: Specifies the starting address to read from. 144 * @param len: Specifies the length of the data to read. 145 * @param data: Specified the address to save the readback data. 146 * @retval 1: Success 147 */ 148 int flash_burst_read(flash_t * obj, uint32_t address, uint32_t Length, uint8_t * data); 149 150 /** 151 * @brief This function is only for Micron 128MB flash to access beyond 16MB by switching between eight 16MB-area(segment). 152 * Please refer to flash datasheet for more information about memory mapping. 153 * @param obj: Flash object define in application software. 154 * @param data: Specified which segment to choose. 155 * @retval 1: Success 156 */ 157 int flash_set_extend_addr(flash_t * obj, uint32_t data); 158 159 /** 160 * @brief This function is only for Micron 128MB flash to read from Extended Address Register, which shows the current segment. 161 * Please refer to flash datasheet for more information about memory mapping. 162 * @param obj: Flash object define in application software. 163 * @retval : The value of current Extended Address Register. 164 */ 165 int flash_get_extend_addr(flash_t * obj); 166 167 /** 168 * @brief Get flash ID (command: 0x9F). 169 * @param obj: Flash object define in application software. 170 * @param buf: Pointer to a byte array to save the readback ID. 171 * @param len: Specifies the length of the buf. It should be 3. 172 * @retval -1: Fail. 173 */ 174 int flash_read_id(flash_t *obj, uint8_t *buf, uint8_t len); 175 176 /** 177 * @brief This function is only for Winbond flash to get unique ID (command: 0x4B). 178 * @param obj: Flash object define in application software. 179 * @param buf: Pointer to a byte array to save the readback unique ID. 180 * @param len: Specifies the length of the buf. It should be 8. 181 * @retval -1: Fail. 182 */ 183 int flash_read_unique_id(flash_t *obj, uint8_t *buf, uint8_t len); 184 185 /** 186 * @brief This function is only for Winbond flash to set lock mode. 187 * @param mode: This parameter can be 1 or 0. 188 * @arg 1: Enable individual sector / block protect feature. 189 * @arg 0: Set status register 1 to enble write protect feature. 190 * @retval none 191 * @note But not all Winbond flash supports the function, plase refer to data sheets of the target flashes. 192 */ 193 void flash_set_lock_mode(uint32_t mode); 194 195 /** 196 * @brief This function is only for Winbond flash to lock whole flash chip. 197 * @param none 198 * @retval none 199 * @note But not all Winbond flash supports the function, plase refer to data sheets of the target flashes. 200 */ 201 void flash_global_lock(void); 202 203 /** 204 * @brief This function is only for Winbond flash to unlock whole flash chip. 205 * @param none 206 * @retval none 207 * @note But not all Winbond flash supports the function, plase refer to data sheets of the target flashes. 208 */ 209 void flash_global_unlock(void); 210 211 /** 212 * @brief This function is only for Winbond flash to lock individual sector or block region, should refer to the datasheet for more details. 213 * @param address 214 * @retval none 215 * @note But not all Winbond flash supports the function, plase refer to data sheets of the target flashes. 216 */ 217 void flash_individual_lock(uint32_t address); 218 219 /** 220 * @brief This function is only for Winbond flash to unlock individual sector or block region, should refer to the datasheet for more details. 221 * @param address 222 * @retval none 223 * @note But not all Winbond flash supports the function, plase refer to data sheets of the target flashes. 224 */ 225 void flash_individual_unlock(uint32_t address); 226 227 /** 228 * @brief This function is only for Winbond flash to get the individual lock state on certain address. 229 * @param address 230 * @retval 1: the target sector/block is locked. 231 * 0: the target sector/block is not locked. 232 * @note But not all Winbond flash supports the function, plase refer to data sheets of the target flashes. 233 */ 234 int flash_read_individual_lock_state(uint32_t address); 235 236 ///@} 237 238 #if ((defined(CONFIG_PLATFORM_8711B) && (CONFIG_PLATFORM_8711B == 1)) || (defined (CONFIG_PLATFORM_8721D) && (CONFIG_PLATFORM_8721D == 1))) 239 ///@name AmebaZ and AmebaD 240 ///@{ 241 /** 242 * @brief Erase the whole flash chip 243 * @param obj: Flash object define in application software. 244 * @retval none 245 */ 246 void flash_erase_chip(flash_t *obj); 247 ///@} 248 #endif //CONFIG_PLATFORM_8711B and CONFIG_PLATFORM_8721D 249 250 /*\@}*/ 251 252 #ifdef __cplusplus 253 } 254 #endif 255 256 #endif 257