NHS31xx SW API

Detailed Description

The application can adapt the storage module to better fit the different application scenarios through the use of diversity settings in the form of defines below. Sensible defaults are chosen. To override the default settings, place the defines with their desired values in the application app_sel.h header file. The compiler will pick up your defines before parsing this file.

Additional notes regarding some flags:

These flags may be overridden:

These defines are fixed or derived from the above flags and may not be defined or redefined in an application:

Macros

#define STORAGE_IDIVUP(n, d)   (((n)+(d)-1)/(d))
 
#define STORAGE_FIRST_ALON_REGISTER   4
 
#define STORAGE_EEPROM_FIRST_ROW   (EEPROM_NR_OF_RW_ROWS - (2048 / EEPROM_ROW_SIZE))
 
#define STORAGE_EEPROM_LAST_ROW   (EEPROM_NR_OF_RW_ROWS - 1)
 
#define STORAGE_EEPROM_ROW_COUNT   (STORAGE_EEPROM_LAST_ROW - STORAGE_EEPROM_FIRST_ROW + 1)
 
#define STORAGE_EEPROM_SIZE   (STORAGE_EEPROM_ROW_COUNT * EEPROM_ROW_SIZE)
 
#define STORAGE_FLASH_FIRST_PAGE   0
 
#define STORAGE_FLASH_LAST_PAGE   (FLASH_NR_OF_RW_SECTORS * FLASH_PAGES_PER_SECTOR - 1)
 
#define STORAGE_TYPE   uint8_t
 
#define STORAGE_BITSIZE   8
 
#define STORAGE_MAX_SAMPLE_ALON_CACHE_COUNT   ((141 - STORAGE_FIRST_ALON_REGISTER * 32) / STORAGE_BITSIZE)
 
#define STORAGE_SAMPLE_ALON_CACHE_COUNT   STORAGE_MAX_SAMPLE_ALON_CACHE_COUNT
 
#define STORAGE_SIGNED   0
 
#define STORAGE_WRITE_RECOVERY_EVERY_X_SAMPLES   (1 + STORAGE_SAMPLE_ALON_CACHE_COUNT)
 
#define STORAGE_REDUCE_RECOVERY_WRITES   0
 
#define STORAGE_MAX_LOSS_AFTER_CORRUPTION
 
#define STORAGE_MAX_BLOCK_SIZE_IN_SAMPLES
 
#define STORAGE_MAX_UNCOMPRESSED_BLOCK_SIZE_IN_BITS   (STORAGE_MAX_BLOCK_SIZE_IN_SAMPLES * STORAGE_BITSIZE)
 
#define STORAGE_BLOCK_HEADER_SIZE   2
 
#define STORAGE_BLOCK_SIZE_IN_SAMPLES   (((1024 - STORAGE_BLOCK_HEADER_SIZE) * 8) / STORAGE_BITSIZE)
 
#define STORAGE_BLOCK_SIZE_IN_SAMPLES   STORAGE_MAX_BLOCK_SIZE_IN_SAMPLES
 
#define STORAGE_UNCOMPRESSED_BLOCK_SIZE_IN_BITS   (STORAGE_BLOCK_SIZE_IN_SAMPLES * STORAGE_BITSIZE)
 
#define STORAGE_UNCOMPRESSED_BLOCK_SIZE_IN_BYTES   STORAGE_IDIVUP(STORAGE_UNCOMPRESSED_BLOCK_SIZE_IN_BITS, 8)
 
#define STORAGE_WORKAREA_SIZE   ((FLASH_PAGE_SIZE * 2) + STORAGE_UNCOMPRESSED_BLOCK_SIZE_IN_BYTES)
 
#define STORAGE_WORKAREA_SELF_DEFINED   1
 
#define STORAGE_WORKAREA   sStorage_Workarea
 
#define STORAGE_COMPRESS_CB   Storage_DummyCompressCb
 
#define STORAGE_DECOMPRESS_CB   Storage_DummyDecompressCb
 

Macro Definition Documentation

◆ STORAGE_IDIVUP

#define STORAGE_IDIVUP (   n,
 
)    (((n)+(d)-1)/(d))

Helper. Performs integer division, rounding up.

Parameters
nMust be a positive number.
dMust be a strict positive number

