![]() |
NHS31xx storage - Maximizing storage for equisized samples
|
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:
STORAGE_UNCOMPRESSED_BLOCK_SIZE_IN_BYTES
To start, determine the correct sizes of the three memory regions the storage module has exclusive access of:
Next, determine what will be stored. Each sample given to the storage module must have the same type. Both basic types and structures or unions are possible. Each sample will be placed back to back, without a single padding bit; if you know that a few MSBits are always 0, you can choose to store fewer bits, resulting in a larger storage capacity.
Compression greatly increases the number of samples that can be stored, at the cost of the size of the compression library itself. Normally, the compression ratio is greater when more samples are compressed at once. The storage module allows you to insert function calls to compress and decompress a large number of samples automatically.
Keep in mind that enlarging STORAGE_UNCOMPRESSED_BLOCK_SIZE_IN_BYTES also enlarges STORAGE_WORKAREA_SIZE, and the memory required for compressing and decompressing.
If a compression is to be used which operates on a single sample at a time, the application can wrap the calls to the storage module and implement this outside the storage module. An example of this is a mapping operation which reduces the resolution in specific value ranges. Be sure to adapt the type and bitsize to match the encoded values.
Data recovery is paramount. Especially when at the end of the use case lifetime, when dealing with batteries which can't maintain a stable voltage any more, the risk of data corruption increases. The chance for data corruption to occur is highly dependent on your specific application, your choice of battery, and your environmental conditions. And apart from data corruption, the IC might also reset during flushing of EEPROM data, or during a FLASH program operation. When any of this happens, the storage module must be able to return as many samples as possible.
The storage module ensures only a few most recent samples may get lost.
The maximum amount of samples that may get lost due to an unexpected reset, a battery failure, or a data corruption, is captured in STORAGE_MAX_LOSS_AFTER_CORRUPTION To recover all samples safe for the very last, at the expense of (a lot) more EEPROM flush operations, use these settings:
#define STORAGE_IDIVUP | ( | n, | |
d | |||
) | (((n)+(d)-1)/(d)) |
Helper. Performs integer division, rounding up.
n | Must be a positive number. |
d | Must be a strict positive number |
Definition at line 158 of file storage_dft.h.
Referenced by MoveSamplesFromEepromToFlash(), ReadFromEeprom(), and WriteToEeprom().
#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.
Definition at line 176 of file storage_dft.h.
Referenced by Storage_DeInit(), and Storage_Init().
#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.
Definition at line 190 of file storage_dft.h.
#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.
Definition at line 202 of file storage_dft.h.
#define STORAGE_EEPROM_ROW_COUNT (STORAGE_EEPROM_LAST_ROW - STORAGE_EEPROM_FIRST_ROW + 1) |
The number of EEPROM rows assigned for sample storage.
Definition at line 209 of file storage_dft.h.
#define STORAGE_EEPROM_SIZE (STORAGE_EEPROM_ROW_COUNT * EEPROM_ROW_SIZE) |
The size of the assigned EEPROM storage in bytes
Definition at line 215 of file storage_dft.h.
#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.
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.
.text and
.data sections. Definition at line 233 of file storage_dft.h.
#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.
Definition at line 246 of file storage_dft.h.
Referenced by MoveSamplesFromEepromToFlash(), and Storage_Reset().
#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.
Definition at line 264 of file storage_dft.h.
Referenced by Storage_Read(), and Storage_Write().
#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;
Definition at line 272 of file storage_dft.h.
Referenced by CacheSample(), FindMarker(), GetCachedSample(), GetEepromCount(), Storage_DeInit(), Storage_Init(), Storage_Read(), Storage_Seek(), Storage_Write(), StoreSamplesInEeprom(), ValidateHint(), and ValidateRecoverInfo().
#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.
Definition at line 281 of file storage_dft.h.
#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.
Definition at line 288 of file storage_dft.h.
Referenced by CacheSample(), Storage_Write(), and ValidateRecoverInfo().
#define STORAGE_SIGNED 0 |
Define or set to a non-zero value (e.g. 1
) to indicate that STORAGE_TYPE is a signed type.
0
.Definition at line 309 of file storage_dft.h.
#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.
STORAGE_WRITE_RECOVERY_EVERY_X_SAMPLES
< 10.000 Definition at line 323 of file storage_dft.h.
Referenced by Storage_DeInit().
#define STORAGE_REDUCE_RECOVERY_WRITES 0 |
Definition at line 343 of file storage_dft.h.
#define STORAGE_MAX_LOSS_AFTER_CORRUPTION |
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.
Definition at line 358 of file storage_dft.h.
#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.
Definition at line 372 of file storage_dft.h.
Referenced by StoreSamplesInEeprom().
#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.
Definition at line 377 of file storage_dft.h.
Referenced by ValidateHint(), and ValidateRecoverInfo().
#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.
Definition at line 382 of file storage_dft.h.
#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.
Definition at line 396 of file storage_dft.h.
Referenced by GetFlashCount(), MoveSamplesFromEepromToFlash(), Storage_Read(), Storage_Seek(), and StoreSamplesInEeprom().
#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.
Definition at line 396 of file storage_dft.h.
#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.
Definition at line 404 of file storage_dft.h.
Referenced by MoveSamplesFromEepromToFlash(), and ReadAndCacheSamplesFromFlash().
#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.
Definition at line 407 of file storage_dft.h.
Referenced by MoveSamplesFromEepromToFlash(), and ReadAndCacheSamplesFromFlash().
#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
Definition at line 410 of file storage_dft.h.
#define STORAGE_WORKAREA_SELF_DEFINED 1 |
Used internally to know when to provide (static) memory for this.
Definition at line 419 of file storage_dft.h.
#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.
Definition at line 426 of file storage_dft.h.
#define STORAGE_COMPRESS_CB |
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.
Definition at line 442 of file storage_dft.h.
#define STORAGE_DECOMPRESS_CB |
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.
Definition at line 454 of file storage_dft.h.