4. Productivity Tips, Advanced Guidelines, Troubleshooting and Common Issues

4.1. Productivity Tips

4.1.1. Managing Support Files

In most cases, support files are automatically installed to the development environment by Renesas extensions whenever they needed (for instance before starting the debug session if they are not installed yet). Developers also can install, update or uninstall the support files manually by following the instructions below:

4.1.1.1. Using Support Files Manager

Press Ctrl+Shift+P or select [View] → [Command Palette…] to open Command Palette.
Run the command "Renesas: Open Renesas Support Files Manager".
Select Devices Families to use → click Install

4.1.1.2. Changing Support Files Path

By default, support files are install to the paths described below:

Window host:

%AppData%\Code\User\globalStorage\renesaselectronicscorporation.renesas-debug

Linux host:

~/.config/Code/User/globalStorage/renesaselectronicscorporation.renesas-debug

macOS host:

~/Library/Application Support/Code/User/globalStorage/renesaselectronicscorporation.renesas-debug

Developers can change the installation location of the support files by following the instructions below:

Open the VSCode Settings user interface
Navigate to Extensions → Renesas menu from the left.
UI will show the "Renesas: Supports Folder Path" to the user.
Type the custom folder path that they want to prefer to use.

4.1.2. Monitoring MI Commands

In the Debug Console view you can interact directly with GDB. To display the value of an expression, type that expression which can reference variables that are in scope. For example type '2 + 3' or the name of a variable. Arbitrary commands can be sent to GDB by prefixing the input with a '>', for example type '>show version' or '>help'.

4.1.3. Debuggers, Device Families and Emulator/Simulator Types in launch.json

The minimum configuration of the launch configuration is shown below:

launch.json format

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "<type>",
            "request": "launch",
            "name": "<display name of the configuration>",
            "target": {
                "deviceFamily": "<device family (RA, RCAR, RH850, RL78, RX or RZ)>",
                "device": "<device code>",
                "debuggerType": "<debugger type (type of the simulator or emulator)>"
            }
        }
    ]
}

Here is the lookup table for "type", "target.deviceFamily" and "target.debuggerType" values for the developers to use in the launch.json configuration file:

Debugger

type

target.deviceFamily

target.debuggerType

Renesas GDB Hardware Target

renesas-hardware

Dialog

SEGGERJLINKARM

E2, E2LITE, SEGGERJLINKARM

RH850

E1, E2

RL78

E1, E2, E2LITE, EZ, IECUBE, COMPORT

E1, E2, E2LITE, E20, SEGGERJLINKRX

SEGGERJLINKARM

Renesas GDB Simulator Target

renesas-simulator

RL78

SIMULATOR

Renesas RCAR Linux Target

renesas-rcar-linux

RCAR

RCAR_PROXY

Renesas RCAR Target

renesas-rcar

RCAR

E2ARM, E2RH850, IE850ARH850, LAUTERBACHT32

RH850

E1, E2, IE850ARH850

4.1.4. How to enable and disable cores

When debugging with multicore, all cores are enabled by default. The user can configure the 'disabledCores' property in the launch.json configuration file’s target to disable the desired cores.

For instance, in the case of the R-Car S4 ARM CA55 device, there are 8 cores ranging from CA55CPU0 to CA55CPU7. To disable cores CA55CPU4 to CA55CPU7, the following configuration should be applied:

launch.json example

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "type": "renesas-rcar",
      "request": "launch",
      "name": "RCAR",
      "program": "${cwd}/Debug/MR_BAREMETAL_CA55.axf",
      "target": {
        "deviceFamily": "RCAR",
        "device": "R8A779F0_CA55",
        "debuggerType": "E2ARM",
        "disabledCores": ["CA55CPU4","CA55CPU5","CA55CPU6","CA55CPU7"]
      }
    }
  ]
}

4.1.5. How to add additional gdb command line arguments

Renesas Debug extension is initializing and passing all required command line arguments to gdb process while starting the debug session. Furthermore, if it’s needed, Renesas Debug Adapters provide injecting additional command line arguments for gdb, which will be passed to the gdb while starting the debug session. Passing the additional gdb command line arguments operation is a straight-forward process, it can be done by defining "gdbArguments" field to the debug configuration in launch.json file.

The following code is showing an example how "gdbArguments" field could be defined in launch configuration:

launch.json example

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "type": "renesas-simulator",
      "request": "launch",
      "name": "Sample Renesas Configuration",
      "gdbArguments": ["-rx-force-isa=v3"],
      "target": {
        "deviceFamily": "RX",
        "device": "R5F566TK",
        "debuggerType": "SIMULATOR"
      }
    }
  ]
}

4.1.6. Alternative ways for opening a project in VSCode

There are 2 different alternatives to open a project in VS Code:

Using the [File: Open Folder…] command in the [Command Palette]
- Select [View] → [Command Palette…] menu item.
- Select [File: Open Folder…] command (can filter the command list using command name).
- In [Open Folder] dialog, browse to project folder and click [Select Folder] button.
Using command-line

Folder can be opened using the below command-line option.
```
code <folder path>
```
E.g. (provide the cmd is opened in the folder that contains CCRX_testprj folder)
```
code CCRX_testprj/
```
Multiple folder paths can be provided on the command line to open multiple folders at once.
```
code CCRX_testprj/ CCRL_testprj/ RA_testprj/
```
Project will be opened and display in [Explorer] view.

4.1.7. Setting Python Directory Manually

In a debug session, RA, RL78, RX and RZ device families require Python 3.10, on the other hand, R-Car and RH850 require a 32-bit version of Python 2.7. The path of Python is automatically selected if the path is already included in environment variable PATH.

Note	For Windows, Renesas Debug extension automatically extracts a local copy of the required version of Python into the support files folder if Python is not installed or included in the `PATH`.

For advanced operations where the Python path doesn’t wanted to be defined in the environment variable PATH, the launch parameter pythonHome could be used for setting the Python directory to be used during the debugging session.

Example for pythonHome usage

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "type": "renesas-simulator",
      "request": "launch",
      "name": "Renesas GDB Simulator Debugging",
      "pythonHome": "C:\\Path\\To\\Python",
      "target": {
        "deviceFamily": "RX",
        "device": "R5F51115",
        "debuggerType": "SIMULATOR"
      }
    }
  ]
}

4.1.8. Tips for using the CMake Tools bar in VSCode

CMake Tools add a variety of controls into the status bar of VSCode, Developers can do the following operations:

Manage the build type by clicking the "Build Type" button:
Select the Active CMake Kit by clicking the "Active Kit" button:
Build the project by clicking the "Build" button:
Start debugging the project by clicking the "Debug" button:

4.1.9. Setting up the RA Debug Environment for VS Code

You must install the support files and register/import the RA Smart Configurator in VS Code before starting the debug session with RA devices. Please follow the instructions below to perform the operation in Windows, Linux and macOS environments.

4.1.9.1. Instructions for Windows Environment

Download and install the latest RA Smart Configurator for Windows from the link below:

https://github.com/renesas/fsp/releases
Open the "Command Palette" (use "View" ⇒ "Command Palette" menu, or use CTRL + SHIFT + P keyboard combination), then click to the "Renesas: Open Renesas Support Files Manager".
Navigate to the "RA" device family.
Click the "Install" button to install the device family support files.
After the support files installation, Renesas Support Files Manager will show the installed RA Smart Configurators. Click the "Import Files" on your desired RA Smart Configurator.
This process will register the RA Smart Configurator for use, and import the necessary device files for debugging for RA devices.

Note

If you can not see installed RA Smart Configurators:

Click the "Select RA SC" button.
VS Code will ask for the path of the RA Smart Configurator binary. Navigate to the installation folder and select the rasc.exe.
Renesas Debug extension will register the RA Smart Configurator for use and automatically import the necessary definition files.

4.1.9.2. Instructions for Linux Environment

Download and install the latest RA Smart Configurator for Linux from the link below:

https://github.com/renesas/fsp/releases
Open the "Command Palette" (use "View" ⇒ "Command Palette" menu, or use CTRL + SHIFT + P keyboard combination), then click to the "Renesas: Open Renesas Support Files Manager".
Navigate to the "RA" device family.
Click the "Install" button to install the device family support files.
After the support files installation, click the "Select RA SC" button.
VS Code will ask for the path of the RA Smart Configurator binary. Navigate to the installation folder and select the rasc binary.
Renesas Debug extension will register the RA Smart Configurator for use and automatically import the necessary definition files.

4.1.9.3. Instructions for macOS Environment

Download and install the latest RA Smart Configurator for macOS from the link below:

https://github.com/renesas/fsp/releases
Open the "Command Palette" (use "View" ⇒ "Command Palette" menu, or use CMD + SHIFT + P keyboard combination), then click to the "Renesas: Open Renesas Support Files Manager".
Navigate to the "RA" device family.
Click to the "Install" button for installing the device family support files.
After the installation, click to the "Select RA SC". It is now asking for the path of the RA Smart Configurator binary. Leave the file dialog open (we will drag&drop the binary to this window later), and open a separate Finder window.
Navigate to the Renesas RA FSP application under the "Applications" folder.
Right click to the "Renesas RA FSP X.Y.Z" application and click to the "Show Package Contents",
Navigate to the "Contents" ⇒ "MacOS" folder inside the package, then, drag&drop the "rasc" binary back to the file dialog window.
Click to the "Select" button.
Now, VS Code is starting to import the additional device files. At the end of the import, RA Smart Configurator will be registered for use.