◆ STORAGE_FIRST_ALON_REGISTER

#define STORAGE_FIRST_ALON_REGISTER   4

The storage module requires the use of at least one general purpose register. This is used for its own housekeeping and allows it to finish initialization (Storage_Init) fast. In addition, all other general purposes registers with an index higher than given are also reserved for the storage module. These will be used to minimize EEPROM flush operations by caching as many samples as possible before committing them to EEPROM.

Precondition
These registers must be guaranteed not to be touched outside the storage module.
Note
More information about the ALON registers can be found in the Power Management Unit driver.
See also
STORAGE_SAMPLE_ALON_CACHE_COUNT

◆ STORAGE_EEPROM_FIRST_ROW

#define STORAGE_EEPROM_FIRST_ROW   (EEPROM_NR_OF_RW_ROWS - (2048 / EEPROM_ROW_SIZE))

The first EEPROM row assigned for sample storage. Starting from the first byte in this row, until the last byte in STORAGE_EEPROM_LAST_ROW, the storage module has full control: no other code may touch this EEPROM region.

Note
By default, the EEPROM row 2 kB below the locked EEPROM rows will be chosen.

◆ STORAGE_EEPROM_LAST_ROW

#define STORAGE_EEPROM_LAST_ROW   (EEPROM_NR_OF_RW_ROWS - 1)

The last EEPROM row assigned for sample storage. Starting from the first byte in STORAGE_EEPROM_FIRST_ROW, until the last byte in this row, the storage module has full control: no other code may touch this EEPROM region.

Note
the size of the EEPROM region is not required to be a multiple of the FLASH sector size.

◆ STORAGE_EEPROM_ROW_COUNT

#define STORAGE_EEPROM_ROW_COUNT   (STORAGE_EEPROM_LAST_ROW - STORAGE_EEPROM_FIRST_ROW + 1)

The number of EEPROM rows assigned for sample storage.

◆ STORAGE_EEPROM_SIZE

#define STORAGE_EEPROM_SIZE   (STORAGE_EEPROM_ROW_COUNT * EEPROM_ROW_SIZE)

The size of the assigned EEPROM storage in bytes

◆ STORAGE_FLASH_FIRST_PAGE

#define STORAGE_FLASH_FIRST_PAGE   0

The first FLASH page assigned for storage. Starting from the first byte in this page, until the last byte in STORAGE_FLASH_LAST_PAGE, the Storage module has full control: no other code will touch this FLASH region.

Note
Two special values exist:
  • When equal to 0, the first empty FLASH page after the .text and .data sections will be used. This page is automatically determined during link time by the Storage module's code.
  • When equal to STORAGE_FLASH_LAST_PAGE, storage to FLASH is disabled. Only the EEPROM will be used to store the data.
The page is not required to be sector aligned.
Warning
If a non-zero value is specified, it is the responsibility of the application programmer to ensure the FLASH location points to outside the .text and .data sections.

◆ STORAGE_FLASH_LAST_PAGE

#define STORAGE_FLASH_LAST_PAGE   (FLASH_NR_OF_RW_SECTORS * FLASH_PAGES_PER_SECTOR - 1)

The last FLASH page assigned for storage. Starting from the first byte in STORAGE_FLASH_FIRST_PAGE, until the last byte in this page, the Storage module has full control: no other code will touch this FLASH region.

Note
the size of the region is not required to be a multiple of the FLASH sector size.

◆ STORAGE_TYPE

#define STORAGE_TYPE   uint8_t

The type that is used to store one decompressed sample. When writing, samples are to be delivered using this type - see Storage_Write; when reading, samples are returned again using this type - see Storage_Read.

◆ STORAGE_BITSIZE

#define STORAGE_BITSIZE   8

The number of bits that are to be stored for each sample. For each sample given using Storage_Write this number of LSBits are written;

◆ STORAGE_MAX_SAMPLE_ALON_CACHE_COUNT

#define STORAGE_MAX_SAMPLE_ALON_CACHE_COUNT   ((141 - STORAGE_FIRST_ALON_REGISTER * 32) / STORAGE_BITSIZE)

The maximum number of samples that can be cached in the ALON general purposes registers before they are committed to EEPROM.

