3. Debugging a Project

Important

1. Please also refer to Configure C/C++ debugging in Visual Studio Code documents for descriptions of launch.json.

2. Please note that the debugger type “renesas” is changed to specific adapter types after the 23.10.10 version of the Renesas Debug extension. If you are still using the “renesas” debugger type in your .vscode/launch.json file, Please read this section carefully and convert your existing configuration.

3.1. Configuring the launch configuration

In order to start debugging a project using VS Code and the Renesas Debug extension, a configuration file called “launch.json” needs to be created. Please follow the instructions below to create the launch configuration:

Note

Smart Configurators are automatically creating the launch.json file while generating the project files. If you already generated the project using a Smart Configurator, then you can skip to section “Starting the debug session”.

1. Select [Run and Debug] view.

   

2. Select [create a launch.json file] link.

   

3. Select one of the Renesas debuggers from the options menu:

   1. Renasas Amalgamator: For running the debug session on R-Car S4 devices with ARM/G4MH, CA55 and CR52 cores.

   2. Renesas GDB Hardware Target: For running the debug session on Dialog, RA, RH850, RL78, RX or RZ device families.

   3. Renesas GDB Simulator Target: For running the debug session on RL78 or RX device family simulators.

   4. Renesas RCAR Target: For running the debug session on R-Car family devices.

   5. Renesas RCAR Linux Target: For running the debug session on R-Car family devices which are running Linux operating system.

   

4. VS Code will generate “launch.json” file will be created inside “.vscode” folder with some default settings.

   

5. 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 (Dialog, RA, RCAR, RH850, RL78, RX or RZ)>",
                   "device": "<device code>",
                   "debuggerType": "<debugger type (type of the simulator or emulator)>"
               }
           }
       ]
   }
   

Note

Different Renesas debuggers support different device families and emulator/simulator types. Please check the section Debuggers, Device Families and Emulator/Simulator Types in launch.json for more details.

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 in section Installation at Quick Start for Renesas RA.

3.1.1. Renesas Amalgamator

Renesas Amalgamator (renesas-amalgamator) type supports debugging session for R-Car S4 devices with ARM/G4MH, CA55 and CR52 cores. Please refer to the advanced guidelines for more details:

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

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

3.1.2. Renesas GDB Hardware Target

Renesas GDB Hardware Target (renesas-hardware) type enables the emulator debugging for hardware devices with RA, RH850, RL78, RX, RZ or Dialog device family Renesas MCU’s. Here are some examples of launch configurations for the Renesas GDB Hardware Target:

.Example launch.json for “Renesas GDB Hardware Target” for RA device family

{
  // 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 Hardware Debugging",
      "target": {
        "deviceFamily": "RA",
        "device": "R5F51101",
        "debuggerType": "SEGGERJLINKARM"
      }
    }
  ]
}

.Example launch.json for “Renesas GDB Hardware Target” for RH850 device family

{
  // 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 Hardware Debugging",
      "target": {
        "deviceFamily": "RH850",
        "device": "R7F701275", // U2B10 use R7F70254x_Fusa or R7F70254x_Performance
        "debuggerType": "E2",
        "serverParameters": ["-uocdID=", "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF"]
      }
    }
  ]
}

Note

If you want to use the E2 emulator as a power supply instead of an external power source, please set the serverParameters configuration as follows:

"serverParameters": ["-uocdID=", "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF","-w", "1", "-usupplyVoltage=","1"]

.Example launch.json for “Renesas GDB Hardware Target” for RL78 device family (F22, F23, F24, F25 series)

{
  // 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 Hardware Debugging",
      "target": {
        "deviceFamily": "RL78",
        "device": "R7F124FBJ",
        "debuggerType": "E2LITE",
        "serverParameters": ["-usecurityID=", "00000000000000000000000000000000", "-usecurityIdSize", "16", "-uprogrammerSecurityID=", "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF"]
      }
    }
  ]
}

Note

Except for the RH850 device family and RL78 (F22, F23, F24, F25 series), other devices share a similar launch.json structure with the RA device family.

Renesas GDB Hardware Target (renesas-hardware) supports variety of device families and hardware debug emulators. Supported device families and debug emulator type listed below:

Debugger	type	target.deviceFamily	target.debuggerType
Renesas GDB Hardware Target	renesas-hardware	Dialog	SEGGERJLINKARM
		RA	E2, E2LITE, SEGGERJLINKARM
		RH850	E1, E2
		RL78	E1, E2, E2LITE, IECUBE, COMPORT
		RX	E1, E2, E2LITE, E20, SEGGERJLINKRX
		RZ	SEGGERJLINKARM

Note

• RA Smart Configurator is generating the contents of the launch.json file during the project initialisation.

• Dialog ADP projects already contain a pre-defined launch.json file. Please check the “target.device” definition in the pre-defined launch configuration, and change the value of the “target.device” to the targeted device if necessary.

3.1.3. Renesas GDB Simulator Target