4.2. Advanced Guidelines

4.2.1. Setup environment and debug multicore CA55 with CR52 using renesas-amalgamator

4.2.1.1. Overview

Support debug multicore with CA55 and CR52 for R-Car S4 device on VS code.

This item describes how to connect the S4 board to the PC host, install an extension, import the project, configure file launch.json, run and debug.

4.2.1.2. Connecting S4 board to PC host

We need to connect between board and PC to debug multicore ARM on VSCode as shown in the picture below:

Select the mode for S4 Spider Configuration tool -Renesas as shown below:

4.2.1.3. Setup debugger options

Install the Renesas Debug extension to VSCode (please refer to Section 1: Installation).
Import the built CA55 and CR52 projects into VS Code.

In order to debug a project using VS Code and the Renesas Debug extension, a configuration file called launch.json needs to be created.

Select [Run and Debug] view.
Select [Create a launch.json file] link.
Select [Renesas Amalgamator].
A launch.json file will be created inside .vscode folder with some default settings.

In the launch.json file, fill in the following fields.

launch.json

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "type": "renesas-amalgamator",
      "request": "launch",
      "name": "<display name of the configuration>",
      "children": [
        {
          "name": "<display name of core>",
          "debugAdapterRuntime": "node",
          "multipleCore": true,
          "interfaceName": "CortexR52",
          "interfaceType": "GDB",
          "arguments": {
            "type": "renesas-rcar",
            "request": "launch",
            "hardwareBreakpoint": true,
            "program": "<absolute path to project's executable file (.x, .elf,...)>",
            "target": {
              "deviceFamily": "RCAR",
              "device": "<CPU of the device>",
              "debuggerType": "<type of the debugger>"
            }
          }
        },
        {
          "name": "<display name of core>",
          "debugAdapterRuntime": "node",
          "multipleCore": true,
          "request": "attach",
          "arguments": {
            "type": "renesas-rcar",
            "request": "attach",
            "hardwareBreakpoint": true,
            "program": "<absolute path to project's executable file (.x, .elf,...)>",
            "target": {
              "deviceFamily": "RCAR",
              "device": "<CPU of the device>",
              "debuggerType": "<type of the debugger>",
            }
          }
        }
      ]
    }
  ]
}

Example configuration file launch.json:

Example: launch.json

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "type": "renesas-amalgamator",
      "request": "launch",
      "name": "Debug Multiple",
      "children": [
        {
          //ARM Core CA55
          "name": "CA55",
          "debugAdapterRuntime": "node",
          "multipleCore": true,
          "interfaceName": "CortexR52",
          "interfaceType": "GDB",
          "arguments": {
            "type": "renesas-rcar",
            "request": "launch",
            "hardwareBreakpoint": true,
            "program": "${cwd}/CACore_Project/build/release/ca55_loader.elf",
            "target": {
              "deviceFamily": "RCAR",
              "device": "R8A779F0",
              "debuggerType": "E2ARM",
              "serverParameters": ["-uInteface=", "JTAG", "-w", "0", "-uConnectMode=", "RESET", "-uWorkRamAddress=", "0x0", "-uSyncMode=", "async", "--gdbVersion=", "7.2"]
            },
          }
        },
        {
          //ARM Core CR52
          "name": "CR52",
          "debugAdapterRuntime": "node",
          "multipleCore": true,
          "request": "attach",
          "arguments": {
            "type": "renesas-rcar",
            "request": "attach",
            "hardwareBreakpoint": true,
            "program": "${cwd}/CRCore_Project/build/release/cr52_loader.elf",
            "target": {
              "deviceFamily": "RCAR",
              "device": "R8A779F0_CR52",
              "debuggerType": "E2ARM"
            },
          }
        }
      ]
    }
  ]
}

4.2.1.4. Start debugging

After setting up debugger options, a debug session can be started by selecting the created configuration and click [Start Debugging] button in [Run and Debug] view, or press [F5].

Waiting for the program to launch and debug successfully.

Displaying variables, watch expression, call stack… are supported in VS Code:

Select [View] → [Open View…]

Select the Views to be displayed on the window.

4.2.2. Setup environment and debug project ARM & G4MH using renesas-amalgamator

4.2.2.1. Overview

Support multiple different (ARM/G4MH) cores for R-Car S4 device on VS code.

This item describes how to debug (Project ARM+G4MH).

4.2.2.2. Connecting S4 board to PC host

We need to connect between board and PC to debug ARM and G4MH on VSCode as shown in the picture below:

Select the mode for S4 Spider Configuration tool -Renesas as shown below:

4.2.2.3. Setup debugger options

Install the Renesas Debug extension to VSCode (please refer to Section 1: Installation).
Import the built G4MH and CR52 projects into VS Code.