◆ STORAGE_SAMPLE_ALON_CACHE_COUNT

#define STORAGE_SAMPLE_ALON_CACHE_COUNT   STORAGE_MAX_SAMPLE_ALON_CACHE_COUNT

The number of samples that are cached in the ALON general purposes registers before they are committed to EEPROM.

◆ STORAGE_SIGNED

#define STORAGE_SIGNED   0

Define or set to a non-zero value (e.g. 1) to indicate that STORAGE_TYPE is a signed type.

  • If defined, the bit at position will be treated as the sign bit: when reading out samples from EEPROM or FLASH, this bit will be propagated left up to the MSBit of STORAGE_TYPE.
  • If not defined, the MSBits at positions STORAGE_BITSIZE and up will be set to 0.
Warning
Setting this diversity flag to 1 while STORAGE_TYPE is a structure, while raise compiler errors. see Storage_Read.

◆ STORAGE_WRITE_RECOVERY_EVERY_X_SAMPLES

#define STORAGE_WRITE_RECOVERY_EVERY_X_SAMPLES   (1 + STORAGE_SAMPLE_ALON_CACHE_COUNT)

Update the recovery information after adding X samples to non-volatile memory. This recovery information is written on a fixed location. When an unexpected reset occurs or a corruption of the data while writing new content, the recovery information is used to recover as much data as possible.

Note
The recovery information is only written in the call to Storage_DeInit. Depending on the number of calls to Storage_Write and its arguments, it is possible more samples have been written than this number.
Precondition
maximum number of expected data samples / STORAGE_WRITE_RECOVERY_EVERY_X_SAMPLES < 10.000

◆ STORAGE_REDUCE_RECOVERY_WRITES

#define STORAGE_REDUCE_RECOVERY_WRITES   0
  • If not defined, or defined to zero, two rows of the assigned EEPROM region for data storage are used for data recovery. When data corruption occurs, no extra loss of bytes will occur, only STORAGE_SAMPLE_ALON_CACHE_COUNT and STORAGE_WRITE_RECOVERY_EVERY_X_SAMPLES contribute to this.
  • If defined to a non-zero value: the space used for recovery - where the duplicate data of the last row and the hint information is stored - is reduced to just one row. When data corruption occurs, an additional loss of up to 8 bytes can occur.

◆ STORAGE_MAX_LOSS_AFTER_CORRUPTION

#define STORAGE_MAX_LOSS_AFTER_CORRUPTION
Value:
1 \
#define STORAGE_REDUCE_RECOVERY_WRITES
Definition: storage_dft.h:343
#define STORAGE_SAMPLE_ALON_CACHE_COUNT
Definition: storage_dft.h:288
#define STORAGE_IDIVUP(n, d)
Definition: storage_dft.h:158
#define STORAGE_WRITE_RECOVERY_EVERY_X_SAMPLES
Definition: storage_dft.h:323
#define STORAGE_BITSIZE
Definition: storage_dft.h:272

The maximum loss of samples that can occur. The storage module may not be able to return the most recently stored samples after an EEPROM corruption occurs. A scenario where this can happen is when printed batteries are used, and the battery has an internal impedance of 2 kOhm or higher, resulting in a barely sufficient voltage when operating normally, and a below-spec voltage when extra load is generated due to an EEPROM flush operation.

See also
STORAGE_SAMPLE_ALON_CACHE_COUNT
STORAGE_WRITE_RECOVERY_EVERY_X_SAMPLES
STORAGE_REDUCE_RECOVERY_WRITES

◆ STORAGE_MAX_BLOCK_SIZE_IN_SAMPLES

#define STORAGE_MAX_BLOCK_SIZE_IN_SAMPLES

The maximum allowed value for STORAGE_BLOCK_SIZE_IN_SAMPLES. After this many samples, the assigned EEPROM region is completely filled and no new sample can be written to EEPROM before its contents are moved to FLASH first.

◆ STORAGE_MAX_UNCOMPRESSED_BLOCK_SIZE_IN_BITS

#define STORAGE_MAX_UNCOMPRESSED_BLOCK_SIZE_IN_BITS   (STORAGE_MAX_BLOCK_SIZE_IN_SAMPLES * STORAGE_BITSIZE)

Defines the number of bits required to store one block of samples.

