16. Quick Start for Renesas RX

16.1. Supported Environments

Operating System

Windows: Windows 10 / Windows 11

Linux: Ubuntu 22.04 / Ubuntu 24.04

macOS: macOS 14 Sonoma (Apple silicon) / macOS 15 Sequoia (Apple silicon)

VS Code version

1.102.0 (minimum)

VS Code can be downloaded and installed from this page https://code.visualstudio.com/.

16.2. Installation

Please choose your operating system for operating system dependent installation steps.

For the Renesas RX Family, Renesas Platform provides a straightforward installation wizard to install the CMake, Ninja, Python and the Support Files for RX Family. To set up your environment:

  1. Open VS Code.

  2. Navigate to the “Renesas” tab in VS Code. Then, click “Renesas Quick Install” in the “Environment” view.

    _images/renesas-quick-install.png

  3. Click the “Install” button for the “Renesas RX” device family. The Renesas Platform will now check the dependencies required by the Renesas RX Device Family. The Renesas Platform extension will check the local environment and CMake, Ninja, Python and the Support Files for RX Family, then create an installation plan for them if necessary.

    _images/rx-install.png

  4. When your selection is ready, click the “Start Installations” button. The download and installation process will start automatically.

    _images/rx-start-installation.png

Installing the latest RX Smart Configurator (RX SC):

Download and install the latest version of RX Smart Configurator

  • https://www.renesas.com/en/software-tool/rx-smart-configurator#downloads

    Note

    Renesas Platform extension scans for changes at start-up, thus, after installing the Renesas RX Smart Configurator, please restart VS Code to force Renesas Platform to detect the recent RX Smart Configurator installation.

    You can click “Manage Smart Configurators” to check the detected Smart Configurators. If it is not automatically detected, you can use the “Register SC” button to register the Smart Configurator manually by selecting the path of the Smart Configurator.

    _images/rx-sc.png

Installing Toolchains for RX Development:

Install one of the preferred toolchains for RX Project Build. It is recommended to use either “CC-RX” or “GCC for Renesas GNURX”.

Installing and Configuring “CC-RX” toolchain

For installing “CC-RX”:

  1. Download and install the latest toolchain:

    https://www.renesas.com/us/en/software-tool/cc-compiler-package-rx-family

    Note

    CC-RX toolchain should be installed to a path that does not contain spaces or special characters.

  2. Add “CC-RX” toolchain to Renesas Platform

    Registering CC-RX toolchain in Renesas Platform

    1. Open VS Code

    2. Navigate to the “Renesas” tab in VS Code and click “Manage Build Tools”.

    3. Click the “Register Toolchain” button in the Build Toolchains table header.

    4. In the folder selection dialog, navigate to the root folder of the CC-RX toolchain (not the bin folder).

    5. Select the folder and complete the toolchain registration.

      _images/registering-ccrx.png
Installing and Configuring “GCC for Renesas GNURX” toolchain

For installing “GCC for Renesas GNURX”:

  1. Download and install the latest toolchain:

    https://llvm-gcc-renesas.com/rx-download-toolchains/

    Note

    GCC-RX toolchain should be installed to a path that does not contain spaces or special characters.

  2. Add “GCC-RX” toolchain to Renesas Platform

    Registering GCC-RX toolchain in Renesas Platform

    1. Open VS Code

    2. Navigate to the “Renesas” tab in VS Code and click “Manage Build Tools”.

    3. Click the “Register Toolchain” button in the Build Toolchains table header.

    4. In the folder selection dialog, navigate to the root folder of the GCC-RX toolchain (not the bin folder).

    5. Select the folder and complete the toolchain registration.

      _images/registering-gccrx.png

Installing Additional Emulator Drivers

You may need to download and install additional USB drivers for establishing a connection with the emulators and devices. Please install the latest drivers before starting your debug session. Use the following links to download the drivers suitable for your operating system and device:

For other Renesas emulators, please check for any recommended drivers:

For the Renesas RX Family, Renesas Platform provides a straightforward installation wizard to install the CMake, Ninja, Python and the Support Files for RX Family. To set up your environment:

  1. Open VS Code.

  2. Navigate to the “Renesas” tab in VS Code. Then, click “Renesas Quick Install” in the “Environment” view.

    _images/renesas-quick-install.png

  3. Click the “Install” button for the “Renesas RX” device family. The Renesas Platform will now check the dependencies required by the Renesas RX Device Family. The Renesas Platform extension will check the local environment and CMake, Ninja, Python and the Support Files for RX Family, then create an installation plan for them if necessary.

    _images/rx-install.png

  4. When your selection is ready, click the “Start Installations” button. The download and installation process will start automatically.

    _images/rx-start-installation.png

Most of the installations will be performed automatically, some installations may require manual interaction.

  • During the “Python 3.10” installation, the terminal wizard will appear for manual interaction. The terminal will show the execution plan and ask for confirmation before continuing. During the installation, it requires administrative rights to execute the installation, thus a password could be needed during the installation. Please make sure that the current user has “sudo” permissions and enter the password.

    _images/common-installation-terminal-attention.png

Installing Toolchains for RX Development:

Install one of the preferred toolchains for RX Project Build. It is recommended to use either “CC-RX” or “GCC for Renesas GNURX”.

Installing and Configuring “CC-RX” toolchain

For installing “CC-RX”:

  1. Download and install the latest toolchain:

    https://www.renesas.com/us/en/software-tool/cc-compiler-package-rx-family

Installing and Configuring “GCC for Renesas GNURX” toolchain

For installing “GCC for Renesas GNURX”:

  1. Download and install the latest toolchain:

    https://llvm-gcc-renesas.com/rx-download-toolchains/

Installing Additional Emulator Drivers

You may need to download and install additional USB drivers for establishing a connection with the emulators and devices. Please install the latest drivers before starting your debug session. Use the following links to download the drivers suitable for your operating system and device:

For other Renesas emulators, please check for any recommended drivers:

For the Renesas RX Family, Renesas Platform provides a straightforward installation wizard to install the CMake, Ninja, Python and the Support Files for RX Family. To set up your environment:

  1. Open VS Code.

  2. Navigate to the “Renesas” tab in VS Code. Then, click “Renesas Quick Install” in the “Environment” view.

    _images/renesas-quick-install.png

  3. Click the “Install” button for the “Renesas RX” device family. The Renesas Platform will now check the dependencies required by the Renesas RX Device Family. The Renesas Platform extension will check the local environment and CMake, Ninja, Python and the Support Files for RX Family, then create an installation plan for them if necessary.

    _images/rx-install.png

  4. When your selection is ready, click the “Start Installations” button. The download and installation process will start automatically.

    _images/rx-start-installation.png

Most of the installations will be performed automatically, some installations may require manual interaction.

  • During the “Python 3.10” installation, the terminal wizard will appear for manual interaction. The terminal will show the execution plan and ask for confirmation before continuing. During the installation, it requires administrative rights to execute the installation, thus a password could be needed during the installation. Please make sure that the current user has “sudo” permissions and enter the password.

    _images/common-installation-terminal-attention.png

Installing Toolchains for RX Development:

Install one of the preferred toolchains for RX Project Build. It is recommended to use either “CC-RX” or “GCC for Renesas GNURX”.

Installing and Configuring “CC-RX” toolchain

For installing “CC-RX”:

  1. Download and install the latest toolchain:

    https://www.renesas.com/us/en/software-tool/cc-compiler-package-rx-family

Installing and Configuring “GCC for Renesas GNURX” toolchain

For installing “GCC for Renesas GNURX”:

  1. Download and install the latest toolchain:

    https://llvm-gcc-renesas.com/rx-download-toolchains/

Installing Additional Emulator Drivers

