14.4.1 PDS Library Usage

PIC32CX-BZ3 Persistent Data Server(PDS) Library Usage

Configuring the library

There is no configuration of this library.

Using the library

Defining Files and Directories

In PDS particular pieces of persistent data are called files (or items), and groups of files are called directories. Note that directories are just the way to refer to particular files, and a file can belong to several directories at once. Files and directories contain the meta-information about the data that allows its maintenance within the NV – file descriptors and directory descriptors.

The PDS component defines a number of file units for individual stack parameters and directories to group files, for more subtle control. The application may define its own items.

File and File Descriptor

Each item which user wants to backup in a non-volatile memory and restore in case of power failure is treated as a FILE - actual item value with associated service information, FILE DESCRIPTOR. Each file could be accessed by it's ID a unique 16-bit value associated with a file. File descriptor keeps information about item's size and it's displacement in RAM and inside the NV storage.

All file descriptors should be placed in a special segment inside the MCU Flash memory - [PDS_FF]. The PDS_FILE_DESCR() macro is used to initialize descriptor and PDS_DECLARE_FILE() macro is used to place descriptor to required segment.

A file descriptor consists of the following parts:

  • memoryId: memory identifier associated with a file
  • size: the size of file’s data
  • ramAddr: the pointer to item’s entity in RAM (that is, to a variable holding file’s data), if one exists, or NULL otherwise
  • fileMarks: file marks, specifying specific characteristics of the file.
    File marks may be set either to following values:
    • SIZE_MODIFICATION_ALLOWED: indicates that size of the file can be different in new firmware image after over-the-air upgrade. Usually is set for files storing table data, such as binding table, group table and others.
    • ITEM_UNDER_SECURITY_CONTROL: no impact, works same as NO_FILE_MARKS
    • NO_FILE_MARKS: no special characteristics for the file

A file descriptor tied to some data in RAM is defined by using the PDS_DECLARE_FILE macro in the code that may be used by both the stack and the application:

PDS_DECLARE_FILE(memoryId, size, ramAddr, fileMarks)

Directory and Directory Descriptor

PDS is able to operate with separate files or with file lists - DIRECTORIES. Directory nesting is allowed. Each directory should be provided with DIRECTORY DESCRIPTOR which keeps information about associated items. Directories could be accessed by 16-bit ID, different from already associated with files.

All directory descriptors should be placed in a special segment inside the MCU Flash memory - [PDS_FD]. The PDS_DECLARE_DIR() macro is used to place a directory to required segment.

Directory descriptors are special entities describing a group of file. A directory descriptor is defined in the code (the stack’s or the application’s one) and is placed to the separate flash memory segment.

The directory descriptor consists of the following parts:
  • list: pointer to the list of files IDs associated with the directory. This list should be placed in the flash memory (by the use of the PROGMEM_DECLARE macro – see an example below).
  • filesCount: the amount of files associated with the directory
  • memoryId: memory identifier associated with the directory

A directory is declared via the PDS_DECLARE_DIR macro in the following way:

PDS_DECLARE_DIR(const PDS_DirDescr_t csGeneralParamsDirDescr) =
{
.list = CsGeneralMemoryIdsTable,
.filesCount = ARRAY_SIZE(CsGeneralMemoryIdsTable),
.memoryId = BC_GENERAL_PARAMS_MEM_ID
};
//Where CsGeneralMemoryIdsTable is the list of objects defined in the following way:
PROGMEM_DECLARE(const PDS_MemId_t CsGeneralMemoryIdsTable[]) =
{
CS_UID_MEM_ID,
CS_RF_TX_POWER_MEM_ID,
//other parameters in this list
}

Table 14-2. Major Functions
Name Description
PDS_Init initializes the Persistence Data Server
PDS_InitItems initializes the Persistence Data Server Items
PDS_Restore Restores data from non-volatile storage
PDS_Store Stores data in non-volatile memory in background, not blocking other processes
PDS_DeleteAll deletes data from non-volatile storage
PDS_AddItemExcpetionFromDeleteAll extempts the item from the Delete All command
PDS_Delete removes specified file records from NV Storage
PDS_IsAbleToRestore Checks if the specified PDS file or directory can be restored from non-volatile memory
PDS_RegisterWriteCompleteCallback registers the callback for the Item Write completion
PDS_RegisterUpdateMemoryCallback registers the callback for the Item update memory
PDS_StoreItemTaskHandler task that handles the store items into NV memory
PDS_GetPendingItemsCount gets the number of items pending in the PDS write queue
PDS_GetItemDescr gets the item descriptor for the given item ID