Renesas GDB Simulator Target (renesas-simulator) type enables the debugging operation for RL78 and RX device family simulators in developer machine. Here is an example launch configuration for using simulator for an RX device family project:

.launch.json example for project build with GCC toolchain

{
  // 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",
      "target": {
        "deviceFamily": "RX",
        "device": "R5F51101",
        "debuggerType": "SIMULATOR"
      }
    }
  ]
}

Renesas GDB Simulator Target (renesas-simulator) supports simulators for RL78 and RX device families.

Debugger	type	target.deviceFamily	target.debuggerType
Renesas GDB Simulator Target	renesas-simulator	RL78	SIMULATOR
		RX	SIMULATOR

3.1.4. Renesas RCAR Target

Renesas RCAR Target (renesas-rcar) type enables the debugging operation for R-Car devices. Here is an example launch configuration for an R-Car device family project:

.launch.json example for project

{
  // 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"
      }
    }
  ]
}

Renesas RCAR Target (renesas-rcar) also supports debugging CVe for Linux Target devices. Here is an example of a launch configuration for Linux Target + CVe debugging:

.launch.json example for project

{
  // 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": "2.0.0",
  "configurations": [
    {
      "name": "ARM",
      "type": "renesas-rcar",
      "request": "launch",
      "targetOS": "linux",
      "program": "${cwd}/build/rcar.debug.DevBoard/imp_inversion_sample_app_v4h2_d",
      "imageAndSymbols": {
        "symbolFileName": "${cwd}/build/rcar.debug.DevBoard/imp_inversion_sample_app_v4h2_d",
      },
      "target": {
        "host": "10.0.0.2",
        "port": "2345",
        "deviceFamily": "RCAR",
        "device": "R8A779G2",
        "debuggerType": "LAN",
      }
    },
    {
      "name": "CVEngine",
      "type": "renesas-rcar",
      "request": "launch",
      "isCVEngine": true,
      "targetOS": "linux",
      "program": "${cwd}/build/rcar.debug.DevBoard/inversion.out",
      "imageAndSymbols": {
        "symbolFileName": "${cwd}/build/rcar.debug.DevBoard/inversion.out",
        "symbolOffset": "0x0"
      },
      "target": {
        "server": "sdb binary file",
        "host": "10.0.0.2",
        "port": "9876",
        "deviceFamily": "RCAR",
        "device": "R8A779G2",
        "type": "extended-remote",
        "debuggerType": "LAN",
      }
    }
  ],
  "compounds": [
    {
      "name": "ARM + CVEngine",
      "configurations": [
        "ARM",
        "CVEngine",
      ]
    }
  ]
}

Renesas RCAR Target (renesas-rcar) supports the following configurations:

Debugger	type	target.deviceFamily	target.debuggerType
Renesas RCAR Target	renesas-rcar	RCAR	E2ARM, E2RH850, IE850ARH850, LAUTERBACHT32
		RH850	E1, E2, IE850ARH850

3.1.5. Renesas RCAR Linux Target

Renesas RCAR Linux Target (renesas-rcar-linux) type enables the debugging operation for Renesas R-Car family Linux devices. Renesas RCAR Linux Target is using SSH connection to connect target device, automatically creating a SSH Tunnel between the target device and the developer machine during the debug session.

The following configuration contains a sample definition for Renesas RCAR Linux Target, where the board accepts username/password authentication method for SSH connection:

.launch.json example for Renesas RCAR Linux project

{
  // 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-linux",
      "request": "launch",
      "name": "Renesas RCAR Linux Debugging",
      "program": "${workspaceFolder}/build/rcar.debug.V3H2/helloworld_sample_app_v3h2_d",
      "target": {
        "deviceFamily": "RCAR",
        "device": "V3H2",
        "debuggerType": "RCAR_PROXY",
        "ssh": {
          "host": "10.0.0.2",
          "user": "root",
          "password": "the-password",
        }
      }
    }
  ]
}

Renesas RCAR Linux Target also supports RSA private key authentication method. The following configuration shows how to pass the private key information to the debug session.

.launch.json example for Renesas RCAR Linux project with private key authentication

{
  // 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-linux",
      "request": "launch",
      "name": "Renesas RCAR Linux Debugging",
      "program": "${workspaceFolder}/build/rcar.debug.V3H2/helloworld_sample_app_v3h2_d",
      "target": {
        "deviceFamily": "RCAR",
        "device": "V3H2",
        "debuggerType": "RCAR_PROXY",
        "ssh": {
          "host": "10.0.0.2",
          "user": "root",
          "privateKeyPath": "~/.ssh/id_rsa"
        }
      }
    }
  ]
}

Renesas RCAR Linux Target (renesas-rcar-linux) supports the following configuration:

Debugger	type	target.deviceFamily	target.debuggerType
Renesas RCAR Linux Target	renesas-rcar-linux	RCAR	RCAR_PROXY

3.2. Starting the debug session

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.

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.

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.