NHS31xx SW API
eeprom: EEPROM driver

Detailed Description

The EEPROM HW block contains two parts: a controller and a memory core.

Key benefit
This EEPROM driver abstracts away the access to the EEPROM memory. The API
  • resolves all alignment requirements imposed by the HW block.
  • minimizes the number of flushes, maximizing the lifetime of the EEPROM.
Usage
  • First call: Chip_EEPROM_Init
    Before the EEPROM memory can be accessed, it must be initialized. During initialization clock and power are provided to the EEPROM controller and EEPROM memory.
  • Any sequence of Chip_EEPROM_Read and Chip_EEPROM_Write
    After initialization, data can be read and written via the API calls at will. Mind, writes are not immediately persistent in EEPROM.
    Both reading and writing, the caller must provide an offset in the EEPROM memory and a buffer with size. The offset for the read and write functions is a byte offset and is relative to EEPROM_START.
  • Last call: Chip_EEPROM_DeInit
    Data is only guaranteed to be committed in non-volatile memory after a call to Chip_EEPROM_Flush or Chip_EEPROM_DeInit.
Warning
EEPROM requires a system clock of 500 kHz or higher. This is not checked for. For a full list of clock restrictions in effect, see SW Clock Restrictions.
Example - Read, modify and write EEPROM content
/* Note: it is possible to read from and write to a non-aligned location and while crossing a row boundary: */
int counter;
Chip_EEPROM_Read(NSS_EEPROM, 61, &counter, sizeof(int));
counter++;
Chip_EEPROM_Write(NSS_EEPROM, 61, &counter, sizeof(int));
Chip_EEPROM_Flush(NSS_EEPROM, true); /* After flush it is ensured that the new value is preserved. */
/* Note: the previous flush call was optional since DeInit will perform it if required. */

Data Structures

struct  NSS_EEPROM_T
 

Functions

void Chip_EEPROM_Init (NSS_EEPROM_T *pEEPROM)
 
void Chip_EEPROM_DeInit (NSS_EEPROM_T *pEEPROM)
 
void Chip_EEPROM_Read (NSS_EEPROM_T *pEEPROM, int offset, void *pBuf, int size)
 
void Chip_EEPROM_Write (NSS_EEPROM_T *pEEPROM, int offset, const void *pBuf, int size)
 
void Chip_EEPROM_Memset (NSS_EEPROM_T *pEEPROM, int offset, uint8_t pattern, int size)
 
void Chip_EEPROM_Flush (NSS_EEPROM_T *pEEPROM, bool wait)
 

Data Structure Documentation

◆ NSS_EEPROM_T

struct NSS_EEPROM_T

NSS EEPROM register block structure

Data Fields
volatile uint32_t CMD

< Defines 'read / write' permissions EEPROM command register

volatile const uint32_t RESERVED1

< Defines 'read only' permissions

volatile uint32_t RWSTATE

< Defines 'read / write' permissions EEPROM read wait state register

volatile uint32_t PAUTOPROG

< Defines 'read / write' permissions EEPROM auto programming register

volatile uint32_t WSTATE

< Defines 'read / write' permissions EEPROM wait state register

volatile uint32_t CLKDIV

< Defines 'read / write' permissions EEPROM clock divider register

volatile uint32_t PWRDWN

< Defines 'read / write' permissions EEPROM power down register

volatile const uint32_t RESERVED2

< Defines 'read only' permissions

volatile uint32_t MSSTART

< Defines 'read / write' permissions EEPROM checksum start address register

volatile uint32_t MSSTOP

< Defines 'read / write' permissions EEPROM checksum stop address register

volatile const uint32_t MSDATASIG

< Defines 'read only' permissions EEPROM Data signature register

volatile const uint32_t MSPARSIG

< Defines 'read only' permissions EEPROM parity signature register

volatile const uint32_t RESERVED3

< Defines 'read only' permissions

volatile const uint32_t STATUS

< Defines 'read only' permissions EEPROM device status register

volatile const uint32_t RESERVED4[998]

< Defines 'read only' permissions

volatile const uint32_t MODULE_CONFIG

< Defines 'read only' permissions Controller configuration options

volatile const uint32_t RESERVED5

< Defines 'read only' permissions

volatile uint32_t INT_CLR_ENABLE

< Defines 'read / write' permissions Clear interrupt enable bits

volatile uint32_t INT_SET_ENABLE

< Defines 'read / write' permissions Set interrupt enable bits

volatile const uint32_t INT_STATUS

< Defines 'read only' permissions Interrupt status bits

volatile const uint32_t INT_ENABLE

< Defines 'read only' permissions Interrupt enable bits

volatile uint32_t INT_CLR_STATUS

< Defines 'read / write' permissions Clear interrupt status bits

volatile uint32_t INT_SET_STATUS

