Contiki 2.6

flash.h

Go to the documentation of this file.
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