In order to debug a project using VS Code and the Renesas Debug extension, a configuration file called launch.json needs to be created.

Select [Run and Debug] view.
Select [Create a launch.json file] link.
Select [Renesas Amalgamator].
A launch.json file will be created inside .vscode folder with some default settings.

In the launch.json file, fill in the following fields

launch.json

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "type": "renesas-amalgamator",
      "request": "launch",
      "name": "<display name of the configuration>",
      "children": [
        {
          //RH850 Core G4MH
          "name": "<display name of core>",
          "debugAdapterRuntime": "node",
          "arguments": {
            "type": "renesas-rcar",
            "request": "launch",
            "program": "<absolute path to project's executable file (.x, .elf,...)>",
            "target": {
              "deviceFamily": "RCAR",
              "device": "<CPU of the device>",
              "debuggerType": "<type of the debugger>"
            }
          }
        },
        {
          //Core Arm (CA/CR)
          "name": "<display name of core>",
          "debugAdapterRuntime": "node",
          "arguments": {
            "type": "renesas-rcar",
            "request": "launch",
            "program": "<absolute path to project's executable file (.x, .elf,...)>",
            "target": {
              "deviceFamily": "RCAR",
              "device": "<CPU of the device>",
              "debuggerType": "<type of the debugger>"
            }
          }
        }
      ]
    }
  ]
}

Example configuration file launch.json:

Example launch.json

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "type": "renesas-amalgamator",
      "request": "launch",
      "name": "Debug Multiple",
      "children": [
        {
          //RH850 Core G4MH
          "name": "G4MH",
          "debugAdapterRuntime": "node",
          "arguments": {
            "type": "renesas-rcar",
            "request": "launch",
            "program": "${cwd}/G4MH/HardwareDebug/G4MH_Debug.x",
            "target": {
              "deviceFamily": "RCAR",
              "device": "R8A779F0",
              "debuggerType": "E2RH850",
              "serverParameters": ["-ulpdType=","15","-uJTagClockFreq=","Default","-setOptJtagLpd=","-uocdID=","0000000000000000000000000000000000000000000000000000000000000000","-ucustomerID=","0000000000000000000000000000000000000000000000000000000000000000","-uneedAuthentication=","0","-uWorkRamAddress=","0x0","-uTraceEnable=","PE0|PE1","-uTraceClock=","PE0|400|PE1|400","-uUseSyncTrace=","1","-uSyncTraceStandard=","0","-uTraceCore=","PE0","--gdbVersion=","7.2"]
            },
          }
        },
        {
          //Core Arm (CA/CR)
          "name": "ARM",
          "debugAdapterRuntime": "node",
          "arguments": {
            "type": "renesas-rcar",
            "request": "launch",
            "program": "${cwd}/BAREMETAL_CR52/Debug/MR_BAREMETAL_CR52.axf",
            "target": {
                "deviceFamily": "RCAR",
                "debuggerType": "E2RARM",
                "device": "R8A779F0_CR52",
                "serverParameters": ["-uInteface=", "JTAG", "-w", "0", "-uWorkRamAddress=", "0x0", "--gdbVersion=", "7.2"]
            },
          }
        }
      ]
    }
  ]
}

4.2.2.4. Start debugging

In the select box RUN AND DEBUG (ctrl+shift+D) select "Debug Multiple" option then click [Start Debugging] (F5) button.

Waiting for program to launch and debug successfully.

4.2.3. Setup environment and debug multi-core ARM device R-Car S4 (CA55: CPU0 to CPU7)

4.2.3.1. Overview

Support debug multicore with CA55 (CPU0 → CPU7) for R-Car S4 device on VS code.

This item describes how to connect the S4 board to the PC host, install an extension, import the project, configure file launch.json, run and debug.

4.2.3.2. Connecting S4 board to PC host

We need to connect between board and PC to debug multicore ARM on VSCode as shown in the picture below:

Select the mode for S4 Spider Configuration tool -Renesas as shown below:

4.2.3.3. Setup debugger options

Install the Renesas Debug extension to VSCode. (Refer to section 2.1 Setup VS Code)
Import the built CA55 projects into VS Code.

In order to debug a project using VS Code and the Renesas Debug extension, a configuration file called launch.json needs to be created.

Select [Run and Debug] view.
Select [Create a launch.json file] link.
Select [Renesas Amalgamator].
A launch.json file will be created inside .vscode folder with some default settings.

In the launch.json file, fill in the following fields.

launch.json

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "type": "renesas-rcar",
      "request": "launch",
      "name": "<display name of the configuration>",
      "program": "<absolute path to project's executable file (.x, .elf,...)>",
      "target": {
        "debuggerType": "<type of the debugger>",
        "device": "<CPU of the device>",
        "deviceFamily": "RCAR",
      }
    }
  ]
}

Example configuration file launch.json:

Example: launch.json

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
      {
        "type": "renesas-rcar",
        "request": "launch",
        "name": "RCAR Multicore CA55",
        "program": "${cwd}/Debug/MR_BAREMETAL_CA55.axf",
        "target": {
          "deviceFamily": "RCAR",
          "device": "R8A779F0_CA55",
          "debuggerType": "E2ARM",
          "serverParameters": ["-uInteface=", "JTAG", "-w", "0", "-uConnectMode=", "RESET", "-uWorkRamAddress=", "0x0", "-uSyncMode=", "async", "--gdbVersion=", "7.2"]
        },
      },
    ]
}

4.2.3.4. Start debugging

After setting up debugger options, a debug session can be started by selecting the created configuration and click [Start Debugging] button in [Run and Debug] view, or press [F5].

Waiting for the program to launch and debug successfully.

4.2.4. Setup environment and debug multi-core G4MH device R-Car S4 or device RH850

4.2.4.1. Overview

Support debug multicore with multi-core G4MH for R-Car S4 device (PE0, PE1) or device RH850 (PE0,PE1,PE2,PE3) on VS code.

This item describes how to connect the S4 board or RH850 board to the PC host, install an extension, import the project, configure file launch.json, run and debug.

4.2.4.2. Connecting S4 board to PC host

We need to connect between board and PC to debug multicore ARM on VSCode.

Select the mode for S4 Spider Configuration tool -Renesas if debug with R-Car S4 device.

4.2.4.3. Setup debugger options

Install the Renesas Debug extension to VSCode. (Refer to section 2.1 Setup VS Code)
Import the built CA55 projects into VS Code.

In order to debug a project using VS Code and the Renesas Debug extension, a configuration file called launch.json needs to be created.

Select [Run and Debug] view.
Select [Create a launch.json file] link.
Select [Renesas Amalgamator].
A launch.json file will be created inside .vscode folder with some default settings.

In the launch.json file, fill in the following fields.

launch.json

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "type": "<type>",
      "request": "launch",
      "name": "<display name of the configuration>",
      "program": "<absolute path to project's executable file (.x, .elf,...)>",
      "target": {
        "deviceFamily": "<the device family name Eg.RCAR>",
        "device": "<CPU of the device>",
        "debuggerType": "<debugger type (type of the simulator or emulator)>"
      }
    }
  ]
}

Example configuration file launch.json:

Example: launch.json multi-core G4MH for R-Car S4 device (PE0, PE1)

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "configurations": [
    {
      "name": "G4MH",
      "type": "renesas-rcar",
      "request": "launch",
      "hardwareBreakpoint": true,
      "program": "${cwd}/HardwareDebug/G4MH_Debug.x",
      "target": {
        "deviceFamily": "RCAR",
        "device": "R8A779F0",
        "debuggerType": "E2RH850",
        "serverParameters": ["-ulpdType=","15","-uJTagClockFreq=","Default","-setOptJtagLpd=","-uocdID=","0000000000000000000000000000000000000000000000000000000000000000","-ucustomerID=","0000000000000000000000000000000000000000000000000000000000000000","-uneedAuthentication=","0","-uWorkRamAddress=","0x0","-uTraceEnable=","PE0|PE1","-uTraceClock=","PE0|400|PE1|400","-uUseSyncTrace=","1","-uSyncTraceStandard=","0","-uTraceCore=","PE0","--gdbVersion=","7.2"]
      }
    }
  ]
}

Example: launch.json multi-core for device RH850 (PE0,PE1,PE2,PE3)

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "configurations": [
    {
      "name": "RH850",
      "type": "renesas-rcar",
      "request": "launch",
      "hardwareBreakpoint": true,
      "program": "${cwd}/HardwareDebug/Project_RH850.x",
      "target": {
        "deviceFamily": "RH850",
        "device": "R7F702Z19A",
        "debuggerType": "E2",
        "serverParameters": ["-ulpdType=", "15","-setOptJtagLpd=", "0", "-w", "1", "-usupplyVoltage=", "0", "-uocdID=", "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF"]
      }
    }
  ]
}

4.2.5. Create and build G4MH project on R-Car SDK

4.2.5.1. Create G4MH project

From the menu bar select File > New > Renesas C/C++ Project > Renesas R-Car

Select R-Car project template "Renesas CC-RH C Executable Project", then click Next button

Input the project name then click Next button.

In New Renesas CC-RH Executable Project select Create Hardware Debug Configuration "E2 (RH850)", then click Finish button

Projects will be created.

4.2.5.2. Build project G4MH

Right-click on the project and select "Build Project"

Or can click on the "Build" icon on the toolbar.

Project after built.

4.2.6. Build CVEngine project on R-Car SDK

4.2.6.1. Build CVEngine project on R-Car SDK

From the menu bar select File > Import…

Select Dialog Import "Existing Projects into Workspace", then click Next button

Select Dialog Import "Select archive file" > Select Browse… > Select the project you want to build in your directory, then click Finish button.

Project after imported

4.2.6.2. Build project

Right-click on the project and select "Clean Project"

Check Toolchain Configuration: From the menu bar select File > Window > Preferences

Select Launch Configuration (the name of the project is imported), and Launch Target "V4H DevBoard" on the toolbar.

Select "Edit" icon of Launch Target "V4H DevBoard" on the toolbar, then select Target Device "Development board / SoC" and IMP Debug Level "CVe (Shader debugging)", then click Finish button.

Right-click on the project and select "Build Project"

Project after built

4.2.7. How to use COMPORT debugger for RL78 devices

Some types of Renesas RL78 devices support com port connection for debugging operations. Developers can use "COMPORT" debugger type to start debug session using com port connection. Format of the launch configuration for "COMPORT" debugger type is shown below:

launch.json format

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "renesas-hardware",
            "request": "launch",
            "name": "<display name of the configuration>",
            "target": {
                "deviceFamily": "RL78",
                "device": "<device code>",
                "debuggerType": "COMPORT",
                "comPort": "<connection port (e.g. COM1)>"
            }
        }
    ]
}

The following configuration is an example launch configuration for R7F100GLG device connected via COM1 port:

launch.json example for using com port

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "type": "renesas-hardware",
      "request": "launch",
      "name": "Renesas GDB Debugging",
      "target": {
        "deviceFamily": "RL78",
        "device": "R7F100GLG",
        "debuggerType": "COMPORT",
        "comPort": "COM1"
      }
    }
  ]
}

4.2.8. How to use SEGGER J-Link Tunnel debugging for Dialog and RA devices

SEGGER J-Link supports tunnel debugging, which enables starting a debug session on a remote device using J-Link Tunnelling. With Renesas Hardware Debugger, you can easily access to configure this feature to start a debug session on a remote device for Dialog and RA device families.

Note

Before starting this guide, use the following link to download the latest J-Link software that is suitable for your operating system:

https://www.segger.com/downloads/jlink/

For more details about how J-Link Remote Server works, please refer to the SEGGER documentation:

https://www.segger.com/products/debug-probes/j-link/tools/j-link-remote-server/.

4.2.8.1 Start a SEGGER J-Link Remote Server

Firstly, you need to connect your device and start the SEGGER J-Link Remote Server on your remote host machine. Please perform the following steps for this operation:

Connect your device to your remote host machine.
Start the SEGGER J-Link Remote Server program on your remote host machine.
Configure the tunnel server settings.

3.1. Select connection method, for example, select "Use SEGGER tunnel server".

3.2. Choose the nearest SEGGER tunnel to your location.

3.3. Choose either "Register by S/N" or "Register by Name" for the identifier definition. If you choose "Register by S/N", then the serial number of the device will be used in the identifier definition; or you can choose "Register by Name" and define the identifier (Please note that, here, the name is defined as 'renesas-test-ra2e1' as an example, please choose a different unique value for your connection settings).

3.4. Set a password for the connection. We strongly recommended to set a password for protecting the device connections.
Click "OK" to continue.
In the second window, you can see that J-Link Remote server is waiting for client connections.

4.2.8.2. Configuring Debug Launch Configuration of the Project

Secondly, we are going to define the launch configuration in the project to connect to the remote device during the debug session. Go to the .vscode/launch.json file and define the debug launch configuration as described below:

launch.json format

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "type": "renesas-hardware",
      "request": "launch",
      "name": "<display name of the configuration>",
      "target": {
        "deviceFamily": "<device family, RA or Dialog>",
        "device": "<device code>",
        "debuggerType": "SEGGERJLINKARM",
        "tunnel": {
          "server": "<tunnel server address>",
          "identifier": "<serial number or defined name in the connection>",
          "password": "<password for connecting to the device>"
        }
      }
    }
  ]
}

The following configuration is an example launch configuration for using SEGGER J-Link Tunnel to connect to a remove RA2E1 device:

launch.json example for using SEGGER J-Link Tunnel for RA

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "type": "renesas-hardware",
      "request": "launch",
      "name": "Renesas GDB Debugging with SEGGER J-Link Tunnel",
      "target": {
        "deviceFamily": "RA",
        "device": "R7FA2E1A9",
        "debuggerType": "SEGGERJLINKARM",
        "tunnel": {
          "server": "jlink-europe.segger.com",
          "identifier": "renesas-test-ra2e1",
          "password": "EnterThePasswordHere"
        }
      }
    }
  ]
}

Now, we are ready to start a debug session to connect to the remote device. To start the debug session, go to the "Run and Debug" tab in VSCode, then select the configuration, and click the "Start Debugging" button.