< Defines 'read / write' permissions Set interrupt status bits

volatile const uint32_t RESERVED6[3]

< Defines 'read only' permissions

volatile uint32_t MODULE_ID

< Defines 'read / write' permissions Controller memory module identification

Function Documentation

◆ Chip_EEPROM_Init()

void Chip_EEPROM_Init ( NSS_EEPROM_T pEEPROM)

Initializes EEPROM peripheral. This function must be the first function to call in this driver after going to deep sleep, deep power down, power-off power save mode, or after changing the system clock frequency.

  • Power and Clock are enabled for EEPROM and for EEPROM controller block.
  • Based upon the configured system clock, the correct clock divider is selected.
  • Will wait after enabling the HW block until the HW block can be used.
Parameters
pEEPROM: ignored. Argument no longer used but kept for compatibility.
Note
The EEPROM requires a minimum system clock frequency before it can be used. See Clock Restrictions.
Postcondition
All others API calls of this driver may now be used.

◆ Chip_EEPROM_DeInit()

void Chip_EEPROM_DeInit ( NSS_EEPROM_T pEEPROM)

Disables EEPROM peripheral. If required, data is flushed Power and Clock are disabled for EEPROM and for EEPROM controller block.

Parameters
pEEPROM: ignored. Argument no longer used but kept for compatibility.
Postcondition
Only Chip_EEPROM_Init may now be used of this driver.

◆ Chip_EEPROM_Read()

void Chip_EEPROM_Read ( NSS_EEPROM_T pEEPROM,
int  offset,
void *  pBuf,
int  size 
)

Reads data from the EEPROM memory into a user allocated buffer.

Parameters
pEEPROM: ignored. Argument no longer used but kept for compatibility.
offset: EEPROM Offset, in bytes, from where to start writing the data into EEPROM. The offset is relative to EEPROM_START
pBuf: Pointer to the user allocated buffer in ram. There are no alignment requirements.
size: Number of bytes to copy
Precondition
offset an size denote a memory region. The caller must ensure this whole region lies inside the EEPROM memory. This is not checked for.

◆ Chip_EEPROM_Write()

void Chip_EEPROM_Write ( NSS_EEPROM_T pEEPROM,
int  offset,
const void *  pBuf,
int  size 
)

Writes data from a user allocated buffer into the EEPROM memory

Parameters
pEEPROM: ignored. Argument no longer used but kept for compatibility.
offset: EEPROM Offset, in bytes, from where to start writing the data into EEPROM. The offset is relative to EEPROM_START
pBuf: Pointer to the data to be copied into EEPROM. There are no alignment requirements.
size: Number of bytes to copy offset + size must not exceed EEPROM_ROW_SIZE * EEPROM_NR_OF_RW_ROWS
Note
This function's timing is non deterministic. Possibly, a pending flush must be executed before data is written; and when the data to write is spread over multiple EEPROM rows, intermediate flushes are also required.
The portion written in the last row is not committed an flushed to EEPROM. To be sure written data is effectively retained in the EEPROM memory, user needs to call Chip_EEPROM_Flush or Chip_EEPROM_DeInit
Precondition
offset an size denote a memory region. The caller must ensure this whole region lies inside the EEPROM memory. This is not checked for.

◆ Chip_EEPROM_Memset()

void Chip_EEPROM_Memset ( NSS_EEPROM_T pEEPROM,
int  offset,
uint8_t  pattern,
int  size 
)

Memsets a pattern into the EEPROM memory

Parameters
pEEPROM: ignored. Argument no longer used but kept for compatibility.
offset: EEPROM Offset, in bytes, from where to start writing the data into EEPROM. The offset is relative to EEPROM_START
patternByte pattern to be set into EEPROM
size: Number of bytes to set
Note
The offset an size denote a memory region. If any part of this region lies outside the EEPROM memory, nothing is written, and the function call is a void operation. offset + size must not exceed EEPROM_ROW_SIZE * EEPROM_NR_OF_RW_ROWS
This function's timing is non deterministic. Possibly, a pending flush must be executed before data is written; and when the data to write is spread over multiple EEPROM rows, intermediate flushes are also required.
The portion written in the last row is not committed an flushed to EEPROM. To be sure written data is effectively retained in the EEPROM memory, user needs to call Chip_EEPROM_Flush or Chip_EEPROM_DeInit

◆ Chip_EEPROM_Flush()

void Chip_EEPROM_Flush ( NSS_EEPROM_T pEEPROM,
bool  wait 
)

If needed, this function flushes pending data into the EEPROM. When this function returns, the flush operation has been completed. To be used only if the user wants to make sure written data is retained, for example before going to sleep.

Parameters
pEEPROM: ignored. Argument no longer used but kept for compatibility.
wait: ignored. Argument no longer used but kept for compatibility.