3. Debugging a Project

Important

Please also refer to Configure C/C++ debugging in Visual Studio Code documents for descriptions of launch.json.
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	RA Smart Configurator is automatically creating the launch.json file while generating the project files. If you already generated the project using RA Smart Configurator, then you can skip to section 3.2. Starting the debug session.

Select [Run and Debug] view.
Select [create a launch.json file] link.
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 Linux Target: For running the debug session on R-Car family devices which are running Linux operating system.
5. Renesas RCAR Target: For running the debug session on R-Car family devices.
VS Code will generate "launch.json" file will be created inside ".vscode" folder with some default settings.

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 4.1.3. 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 4.1.9. Setting up the RA Debug Environment for VS Code.

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:

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. For Renesas GDB Hardware Target, an example launch configuration shown below:

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

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

E2LITE

SEGGERJLINKARM

RH850

RL78

E2LITE

IECUBE

COMPORT

E20

E2LITE

SEGGERJLINKRX

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

3.1.4. 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.1.5. 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, SIMULATOR, LAN

RH850

E1, E2, IE850ARH850

3.2. Starting the debug session

After setting up the launch configuration, 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.

< 2. Creating and Building a Project

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