Note	For more details about starting the debug session, please refer to the section 3.2. Starting the Debug Session.

4.2.9. How to specify custom GDB server parameters

Renesas VS Code extensions will automatically inject default values required to be passed to GDB server in debug session. On the other hand, it is possible to override GDB server parameters passed in debug session. For this purpose, "serverParameters" option could be used to pass the custom GDB server parameters.

First, developer need to find the device family/device specific parameters and their default values. It could accessed by starting debug session started with a default configuration like shown below in VS Code. After the start of the debug session, the server parameters shown in the flow of [DEBUG CONSOLE] panel, with line starting with [Raw options] text.

Then, the raw options list needs to be converted to "serverParameters" array. The example for this operation is shown below:

Raw options

-g SIMULATOR -t R5F51101 -uConnectionTimeout= 30 -uPeripheralClkRatio= 1 -uCpuClkFreq= 12 -uRegisterSetting= 0 -uModePin= 0 -uCacheDecode= 1 -n 0 -uWorkRamAddress= 0 -uEmStopInt= 1 -uEmStopInterrupt= 1 -uEmStopFPexp= 1 -l -uCore= SINGLE_CORE|enabled|1|main -uSyncMode= async -uFirstGDB= main --english --gdbVersion= 7.2

"serverParameters" array

["-uConnectionTimeout=", "30", "-uPeripheralClkRatio=", "1", "-uCpuClkFreq=", "12", "-uRegisterSetting=", "0", "-uModePin=", "0", "-uCacheDecode=", "1", "-n", "0", "-uWorkRamAddress=", "0", "-uEmStopInt=", "1", "-uEmStopInterrupt=", "1", "-uEmStopFPexp=", "1", "-l", "-uSyncMode=", "async", "-uFirstGDB=", "main", "--english", "--gdbVersion=", "7.2"]

Note: Please note that -g parameter which is defined as debuggerType, and -t parameter which is defined as device on target parameters of launch configuration; and -uCore= parameter which is injected by Renesas VS Code Extension itself removed from the list and they should not be passed in "serverParameters" array.

At last, the parameter array could be passed via "serverParameters" in "target" configuration.

launch.json example for overriding GDB server parameters

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "type": "renesas-simulator",
      "request": "launch",
      "name": "Renesas GDB Debugging",
      "program": "${command:askProgramPath}",
      "target": {
        "deviceFamily": "RX",
        "device": "R5F51101",
        "debuggerType": "SIMULATOR",
        "serverParameters": ["-uConnectionTimeout=", "30", "-uPeripheralClkRatio=", "1", "-uCpuClkFreq=", "12", "-uRegisterSetting=", "0", "-uModePin=", "0", "-uCacheDecode=", "1", "-n", "0", "-uWorkRamAddress=", "0", "-uEmStopInt=", "1", "-uEmStopInterrupt=", "1", "-uEmStopFPexp=", "1", "-l", "-uSyncMode=", "async", "-uFirstGDB=", "main", "--english", "--gdbVersion=", "7.2"]
      }
    }
  ]
}

It is not required to pass all the parameters in the launch.json file while overriding the parameters. Developer can choose necessary parameters and override their values by passing them with their new values through "serverParameters", parameters that do not require value change does not need to be defined again.

For example, to only change -uConnectionTimeout= parameter the following configuration could be used:

launch.json example for overriding GDB server parameters

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "type": "renesas-simulator",
      "request": "launch",
      "name": "Renesas GDB Debugging",
      "program": "${command:askProgramPath}",
      "target": {
        "deviceFamily": "RX",
        "device": "R5F51101",
        "debuggerType": "SIMULATOR",
        "serverParameters": ["-uConnectionTimeout=", "120"]
      }
    }
  ]
}

Alternatively, it is also possible for to use a project created and built in e² studio to get the GDB server parameters. For this purpose, start a debug session in e² studio, then, the GDB server parameters will be displayed in [Console] with line starting with [Raw options] text.

4.2.10. Installing CMake and Ninja Build using winget

It is a straightforward process if you want to use winget package manager for CMake and Ninja Build installation. Please run the following commands in Windows Command Prompt:

> winget install Kitware.CMake
> winget install Ninja-build.Ninja

Note

The winget is a command line tool enables users to discover, install, upgrade, remove and configure applications on Windows 10 and Windows 11 computers. This tool is the client interface to the Windows Package Manager service.

For more information, please visit:

https://learn.microsoft.com/en-us/windows/package-manager/winget/

4.2.11. Setting up a build environment with MinGW over MSYS2 for Windows

For the projects that require MinGW Makefiles in the development environment on Windows, install CMake and MSYS2 packages.

Step 1: Install the latest CMake version for Windows.

Download the latest version of CMake for Windows.

