LAB PROCEDURE
Implementing Bootloaders on Renesas MCUs
RX600 Series
Description: This lab will take the user through using two different implementations of the Flash
Loader framework. The first will be the default implementation where firmware images are downloaded
from a host PC and stored in an external SPI flash. The second implementation will obtain firmware
images from a SD card inserted by the user.
Lab Objectives
1. Learn to use the Flash Loader framework
2. Learn to use the Host side tools
3. Learn how to modify the Flash Loader to
meet your specific needs.
Skill Level
1. Programming in C
Lab Materials
Please verify you have the following materials at
your lab station.
• RDKRX63N
• E2Studio
• USB to RS232 Adapter
• RS232 cable [Optional]
• Renesas RX Toolchain
Time to Complete Lab
60 Minutes
Lab Sections
1
2
3
4
Programming Default Bootloader .......................................................... 2
Using the Default Flash Loader Implementation .................................... 6
Updating Firmware While User App is Running ................................... 18
SD Card Flash Loader Implementation ............................................... 21
Using SW Building Blocks
Page 1 of 26
LAB PROCEDURE
1 Programming Default Bootloader
Overview:
This section will go over programming the default Flash Loader implementation’s bootloader into the User
Boot Area on the RDKRX63N.
Procedural Steps
Step 1.1
Open up E2Studio.
Step 1.2
If the ‘Workspace Launcher’ window pops up, select C:\Workspace\cl09i_flash_loader 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\cl09i_flash_loader for the Workspace
and hit OK.
Step 1.3
In the ‘Project Explorer’ pane, look for a project named ‘fl_default_bootloader’. Right click on
the folder and choose ‘Build Project’.
Step 1.4
Verify that at the end of the build you see ‘Build complete’ at the bottom of the Console pane.
Step 1.5
Plug in the USB-to-RS232 adapter into your PC. Connect the supplied serial cable between
the adapter and the RDK board.
The default Flash Loader implementation uses asynchronous serial for
communications. In order to use our host-side tools, we need to know which
COM port has been assigned to our USB to RS232 adapter. In this lab we will
assign the adapter to a high COM port that should be available.
Step 1.6
Click Run >> External Tools >> device_manager.
Using SW Building Blocks
Page 2 of 26
LAB PROCEDURE
Step 1.7
The Device Manager window should pop up. Expand the ‘Ports (COM & LPT)’ entry.
Step 1.8
Find the entry for your USB-to-RS232 adapter.
Step 1.9
Right click on the USB-to-RS232 adapter entry and select ‘Properties’.
Step 1.10 In the window that pops up select the ‘Port Settings’ tab.
Step 1.11 Click ‘Advanced’.
Using SW Building Blocks
Page 3 of 26
LAB PROCEDURE
Step 1.12 In the window that pops up change the ‘COM Port Number’ drop down to ‘COM10’. Click OK.
Step 1.13 Click OK and then click File >> Exit to close the Device Manager.
Step 1.14 Make sure that the shunt on JP13 (‘J-Link Disable’) covers both pins (shorted).
Step 1.15 To make sure that the J-Link is disabled cycle power by disconnecting the USB cable from the
RDK board and then reconnecting it. Make sure that you use the USB port labeled ‘J-Link’
which is right beside the DB9 connector. NOTE: The Reset switch will not work for this.
Step 1.16 On SW5 on the RDK board choose the following settings to put the MCU in Boot Mode:
Using SW Building Blocks
Page 4 of 26
LAB PROCEDURE
Step 1.17 Click the Reset switch on the board to reset the MCU into Boot Mode.
Now that the MCU is in Boot Mode and we have our COM port setup
correctly we will use FDT to program the User Boot Area with the default Flash
Loader bootloader. This lab uses the scripting capability of FDT which means
the user will only have to start the process.
Step 1.18 Click Run >> External Tools >> fl_bootloader_write.
Step 1.19 FDT should pop up on your screen. It is being controlled by a script file. Verify that it finishes
and closes itself.
End of Section
Using SW Building Blocks
Page 5 of 26
LAB PROCEDURE
2 Using the Default Flash Loader Implementation
Overview:
Now that the Flash Loader bootloader resides in the User Boot Area, we can use it to program new
images into the MCU’s application area. In this section we will start off by adding the Flash Loader
Downloader to an existing application. We will then use the bootloader to download the application and
program it into the MCU’s flash.
Procedural Steps
Step 2.1
On SW5 on the RDK board choose the following settings to put the MCU in User Boot Mode.
Step 2.2
While holding SW1, SW2, and SW3 at the same time click the Reset switch on the board to
reset the MCU into User Boot Mode. Verify that LED4, LED5, LED6, and LED7 turn on.
Step 2.3
On SW5 on the RDK board choose the following settings to allow UART communications.
User Boot Mode is also called USB Boot because from the factory the User Boot
Area is programmed with a USB Bootloader. If the user puts their own code in the User
Boot Area then the USB Bootloader is deleted. The changing on the settings on SW5 after
reset is required because an analog mux on the RDK board controls which UART channel
is connected to the boards DB9 connector. In order for the MCU to be put in User Boot
Mode on reset SW5 #1 needs to be set to ON. In order to choose the correct UART
channel SW5 #1 needs to be OFF. This means the user will need to change SW5
whenever performing a hard reset on the MCU.
Step 2.4
In the ‘Project Explorer’ pane, look for a project named ‘fl_default_user_app’. 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.
Using SW Building Blocks
Page 6 of 26
LAB PROCEDURE
Step 2.5
Click to File >> Import.
Step 2.6
Choose General >> Existing Projects into Workspace. Click Next.
Step 2.7
Check the ‘Select archive file:’ button and then click ‘Browse’.
Step 2.8
Browse to C:\Workspace\cl09i_flash_loader\sections\ and choose fl_default_user_app.zip.
Click Open.
Using SW Building Blocks
Page 7 of 26
LAB PROCEDURE
Step 2.9
Make sure the box next to ‘fl_default_user_app’ is checked in the ‘Projects’ box.
Step 2.10 Click ‘Finish’. You should now have a project in the Project Explorer pane named
fl_default_user_app.
This project implements a game where the user tries to navigate a
spaceship through a meteoroid field.
Step 2.11 We will now add the Flash Loader Downloader 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.
Using SW Building Blocks
Page 8 of 26
LAB PROCEDURE
Step 2.12 We are going to add the r_flash_loader_rx module to our existing application. In the module
list you will see two entries with the name r_flash_loader_rx. Look in the Description field and
choose the entry that says ‘Flash Loader Framework – User Application’.
After clicking on the r_flash_loader_rx module note the dependencies that are
shown in the ‘Details’ box. Some of these modules are already installed and others are
not. We will see how this is handled in upcoming steps.
Question
1. How many modules is this r_flash_loader_rx package dependent upon
(e.g. r_bsp is one)?
2. Which version of the r_crc_rx package is this module dependent upon?
Step 2.13 Make sure that the ‘Project adding to’ drop down has ‘fl_default_user_app’ selected. Verify
that your window looks like the one shown below and click ‘Finish’.
Using SW Building Blocks
Page 9 of 26
LAB PROCEDURE
Step 2.14 A ‘Module Information’ window should pop up indicating the r_flash_loader_rx package
requires the r_bsp and r_rspi_rx packages which already appear to be installed. Click OK.
Step 2.15 A ‘Module Warning’ window should pop up informing you that the r_flash_loader_rx package
also depends on the r_crc_rx, r_sci_async_rx, and r_spi_flash packages which do not appear
to be installed. The plug-in offers to automatically install the plug-in for you. Click Yes to have
the modules installed.
Step 2.16 The plug-in will alert you that the Source Location and Include paths have been updated. Click
OK.
Step 2.17 The plug-in will now open the properties window for the selected project. Click the Apply
button.
Using SW Building Blocks
Page 10 of 26
LAB PROCEDURE
Step 2.18 Navigate to the ‘Source Location’ tab underneath C/C++ General >> Paths and Symbols and
verify that the r_flash_loader_rx, r_crc_rx, r_sci_async_rx, and r_spi_flash folders are in the
list.
Step 2.19 Navigate to the C/C++ Build >> Settings >> Tool Settings >> Compiler >> Source window and
verify that the r_flash_loader_rx, r_crc_rx, r_sci_async_rx, and r_spi_flash include directories
were added. Click OK to close the window.
The FIT E2Studio plug-in added the needed code to the project by 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 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.
Using SW Building Blocks
Page 11 of 26
LAB PROCEDURE
Step 2.20 Verify that the ‘fl_default_user_app’ project now contains the r_flash_loader_rx, r_crc_rx,
r_sci_async_rx, and r_spi_flash folders.
The only information the Flash Loader Bootloader has about the currently running
application is the information found it the image’s Flash Loader Application Header. This
information is found in the file r_flash_loader_rx >> src >> r_fl_app_header.c. The Flash
Loader Bootloader must know the address of this application header in order to use it.
We will now make sure that this information is in the correct place.
Step 2.21 Right-click on the fl_default_user_app folder in the Project Explorer pane and choose
Renesas Tool Settings.
Step 2.22 In the window that pops up choose Tool Settings >> Linker >> Section.
CONTINUED ON NEXT PAGE
Using SW Building Blocks
Page 12 of 26
LAB PROCEDURE
Step 2.23 In the ‘Section viewer’ click on the last entry before FIXEDVECT (should be ‘P*’) and click the
‘Add Section’ button.
Step 2.24 A new entry named ‘NEW_SECTION_1’ should appear. Click on this entry and rename it to
‘APPHEADER_1’.
Step 2.25 Click on the ‘Address’ column next to this entry and input the address ‘0xFFFFFE00’.
Step 2.26 Your window should look like the one below. Click OK to save the changes and close the
window.
Step 2.27 Right-click on the fl_default_user_app folder in the Project Explorer pane and choose ‘Build
Project’.
Step 2.28 Verify that ‘Build complete’ is shown in the Console pane when the build has finished.
We have now built the application with the Flash Loader Downloader. Currently the
Flash Loader state machine is not being called as needed. To do this we will add calls to
the Flash Loader state machine.
Step 2.29 Open up the file src >> main.c.
Step 2.30 Uncomment the #include for r_flash_loader_rx_if.h. This is at line 23 by default.
/* Used for calling Flash Loader state machine. */
#include "r_flash_loader_rx_if.h"
Step 2.31 Before calling the Flash Loader state machine, it needs to be initialized. Do this by
uncommenting the call to R_FL_DownloaderInit(). This is on line 47 by default.
/* Initialize Flash Loader Downloader. */
R_FL_DownloaderInit();
Using SW Building Blocks
Page 13 of 26
LAB PROCEDURE
Step 2.32 The last thing to add is a call to the Flash Loader state machine. This call should be done in
the tick timer routine of the application. Uncomment the call to R_FL_StateMachine(). This is
on line 56 by default.
/* Call Flash Loader state machine. */
R_FL_StateMachine();
Step 2.33 Build the project and verify that ‘Build complete’ is shown in the Console pane.
Step 2.34 To make sure that there is room for our new Load Image we are going to delete any existing
data in the RDK’s SPI flash. Click Run >> External Tools >> fl_erase.
Step 2.35 A window should pop up asking you which block to erase. Enter 0 and hit OK.
Step 2.36 Verify that you see the following text in the Console pane.
Step 2.37 The default Flash Loader implementation has 2 available blocks for storing Load Images.
Repeat this process to erase block 1.
Using SW Building Blocks
Page 14 of 26
LAB PROCEDURE
Step 2.38 We will now verify that the SPI flash is empty. Click Run >> External Tools >> fl_info.
Step 2.39 In the Console pane verify that the information for Load Image 1 and Load Image 2 is all
0xFF’s as shown in the picture below.
The application is now ready to be converted into a Flash Loader Load Image and
transferred to the MCU on the RDK. The Load Image is created using the
r_fl_mot_converter.py Python script. The Load Image is then transferred to the RDK over
RS232 using the r_fl_serial_flash_loader.py Python script. These steps are automated for
this lab by using batch files in the C:\Workspace\cl09i_flash_loader\utilities\batch_files
directory. If you have time, you can examine these files to see what is being called.
Step 2.40 In the Project Explorer pane select the file fl_default_user_app >> Release >>
fl_default_user_app.mot.
Step 2.41 With the MOT file selected start the process of making a Load Image and transferring it to the
MCU by clicking Run >> External Tools >> fl_load.
Using SW Building Blocks
Page 15 of 26
LAB PROCEDURE
Step 2.42 The Console pane will be updated as the firmware image is transferred to the MCU. Verify that
at the end you see the message ‘File transferred successfully!’.
Step 2.43 Click Run >> External Tools >> fl_info to once again query the MCU for what images are
running and currently being stored. Verify that the currently running image matches the image
that was just downloaded. By default the Image ID should be ‘0x24’ and the Version # ‘0x06’.
Step 2.44 After the file was transferred successfully the MCU should have reprogrammed the part and
reset itself. You should now see a game running on the RDK. Before starting the game 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 26
LAB PROCEDURE
Step 2.45 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.46 Try to get as far as you can in the game.
End of Section
Using SW Building Blocks
Page 17 of 26
LAB PROCEDURE
3 Updating Firmware While User App is Running
Overview:
In the last section we successfully added the Flash Loader Downloader to an existing application. The
Flash Loader state machine is now running in parallel with the user’s application waiting for a new
firmware image. We are now going to alter the application and download a new version while the previous
version is still running.
Procedural Steps
Step 3.1
Follow the same process as shown in Step 2.4 through Step 2.10 to add the project
‘fl_default_user_app_2’ to your E2Studio workspace.
This first step imports a project that is identical to the way your project should have
looked at the end of Section 2. We provide this step to make it easier for people to start
this section when they were not able to finish the previous section or did not want to run
it. You can continue with your previous project but since the project name is different you
will need to substitute your project’s name in the following steps.
Step 3.2
Expand the r_game_spaceship folder in the Project Explorer pane and open up
r_game_spaceship_config.h
Step 3.3
Find the SPACESHIP_USE_ACCELEROMETER macro and uncomment it.
#define SPACESHIP_USE_ACCELEROMETER
(1)
2
The accelerometer on the RDKRX63N uses an I C interface. In order to read the
accelerometer the r_game_spaceship module needs the r_riic_rx600 and r_sensors
modules.
Step 3.4
Using the FIT E2Studio plug-in add in the r_sensors module. When adding this module it will
automatically bring in the r_riic_rx600 module.
The Flash Loader Downloader uses the Load Image’s Image ID and Version
Number to identify firmware images. We have not updated this information in
r_fl_app_header.c so if we send this updated image to the MCU it will deny it. We need to
update the version number so that the MCU knows it is a new image.
Step 3.5
Open the file fl_default_user_app_2 >> r_flash_loader_rx >> src >> r_fl_app_header.c.
Using SW Building Blocks
Page 18 of 26
LAB PROCEDURE
Step 3.6
Find the Version Number entry and update the value to be 0x07. Save the file.
Step 3.7
Rebuild the project and verify that you get the ‘Build complete’ message in the Console pane.
We can now convert the MOT file into a Load Image and send it to the RDK board.
Step 3.8
In the Project Explorer pane select the file fl_default_user_app_2 >> Release >>
fl_default_user_app_2.mot.
The purpose of the next step is to show that the new firmware image is
downloaded while the user application is still executing. To test this, start a new game
before (or during) the transfer and verify that during the transfer the user application still
runs as expected. When the image transfer has completed, the MCU will reset and
reprogram itself.
Step 3.9
With the MOT file selected start the process of making a Load Image and transferring it to the
MCU by clicking Run >> External Tools >> fl_load.
When starting the application make sure to have the RDKRX63N board flat on the
table. The accelerometer is calibrated after reset and if the board is tilted then it will take
that position as the default.
Step 3.10 Start a new game and verify that the spaceship moves based on the tilt of the board.
Using SW Building Blocks
Page 19 of 26
LAB PROCEDURE
Step 3.11 Click Run >> External Tools >> fl_info to once again query the MCU for what images are
running and currently being stored. Verify that the currently running image matches the image
that was just downloaded. By default the Image ID should be ‘0x24’ and the Version # ‘0x07’.
Question
3. Examine the Load Images reported by the fl_info command (not the
‘Current Running Image Info’). Which field do you think this is currently
used for determining which Load Image was the last downloaded?
(Hint: a lower Version # might be downloaded later due to a bug in a
newer version).
4. What is the Image CRC for the image that was just downloaded?
End of Section
Using SW Building Blocks
Page 20 of 26
LAB PROCEDURE
4 SD Card Flash Loader Implementation
Overview:
In the previous sections we used the default Flash Loader implementation. In this section, we are going to
cover a different implementation where new firmware images are obtained from a SD card.
Procedural Steps
Step 4.1
In the ‘Project Explorer’ pane, look for a project named ‘fl_sd_card_bootloader’. Right click on
the folder and choose ‘Build Project’.
Step 4.2
Verify that at the end of the build you see ‘Build complete’ at the bottom of the Console pane.
This project includes a Flash Loader Bootloader that obtains firmware images from
a SD card. We are going to replace the default Flash Loader Bootloader that we
programmed in Section 1 with this one.
Step 4.3
If you did not setup the USB-to-RS232 in Section 1 then please go back and perform Step 1.5
through Step 1.13.
Step 4.4
Follow Step 1.14 through Step 1.17 to put the RDK in Boot Mode.
Step 4.5
Click Run >> External Tools >> fl_bootloader_write_sd_card.
Step 4.6
FDT should pop up on your screen. It is being controlled by a script file. Verify that it finishes
and closes itself.
Using SW Building Blocks
Page 21 of 26
LAB PROCEDURE
Step 4.7
On SW5 on the RDK board choose the following settings to put the MCU in User Boot Mode.
Step 4.8
Click the Reset switch on the board to reset the MCU into User Boot Mode. Verify that LED4,
LED5, LED6, and LED7 turn on.
The Flash Loader Bootloader is now running and waiting for the user to insert a SD
card. The SD cards that are provided with this lab have the firmware image that was
created in Section 3 already on them.
Step 4.9
Take the Micro SD card that was provided to you and insert it in to the RDK’s Micro SD slot.
Step 4.10 Verify that the RDK resets and that the application from Section 3 is now running on the RDK.
We will now look through the code to see some of the differences between the
default Flash Loader implementation and this new one that uses SD cards. For
comparing the code we will be using the built-in ‘Compare’ tool in E2Studio.
CONTINUED ON NEXT PAGE
Using SW Building Blocks
Page 22 of 26
LAB PROCEDURE
Step 4.11 In the Project Explorer pane select the fl_sd_card_bootloader >> r_flash_loader_rx folder.
Step 4.12 While holding the ‘Control’ button on your keyboard choose the fl_default_bootloader >>
r_flash_loader_rx folder. Use of the ‘Control’ key allows you to select multiple files/folders at
once.
Step 4.13 Right-click on one of the chosen r_flash_loader_rx folders and choose Compare With >> Each
Other.
Step 4.14 A new tab will open in the Editor window. Verify that the text in the tab starts with ‘Compare’.
Using SW Building Blocks
Page 23 of 26
LAB PROCEDURE
To get more screen real estate for a tab you can double click on the tab.
Step 4.15 Double-click on the ‘Compare’ tab to maximize this pane.
Step 4.16 In the ‘Compare’ pane, double-click on the r_flash_loader_rx_config.h file.
The ‘C Compare Viewer’ will highlight differences between the 2 different versions
of the selected file.
Step 4.17 The ‘C Compare Viewer’ should open and show you a diff between the two configuration files.
Question
5. Which configuration macros were removed going from the default
implementation to the new SD card implementation?
Step 4.18 In the ‘Compare’ pane, expand the src >> memory folders. Verify that r_fl_memory_sdcard.c
and r_fl_memory_spi_flash.c are shown with one icon having a minus sign (-) and the other
having a plus sign (+).
The use of the plus and minus signs means that the file was present in one project
and not in the other. In this case this is showing us that one project used a SPI flash and
the other used a SD card. This should make sense because the default Flash Loader
implementation stored firmware images in SPI flash while the bootloader in this section
gets firmware images from a SD card.
Step 4.19 In the src folder double-click on the file r_fl_bootloader.c.
Step 4.20 Scroll down in the file past the main() function and review the changes in the
fl_write_new_image(), fl_process_write_buffer(), and fl_flush_write_buffer() functions.
Question
6. Which of these functions were NOT changed between
implementations: fl_write_new_image(), fl_process_write_buffer(), and
fl_flush_write_buffer()?
7. In the SD card implementation version of the fl_write_new_image()
function which function was used in place of fl_mem_read()?
Using SW Building Blocks
Page 24 of 26
LAB PROCEDURE
The other main changes between the two implementations can be viewed by
comparing the r_fl_store_manager.c and r_fl_downloader.c files. For example, if you view
the fl_get_load_image_headers() function in r_fl_store_manager.c then you can see the 2
different methods of finding valid firmware images.
End of Section
Using SW Building Blocks
Page 25 of 26
LAB PROCEDURE
Question Answers
Question
1. How many modules is this r_flash_loader_rx package dependent upon
(e.g. r_bsp is one)?
5 – r_bsp, r_crc_rx, r_rspi_rx, r_sci_async_rx, and r_spi_flash
2. Which version of the r_crc_rx package is this module dependent upon?
r_crc_rx v1.10
Question
3. Examine the Load Images reported by the fl_info command (not the
‘Current Running Image Info’). Which field do you think this is currently
used for determining which Load Image was the last downloaded?
(Hint: a lower Version # might be downloaded later due to a bug in a
newer version).
The Successfully Stored field is used. It indicates that the firmware image
was successfully downloaded and is also a counter. The higher the
number, the more recent the image was stored.
4. What is the Image CRC for the image that was just downloaded?
0xB801
Question
5. Which configuration macros were removed going from the default
implementation to the new SD card implementation?
FL_TIMEOUT_ENABLE, FL_TIMEOUT_TICKS, FL_MEM_BASE_ADDR
Question
6. Which of these functions were NOT changed between
implementations: fl_write_new_image(), fl_process_write_buffer(), and
fl_flush_write_buffer()?
fl_process_write_buffer() and fl_flush_write_buffer()
7. In the SD card implementation version of the fl_write_new_image()
function which function was used in place of fl_mem_read()?
fl_read_file_data()
Using SW Building Blocks
Page 26 of 26