Class supporting persistence of tagged records to non-volatile memory.
More...
#include <nrfcxx/utility.hpp>
|
|
static constexpr uint16_t | TAG_ERASED = 0 |
| | header_type::tag value for a record that has been erased.
|
| |
|
static constexpr uint16_t | TAG_UNUSED = 0xFFFF |
| | header_type::tag value for the placeholder header of the next record to be written.
|
| |
| static constexpr const uint32_t * | REGION_BEGIN = &__PersistBase |
| | pointer to the first word of the PERSIST memory region. More...
|
| |
| static constexpr const uint32_t * | REGION_END = &__PersistLimit |
| | pointer to the first word after the PERSIST memory region. More...
|
| |
| static constexpr unsigned int | PAGE_SIZE = 1024 |
| | Number of bytes in a flash page. More...
|
| |
| static constexpr unsigned int | BLOCK_SIZE = PAGE_SIZE |
| | Number of bytes in a flash block. More...
|
| |
Class supporting persistence of tagged records to non-volatile memory.
Page-aligned regions of flash memory may be reserved by defining a non-empty PERSIST region in the linker memory map and defining objects that are placed in the .persist (or a .persist.*) section. Instantiating an instance of Persist and configuring it to reference one of those regions allows tagged records to be stored in flash and retrieved by their tag.
- Tags must be unique to each persisted record (type). Attempting to add a record (instance) with the same tag as an existing record will cause the previous record (instance) to be removed.
- The system does not automatically perform garbage collection. When there is insufficient space to store a record the application must use extract() to extract the active records, clear() to erase the region, and restore() to put the records back leaving the maximum possible space for additional records.
- On nRF52 the flash is restricted to a certain number of writes per 128-word block before additional writes to the block may cause data loss. If more than 53 records are stored in a single block this limitation may be exceeded for nRF52832. The system does not detect or mitigate against violating this requirement.
- Retrieved records provide information that describes their content length in aligned words. If it is necessary to get byte- or half-word lengths of record data that information must be extracted from the record or other external sources.
◆ Persist()
Construct the wrapper class.
- Parameters
-
| code | the failsafe code to be generated when an unrecoverable error is detected using the Persist API. |
◆ addReplace()
| const header_type* nrfcxx::utility::Persist::addReplace |
( |
uint16_t |
tag, |
|
|
const void * |
data, |
|
|
size_t |
count |
|
) |
| |
Add or replace the record with the given tag.
- Parameters
-
| tag | the header_type::tag value for the record. If a record with this tag is already present it will be erased prior to creating the new record. |
| data | pointer to the data to be associated with the record. If a null pointer is passed the record will have no data. |
| count | the number of bytes at data that should be preserved at header_type::data in the resulting record. |
- Returns
- a null pointer if the record could not be created, otherwise a pointer to the new record. If a null pointer is returned any previous record with
tag is left unmodified.
◆ available()
| size_t nrfcxx::utility::Persist::available |
( |
| ) |
const |
|
inline |
Return the number of bytes available for payload in a new record.
- Note
- This is the maximum payload length for a single record. It does not include the length of the headers for additional records.
◆ configure()
| int nrfcxx::utility::Persist::configure |
( |
const uint32_t * |
begin, |
|
|
const uint32_t * |
end |
|
) |
| |
Configure the instance to operate on a specific persisted region.
An instance can be successfully configured at most once.
- Parameters
-
| begin | page-aligned pointer to NVMC data. |
| end | page-aligned pointer to NVMC data, at or above begin |
- Returns
- zero if the configuration was acceptable, otherwise a negative error code.
◆ erase()
| int nrfcxx::utility::Persist::erase |
( |
uint16_t |
tag | ) |
|
|
inline |
Remove the record with the given tag.
- Parameters
-
- Returns
- zero if the record was found and removed, or a negative error code.
◆ extract()
| ptrdiff_t nrfcxx::utility::Persist::extract |
( |
header_type * |
buffer = nullptr, |
|
|
size_t |
length = 0 |
|
) |
| const |
Extract the active records from the region.
- Parameters
-
| buffer | where to store the record data. If a null pointer is passed the records will not be extracted, but the return value will indicate the buffer length required to successfully extract the data. |
| length | the number of words that may be stored in buffer when that is a non-null pointer. |
- Returns
- the number of words stored in
buffer (or that would be stored in buffer if it were not null), or a negative error code if the provided non-null buffer and length cannot accommodate all records.
◆ find()
| const header_type* nrfcxx::utility::Persist::find |
( |
uint16_t |
tag | ) |
|
|
inline |
Find the record with the given tag, if it is present.
- Parameters
-
- Returns
- a pointer to the record if it is found, otherwise a null pointer.
◆ gc()
| int nrfcxx::utility::Persist::gc |
( |
| ) |
|
Extract, clear, and restore the page contents.
This uses the stack to store the extracted information.
- Returns
- as with restore().
◆ restore()
| int nrfcxx::utility::Persist::restore |
( |
const header_type * |
buffer, |
|
|
size_t |
length |
|
) |
| |
Replay extracted records into the persisted region.
If a record has the same tag as a record in the region, it supersedes the existing record as with addReplace().
- Parameters
-
| buffer | pointer to a record set extracted from a Persist instance using extract(). |
| length | the non-negative size returned from the extract() call that filled buffer. |
- Returns
- A non-negative count of the number of records restored, if all records were restored. A negative error code indicates that the region did not have sufficient unused space to store the records.
◆ BLOCK_SIZE
| constexpr unsigned int nrfcxx::utility::Persist::BLOCK_SIZE = PAGE_SIZE |
|
staticconstexpr |
Number of bytes in a flash block.
- Note
- This constant is nRF5 series-specific; this value is for nRF51.
◆ erased_
| unsigned int nrfcxx::utility::Persist::erased_ |
|
protected |
Number of words in the region covered by erased records.
This includes the header word as well as record content.
◆ first_
Pointer to the first used and unerased record in the region.
If the region has never had a record added the pointer is null.
◆ PAGE_SIZE
| constexpr unsigned int nrfcxx::utility::Persist::PAGE_SIZE = 1024 |
|
staticconstexpr |
Number of bytes in a flash page.
- Note
- This constant is nRF5 series-specific; this value is for nRF51.
◆ REGION_BEGIN
| constexpr const uint32_t* nrfcxx::utility::Persist::REGION_BEGIN = &__PersistBase |
|
staticconstexpr |
pointer to the first word of the PERSIST memory region.
This may be used as the begin parameter to configure() when a single persist instance that covers the region is desired.
◆ REGION_END
| constexpr const uint32_t* nrfcxx::utility::Persist::REGION_END = &__PersistLimit |
|
staticconstexpr |
pointer to the first word after the PERSIST memory region.
This may be used as the end parameter to configure() when a single persist instance that covers the region is desired.
◆ unused_
Pointer to the region's unused record.
If there is no unused space in the region the pointer is null.
- Note
- An unused record has tag TAG_UNUSED and span of 0xFFFF. There is at most one of these in the region, and it should generally not be exposed to the application.
The documentation for this class was generated from the following file:
