Using Virtual EEPROM and Flash API for Renesas MCUs RX600 Series

Using Virtual EEPROM and Flash API for Renesas MCUs RX600 Series Description: This lab will take the user through using the Virtual EEPROM (VEE) project for RX. The user will learn to use the Virtual EEPROM API and how to configure the Virtual EEPROM project to be most efficient for their system. Lab Objectives 1. Learn to add Virtual EEPROM to a project 2. Learn to use Virtual EEPROM API 3. Learn to configure Virtual EEPROM Lab Materials Please verify you have the following materials at your lab station. RDKRX63N E2Studio Renesas RX Toolchain Skill Level 1. Programming in C Time to Complete Lab 50 Minutes Lab Sections 1 Adding VEE to your Project... 2 2 Using the Virtual EEPROM... 12 3 Configuring the Virtual EEPROM... 18 Using SW Building Blocks Page 1 of 23

1 Adding VEE to your Project LAB PROCEDURE Overview: This section will go over adding the VEE code to an existing project. The main() function in this project will test the VEE API to make sure that the VEE is properly installed and configured. Procedural Steps Step 1.1 Step 1.2 Step 1.3 Open up E2Studio. If the Workspace Launcher window pops up, select C:\Workspace\cl08i_virtual_eeprom_lab for the Workspace and hit OK. If this window did not pop up then click File >> Switch Workspace >> Other. In the window that pops up select C:\Workspace\cl08i_virtual_eeprom_lab for the Workspace and hit OK. In the Project Explorer pane, look for a project named virtual_eeprom_section_1. If you do not see this project then move on to the next step. If you do see this project then delete it by right clicking on the project folder and clicking delete. In the Delete Resources window that pops up make sure to click the Delete project contents on disk checkbox and click OK. Step 1.4 Step 1.5 Click File >> Import. Choose General >> Existing Projects into Workspace. Click Next. Using SW Building Blocks Page 2 of 23

Step 1.6 Step 1.7 Check the Select archive file: button and then click Browse. Browse to C:\Workspace\cl08i_virtual_eeprom_lab\sections\ and choose virtual_eeprom_section_1.zip. Click Open. Step 1.8 Step 1.9 Make sure the box next to virtual_eeprom_section_1 is checked in the Projects box. Click Finish. You should now have a project in the Project Explorer pane named virtual_eeprom_section_1. Step 1.10 Expand the project and verify that you have folders named src, r_bsp, r_glyph, and r_rspi_rx. This project has only the board support package code needed to initialize the RDKRX63N and a main() that tests the Virtual EEPROM. Using SW Building Blocks Page 3 of 23

Step 1.11 We will now add the Virtual EEPROM code to our existing project. To do this we are going to use the FIT E2Studio plug-in. Click File >> New >> Renesas FIT Module. The FIT E2Studio plug-in should pop up. Step 1.12 We are going to add the r_vee module to our code so choose it in the module list. You will need to scroll down the list to find the module. After clicking on the r_vee module note the dependencies that are shown in the Details box. The first dependency is the r_bsp package which was already installed when we imported this project. The r_flash_api_rx600 package has not been added yet. We will see how this is handled in the upcoming steps. Using SW Building Blocks Page 4 of 23

Step 1.13 Make sure that the Project adding to drop down has virtual_eerprom_section_1 selected. Verify that your window looks like the one shown below and click Finish. Step 1.14 A Module Information window should pop up indicating the r_vee package requires the r_bsp package which already appears to be installed. Click OK. Using SW Building Blocks Page 5 of 23

Step 1.15 A Module Warning window should pop up informing you that the r_vee package also depends on the r_flash_api_rx600 package which does not appear to be installed. The plug-in offers to automatically install the plug-in for you. Click Yes to have the module installed. Step 1.16 The plug-in will alert you that the Source Location and Include paths have been updated. Click OK. Step 1.17 The plug-in will now open the properties window for the selected project. Click the Apply button. Step 1.18 Navigate to the Source Location tab underneath C/C++ General >> Paths and Symbols and verify that the r_vee and r_flash_api_rx600 folders are in the list. Using SW Building Blocks Page 6 of 23

Step 1.19 Navigate to the C/C++ Build >> Settings >> Tool Settings >> Compiler >> Source window and verify that the r_vee and r_flash_api_rx600 include directories were added. Click OK to close the window. The FIT E2Studio plug-in added the Virtual EEPROM and Flash API code to the project by copying over the code and setting up the source locations and includes paths. The user could do the same thing manually if they wanted. If you wish to do this manually for a FIT module (which the r_vee and r_flash_api_rx600 modules are) then you should follow the directions under the How to add to your project section in the readme.txt file that comes with every FIT module. Step 1.20 Verify that the virtual_eeprom_section_1 project now contains the r_vee and r_flash_api_rx600 folders. The Virtual EEPROM code contains a port directory that holds ports for various MCUs. When adding a Source Location in E2Studio it compiles all of the C source files in that folder and all of its subdirectories. This means that by default E2Studio will try to build all of the port folders at once. Since they contain the same functions, this will cause duplication errors. To fix this we need to either delete the unused port folders or exclude them from the build. Using SW Building Blocks Page 7 of 23

Step 1.21 Expand the r_vee >> src >> ports folder. Right click on the rx62x directory and click Delete. If an E2Studio window pops up, click OK to confirm the deletion. The default configuration of the Flash API enables ROM operations and disables data flash background operations (BGO). The Virtual EEPROM project requires the use of data flash BGO so we need to enable it. Step 1.22 We now need to configure the Flash API and Virtual EEPROM modules to work with the game. Expand the r_flash_api_rx600 folder and open the file r_flash_api_rx600_config.h. Step 1.23 Disable ROM operations by commenting out the ENABLE_ROM_PROGRAMMING macro. //#define ENABLE_ROM_PROGRAMMING Step 1.24 Enable data flash background operations by uncommenting the DATA_FLASH_BGO macro. #define DATA_FLASH_BGO Step 1.25 Save the file and close it. Step 1.26 Select the virtual_eeprom_section_1 folder in the Project Explorer pane and build the project by clicking Project >> Build Project (or click the Build icon out then you did not select the project folder first. ). If Build Project is grayed Step 1.27 Verify that you get the message Build Complete at the bottom of the Console pane. Using SW Building Blocks Page 8 of 23

Step 1.28 We are now ready to debug the project. Make sure that the RDKRX63N is connected to your PC using the included USB cable. Make sure that you use the USB port on the RDKRX63N labeled J-Link which is right beside the DB9 connector. Step 1.29 Select the virtual_eeprom_section_1 folder in the Project Explorer and start debugging by clicking Run >> Debug As >> Renesas GDB Hardware Launch. Step 1.30 If you are asked to select the Debug Hardware then choose Segger JLink and click OK. Step 1.31 If asked to choose a target device choose the R5F563NB and click OK. Using SW Building Blocks Page 9 of 23

Step 1.32 E2Studio by default will ask you to switch your perspective when you start debugging. This different layout makes debugging easier. Click Yes. Step 1.33 Once the perspective has been changed you can start running the application by either clicking the Resume button or clicking Run >> Resume. Step 1.34 If execution stops at the beginning of the main() function click Resume again to continue. Step 1.35 Verify that the LCD shows VEE Demo Success!. Step 1.36 Click Run >> Suspend or use the Suspend button to stop MCU execution. Verify that the MCU is executing the while(1) loop at the end of the main() function. Step 1.37 Stop debugging by clicking the Terminate button or clicking Run >> Terminate. By seeing the message on the LCD we know that the VEE is correctly configured and working. The main() function in this project tests the VEE by using all of the VEE API functions. If the message is displayed then that means all of the VEE API tests were passed. Using SW Building Blocks Page 10 of 23

Step 1.38 Switch back to C/C++ perspective by clicking Window >> Open Perspective >> Other. In the window that pops up choose C/C++ and click OK. You can change perspectives quickly using the icons at the top right of the E2Studio window. End of Section Using SW Building Blocks Page 11 of 23

2 Using the Virtual EEPROM LAB PROCEDURE Overview: In the last section we successfully added the Virtual EEPROM and Flash API code to our project. We are now going to learn to use the Virtual EEPROM API functions. The project that is used in this section implements a game on the RDK board. Currently the game stores the high scores in RAM. This means that whenever the MCU loses power or is reset, the scores are lost. We are going to use the Virtual EEPROM to save the high scores in non-volatile data flash. Procedural Steps This first step imports a game that stores high scores in RAM. We are going to modify this project to store the data using the Virtual EEPROM project. Step 2.1 Step 2.2 Step 2.3 Follow the same process as shown in Step 1.1 through Step 1.9 to add the project virtual_eeprom_section_2 to your E2Studio workspace. Expand the r_game_spaceship >> src folder in the Project Explorer pane and open the file r_game_spaceship_data.c. The first thing we will do is add a #include for the Virtual EEPROM s interface file r_vee_if.h. Find the following location in the source file (should be line #42) and uncomment the #include. /* VEE API functions. */ #include r_vee_if.h By including the file r_vee_if.h we now have access to all Virtual EEPROM s public API functions, typedefs, and macros. Step 2.4 Step 2.5 We will now work on reading a record from the Virtual EEPROM. Scroll down to the gss_data_read() function (line #68). In order to read from, or write to, the Virtual EEPROM we first need to have a vee_record_t variable. Inside of the gss_data_read() function uncomment the line of code that declares the variable rec. /* Used for VEE reading. */ vee_record_t rec; Step 2.6 Now that we have a record to use, we need to set the record ID that we are looking for. Uncomment the line of code that sets the record s ID to the ranking on the high score list. /* Set VEE record info. */ rec.id = score_number; Using SW Building Blocks Page 12 of 23

When attempting to read a Virtual EEPROM record, the ID is only field that needs to be written by the user. The R_VEE_Read() function will fill in the rest of the structure members if the record is found. Step 2.7 We can now attempt to read the record from the Virtual EEPROM. Uncomment the line of code that calls R_VEE_Read(). /* Attempt to read record. */ if (VEE_SUCCESS == R_VEE_Read(&rec)) Note that we are checking for R_VEE_Read() to return VEE_SUCCESS. If this is returned, then the record was found and the record s structure members have been filled in. The user can use this information to read the record s data and information. If anything else is returned, then the record was either not found or the Virtual EEPROM is busy with another operation. The user can add more code to check for other return values. Step 2.8 If a record was found then we want to copy the data to RAM location for safe use. Uncomment the line of code that copies the score to RAM. /* Record found fill in score. */ memcpy(score, rec.pdata, sizeof(score_t)); In some cases it is best to copy the data from the data flash into RAM. This should be done when there is a chance that the data might be read at the same time as a Virtual EEPROM write. If the user attempts to read the data flash while another data flash operation is on-going (write or erase) then a data flash error will occur. To prevent this from happening the Virtual EEPROM code provides the R_VEE_ReleaseState() function. After a successful read, subsequent data flash operations (other than read) will not be allowed until the R_VEE_ReleaseState() function is called. This could lead to delays in your system if one tasks holds on to the Virtual EEPROM state for too long. To get around the user can copy the data from data flash into a RAM variable. At this point the user can release the VEE state and continue to use the data that is now in RAM. Step 2.9 Now that we have copied the data over for local use we can release our hold on the VEE state. Uncomment the line of code that calls R_VEE_ReleaseState(). /* Release hold on VEE. */ R_VEE_ReleaseState(); Using SW Building Blocks Page 13 of 23

The reading portion of the code is now successfully implemented. We can now move on to the writing portion. Each high score is written individually using its position on the list as its record ID. Step 2.10 Scroll down and locate the gss_data_write() function (line #109). Step 2.11 Verify that a vee_record_t type variable ( rec ) has already been declared and that the record s ID is being set. /* Used for VEE writing. */ vee_record_t rec; /* Set VEE record info. */ /* Set the record ID. */ rec.id = score_number; Earlier when we performed a VEE read we only had to fill in the record s ID. The VEE would then fill in the rest of the structure s members if the record was found. When writing, all the structure s members must be written (except for the block member which is used for internal purposes). Step 2.12 Set the size of the data in the record to be written by uncommenting the line of code that sets the record s size member. /* Set size of record. */ rec.size = sizeof(score_t); Step 2.13 In order to write the data the record needs a pointer to the data. Set the pdata structure member to the address of the high score structure by uncommenting the following line of code. /* Set pointer to data to write with record. */ rec.pdata = (uint8_t *)score; The Virtual EEPROM record structure has a member named check which is used to validate VEE records. By default the VEE code just sets this member to a constant value which is checked by the VEE code when performing a read. If the member does not match the constant value, then the VEE knows that the record was not successfully written. Since the check member is the last part of the VEE record that is written, if it was written successfully, then the rest of the record was also written successfully. Users can substitute their own checking mechanism (e.g. use CRC) if they wish. Using SW Building Blocks Page 14 of 23

Step 2.14 Set the check member of the record structure by calling the R_VEE_GenerateCheck() function. /* Generate check code for record. */ R_VEE_GenerateCheck(&rec); The Virtual EEPROM uses the background operations feature of the Flash API. The benefit of this is that it allows VEE operations to continue in the background without blocking the MCU. Since the operation continues in the background, there is a chance that the user s application will attempt to start another VEE operation in the foreground. The VEE protects against this and the new function calls will return VEE_BUSY if another VEE operation is already on-going. Because of this, it is good practice for the user s application to check and make sure the VEE is ready when trying to perform a VEE operation. Step 2.15 Uncomment the while() loop that checks to make sure any previous VEE operations have finished. while (R_VEE_GetState()!= VEE_READY) { /* Make sure VEE is finished with any previous writes. */ } After getting past the while() loop the record is ready to be written. All of the structure members have been written and the Virtual EEPROM is finished with any previous operations. Even at this point the write may not go through. There are a couple of reasons this could happen. The first is that another process started a new VEE operation between the time that we checked the VEE state and issued a VEE write. This could be solved by having using a semaphore, or by looping on the return value of the R_VEE_Write() function. The other reason the write may not go through would be that an error was detected in the VEE. This would typically happen the first time a write is issued after a previous write was not successfully finished. For example, if a power down or MCU reset occurred during the writing of a previous record, then the VEE will have to recover the next time a write is issued. If this occurs then the R_VEE_Write() function will return VEE_BUSY and attempt to the fix the issue. After the issue is resolved the user can go about using the VEE as usual. Step 2.16 Attempt to write the new record by uncommenting the line of code that calls R_VEE_Write(). /* Write VEE record. */ if (VEE_SUCCESS == R_VEE_Write(&rec)) { ret = true; } Using SW Building Blocks Page 15 of 23

Step 2.17 Follow Step 1.26 through Step 1.34 to build the project and start debugging. LAB PROCEDURE Step 2.18 When you start the application the LCD screen on the RDKRX63N should cycle through 3 screens: a title screen with the last score at the bottom, an instructions screen, and a screen showing the high scores. Using SW Building Blocks Page 16 of 23

Step 2.19 Start the game by pressing SW1 on the RDKRX63N. You can then move the ship using the onboard potentiometer and shoot missiles by pressing SW2. Step 2.20 Try to get as far as you can in the game and get a high score. Step 2.21 After you have obtained a high score and input your initials stop debugging by clicking the Terminate button or clicking Run >> Terminate. Step 2.22 Unplug the USB cable from the RDK board to ensure that power has been completely removed. Step 2.23 Reconnect the RDK to your PC with the included USB cable and start the debugging session again. Verify that the previous high scores are still shown. Question 1. Why was the high score list (which is in RAM) still correct after cycling power? 2. Why did we have to have call R_VEE_ReleaseState() after calling R_VEE_Read()? 3. What does the VEE do if a VEE operation is already on-going and the user attempts to start a new VEE operation? 4. Does the VEE protect against the user accessing the data flash directly (without using a VEE function)? End of Section Using SW Building Blocks Page 17 of 23

3 Configuring the Virtual EEPROM LAB PROCEDURE Overview: Now that you know how to use the Virtual EEPROM API, we will look at configuring it to be more efficient for your system. The VEE consists of at least 1 VEE Sector. The more VEE Sectors you have, the smaller each one is. You can use multiple sectors to partition your data. For example, you could put small, oftenwritten data in one sector, and large, occasionally written data in another sector. This effectively eliminates the two records from interfering with each other by causing frequent defrags. In this section of the lab we will use the 3 different default configurations and see the impact they have. To test the changes we will be using a VEE time range simulator. Basically the user inputs the number of records they have, the size of each record, how often each record is written, and the time span they wish to simulate. The application then simulates this time span and writes the VEE records as they would be in reality; just in a much shorter time span. In the end, the number of erases that was required will be displayed on the LCD for each VEE Sector. In general, the lower the number of erased blocks, the better. Procedural Steps This first step imports a project with the VEE and time span simulator already installed. Step 3.1 Step 3.2 Follow the same process as shown in Step 1.1 through Step 1.9 to add the project virtual_eeprom_section_3 to your E2Studio workspace. Expand the r_vee folder in the Project Explorer pane and open the file r_vee_config.h. Step 3.3 Find the macro for VEE_NUM_SECTORS and verify that it is defined as 1. /* VEE API functions. */ #define VEE_NUM_SECTORS 1 Out-of-the-box the VEE is set to operate with 1 VEE Sector. With this configuration the one VEE Sector is the full size of the MCU s data flash and all of the records are stored in the same sector. To see all information about the different sector configurations reference the file r_vee_config_rx63x.h located at r_vee >> src >> ports >> rx63x. VEE Sector 0-32KB 16KB per VEE Block Records 0-7 1 VEE Sector Configuration Using SW Building Blocks Page 18 of 23

Step 3.4 Step 3.5 We will now look at the time span simulator and see the available user options. Open up src >> vee_time_lapse_sim_main.c. Scroll down the file and find the constant variables that define the time period that will be simulated. It should look like the code shown below. /* These constants set the length of the simulation. For example, for a * simulation of 20 days, 8 hours, 10 minutes, 30 * seconds you would use: * g_vee_sim_days = 20 * g_vee_sim_hours = 8 * g_vee_sim_minutes = 10 * g_vee_sim_seconds = 30 */ static const uint32_t g_vee_sim_days = 30; static const uint32_t g_vee_sim_hours = 0; static const uint32_t g_vee_sim_minutes = 0; static const uint32_t g_vee_sim_seconds = 0; By default the time span simulator is set to simulate 30 days worth of VEE activity. Question 5. Set the values below correctly to simulate 62 days, 14 hours, 28 minutes, and 42 seconds of VEE activity. g_vee_sim_days = g_vee_sim_hours = g_vee_sim_minutes = g_vee_sim_seconds = Step 3.6 Step 3.7 Verify that the application is set to simulate 30 days of VEE activity. Scroll down a little further and find the g_sim_recs array. Each entry in the g_sim_recs array defines a record s ID, its size, and how often it is written. The structure members are {ID, size, days, hours, minutes, seconds}. This means that an entry of {1, 1024, 3, 12, 4, 10} would correspond to record ID 1 with a size of 1024 bytes that is written every 3 days, 12 hours, 4 minutes, and 10 seconds. Question 6. For the entry in g_sim_recs with a record ID of 5 what is the size of the record in bytes and how often is it written? Using SW Building Blocks Page 19 of 23

Step 3.8 Step 3.9 Follow Step 1.26 through Step 1.34 to build the project and start debugging. The application should take around 30 seconds to run the simulation. When it is finished it will display the number of erases per sector on the LCD. Question 7. How many erases were required for 30 days of VEE operations with 1 VEE Sector? Note that you could record the number of defrags instead of erases. The problem with recording the number of defrags is that the number of blocks erased during a defrag depends upon the configuration of the VEE Sector. For example, one VEE Sector might require 2 blocks to be erased on a defrag while another might require 8. In this case the defrags should not be valued equally. Step 3.10 Go back to the VEE_NUM_SECTORS macro in r_vee_config.h and change its definition to 2. Save the file but do not close it. /* VEE API functions. */ #define VEE_NUM_SECTORS 2 VEE Sector 0-16KB 8KB per VEE Block Records 0-3 VEE Sector 1-16KB 8KB per VEE Block Records 4-7 2 VEE Sectors Configuration Step 3.11 Right-click on the virtual_eeprom_section_3 folder in the Project Explorer pane and click Clean Project. Using SW Building Blocks Page 20 of 23

Step 3.12 Build, debug, and let the simulation finish as was done before. Question 8. How many erases were required per sector for 30 days of VEE operations with 2 VEE Sectors? How many erases were required total? Step 3.13 Go back to the VEE_NUM_SECTORS macro in r_vee_config.h and change its definition to 3. Save the file. /* VEE API functions. */ #define VEE_NUM_SECTORS 3 VEE Sector 0-16KB 8KB per VEE Block Records 0-2 VEE Sector 1-12KB 6KB per VEE Block Records 3-5 3 VEE Sectors Configuration VEE Sector 2-4KB 2KB per VEE Block Records 6 & 7 Step 3.14 Clean the project as shown in Step 3.10. Step 3.15 Build, debug, and let the simulation finish as before. Question 9. How many erases were required per sector for 30 days of VEE operations with 3 VEE Sectors? How many erases were required total? 10. Which sector configuration was most efficient in terms of erases required? Will this configuration always be the most efficient? As was mentioned earlier, all of these configurations are defined in the header file r_vee_config_rx63x.h which can be found under r_vee >> src >> ports >> rx63x. The configurations that were shown were the defaults but are expected to be modified by the user. End of Section Using SW Building Blocks Page 21 of 23

Question Answers Question (& Answers) 1. Why was the high score list (which is in RAM) still correct after cycling power? Because it was stored in non-volatile data flash using the Virtual EEPROM. 2. Why did we have to have call R_VEE_ReleaseState() after calling R_VEE_Read()? Because when a record is read from the VEE its data is still in data flash. The VEE cannot prevent the user from attempting to access this data at any point. If another data flash operation (i.e. VEE operation) is on-going and the user attempts to read this data then a data flash access violation will occur. To prevent this, the VEE requires the user to call the R_VEE_ReleaseState() function which tells the VEE that the user is done using the data that was read previously and it is safe to execute new VEE operations. 3. What does the VEE do if a VEE operation is already on-going and the user attempts to start a new VEE operation? The VEE will return VEE_BUSY and ignore the request. 4. Does the VEE protect against the user accessing the data flash directly (without using a VEE function)? No. This is why the R_VEE_ReleaseState() function exists and why we recommend that you reserve the entire data flash for VEE operations. The user can split up the data flash if they desire, but they will need to provide safeguards to make sure that their data flash operations do not interfere with VEE operations. Question 5. Set the values below correctly to simulate 62 days, 14 hours, 28 minutes, and 42 seconds of VEE activity. g_vee_sim_days = 62; g_vee_sim_hours = 14; g_vee_sim_minutes = 28; g_vee_sim_seconds = 42; Using SW Building Blocks Page 22 of 23

Question 6. For the entry in g_sim_recs with a record ID of 5 what is the size of the record in bytes and how often is it written? Size = 32 bytes Written every 3 days Question 7. How many erases were required for 30 days of VEE operations with 1 VEE Sector? 40 erases Question 8. How many erases were required per sector for 30 days of VEE operations with 2 VEE Sectors? How many erases were required total? Sector 0 = 12 erases Sector 1 = 24 erases Total = 36 erases Question 9. How many erases were required per sector for 30 days of VEE operations with 3 VEE Sectors? How many erases were required total? Sector 0 = 8 erases Sector 1 = 9 erases Sector 2 = 15 erases Total = 32 erases 10. Which sector configuration was most efficient in terms of erases required? Will this configuration always be the most efficient? Using 3 VEE Sectors was most efficient with these record configurations. This configuration will not always be the most efficient; it depends upon the number records, how big the records are, and how often they are written. Using SW Building Blocks Page 23 of 23