https://cmake.org/download/
Install CMake for Windows.

Important!: You must add the CMake folders to the "Path" environment variable. The Windows Installer of CMake has an option to modify the system’s environment variables and add the CMake folders to the "Path" variable. Please select this option during installation. If you are not using the installer or this option is not selected during installation, please use the notes at step 3 to manually add CMake’s bin folder to the Path variable.

Step 2: Install and configure the latest MSYS2 package.

Download the latest version of the "MSYS2" package.

https://www.msys2.org/.
Install the MSYS2 package. The MSYS2 package will automatically install the MinGW environment.
Use Windows Search to find and open "MSYS2 MINGW64" terminal.
Install the make package for MinGW64 using pacman package manager.
```
$ pacman -S mingw-w64-x86_64-make
```
Check if make package is installed correctly.
```
$ mingw32-make --version
```

Note

make package is a 32-bit package. You can install it by using "MSYS2 MINGW32" terminal instead of "MSYS2 MINGW64" terminal. If you are using "MSYS2 MINGW32" then run the following command for the installation:

$ pacman -S mingw-w64-i686-make

Also, please make sure you include the correct folder for the "Path" environment variable in the next step (e.g. C:\msys64\mingw32\bin).

Step 3: Configure the Path environment variable.

Use Windows Search to find and open "Edit the system environment variables"
In the "Advanced" tab, click on the "Environment Variables…" button to open the "Environment Variables" dialog.
Select to edit the "Path".
Add the path of CMake’s bin folder if it is not defined during the CMake installation. (e.g. C:\Program Files\CMake\bin).
Add the path of the MSYS2 and MinGW bin folders. (e.g. C:\msys64\usr\bin, C:\msys64\mingw64\bin).

4.3. Troubleshooting and Common Issues

4.3.1. Setup environment when using renesas-amalgamator

When debugging with renesas-amalgamator users need to install Node.js. You can download and install Node.js from Node v16.20.0 (LTS).

4.3.2. Debugging failed with message: Don’t know how to attach. Try "help target".

If the debug session failed with the error message [Don’t know how to attach. Try "help target".], then open the launch.json file and control the serverParameters array. There shouldn’t be any -uCore= parameter in the "serverParameters" array. Any definition of -uCore= needs to be removed from the "serverParameters" array.

4.3.3. Renesas extensions failed in macOS: "Error occurred during *.xz file extraction. Please check the installation requirements of Renesas VS Code Extensions."

If the error message "Error occurred during *.xz file extraction. Please check the installation requirements of Renesas VS Code Extensions." appeared while using Renesas extensions in macOS, it is probably because the "XZ Archive Manager", which is one of the prerequisites for using Renesas extensions in macOS, is not installed in the development environment.

Install the XZ Archive Manager by using brew install xz command.

$ brew install xz

Also, please refer to the installation steps in the section 1.2. Installing Prerequisites for the Development Environment to check any other steps missed during the setup.

Note	Installation steps for macOS use Homebrew (`brew`), which is an open-source software package management system that simplifies the installation of software for macOS. For installation and more information about Homebrew, please refer to https://brew.sh/.

4.3.4. Renesas Project Build is failing due to incorrect CMake Generator

Renesas build scripts require "Ninja Build" to run correctly. In development environments, where multiple CMake Generators are installed, developers needed to be aware of the selected CMake Generator during the build operation. If the build operation fails due to incorrect CMake Generator. Please check the following steps:

Step 1: Check the Ninja Build installation.

Open a terminal window.
Run the following command to check if "Ninja Build"
```
ninja --version
```
If the command fails. Please check the installation guide and control the installation steps for Ninja Build in section 1.2.1. Prerequisites for Building.

Step 2: Set the Ninja Build as the default Cmake Generator for the project

If Ninja Build is not the default CMake Generator in your environment, you can still define Ninja Build to be selected as the default Cmake Generator for your project. To make this definition, please follow the instructions below:

Open VS Code settings using "File" ⇒ "Preferences" ⇒ "Settings" menu.
Search for "cmake generator", and switch to the "Workspace" tab.
Then, set the value of the "Cmake: Generator" to "Ninja"

Note

Alternative Method: Changing the settings file directly

Alternatively, you can directly change the settings file of your project to make "Ninja" your CMake Generator for this project.

Open the ".vscode/settings.json" file in your project folder.
Insert the following definition into the file:

"cmake.generator": "Ninja"

Step 3: Delete the old build cache and rebuild the project

After making these changes, please delete the old build cache and rebuild the project again.

Open VS Code command palette by running "View" ⇒ "Command Palette"
Find and click to "CMake: Delete Cache and Reconfigure"
Then, build the project again by opening the Command Palette again ("View" ⇒ "Command Palette") and running the "CMake: Build" command.

< 3. Debugging a Project