◆ STORAGE_BLOCK_HEADER_SIZE

#define STORAGE_BLOCK_HEADER_SIZE   2

The size in bytes of the meta data stored just in front of the (compressed) data block in FLASH.

◆ STORAGE_BLOCK_SIZE_IN_SAMPLES [1/2]

#define STORAGE_BLOCK_SIZE_IN_SAMPLES   (((1024 - STORAGE_BLOCK_HEADER_SIZE) * 8) / STORAGE_BITSIZE)

After writing this number of samples to EEPROM, the module will try to compress them all at once - see STORAGE_COMPRESS_CB - and move them to FLASH - defined by STORAGE_FLASH_FIRST_PAGE and STORAGE_FLASH_LAST_PAGE.

Note
This size determines the value of STORAGE_WORKAREA_SIZE - the larger this number, the more SRAM is required, and the larger chunks the compression and decompression algorithms have to work with.
By default, the block size will be chosen such that an uncompressed block can fit in one FLASH sector, including the accompanying meta data.

◆ STORAGE_BLOCK_SIZE_IN_SAMPLES [2/2]

#define STORAGE_BLOCK_SIZE_IN_SAMPLES   STORAGE_MAX_BLOCK_SIZE_IN_SAMPLES

After writing this number of samples to EEPROM, the module will try to compress them all at once - see STORAGE_COMPRESS_CB - and move them to FLASH - defined by STORAGE_FLASH_FIRST_PAGE and STORAGE_FLASH_LAST_PAGE.

Note
This size determines the value of STORAGE_WORKAREA_SIZE - the larger this number, the more SRAM is required, and the larger chunks the compression and decompression algorithms have to work with.
By default, the block size will be chosen such that an uncompressed block can fit in one FLASH sector, including the accompanying meta data.

◆ STORAGE_UNCOMPRESSED_BLOCK_SIZE_IN_BITS

#define STORAGE_UNCOMPRESSED_BLOCK_SIZE_IN_BITS   (STORAGE_BLOCK_SIZE_IN_SAMPLES * STORAGE_BITSIZE)

Defines the number of bits required to store one block of samples.

◆ STORAGE_UNCOMPRESSED_BLOCK_SIZE_IN_BYTES

#define STORAGE_UNCOMPRESSED_BLOCK_SIZE_IN_BYTES   STORAGE_IDIVUP(STORAGE_UNCOMPRESSED_BLOCK_SIZE_IN_BITS, 8)

Defines the number of bytes required to store one block of samples.

◆ STORAGE_WORKAREA_SIZE

#define STORAGE_WORKAREA_SIZE   ((FLASH_PAGE_SIZE * 2) + STORAGE_UNCOMPRESSED_BLOCK_SIZE_IN_BYTES)

The size in bytes of the required memory for this module

◆ STORAGE_WORKAREA_SELF_DEFINED

#define STORAGE_WORKAREA_SELF_DEFINED   1

Used internally to know when to provide (static) memory for this.

◆ STORAGE_WORKAREA

#define STORAGE_WORKAREA   sStorage_Workarea

An array, or a pointer to an array of at least STORAGE_WORKAREA_SIZE bytes. During the lifetime of this module - starting from the start of the call to Storage_Init until the end of the call to Storage_DeInit, this memory is under full control by this module.

Precondition
Must be word (32 bits) aligned.

◆ STORAGE_COMPRESS_CB

#define STORAGE_COMPRESS_CB   Storage_DummyCompressCb

The name of the function - not a function pointer - of type pStorage_CompressCb_t that is able to compress STORAGE_BLOCK_SIZE_IN_SAMPLES packed samples of type STORAGE_TYPE where STORAGE_BITSIZE bits are retained for each.

Note
When not overridden, the default behavior is to store the data uncompressed, i.e. the data is copied from EEPROM to FLASH unmodified.

◆ STORAGE_DECOMPRESS_CB

#define STORAGE_DECOMPRESS_CB   Storage_DummyDecompressCb

The name of the function - not a function pointer - of type pStorage_DecompressCb_t that is able to decompress STORAGE_BLOCK_SIZE_IN_SAMPLES packed samples of type STORAGE_TYPE where STORAGE_BITSIZE bits are retained for each.