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:

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.

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
}