279 lines
12 KiB
C
279 lines
12 KiB
C
/** @file hal/micro/cortexm3/nvm.h
|
|
* @brief Cortex-M3 Non-Volatile Memory data storage system.
|
|
* See @ref nvm for documentation.
|
|
*
|
|
* The functions in this file return an ::StStatus value.
|
|
* See error-def.h for definitions of all ::StStatus return values.
|
|
*
|
|
* See hal/micro/cortexm3/nvm.h for source code.
|
|
*
|
|
* <!--(C) COPYRIGHT 2010 STMicroelectronics. All rights reserved. -->
|
|
*/
|
|
|
|
/** @addtogroup nvm
|
|
* @brief Cortex-M3 Non-Volatile Memory data storage system.
|
|
*
|
|
* This header defines the API for NVM data storage. This header also
|
|
* describes the algorithm behind the NVM data storage system with notes
|
|
* on algorithm behavior.
|
|
*
|
|
* See hal/micro/cortexm3/nvm.h for source code.
|
|
*
|
|
* @note The algorithm description uses "page" to indicate an area of memory
|
|
* that is a multiple of physical flash pages. There are two pages: LEFT
|
|
* and RIGHT. The term "flash page" is used to refer to a page of
|
|
* physical flash.
|
|
*
|
|
* NVM data storage works by alternating between two pages: LEFT and RIGHT.
|
|
* The basic algorithm is driven by a call to halCommonSaveToNvm(). It will:
|
|
* - erase the inactive page
|
|
* - write the new data to the inactive page
|
|
* - copy existing data from the active page to the inactive page
|
|
* - mark the inactive page as the new active page
|
|
* - mark the old active page as the new inactive page
|
|
* To accomplish alternating between two pages and knowing which page has the
|
|
* valid set of data, the algorithm uses 4 bytes of mgmt data that exists
|
|
* at the top of both LEFT and RIGHT (the term "mgmt" is shorthand referring to
|
|
* the management data). The management data is comprised of a Valid marker,
|
|
* an Active marker, a Dead marker, and a Spare byte. Viewing the
|
|
* management data as a single 32 bit quantity yields:
|
|
* - Valid is mgmt[0]
|
|
* - Active is mgmt[1]
|
|
* - Dead is mgmt[2]
|
|
* - Spare is mgmt[3]
|
|
* The algorithm is based on a simple, circular state machine. The following
|
|
* discussion details all of the possible mgmt bytes and the states they
|
|
* correspond to. The "Reads from" line indicates which page a call to
|
|
* halCommonReadFromNvm() will read from (an 'x' page will stuff the read
|
|
* data with 0xFF). The vertical "erase" and "write" words indicate the
|
|
* flash altering actions taken between those states. Invalid mgmt bytes
|
|
* is equivalent to erased mgmt bytes (state 0) and will trigger an
|
|
* erase of both LEFT and RIGHT. State 3 and state 7 are the only exit
|
|
* states. When the algorithm is run, regardless of starting state, it
|
|
* will advance to the next exit state. This means if the "Read from"
|
|
* is LEFT then the state machine will advance until state 7 and then exit.
|
|
* If "Read from" is RIGHT, then the state machine will advance until
|
|
* state 3 and then exit.
|
|
*
|
|
* @code
|
|
* Starting from erased or invalid mgmt, write to LEFT
|
|
* State # 0 0 1 2 3
|
|
* Reads from: x x e w L L L
|
|
* Valid xx|xx FF|FF r r 00|FF 00|FF 00|00
|
|
* Active xx|xx FF|FF a i 00|FF 00|FF 00|00
|
|
* Dead xx|xx FF|FF s t FF|FF FF|00 FF|00
|
|
* Spare xx|xx FF|FF e e FF|FF FF|FF FF|FF
|
|
*
|
|
*
|
|
* Starting from LEFT page, transition to RIGHT page:
|
|
* State # 3 4 5 6 7
|
|
* Reads from: L e L w R R R
|
|
* Valid 00|00 r 00|FF r 00|00 00|00 00|00
|
|
* Active 00|00 a 00|FF i 00|FF 00|FF 00|00
|
|
* Dead FF|00 s FF|FF t FF|FF 00|FF 00|FF
|
|
* Spare FF|FF e FF|FF e FF|FF FF|FF FF|FF
|
|
*
|
|
*
|
|
* Starting from RIGHT page, transition to LEFT page:
|
|
* State # 7 8 9 10 3
|
|
* Reads from: R e R w L L L
|
|
* Valid 00|00 r FF|00 r 00|00 00|00 00|00
|
|
* Active 00|00 a FF|00 i FF|00 FF|00 00|00
|
|
* Dead 00|FF s FF|FF t FF|FF FF|00 FF|00
|
|
* Spare FF|FF e FF|FF e FF|FF FF|FF FF|FF
|
|
* @endcode
|
|
*
|
|
* Based on the 10 possible states, there are 5 valid 32bit mgmt words:
|
|
* - 0xFFFFFFFF
|
|
* - 0xFFFFFF00
|
|
* - 0xFFFF0000
|
|
* - 0xFF000000
|
|
* - 0xFF00FFFF
|
|
* The algorithm determines the current state by using these 5 mgmt words
|
|
* with the 10 possible combinations of LEFT mgmt and RIGHT mgmt.
|
|
*
|
|
* Detailed State Description:
|
|
* - State 0:
|
|
* In this state the mgmt bytes do not conform to any of the other states
|
|
* and therefore the entire NVM system, both the LEFT and RIGHT, is
|
|
* invalid. Invalid could be as simple as both LEFT and RIGHT are erased
|
|
* or as complex as serious memory corruption or a bug caused bad data to
|
|
* be written to the NVM. By using a small set of very strict, precise,
|
|
* valid states (versus other management systems such as a simple counter),
|
|
* the algorithm/data gains some protection against not only corruption, but
|
|
* also executing the NVM algorithm on a chip that previously did not
|
|
* have the NVM system running on it.
|
|
* - State 1, 4, 8
|
|
* In these states, mgmt is saying that one page is valid and active, while
|
|
* the other page is erased. This tells the algorithm which page to read
|
|
* from and indicates that the other page has already been erased.
|
|
* - State 2
|
|
* This state is only necessary for transitioning from state 0. From state
|
|
* 0, the goal is to arrive at state 3. Ideally, the RIGHT mgmt would
|
|
* be written with 0xFF000000, but the flash library only permits 16 bit
|
|
* writes. If a reset were to occur in the middle of this section of the
|
|
* algorithm, we want to ensure that the mgmt is left in a known state,
|
|
* state 2, so that the algorithm could continue from where it got
|
|
* interrupted.
|
|
* - State 5, 9
|
|
* These states indicate that the other page has just become valid because
|
|
* the new data has just been written. Once at these states, reading
|
|
* from the NVM will now pull data from the other page.
|
|
* - State 6, 10
|
|
* These states indicate that the old page is now dead and not in use.
|
|
* While the algorithm already knows to read from the new page, the Dead
|
|
* mgmt byte is primarily used to indicate that the other page needs to
|
|
* be erased. Conceptually, the Dead byte can also be considered a type
|
|
* of "garbage collection" flag indicating the old page needs to be
|
|
* destroyed and has not yet been erased.
|
|
* - State 3, 7
|
|
* These states are the final exit points of the circular state machine.
|
|
* Once at these states, the current page is marked Valid and Active and
|
|
* the old page is marked as Dead. The algorithm knows which page to
|
|
* read from and which page needs to be erased on the next write to the NVM.
|
|
*
|
|
*
|
|
* Notes on algorithm behavior:
|
|
* - Refer to nvm-def.h for a list of offset/length that define the data
|
|
* stored in NVM storage space.
|
|
* - All writes to flash are 16bit granularity and therefore the internal
|
|
* flash writes cast the data to uint16_t. Length is also required to be
|
|
* a multiple of 16bits.
|
|
* - Flash page erase uses a granularity of a single flash page. The size
|
|
* of a flash page depends on the chip and is defined in memmap.h with
|
|
* the define MFB_PAGE_SIZE_B.
|
|
* - Erasing will only occur when halCommonSaveToNvm() is called.
|
|
* - Erasing will always occur when halCommonSaveToNvm() is called unless the
|
|
* page intended to be erased is already entirely 0xFFFF.
|
|
* - When reading and management is invalid, the read will return 0xFF for data.
|
|
* - Calling halCommonSaveToNvm() while in any state is always valid and the
|
|
* new data will be written to flash.
|
|
* - halCommonSaveToNvm() will always advance the state machine to 3 or 7.
|
|
* - When writing and management is invalid, both LEFT and RIGHT will be erased
|
|
* and the new data will be written to LEFT.
|
|
* - Writing causes the new data being passed into halCommonSaveToNvm() to be
|
|
* written to flash. The data already existing in the currently valid page
|
|
* will be copied over to the new page.
|
|
* - Reading or writing to an offset equal to or greater than NVM_DATA_SIZE_B is
|
|
* illegal and will cause an assert.
|
|
* - Offset and length must always be multiples of 16bits. If not, both a read
|
|
* and a write will trigger an assert.
|
|
* - Offset and length must be supplied in bytes.
|
|
* - All data in NVM storage must exist above the mgmt bytes, denoted by
|
|
* NVM_MGMT_SIZE_B.
|
|
* - The bottom 64 bytes of NVM storage are allocated to radio calibration
|
|
* values. These 64 bytes *must* exist for the radio to function.
|
|
* - There is no error checking beyond checking for 16bit alignment. This
|
|
* means it is possible to use data offset and size combinations that
|
|
* exceed NVM storage space or overlap with other data. Be careful!
|
|
*@{
|
|
*/
|
|
|
|
|
|
#ifndef NVM_H_
|
|
#define NVM_H_
|
|
|
|
//Pull in the MFB_ definitions.
|
|
#include "hal/micro/cortexm3/memmap.h"
|
|
//Pull in nvm-def.h so any code including nvm.h has access to the
|
|
//offsets and sizes defining the NVM data.
|
|
#include "hal/micro/cortexm3/nvm-def.h"
|
|
//Necessary to define StStatus and codes.
|
|
#include "error.h"
|
|
|
|
|
|
/**
|
|
* @brief Copy the NVM data from flash into the provided RAM location.
|
|
* It is illegal for the offset to be greater than NVM_DATA_SIZE_B.
|
|
*
|
|
* @param data A (RAM) pointer to where the data should be copied.
|
|
*
|
|
* @param offset The location from which the data should be copied. Must be
|
|
* 16bit aligned.
|
|
*
|
|
* @param length The length of the data in bytes. Must be 16bit aligned.
|
|
*
|
|
* @return An StStatus value indicating the success of the function.
|
|
* - ST_SUCCESS if the read completed cleanly.
|
|
* - ST_ERR_FATAL if the NVM storage management indicated an invalid
|
|
* state. The function will return entirely 0xFF in the data parameter.
|
|
*/
|
|
StStatus halCommonReadFromNvm(void *data, uint32_t offset, uint16_t length);
|
|
|
|
/**
|
|
* @brief Return the address of the token in NVM
|
|
*
|
|
* @param offset The location offset from which the address should be returned
|
|
*
|
|
*
|
|
* @return The address requested
|
|
*/
|
|
uint16_t *halCommonGetAddressFromNvm(uint32_t offset);
|
|
|
|
/**
|
|
* @brief Write the NVM data from the provided location RAM into flash.
|
|
* It is illegal for the offset to be greater than NVM_DATA_SIZE_B.
|
|
*
|
|
* @param data A (RAM) pointer from where the data should be taken.
|
|
*
|
|
* @param offset The location to which the data should be written. Must be
|
|
* 16bit aligned.
|
|
*
|
|
* @param length The length of the data in bytes. Must be 16bit aligned.
|
|
*
|
|
* @return An StStatus value indicating the success of the function.
|
|
* - ST_SUCCESS if the write completed cleanly.
|
|
* - Any other status value is an error code generated by the low level
|
|
* flash erase and write API. Refer to flash.h for details.
|
|
*/
|
|
StStatus halCommonWriteToNvm(const void *data, uint32_t offset, uint16_t length);
|
|
|
|
/**
|
|
* @brief Define the number of physical flash pages that comprise a NVM page.
|
|
* Since NVM_DATA_SIZE_B must be a multiple of MFB_PAGE_SIZE_B, increasing the
|
|
* size of NVM storage should be done by modifying this define.
|
|
*
|
|
* @note The total flash area consumed by NVM storage is double this value.
|
|
* This is due to the fact that there are two NVM pages, LEFT and RIGHT,
|
|
* which the algorithm alternates between.
|
|
*/
|
|
#define NVM_FLASH_PAGE_COUNT (1)
|
|
|
|
/**
|
|
* @brief Define the total size of a NVM page, in bytes. This must be a
|
|
* multiple of the memory map define MFB_PAGE_SIZE_B. Note that 4 bytes of
|
|
* the total size of an NVM page are dedicated to page management.
|
|
*
|
|
* @note <b>DO NOT EDIT THIS DEFINE. Instead, edit NVM_FLASH_PAGE_COUNT.</b>
|
|
*/
|
|
#define NVM_DATA_SIZE_B (MFB_PAGE_SIZE_B*NVM_FLASH_PAGE_COUNT)
|
|
#if ((NVM_DATA_SIZE_B%MFB_PAGE_SIZE_B) != 0)
|
|
#error Illegal NVM data storage size. NVM_DATA_SIZE_B must be a multiple of MFB_PAGE_SIZE_B.
|
|
#endif
|
|
|
|
/**
|
|
* @brief Define the absolute address of the LEFT page. LEFT page storage
|
|
* is defined by nvmStorageLeft[NVM_DATA_SIZE_B] and placed by the linker
|
|
* using the segment "NVM".
|
|
*/
|
|
#define NVM_LEFT_PAGE ((uint32_t)nvmStorageLeft)
|
|
|
|
/**
|
|
* @brief Define the absolute address of the RIGHT page. RIGHT page storage
|
|
* is defined by nvmStorageRight[NVM_DATA_SIZE_B] and placed by the linker
|
|
* using the segment "NVM".
|
|
*/
|
|
#define NVM_RIGHT_PAGE ((uint32_t)nvmStorageRight)
|
|
|
|
/**
|
|
* @brief Define the number of bytes that comprise the NVM management bytes.
|
|
* All data must begin at an offset above the management bytes.
|
|
*
|
|
* @note This value <b>must not change</b>.
|
|
*/
|
|
#define NVM_MGMT_SIZE_B (4)
|
|
|
|
/** @} END addtogroup */
|
|
|
|
#endif // NVM_H_
|
|
|