Contiki 2.6

Nvm

Data definitions for the Cortex-M3 Non-Volatile Memory data storage system. More...

Defines

#define NVM_FLASH_PAGE_COUNT   (1)
 Define the number of physical flash pages that comprise a NVM page.
#define NVM_DATA_SIZE_B   (MFB_PAGE_SIZE_B*NVM_FLASH_PAGE_COUNT)
 Define the total size of a NVM page, in bytes.
#define NVM_LEFT_PAGE   ((int32u)nvmStorageLeft)
 Define the absolute address of the LEFT page.
#define NVM_RIGHT_PAGE   ((int32u)nvmStorageRight)
 Define the absolute address of the RIGHT page.
#define NVM_MGMT_SIZE_B   (4)
 Define the number of bytes that comprise the NVM management bytes.

Functions

StStatus halCommonReadFromNvm (void *data, int32u offset, int16u length)
 Copy the NVM data from flash into the provided RAM location.
int16u * halCommonGetAddressFromNvm (int32u offset)
 Return the address of the token in NVM.
StStatus halCommonWriteToNvm (const void *data, int32u offset, int16u length)
 Write the NVM data from the provided location RAM into flash.

Detailed Description

Data definitions for the Cortex-M3 Non-Volatile Memory data storage system.

Cortex-M3 Non-Volatile Memory data storage system.

This header defines all of the data sets in the NVM data storage. Each piece of data in NVM storage uses an offset to indicate where the data lives and a size to indicate the size of that data. Both the offset and size are defined in bytes and must be a mupltiple of 16bits. The offset is from the start of an NVM page, defined by NVM_LEFT_PAGE and NVM_RIGHT_PAGE. The offset and size must be below the maximum size of NVM storage as defined by NVM_DATA_SIZE_B. All NVM data must start above NVM_MGMT_SIZE_B, since this is where the management bytes live.

Note:
This file is not directly used by the nvm.c or nvm.h files. This file is intended to be a convenient place to define all data that lives in NVM so it can be seen together in one group. nvm.h includes this file which means any code that includes nvm.h to call the read and write functions also has access to these defines.

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:

 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

Based on the 10 possible states, there are 5 valid 32bit mgmt words:

Detailed State Description:

Notes on algorithm behavior:


Define Documentation

#define NVM_DATA_SIZE_B   (MFB_PAGE_SIZE_B*NVM_FLASH_PAGE_COUNT)

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:
DO NOT EDIT THIS DEFINE. Instead, edit NVM_FLASH_PAGE_COUNT.

Definition at line 249 of file nvm.h.

Referenced by halCommonReadFromNvm(), and halCommonWriteToNvm().

#define NVM_FLASH_PAGE_COUNT   (1)

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.

Definition at line 240 of file nvm.h.

#define NVM_LEFT_PAGE   ((int32u)nvmStorageLeft)

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".

Definition at line 259 of file nvm.h.

Referenced by halCommonGetAddressFromNvm(), halCommonReadFromNvm(), and halCommonWriteToNvm().

#define NVM_MGMT_SIZE_B   (4)

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 must not change.

Definition at line 274 of file nvm.h.

#define NVM_RIGHT_PAGE   ((int32u)nvmStorageRight)

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".

Definition at line 266 of file nvm.h.

Referenced by halCommonGetAddressFromNvm(), halCommonReadFromNvm(), and halCommonWriteToNvm().


Function Documentation

int16u* halCommonGetAddressFromNvm ( int32u  offset)

Return the address of the token in NVM.

Parameters:
offsetThe location offset from which the address should be returned
Returns:
The address requested

Definition at line 158 of file nvm.c.

References halCommonWriteToNvm(), NVM_LEFT_PAGE, and NVM_RIGHT_PAGE.

StStatus halCommonReadFromNvm ( void *  data,
int32u  offset,
int16u  length 
)

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.

Parameters:
dataA (RAM) pointer to where the data should be copied.
offsetThe location from which the data should be copied. Must be 16bit aligned.
lengthThe length of the data in bytes. Must be 16bit aligned.
Returns:
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.

Definition at line 98 of file nvm.c.

References NVM_DATA_SIZE_B, NVM_LEFT_PAGE, and NVM_RIGHT_PAGE.

StStatus halCommonWriteToNvm ( const void *  data,
int32u  offset,
int16u  length 
)

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.

Parameters:
dataA (RAM) pointer from where the data should be taken.
offsetThe location to which the data should be written. Must be 16bit aligned.
lengthThe length of the data in bytes. Must be 16bit aligned.
Returns:
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.

Definition at line 280 of file nvm.c.

References NVM_DATA_SIZE_B, NVM_LEFT_PAGE, NVM_RIGHT_PAGE, and TRUE.

Referenced by halCommonGetAddressFromNvm().