You may need to download and install additional USB drivers for establishing a connection with the emulators and devices. Please install the latest drivers before starting your debug session. Use the following links to download the drivers suitable for your operating system and device:

For other Renesas emulators, please check for any recommended drivers:

To utilise the Renesas extensions on macOS, it’s necessary to install:

  • Homebrew

  • XZ Archive Utilities

First, install Homebrew (brew), which is an open-source software package management system that manages the installation of software for macOS. For installation and more information about Homebrew, please refer to https://brew.sh/.

After installing the Homebrew, install the “XZ Archive Utilities” by using brew install xz command.

$ brew install xz

For the Renesas RX Family, Renesas Platform provides a straightforward installation wizard to install the CMake, Ninja, Python and the Support Files for RX Family. To set up your environment:

  1. Open VS Code.

  2. Navigate to the “Renesas” tab in VS Code. Then, click “Renesas Quick Install” in the “Environment” view.

    _images/renesas-quick-install.png

  3. Click the “Install” button for the “Renesas RX” device family. The Renesas Platform will now check the dependencies required by the Renesas RX Device Family. The Renesas Platform extension will check the local environment and CMake, Ninja, Python and the Support Files for RX Family, then create an installation plan for them if necessary.

    _images/rx-install.png

  4. When your selection is ready, click the “Start Installations” button. The download and installation process will start automatically.

    _images/rx-start-installation.png

Most of the installations will be performed automatically, some installations may require manual interaction.

  • During the “Python 3.10” installation, the terminal wizard will appear for manual interaction. The terminal will show the execution plan and ask for confirmation before continuing. During the installation, it requires administrative rights to execute the installation, thus a password could be needed during the installation. Please make sure that the current user has “sudo” permissions and enter the password.

    _images/common-installation-terminal-attention.png

Installing Toolchains for RX Development:

Install the “GCC for Renesas GNURX” toolchain for RX project development in macOS operating system. For installing “GCC for Renesas GNURX”:

  1. Download and install the latest toolchain:

    https://llvm-gcc-renesas.com/rx-download-toolchains/

Installing Additional Emulator Drivers

You may need to download and install additional USB drivers for establishing a connection with the emulators and devices. Please install the latest drivers before starting your debug session. Please check for the recommended drivers:

16.3. Creating a Project

For RX device family projects, Smart Configurator can be accessed via the “Create Project” view in the “Renesas” tab. Please use the following instructions to create and build a project for RX device family.

  1. Navigate to “Renesas” and click [Create Renesas RX project] from the commands.

    _images/create-project3.png

  2. Select [Create RX Project with Smart Configurator] option from the list.

    _images/pick-method2.png

  3. Then, VSCode will show installed [RX Smart Configurator] list, select a [Smart Configurator] from the list.

    _images/pick-sc3.png

  4. Select a [Folder] to create the project.

    _images/pick-folder3.png

  5. Enter [File name], configure your board and device type, select either [Renesas RXC Toolchain] or [GCC RX Toolchain], and then click [Next].

    _images/sc-step13.png

  6. Choose one of the [Bank mode setting] (applicable for some devices) then click [Finish] to complete the project creation steps.

    _images/sc-step23.png

  7. Click [Generate Code] and close [RX Smart Configurator] after generation of the project files completes.

    _images/sc-step33.png

16.4. Building the Project

For building a project, which has been created with RX Smart Configurator, please follow the steps below:

  1. In the VS Code Command Palette, run the “CMake: Delete Cache and Reconfigure” command.

    _images/delete_cache_and_reconfigure.png

  2. In the first time of running, a kit selection is shown. Select “[Unspecified]”.

    _images/select_unspecified_kit.png

  3. In VS Code, click [Terminal] ⇒ [Run Build Task] from the menu. Alternatively, press ctrl+shift+B to quickly open the Build task.

    _images/sc_run_build_task.png

  4. Select [Build Project] from the commands.

    _images/run-build-project-task.png

TIP: For more information about RX Smart Configurator, click here to visit the RX Smart Configurator page.

