Persistent Data Manager (PDM) for Zigbee application on KW41Z

[#1]

This document describes the Persistent Data Manager (PDM) module which handles the storage of stack context data and application data in Non-Volatile Memory (NVM). For the KW41Z devices, this memory is internal Flash and this document will therefore refer to Flash.

Tip: In this document, a cold start refers to either a first-time start or a re-start without memory (RAM) held. A warm start refers to a re-start with memory held (for example following sleep with memory held).

1.    Overview

If the data needed for the operation of a network node is stored only in on-chip RAM, this data is maintained in memory only while the node is powered and will be lost during an interruption to the power supply (e.g. power failure or battery replacement). This data includes context data for the network stack and application data.

In order for the node to recover from a power interruption with continuity of service, provision must be made for storing essential operational data in Non-Volatile Memory (NVM), such as Flash. This data can then be recovered during a re-boot following power loss, allowing the node to resume its role in the network.

The storage and recovery of operational data in KW41Z Flash can be handled using the Persistent Data Manager (PDM) module, as described in the rest of this document, which covers the following topics:

• Initializing the PDM module - see Section 2
• Managing data in Flash - see Section 3
• PDM features like record searching by record ID – see Section 4
• The PDM can be used with ZigBee PRO and IEEE802.15.4 wireless networking protocols.

2.    Initializing the PDM and Building a File System

Using the Kinetis NVM framework requires that the user must register the necessary data sets for NVM writing. This is done by calling function NVM_RegisterDataSet(). This function registers the given data set to be written in the NVM_TABLE section from Flash.

The PDM module must be initialized by the application following a cold or warm start, irrespective of the PDM functionality used (e.g. context data storage or counter implementation). PDM initialization is performed using the function PDM_eInitialise().

This function requires the following information to be specified:

• The number of Flash sectors to be used by PDM (a zero value means use all segments)

Once the PDM_eInitialise() function has been called, the PDM module builds a file system in RAM containing information about the sectors that it manages in Flash. The PDM reads the header data from each Flash sector and builds the file system.

Application records are grouped and initialized in function InitAplRecords(), while network stack records are grouped and initialized in function InitNwkRecords().

For ZigBee PRO, the PDM is used in its most general form, as described above.

3.    Managing Data in Flash

This section describes use of the PDM module to persist data in Flash in order to provide continuity of service when the KW41Z device resumes operation after a cold start or a warm start without memory held.

Data is stored in Flash in terms of ‘records’. A record occupies at least one Flash sector but may be larger than a sector and occupy multiple sectors. Any number of records of different lengths can be created, provided that they do not exceed the Flash capacity. The records are created automatically for stack context data and by the application (as indicated in Section 3.1) for application data. Each record is identified by a unique 16-bit value which is assigned when the record is created - for application data, this identifier is user-defined.

The stack context data which is stored in Flash includes the following:

• Application layer data:

1. AIB members, such as the EPID and ZDO state
2. Group Address table
3. Binding table
4. Application key-pair descriptor
5. Trust Centre device table

• Network layer data:

1. NIB members, such as PAN ID and radio channel
2. Neighbor table
3. Network keys
4. Address Map table

On performing a KW41Z cold start or warm start without RAM held, the PDM must be initialized in the application as described in Section 2.

• If this is the first ever cold start, there will be no stack context data or application data preserved in the Flash.
• If it is a cold or warm start following previous use (such as after a reset), there should be stack context data and application data preserved in the Flash.

On start-up, the PDM builds a file system in RAM and scans the Flash for valid data. If any data is found, it is incorporated in the file system.

Saving and recovering application data in Flash are described in the subsections below.

3.1   Saving Data to Flash

      Application data and stack context data are saved from RAM to Flash as described below.

      Note: During a data save, if the Flash needs to be defragmented and purged, this will be performed automatically resulting in all records being re-saved.

    Application data

          You should save application data to Flash when important changes have been made to the data in RAM. Application data in RAM can be saved to an individual record           in Flash using the function PDM_eSaveRecordData(). A buffer of data in RAM is saved to a single record in Flash (a record may span multiple Flash sectors).

         The records are created when calling PDM_eInitialise(). These records are traced by a unique 16-bit identifier assigned by the application - this identifier is subsequently          used to reference the record. The value used must not clash with those used by the NXP libraries - the ZigBee PRO stack libraries use values above 0x8000.

         Subsequently, in performing a re-save to the same record (specified by its 16-bit identifier), the original Flash sectors associated with the record will be overwritten but          only the sector(s) containing data changes will be altered (if no data has changed, no write will be performed). This method of only making incremental saves improves          the occupancy level of the size-restricted Flash.

    Stack Context Data

         The NXP ZigBee PRO stack automatically saves its own context data from RAM to Flash when certain data items change. This data will not be encrypted.

3.2   Recovering Data from Flash

      Application data and stack context data are loaded from the Flash to RAM as described below.

    Application Data

            During a cold start or a warm start without memory held, once the PDM module has been initialized (see Section 2.2), PDM_eReadDataFromRecord() must be called             for each record of application data in Flash that needs to be copied to RAM.

    Stack Context Data

            The function PDM_eReadDataFromRecord(), described above, is not used for records of stack context data. Loading this data from the Flash to RAM is handled             automatically by the stack (provided that the PDM has been initialized).

3.3   Deleting Data in Flash

        All records (application data and stack context data) in the Flash can be deleted using the function PDM_vDeleteAllDataRecords().

         Caution: You are not recommended to delete records of ZigBee PRO stack context data by calling PDM_vDeleteAllDataRecords() before a rejoin of the same secured          network. If these records are deleted, data sent by the node after the rejoin will be rejected by the destination node since the frame counter has been reset on the source          node. For more information and advice, refer to the “Application Design Notes” appendix in the ZigBee 3.0 Stack User Guide.

4.    PDM Features

PDM offers a function that can be used to search for a specific record by using the 16-bit record ID. This function is called PDM_GetNVMTableEntry() and the required parameters are the record ID and an output pointer for the found entry.

Another available PDM feature is providing a mechanism to safely write the data to NVM. This is done by calling the function PDM_vCompletePendingOperations(), which calls the appropriate NVM function that is used to complete all writings to NVM before any other operation. As an example, user can use this function to make sure that the data is written to the NVM before a reset.