Contiki 2.6
|
00001 /** @file hal/micro/cortexm3/flash.h 00002 * @brief Header for flash for APIs 00003 * 00004 * <!--(C) COPYRIGHT 2010 STMicroelectronics. All rights reserved. --> 00005 */ 00006 00007 /** @addtogroup flash 00008 * @brief Definition and description of public flash manipulation routines. 00009 * 00010 * @note 00011 * During an erase or a write the flash is not available, 00012 * which means code will not be executable from flash. These routines still 00013 * execute from flash, though, since the bus architecture can support doing so. 00014 * <b>Additonally, this also means all interrupts will be disabled.</b> 00015 * 00016 * <b>Hardware documentation indicates 40us for a write and 21ms for an erase.</b> 00017 * 00018 * See flash.h for source code. 00019 *@{ 00020 */ 00021 00022 #ifndef __FLASH_H__ 00023 #define __FLASH_H__ 00024 00025 #include "memmap.h" 00026 00027 00028 /** @brief Tells the calling code if a Flash Erase operation is active. 00029 * 00030 * This state is import to know because Flash Erasing is ATOMIC for 21ms 00031 * and could disrupt interrupt latency. But if an ISR can know that it wasn't 00032 * serviced immediately due to Flash Erasing, then the ISR has the opportunity 00033 * to correct in whatever manner it needs to. 00034 * 00035 * @return A boolean flag: TRUE if Flash Erase is active, FALSE otherwise. 00036 */ 00037 boolean halFlashEraseIsActive(void); 00038 00039 #ifndef DOXYGEN_SHOULD_SKIP_THIS 00040 00041 //[[ The following eraseType definitions must match the FIB erase types! ]] 00042 /** 00043 * @brief Assign numerical value to the type of erasure requested. 00044 */ 00045 #define MFB_MASS_ERASE 0x01 00046 #define MFB_PAGE_ERASE 0x02 00047 #define CIB_ERASE 0x03 00048 00049 /** @brief Erases a section of flash back to all 0xFFFF. 00050 * 00051 * @param eraseType Choose one of the three types of erasures to perform. 00052 * - MFB_MASS_ERASE (0x01) Erase the entire main flash block. 00053 * - MFB_PAGE_ERASE (0x02) Erase one hardware page in the main flash block 00054 * chosen by the \c address parameter. 00055 * - CIB_ERASE (0x03) Erase the entire customer information block. 00056 * 00057 * @param address This parameter is only effectual when a MFB_PAGE_ERASE is 00058 * being performed. The hardware page encapsulating the address given in this 00059 * parameter will be erased. A hardware page size depends on the chip 00060 * 00061 * @return An ::StStatus value indicating the success or failure of the 00062 * command: 00063 * - ST_ERR_FATAL if the \c eraseType is not valid 00064 * - ST_ERR_FLASH_ERASE_FAIL if erasing failed due to write protection 00065 * - ST_ERR_FLASH_VERIFY_FAILED if erase verification failed 00066 * - ST_SUCCESS if erasure completed and verified properly 00067 */ 00068 StStatus halInternalFlashErase(int8u eraseType, int32u address); 00069 00070 /** @brief Writes a block of words to flash. A page is erased 00071 * to 0xFFFF at every address. Only two writes can be performed to the same 00072 * address between erasures and this is enforced by the flash interface 00073 * controller. If the value already in the address being written to is 0xFFFF, 00074 * any value can be written. If the value is not 0xFFFF and not 0x0000, only 00075 * 0x0000 can be written. If the value is 0x0000, nothing can be written. 00076 * 00077 * \b NOTE: This function can NOT write the option bytes and will throw an 00078 * error if that is attempted. 00079 * 00080 * @param address The starting address of where the programming will occur. 00081 * This parameter MUST be half-word aligned since all programming operations 00082 * are half-words. Also, the address parameter is NOT a pointer. This 00083 * routines will cast the address to a pointer for the actual hardware access. 00084 * 00085 * @param data A pointer to a buffer containing the 16bit (half-words) to 00086 * be written. 00087 * 00088 * @param length The number of 16bit (half-words) contained in the data buffer 00089 * to be written to flash. 00090 * 00091 * @return An ::StStatus value indicating the success or failure of the 00092 * command: 00093 * - ST_ERR_FLASH_PROG_FAIL if the address is not half-word aligned, the 00094 * address is inside the option bytes, write protection is enabled, or the 00095 * address is being written to more than twice between erasures. 00096 * - ST_ERR_FLASH_VERIFY_FAILED if write verification failed 00097 * - ST_SUCCESS if writing completed and verified properly 00098 */ 00099 StStatus halInternalFlashWrite(int32u address, int16u * data, int32u length); 00100 00101 /** @brief Writes an option byte to the customer information block. Only 00102 * two writes can be performed to the same address between erasures and this 00103 * is enforced by the flash interface controller. 00104 * 00105 * @param byte The option byte number, 0 though 7, to be programmed. 00106 * 00107 * @param data The 8 bit value to be programmed into the option byte. The 00108 * hardware is responsible for calculating the compliment and programming 00109 * the full 16bit option byte space. 00110 * 00111 * @return An ::StStatus value indicating the success or failure of the 00112 * command: 00113 * - ST_ERR_FLASH_PROG_FAIL if the byte chosen is greater than 7, write 00114 * protection is enabled, or the byte is being written to more than twice 00115 * between erasures. 00116 * - ST_ERR_FLASH_VERIFY_FAILED if write verification failed 00117 * - ST_SUCCESS if writing completed and verified properly 00118 */ 00119 StStatus halInternalCibOptionByteWrite(int8u byte, int8u data); 00120 00121 #endif //DOXYGEN_SHOULD_SKIP_THIS 00122 00123 #endif //__FLASH_H__ 00124 00125 /** @} END addtogroup */ 00126