16.5. Debugging the Project

A debug session can be started by selecting the created configuration and clicking the [Start Debugging] button in the [Run and Debug] tab, or pressing [F5] from the keyboard.

_images/vscode-debug-start5.png

When VS Code starts the debug session, common debug control flow functions like resume, suspend, step into, step over, step out, restart, terminate debug session can be performed via the debug flow control buttons. Also, the [Debug Console] view will contain useful messages during the debug session.

_images/vscode-debug-start6.png

During the debug session, details about the local variables, device registers, call stack, watched variables, states of the peripherals can be accessed at the primary sidebar of VS Code in the [Run and Debug] tab.

_images/vscode-debug-start7.png

16.6. GDB Server launch parameters for RX devices

Reference for common parameters: All common server parameters, including default settings and options applicable to Renesas device families, are documented in the GDB Server Parameters section. The specific parameters of the RX devices are described below.

16.6.1. Connection Settings

16.6.1.2. Clock

Option

Details

-uClockSrcHoco=
Description: Specify the Main Clock Source.
Default Values: 0
Emulator: E1, E20, E2, E2LITE, SEGGERJLINKRX
Available Values: 0: EXTAL, 1: HOCO
Example: "serverParameters": { "-uClockSrcHoco=": 0 }

-uInputClock=
Description: Specify EXTAL frequency in MHz.
Default Values: None
Emulator: E1, E20, E2, E2LITE, SEGGERJLINKRX
Available Values: Between 0.001 to 99.999
Example: "serverParameters": { "-uInputClock=": 27.0 }

-uAllowClockSourceInternal=
Description: Specify whether or not to allow manipulation of the main clock source by debugger when internal flash memory is rewritten.
Default Values: 1
Emulator: E1, E20, E2, E2LITE, SEGGERJLINKRX
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uAllowClockSourceInternal=": 1 }

-uPTimerClock=
Description: Specify the operating frequency which is used to calculate the performance counter.
Default Values: None
Emulator: E1, E20, E2, E2LITE, SEGGERJLINKRX
Available Values: The frequency in Hz in range 1000 - 999999000
Example: "serverParameters": { "-uPTimerClock=": 120000000 }

-uCpuClkFreq=
Description: Specify the CPU clock frequency in MHz.
Default Values: Depend on the target device
Emulator: Simulator
Available Values: The frequency in MHz
Example: "serverParameters": { "-uCpuClkFreq=": 12 }

-uPeripheralClkRatio=
Description: Specifies the clock division ratio applied to the system clock to generate the peripheral clock.
Default Values: 1
Emulator: Simulator
Available Values: 1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48, 64
Example: "serverParameters": { "-uPeripheralClkRatio=": 1 }

16.6.1.3. Connection with Target Board

Option

Details

-sn=
Description: Select the emulator to connect.
Default Values: Auto (Emulator will be selected automatically.)
Emulator: E1, E20, E2, E2Lite
Available Values: Emulator information with format: <emulator type>:<serial number>
Example: "serverParameters": { "-sn=": "e2:_9es002310c" }

-uUseFine=
Description: Specifies the connection type to be used when by the emulator when communicating with the CPU on target system.
Default Values: 0
Emulator: E1, E20, E2, E2LITE, SEGGERJLINKRX
Available Values: 0: JTag, 1: Fine
Example: "serverParameters": { "-uUseFine=": 0 }

-uJTagClockFreq=
Description: Specify JTAG communication speed between the emulator and the CPU on target system.
Default Values: Depend on the debugger type
Emulator: E1, E20, E2, E2LITE, SEGGERJLINKRX
Available Values:
E2Lite: 6.00, 3.00, 1.50
E2: 16.5, 12.5, 6.25, 3.125, 1.562
E1, E20, SEGGERJLINKRX: 16.5, 12.38, 6.188, 3.094, 1.547
Example: "serverParameters": { "-uJTagClockFreq=": 6.00 }

