Token Manager

Description

Routines for working with tokens.


Introduction

The token system stores such non-volatile information as the manufacturing ID, channel number, transmit power, and various pieces of information that the application needs to be persistent between device power cycles. The token system is design to abstract implementation details and simplify interacting with differing non-volatile systems. The majority of tokens are stored in NVM3 or Simulated EEPROM (both use Flash) where they can be rewritten. Manufacturing tokens are stored in dedicated regions of flash and are not designed to be rewritten.

The NVM3 component is the preferred method and should be used on its own for data storage if SimEE has not been used. Token Manager is not required to access NVM3 data. The NVM3 system has its own APIs for interacting with NVM3.

The Token Manager is only used if existing systems already have SimEE. Token Manager enables SimEE data storage with the same API for accessing NVM3 or SimEE storage.

By default the Token Manager pulls in the NVM3 component for storage. The "Token Manager using NVM3" still requires the "Token Manager" component. If the SimEE1 or SimEE2 component is added into the project alongside the Token Manager, then SimEE1 or SimEE2 will be used for storage. If the Sim EEPROM 2 to NVM3 Upgrade component is added to the project alongside the Token Manager, then the upgrade will run at startup to transition as much stored data as possible into NVM3 format. When using the upgrade component don't include NVM3 or SimEE2 components. Once an upgrade is run, it would be possible to use stock Token Manager since Token Manager defaults to NVM3.

Functions

Ecode_t sl_token_init (void)
Initialize the Token Manager.
Ecode_t sl_token_get_data (uint32_t token, uint32_t index, void *data, uint32_t length)
Read the data stored in the specified data or manufacturing token.
Ecode_t sl_token_set_data (uint32_t token, uint32_t index, void *data, uint32_t length)
Writes the data to the specified token.
Ecode_t sl_token_increment_counter (uint32_t token)
Increments the value of a counter token.
Ecode_t sl_token_get_manufacturing_data (uint32_t token, uint32_t index, void *data, uint32_t length)
Read the data associated with the specified manufacturing token.
Ecode_t sl_token_set_manufacturing_data (uint32_t token, void *data, uint32_t length)
Writes data to a manufacturing token.

Function Documentation

◆ sl_token_init()

Ecode_t sl_token_init ( void )

Initialize the Token Manager.

Note
This function must be called before any other sl_token functions. If it does not return success, the other sl_token functions will not work.
Returns
0 if successful. Error code otherwise.

◆ sl_token_get_data()

Ecode_t sl_token_get_data ( uint32_t token,
uint32_t index,
void * data,
uint32_t length
)

Read the data stored in the specified data or manufacturing token.

Parameters
token The NVM3KEY or SimEE CREATOR define for the token.
index The index to access in the indexed token.
data A pointer to where the token data should be placed.
length The size of the token data in number of bytes.
Returns
0 if successful. Error code otherwise.

◆ sl_token_set_data()

Ecode_t sl_token_set_data ( uint32_t token,
uint32_t index,
void * data,
uint32_t length
)

Writes the data to the specified token.

Parameters
token The NVM3KEY or SimEE CREATOR define for the token.
index The index to access in the indexed token.
data A pointer to the data being written.
length The size of the token data in number of bytes.
Returns
0 if successful. Error code otherwise.

◆ sl_token_increment_counter()

Ecode_t sl_token_increment_counter ( uint32_t token )

Increments the value of a counter token.

This call does not support manufacturing tokens.

Parameters
token The NVM3KEY or SimEE CREATOR define for the token.
Returns
0 if successful. Error code otherwise.

◆ sl_token_get_manufacturing_data()

Ecode_t sl_token_get_manufacturing_data ( uint32_t token,
uint32_t index,
void * data,
uint32_t length
)

Read the data associated with the specified manufacturing token.

Parameters
token The NVM3KEY or SimEE CREATOR define for the token.
index The index to access in the indexed token.
data A pointer to where the token data should be placed.
length The size of the token data in number of bytes.
Returns
0 if successful. Error code otherwise.

◆ sl_token_set_manufacturing_data()

Ecode_t sl_token_set_manufacturing_data ( uint32_t token,
void * data,
uint32_t length
)

Writes data to a manufacturing token.

Note
Only manufacturing token values that have not been written since the last erase can be written. For areas of flash that cannot be erased by user code, those manufacturing tokens are effectively write-once.
Parameters
token The NVM3KEY or SimEE CREATOR define for the token.
data A pointer to the data being written.
length The size of the token data in number of bytes.
Returns
0 if successful. Error code otherwise.