@mchp-mcc/16bit_data_eeprom_emulation v2.1.0

MCC Melody 16 Bit Data EEPROM Emulation

Emulating Data EEPROM for PIC24 Microcontrollers and dsPIC® Digital Signal Controllers

DATA EEPROM EMULATION INTRODUCTION

Microchip Technology Inc. has expanded its product portfolio to include a wide variety of cost-effective PIC® Microcontrollers (MCUs) without an internal data EEPROM.

Many applications store nonvolatile information in the Flash program memory using table read and write operations. Applications that need to frequently update this data may have greater endurance requirements than the specified Flash endurance for the MCU/Digital Signal Controller (DSC) devices.

The alternate solution of using an external, serial EEPROM device may not be appropriate for cost-sensitive or pin-constrained applications.

This document presents another alternative that addresses these issues. This algorithm features an interface similar to an internal data EEPROM, which uses available program memory and can effectively improve endurance typically by a factor as high as 500 or more.

Note: : To use this solution, the device must have word write or double-word write capability. Refer to the specific device data sheet to verify the availability of this feature.

Definition of Terms

Page – The minimum amount of program memory affected by an erase operation.

Row – The maximum amount of program memory that can be written in one attempt.

Bank - Bank is a logical entity that signifies a group of addresses. Each EEPROM bank can have a maximum of 255 addresses.

Erase/Write Cycle – The number of erase and write operation pairs.

Endurance – A specification indicating the maximum number of erase/write cycles and associated conditions.

Retention – A specification indicating the minimum time and associated conditions for the retention of data in Flash program memory.

Effective Endurance – The improved endurance of the emulated data EEPROM as a result of using an efficient programming algorithm.

Current (Active) Page – A page in program memory that is being written and read by the data EEPROM emulation algorithm.

Packed Page – The new current page after the pack routine (this routine is not exposed) is complete.

Page Status – Program memory locations at the beginning of the current page that store data EEPROM emulation status. The PIC24/PIC24/dsPIC33F/dsPIC33E devices use one location (address).

Maximum Data EE Size Per Bank - Maximum addresses per bank or Maximum addresses that can be stored in a flash page.

THEORY OF OPERATION

The algorithm in this application note supports selectable, multiple emulated data EEPROM banks with a total size of up to multiples of "Maximum Data EE Size" locations, with a single address space, ranging from 0 to the total size of the emulated data EEPROM’s minus one (see the below note).

For example, if the implemented size of the data EEPROM is five, and two data EEPROMs are used, only the addresses in the range, 0 to 9, are available.

Note: PIC24/dsPIC33F/dsPIC33E implementations support multiple EEPROM banks. Each EEPROM can have a maximum of 255 addresses(This is not always true , please check the value of Maximum Data EE Size Per Bank for the given device). Therefore, the total addresses are from 0 to N x 255 – 1, where N = the number of EEPROM banks.

PIC24/dsPIC33F/dsPIC33E DATA EEPROM INFORMATION FORMAT IN PROGRAM MEMORY

Table 1

USE CASE

To understand how the algorithm works, a simple case example for the PIC24/dsPIC33F/dsPIC33E devices is described in this section.

After the first page of each EEPROM bank is initialized, the first location is reserved for the page status information. This indicates whether a page is active or expired, and how many erase/write cycles have been performed. This information is not directly accessible by the user but is used by the algorithm to find the available pages and update status flags. After initialization, the first page is designated as the active page.

In this example, a write operation has been performed to store a data value of 0x0202 to data EEPROM address, 0x10. As provided in Table 2, this information is stored in the first available location in the page. As more writes are performed, the algorithm continues to write the information, similarly, as provided in Table 3 through Table 5.

In this example, the data EEPROM address 0x20 is written with 0x0707, 0x10 is updated to 0x2222 and address 0x30 is written with 0x0A0A.

In Table 6, the last location in the page is written with a rewrite to address 0x20 to 0x7777. The data EEPROM information will move to the next available page because the currently active page is full. This new page is referred to as the packed page. The pack routine performs this task. Since only the most current data for each data EEPROM address is needed, the amount of information decreases.

After the data is moved, this page is designated as the current page. If the current page has incremented through all allocated pages in program memory, the erase/write count is incremented as provided in Table 7. The page is now ready to store more information through write operations.

Table 2

Table 3

Table 4

Table 5

Table 6

Table 7

Only one erase/write cycle is consumed for the page as each location within the page is programmed once prior to the page erase. As a result, the algorithm multiplicatively improves the emulated data EEPROM's effective endurance.

The previously filled page is erased only after the latest information has been programmed into the next available page and successfully verified. Through this process, the information is always stored in nonvolatile memory, which minimizes the effects of an unexpected loss of power.

As the program memory page is filled sequentially from beginning to end, the algorithm assumes the most current data EEPROM information is the closest instance to the end of the page. To simplify the read operation, the search begins at the end of the current program memory page and works toward the start of the page – looking for the specified data EEPROM address.

When a match is found, the associated data is returned for the first instance of the provided address. If the address is not found, the return value of all ones, 0xFF or 0xFFFF, is returned to emulate the result of an unwritten address in an independent data EEPROM.

PIC24/dsPIC33F/dsPIC33E Emulation Checklist

Following are the configuration users were required to make for generating the Data EEPROM Emulation algorithm/code for the PIC24/dsPIC33F/dsPIC33E devices without using the 16 Bit Data EEPROM EMULATION Module.

1. Specify the number of EEPROM banks required in DATA_EE_BANKS; the maximum number is limited by the device memory.

2. Specify the amount of data EEPROM needed for each bank in DATA_EE_SIZE. The maximum is 255 (0xFE). A compile-time error will generate if the data EEPROM size exceeds 255.

3. Specify the number of program memory pages in NUM_DATA_EE_PAGES. The minimum is two pages. A compile-time error will generate if fewer than two pages are defined.

4. Verify the ERASE, PROGRAM_ROW and PROGRAM_WORD opcode values.

5. Specify the page erase size (in instructions) in NUMBER_OF_INSTRUCTIONS_IN_PAGE. Refer to the specific device data sheet to verify the page erase size for the device.

6. Specify the maximum programming size (in instructions) in NUMBER_OF_INSTRUCTIONS_IN_ROW (128 for the dsPIC33E/PIC24E devices and 64 for other device families).

7. Select the maximum erase/write cycle count in ERASE_WRITE_CYCLE_MAX. The maximum is 65,535. A compile-time error will generate if the limit is exceeded.

8. In all dsPIC33E and PIC24F devices containing the Flash ECC feature (check the specific device data sheet to find out if ECC is present), uncomment the following line in the include file, “DEE Emulation 16-bit.h”: #define __HAS_ECC.

9. For the dsPIC33E/PIC24E devices, comment or uncomment the _AUXFLASH preprocessor definition for using the primary Flash program memory or auxiliary Flash program memory, respectively.

10. Add a function call to DataEEInit prior to any other operation to emulated data EEPROM.

11. Add the data emulation algorithm source files to your project

16 BIT DATA EEPROM EMULATION MCC MODULE

The 16-bit Data EEPROM emulation MCC module provides a simple GUI for the user to configure the EEPROM emulation algorithm and generates the code for the Data EEPROM emulation.

This module avoids the users from making the above configuration manually, instead users have to provide 2 parameters i.e. the numbers 16-bit data EEPROM data users want to store and the required endurance for their application/data.

Based on the users input all the required parameters which are mentioned in the previous section are automatically calculated by the module.

In devices with dual partition support , users are provided an option to choose whether they want the DEE library to copy the DEE data from active partition to inactive partition in case of an execution switch. Execution switch can happen if there exists a new version of the application/firmware (using live update functionality provided by the bootloader) in the inactive panel and if there is a requirement to copy DEE data from the previous execution of the application so that the previous data is not lost.

Note: Application by default uses the highest flash memory area excluding the configuration settings area for the emulated structure. If the uses want to provide the start address for the emulated data structure they can do so by disabling the Use Highest Flash Memory Area for Emulated EEPROM Data Structure button.

This module also provides the following useful information to the users

1. Calculated Total Effective endurance: The achieved endurance is not exactly same as the requested endurance, the algorithm will always achieve the requested endurance. This parameter provides the actual endurance achieved using this algorithm.

   Calculated Total Effective endurance = (Page Size – Page Status Size – Maximum Data EE Size Per Bank) x Number of Pages Flash Pages Per EEPROM Bank x Requested Total Effective Endurance.

   If the device has ECC, the hardware has one ECC per two instruction words, but DEE operate at a single instruction word level. So for devices with ECC, DEE uses every other instruction word only, So Page size should be half.

   Page Status Size is 1(size of the status info).

2. Maximum Data EE Size Per Bank: This is the maximum EE data that can be stored in a bank i.e. this will decide the number of EE addresses per flash page. The maximum value is 255.

3. Maximum number of 16-bit EEPROM Data user can store: The memory allocated in terms of banks, so the actual memory allocation always would be multiple of Maximum Data EE Size Per Bank. If the user wants to store 255, then if the value of Maximum Data EE Size Per Bank is 255 then only one bank will be allocated and maximum number of 16-bit EEPROM data users can store would be 255. If the user wants to store 256 16-bit data elements then, 2 banks are needed and maximum number of 16-bit EEPROM data users can store would be 510.

4) Number of EEPROM Banks: This tells the number of EEPROM banks required to store the user data. EEPROM data bank is a logical entity. The maximum size of a bank is 255 i.e. in a flash page maximum of 255 addresses and their data will be stored.

5. Number of Flash Pages per bank: This tells the number of flash pages allocated per bank to achieve the required endurance.

6. Minimum Flash Cell Endurance: This is the minimum endurance of the flash cell in the given device.

7. End Flash Address of Emulated EEPROM data structure: This is the end address of the emulated data structure.

8. Flash Size of Emulated EEPROM data structure (Instruction words): This gives the actual size in Instruction Words occupied by the emulated data structure in the flash. 1 Instruction word = 3 Bytes.

16 BIT DATA EEPROM Emulation Interface Functions:

INITIALIZATION OPERATION(DEE_Init()):

The initialization routine, DEE_Init(), must be called before any other data EEPROM operation can occur. This initializes all of the EEPROM banks. If the routine determines that program memory has not been initialized for emulation, it will find the first allocated page of program memory and initialize its status information. Thereafter, the read and write functions may be called as needed.

The routine may also determine whether data EEPROM emulation is already underway. If so, one of three scenarios may occur:

• If only one active page is found, the routine assumes a Reset occurred. No action is taken and the routine exits normally. Any read/write operation that may have been active during the Reset should be repeated.

• If two active pages are found, the routine assumes that an unexpected Reset occurred during a pack operation. The routine will erase the newest active page and call the pack routine to permit the refresh to complete.

• If more than two active pages are found, the routine assumes program memory has been corrupted by the application code and sets the pageCorrupt flag(Status Flags).

It is important to monitor the page status bits, as well as the RCON and NVMCON (PIC24/dsPIC33F/dsPIC33E), the application can respond appropriately to Resets and supply voltage changes.

READ OPERATION(DEE_Read()):

The DEE_Read() function is used to retrieve data EEPROM information. It returns the data associated with the data EEPROM address. If the provided address is equal to or greater than the amount of defined data EEPROM, the illegalAddress flag(Status Flags) is set and a value of all ‘1’s is returned. This return value mimics the response of dedicated data EEPROM, where an unwritten address returns an erased value.

The routine then searches for the active page in the EEPROM bank corresponding to the address. Once located, the active page is searched for an address match, starting from the last location in the page. For details on how data EEPROM information is stored in program memory, refer to Table 1.

If an active page is not found, the pageCorrupt flag(Status Flags) is set. A flowchart of the read operation is illustrated in the following figure.

WRITE OPERATION(DEE_Write()):

To write emulated data EEPROM, the application uses the DEE_Write() function. Like the read function, it verifies that the data EEPROM address is between 0 and one less than the size of the emulated data EEPROM. If an unimplemented address is supplied, the illegalAddress flag(Status Flags) is set and write operation is aborted.

The routine then searches for the active page of the EEPROM bank corresponding to the address. After the active page is located, a read operation is performed. To minimize the number of erase/write cycles, the value is programmed only if it has changed.

If an active page is not found, the pageCorrupt flag is set and a non-zero value is returned.

A forward search of the active page returns the offset for the next available address. If the next available address is equal to, or greater than, the last address in the page, the packSkipped flag is set and the write operation is aborted. Otherwise, the data EEPROM information is written to the next available address in the page.

If the information does not verify, the writeError flag(Status Flags) is set and a non-zero value is returned. The user can attempt to rewrite the data or respond as needed.

The algorithm is designed to maintain at least one available location in the active page for the next write operation. After a successful verification of the write operation, the pack routine is called if no available locations remain.

After the routine completes successfully, a zero value is returned.

A flowchart of the write operation is illustrated in following Figure.

PERFORMANCE:

Effective Endurnace

Determining effective endurance is not a trivial calculation because it is dependent on many factors. Traditionally, endurance is defined as the number of times a single address can be safely written. This definition does not apply to emulated data EEPROM for a few different reasons.

First, writing a data EEPROM address five times does not mean five erase/write cycles of endurance were consumed. From the perspective of the program memory, five writes were made to five different program memory addresses. These five writes will not cost any additional endurance cycles until the page is filled and the pack routine is called.

Second, calculating effective endurance is more than simply multiplying program memory page size and the size of the emulated data EEPROM. The entire page is not available for emulation. The page status information is stored in the beginning of the page, which is either one location of program memory for the 16-bit algorithm or two for 8-bit. In addition, more locations will be consumed after the pack routine depending on how many data EEPROM addresses were written. As a result, writing an address once has a significant impact to endurance because one less location is available after the array is packed.

Based on the discussion to this point, a simplified equation (see equation1) can be made for total effective endurance. For more information on the terms, refer to “Definition of Terms”.

Working through an example for the PIC24FJ128GA010, this device has a 512-word page. The 16-bit algorithm reserves one location for page status.

equation 2 provides the formula for calculating two pages of program memory, 10 locations of emulated data EEPROM and the typical endurance limit.

An average effective endurance can be calculated by dividing the total effective endurance by the size of the emulated data EEPROM bank, but this does not tell the whole story. It assumes that every data EEPROM address is updated at the same rate. In most applications, this is not true. Some data, such as calibration data or user information, may be rarely updated, while sensor information can be written more frequently. Addresses written more often will consume a greater amount of program memory endurance. Therefore, how writes are distributed across the data EEPROM addresses significantly affects effective endurance. Ratios could be assigned to each address to create a more accurate calculation, but this is still only an approximation. It is difficult to predict how often each address will be written during an application’s lifetime.

EQUATION 1: EFFECTIVE ENDURANCE

Calculated Total Effective endurance = (Page Size – Page Status Size – Maximum Data EE Size Per Bank) x Number of Pages Flash Pages Per EEPROM Bank x Requested Total Effective Endurance.

EQUATION 2: EFFECTIVE ENDURANCE CALCULATION EXAMPLE

Calculated Total Effective endurance = (512 – 1 – 10) x 2 x 1000 = 1002000 Cycles

Note: In devices with ECC , the flash page size to be used for calculation should be (flash page size /2) because the hardware has one ECC per two instruction words, but DEE operate at a single instruction word level. So for devices with ECC, DEE uses every other instruction word only.

STATUS FLAGS:

flags have been provided to indicate whether an error or warning condition occurs during the emulation process. These indicators are accessed in the Data EEPROM Flags register; all flags are active-high. The status bits and return values are defined as follows:

• addrNotFound(0xFF/0xFFFF) – A read operation occurred on a previously unwritten data EEPROM address.

• expiredPage(0x1) – The program memory erase/write cycle count has exceeded the user-defined limit. The algorithm will attempt to execute the write operation.

• packBeforePageFull(0x2) – The pack routine was called before the currently active page was full. The routine will attempt to move the latest data EEPROM information to the packed page, even though the active page is not full.

• packBeforeInit(0x3) – The pack routine was executed before the initialization routine. The pack operation was aborted.

• packSkipped(0x4) – A page was written beyond the page boundary. This may be a result of the pack routine not being executed properly. The pack operation was aborted.

• illegalAddress(0x5) – There was an attempt to write/read with a data EEPROM address equal to or greater than the size of data EEPROM. The read/write operation was aborted.

• pageCorrupt(0x6) – The page status information was corrupted. The current operation was aborted. • writeError(0x7) – The information that was written into program memory failed the verification. The current operation was aborted.

The status flags differ in severity and how they are serviced. The informational status flags are expected to occur during normal processing and are serviced by simply clearing the flag with the associated macro. These include: addrNotFound, packBeforePageFull and illegalAddress flags.

Warning status flags indicate a condition has been exceeded but processing will continue. This includes the expiredPage status flag. With this flag set, the algorithm will attempt to process read and write requests, but the flag will be set after each operation.

The most severe flags are the system error status flags. These imply either the integrity of the data EEPROM information has been compromised and/or the algorithm cannot continue until the offending condition has been resolved. These include packBeforeInit, pageCorrupt and writeError flags.

To avoid a packBeforeInit event, ensure the initialization routine, DEE_Init, is called before performing any other emulation routine. Since this routine accesses the current state of the emulation process, it will take action only if it is required. Therefore, it can be called at any time during data EEPROM emulation.

The pageCorrupt and writeError flags indicate that a write operation failed to verify and the current operation was aborted. If this occurs, the integrity of the data EEPROM information has been compromised. No further emulation operations should be attempted. The memory reserved for data EEPROM emulation and attempt to reinitialize them.

Macros are available to retrieve and clear the status flag values. Status flags are cleared only by the user. No operation is affected by the value of any flag, but the flag’s value will indicate.

DUAL PANEL OPERATION

In devices with dual flash partitions there can be execution switches . Execution switch can happen if there is a new version of the firmware available on the inactive partition through the live update feature. Through execution switch the new version of the application in the inactive partition can be executed , this makes the inactive partition active and active partition inactive.

In devices with dual panel support DEE Library uses the inactive partition to store the DEE data structure. The advantage of using the inactive partition to store DEE data structure is that there is no CPU stall during inactive flash panel programming, whereas the CPU stalls when programming the active flash panel. For better performances it is recommended to use inactive partition to store DEE data in devices with dual flash panel support.

In case of execution switch the DEE library first copies the data from the active partition(which was previously inactive partition) to the inactive partition(which was previously active partition) so that the data from the previous iteration is not lost.

INITIALIZATION OPERATION(DEE_Init()) in DUAL PANEL DEVICES:

If the “Copy DEE Data to Inactive partition after execution switch” check box is checked in the UI of the 16-Bit Data EEPROM Emulation module , then the initialization operation i.e. DEE_Init() has slight variation compared to DEE_Init() operation explained here.

DEE_Init() function first performs the DEE Page initialization in the active partition. It checks whether there is any data in active partition from the previous iteration , if the data is available then it copies the data from active to inactive partition. If there is no data available then it performs the DEE Page initialization in the inactive partition.

A flowchart of the Dual Panel DEE_Init() operation is illustrated in following Figure.

For details about DEE Pages initialization please refer DEE_Init().

DUAL PANEL PROJECT CONFIGURATION

Please follow the following steps to configure the dual panel projects,

1. Set the BTMODE configuration bit to “DUAL” in the configuration bits module.
2. Set MPLAB Project properties ->XC16(Global Options) ->Partition to “Partition One/Active” for the primary project(active partition project).
3. Set MPLAB Project properties ->XC16(Global Options)->Partition to “Partition Two/Inactive” for the secondary project(inactive partition project, to be attached as loadable in the primary project).
4. ConfigureBSEQ and IBSEQ for both the projects. The panel with lower value of BSEQ will become active partition after any reset. For example for BSEQ=0x002 and IBSEQ = 0xFFD for Primary Project(project which configured as Partition One/Active) and BSEQ=0x001 and IBSEQ = 0xFFE for Secondary project(project which is configured as Partition Two/Inactive). After flashing the code to the device Primary Project will be executed . In case of any reset Secondary Project(project in inactive partition) will be executed, and inactive partition becomes active and active partition becomes inactive.
5. Set MPLAB Project properties->Programmer Selected(PKOB or PICkit or ICD or any)->Secure Segment->Segments to be Programmed to “Boot, General and Config Segments”.

POWER FAILURE/RESET SCENARIOS

1. What if there is power failure during DEE Initialization: If there are no active pages , DEE_Init() routine will continue to initialize DEE pages , if there is only one active page, then routine exits normally assuming there was a reset during DEE_Init() or DEE_Write(). No user data will be lost.

2. What if there is power failure during DEE Write: If the write is completed before the power failure then there is no problem , if not the last data will be lost.

3. What if there is power failure during Pack operation: If there is a reset during pack operation , the DEE_Init() routine will find 2 active pages during initialization and the DEE_Init() routine will erase the newer active page and call the pack operation on first page. Also page status is written after writing all the data. If there is a power reset before writing the page status pack operation will be performed in the next iteration during DEE_Init(). No user data will be lost.

4. What if there is power failure during copying data from active partition to inactive partition: The source data i.e. DEE data in the active partition is deleted only after all the data is copied from the active partition to the inactive partition. In case of power failure during copying , the data copy procedure is re-executed as long as there is data in the active partition. Each page data is copied first then the page status is copied and this makes sure that data is not lost.

Limitations

Algorithm uses the PSV area for the data , size of the PSV area is limited to 32KB. So the size of the Emulated Data Structure can not exceed th PSV window.

Changelog

All notable changes to this project will be documented in this file.

2.1.0 - 2023-09-29

New Features

• CC16SCRIP-1296 :- Dual Panel 16 Bit Data EEPROM Emulation Support

2.0.2 - 2022-09-05

Bug Fixes

• CC16SCRIP-5229 :- Make DEE Library compatible with latest content manager

2.0.1 - 2022-03-15

Bug Fixes

• CC16SCRIP-4011 :- All the UI elements are disabled and users are not able to make any configuration changes

2.0.0 - 2021-12-21

New Features

• CC16SCRIP-1634 :- Update FLASH API interfaces to be compatible with 8Bit devices