-uFineBaudRate=
Description: Specify FINE communication speed between the emulator and the CPU on target system.
Default Values: Depend on the debugger type
Emulator: E1, E20, E2, E2LITE, SEGGERJLINKRX
Available Values:
E2Lite: 1.50, 0.75, 0.50, 0.25
E1, E20, E2, SEGGERJLINKRX: 2.00, 0.75, 0.5, 0.25
Example: "serverParameters": { "-uFineBaudRate=": 1.50 }

-uHotPlug=
Description: Specify if connecting to an already running target system.
Default Values: 0
Emulator: E1, E20, E2, E2LITE
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uHotPlug=": 1 }

16.6.1.4. Power

Option

Details

-w
Description: Select whether to supply power to the target board from emulator.
Default Values: 0
Emulator: E1, E20, E2, E2Lite
Available Values: 0, 1, 2
Example: "serverParameters": { "-w": 1 }
Note: Value 2 is just supported for E2 emulator.

-z
Description: Specify the power voltage supplied to the target board.
Default Values: 0
Emulator: E1, E20, E2, E2Lite
Available Values: 0: 3.3 V, 1: 5.0 V, From 18 to 50: From 1.8 V to 5.0 V
Example: "serverParameters": { "-z": 0 }: using for 3.3 V, "serverParameters": { "-z": 1 }: using for 5.0 V, "serverParameters": { "-z": 18 }: using for 1.8 V
Note: E2Lite emulator is just supported 3.3 V. Just E2 emulator allows to specify a arbitrary value from 1.8 V to 5.0 V

16.6.1.5. CPU Operating Mode

Option

Details

-uRegisterSetting=
Description: Specify the operation mode set by registers.
Default Values: 0
Emulator: Simulator, E1, E20, E2, E2LITE, SEGGERJLINKRX
Available Values: 0: “Single Chip”, 1: “On-Chip ROM Ext. On”, 2: “On-Chip ROM Ext. Off”
Example: "serverParameters": { "-uRegisterSetting=": 0 }

-uModePin=
Description: Specify the operation mode set by mode pins.
Default Values: 0
Emulator: Simulator, E1, E20, E2, E2LITE, SEGGERJLINKRX
Available Values: 0: Single-chip mode, 1: User boot mode
Example: "serverParameters": { "-uModePin=": 0 }

-uChangeStartupBank=
Description: Specify if the start up bank needs to be changed, when the target device supports “Dual Mode”.
Default Values: 0
Emulator: E1, E20, E2, E2LITE
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uChangeStartupBank=": 0 }

-uStartupBank=
Description: Specify the start up bank when it needs to be changed.
Default Values: Bank 0
Emulator: E1, E20, E2, E2LITE
Available Values: Bank 0, Bank 1
Example: "serverParameters": { "-uStartupBank=": "BANK_0" }

-uCacheDecode=
Description: Enables or disables cache decoding.
Default Values: 1
Emulator: Simulator
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uCacheDecode=": 1 }

16.6.1.6. Communications Mode

Option

Details

-uDebugMode=
Description: Specify the emulation mode.
Default Values: 0
Emulator: E1, E20, E2, E2LITE, SEGGERJLINKRX
Available Values: 0: “Debug Mode”, 1: “Write On Chip Flash Memory”
Example: "serverParameters": { "-uDebugMode=": 0 }

-uExecuteProgram=
Description: Specify if the user program should be executed after disconnecting the debugger.
Default Values: 0
Emulator: E1, E20, E2, E2LITE, SEGGERJLINKRX
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uExecuteProgram=": 0 }

16.6.1.7. Flash

Option

Details

-uIdCode=
Description: Enter ID code to unlock the flash memory from the protected state.
Default Values: FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
Emulator: E1, E20, E2, E2LITE, SEGGERJLINKRX
Available Values: 32 hex digit
Example: "serverParameters": { "-uIdCode=": "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF" }

16.6.2. Debug Tool Settings

16.6.2.1. General Debug

Option

Details

-uresetOnReload=
Description: Select whether to reset the program after downloaded.
Default Values: 1
Emulator: E1, E20, E2, E2LITE, SEGGERJLINKRX
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uresetOnReload=": 1 }

16.6.2.2. Memory

Option

Details

-uWorkRamAddress=
Description: Specify the first address of the working RAM area for debugger firmware.
Default Values: Depends on the target device
Emulator: Simulator, E1, E20, E2, E2LITE, SEGGERJLINKRX
Available Values: Internal RAM area
Example: "serverParameters": { "-uWorkRamAddress=": "0x1000" }

-uverifyOnWritingMemory=
Description: Select whether to verify data when writing to memory.
Default Values: 0
Emulator: E1, E20, E2, E2LITE, SEGGERJLINKRX
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uverifyOnWritingMemory=": 0 }

16.6.2.3. System

Option

Details

-uProgReWriteIRom=
Description: Specify whether or not the program being debugged rewrites the internal program ROM.
Default Values: 0
Emulator: E1, E20, E2, E2LITE, SEGGERJLINKRX
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uProgReWriteIRom=": 0 }

-uProgReWriteDFlash=
Description: Specify whether or not to debug a program that involves rewriting the internal data flash.
Default Values: 0
Emulator: E1, E20, E2, E2LITE, SEGGERJLINKRX
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uProgReWriteDFlash=": 0 }

16.6.2.4. Start/Stop Function

Option

Details

-uhookEnableStart=
Description: Specify if a function should be executed before running user program.
Default Values: 0
Emulator: E1, E20, E2, E2LITE
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uhookEnableStart=": 0 }

-uhookStartFunc=
Description: Specify the address of the start function.
Default Values: 0
Emulator: E1, E20, E2, E2LITE
Available Values: Any valid hex address.
Example: "serverParameters": { "-uhookStartFunc=": "&R_BSP_ChangeToUserMode" }
Note: This parameter is just sent when allow to execute function before running user program

-uhookEnableStop=
Description: Specify if a function should be executed after stopping user program.
Default Values: 0
Emulator: E1, E20, E2, E2LITE
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uhookEnableStop=": 0 }

-uhookStopFunc=
Description: Specify the address of the stop function.
Default Values: None
Emulator: E1, E20, E2, E2LITE
Available Values: Any valid hex address.
Example: "serverParameters": { "-uhookStopFunc=": "&R_BSP_InterruptRead" }
Note: This parameter is just sent when allow to execute function after stopping user program

-uhookWorkRamAddr=
Description: Specify the first address of the working RAM area for start/stop function.
Default Values: 0
Emulator: E1, E20, E2, E2LITE
Available Values: Internal RAM area
Example: "serverParameters": { "-uhookWorkRamAddr=": "0x20001000" }

16.6.2.5. Execution Mode

Option

Details

-uEmStopInt=
Description: Enables to stop execution when an INT instruction is executed.
Default Values: 1
Emulator: Simulator
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uEmStopInt=": 1 }

-uEmStopInterrupt=
Description: Enables to stop execution when an interrupt is encountered.
Default Values: 1
Emulator: Simulator
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uEmStopInterrupt=": 1 }

-uEmStopFPexp=
Description: Enables to stop execution when a floating-point exception is encountered.
Default Values: 1
Emulator: Simulator
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uEmStopFPexp=": 1 }

16.6.2.6. RTOS

Option

Details

-uOSRestriction=
Description: When debugging a project with a large number of OS threads the Debug View will always check the status of every thread. Selecting Yes will
force the view to only check the current thread. This speeds up debugger responsiveness.
Default Values: 0
Emulator: Simulator, E2, E2LITE
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uOSRestriction=": 1 }
Note: "-uOSRestriction=": 0: Do not restrict OS thread checking, "-uOSRestriction=": 1: Restrict OS thread checking to the current thread