17. Advanced Guidelines

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

17.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.

17.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:

_images/connecting-s4-board-to-pc-host.gif

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

17.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.
For debugging multicore with multiple architectures on a single device, the configuration can be combined into a single launch entry.

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

Example configuration file launch.json:

17.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:
1. Select [View] -> [Open View…]
2. Select the Views to be displayed on the window.

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

17.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).

17.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:

_images/connecting-arm-and-g4mh-to-pc.gif

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

17.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

Example configuration file launch.json:

17.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.

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

17.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.

17.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:

17.3.3. Setup debugger options

Install the Renesas Debug extension to VSCode. (please refer to Section 1: Installation).
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 GDB Hardware Target].
A launch.json file will be created inside .vscode folder with some default settings.

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

Example configuration file launch.json:

17.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.

_images/waiting-for-ca55-to-debug-successfully.png

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

17.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.

17.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.

17.4.3. Setup debugger options

Install the Renesas Debug extension to VSCode. (please refer to Section 1: Installation).
Import the built G4MH/RH850 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 GDB Hardware Target].
A launch.json file will be created inside .vscode folder with some default settings.

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

Format of .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)>"
      }
    }
  ]
}

Sample configurations for launch.json file:

17.5. Create and build G4MH project on R-Car SDK

17.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.

17.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.

17.6. Build CVEngine project on R-Car SDK

17.6.1. Create Project

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

17.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

17.7. How to specify device specific parameters in CMake scripts

Note

The following instructions are applicable for non Smart Configurator projects. The projects generated by the Smart Configurators will already have the correct build scripts, including device specific parameters for the target device.

17.7.1. Creating CMake Toolchain Scripts and Building the Project

It is recommended to use the Smart Configurators in VS Code when creating new projects. When projects are generated by the Smart Configurators through VS Code, there is no need to perform additional steps to configure the CMake build scripts. On the other hand, Renesas extensions provide predefined scripts to define the build environment for Renesas C/C++ projects, which are generated with e2 studio. The predefined build scripts can be accessed in the “Create Project” view in the “Renesas” tab. The following list contains all the predefined script options under the various device families:

Create Renesas R-Car Project
- Create RCar CMake (Development board / SoC) project files
- Create RCar CMake (Instruction Set Simulators) project files
Create Renesas RH850 Project
- Create CC-RH project files
Create Renesas RL78 Project
- Create CC-RL project files
- Create GCC RL78 project files
- Create LLVM for RL78 project files
Create Renesas RX Project
- Create CC-RX project files
- Create GCC RX project files
Create Renesas RZ Project
- Create GCC RZ project files

Click the desired family to start the project files generation:
Then, select the desired toolchain and continue (e.g. sample options for RX shown below).
The VSCode will ask to select the project root folder, select the target project folder.

The commands will open the project and generate the VS Code settings files, as well as the CMake script files cross.cmake and CMakeLists.txt files:

.vscode/settings.json - this file contains the settings for CMake.

.vscode/tasks.json - this file contains the build definitions for VSCode.

Cross.cmake - this file contains the information about the toolchain to use.

CMakeLists.txt - this file contains the information about the building project (which files to build, which options to set etc.).

.vscode/settings.json

File .vscode/settings.json - this file contains the settings for CMake.

.settings.json file’s general content:

{
    "cmake.configureArgs": [
        "-DCMAKE_TOOLCHAIN_FILE=<absolute/relative path of toolchain information file (<file name>.cmake file)"
    ],
    "cmake.sourceDirectory": "<absolute/relative path of the folder containing the root CMakeLists.txt file>"
}

.vscode/tasks.json

File .vscode/tasks.json - this file contains the build definitions for VSCode.

.tasks.json file’s general content:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Build Project",
      "group": "build",
      "type": "renesas-build",
      "command": "build",
      "deviceFamily": "<Device family (e.g. RA, RCAR, RH850, RL78, RX or RZ)>",
      "toolchain": "<Toolchain (e.g. gcc, cc-rl, cc-rx, llvm)>"
    }
  ]
}

Cross.cmake

Cross.cmake - this file contains the information about the toolchain to use.

Cross.cmake file’s general content:

# Specify toolchain path
SET(CMAKE_FIND_ROOT_PATH "<absolute path of toolchain's bin folder>")

# Specify the C compiler and necessary options
SET(CMAKE_C_COMPILER ${CMAKE_FIND_ROOT_PATH}/<C compiler executable file>)

# Specify the CPP compiler and necessary options
SET(CMAKE_CXX_COMPILER ${CMAKE_FIND_ROOT_PATH}/<CPP compiler executable file>)

# Specify the assembler and necessary options
SET(CMAKE_ASM_COMPILER ${CMAKE_FIND_ROOT_PATH}/<assembler executable file>)

# Specify the linker and necessary options
SET(CMAKE_LINKER ${CMAKE_FIND_ROOT_PATH}/<linker executable file>)

# Specify the library generator and necessary options
SET(CMAKE_LIBRARY ${CMAKE_FIND_ROOT_PATH}/<library generator executable file>)

# Specify the converter and necessary options
SET(CMAKE_CONVERTER_EXECUTABLE ${CMAKE_FIND_ROOT_PATH}/<converter executable file>)

CMakeLists.txt

CMakeLists.txt - this file contains the information about the building project (which files to build, which options to set etc.).

.CMakeLists.txt file’s general content:

cmake_minimum_required(VERSION 3.16)

# Set project name
project("<project name>")

enable_language(C ASM)

# Collect source files
FILE (GLOB_RECURSE SOURCE ${CMAKE_CURRENT_SOURCE_DIR}
"*.c" "*.cpp" "*.asm"
)
add_executable(${PROJECT_NAME} ${SOURCE})

# Set C compiler command
SET(CMAKE_C_COMPILE_OBJECT "${CMAKE_C_COMPILER} <specify C compiler options here>")

# Set C++ compiler command
SET(CMAKE_CXX_COMPILE_OBJECT "${CMAKE_CXX_COMPILER} <specify C++ compiler options here>")

# Set Assembler command
SET(CMAKE_ASM_COMPILE_OBJECT "${CMAKE_ASM_COMPILER} <specify assembler options here>")

# Set Linker command
SET(CMAKE_C_LINK_EXECUTABLE "${CMAKE_LINKER} <specify linker options here>")

# Set Library generator command
add_custom_COMMAND(
 TARGET ${CMAKE_PROJECT_NAME}
 PRE_LINK
 COMMAND ${CMAKE_LIBRARY} <specify library generator options here>
 COMMENT "Libgen:"
 VERBATIM
)

# Set Converter Command
add_custom_command (
 TARGET ${CMAKE_PROJECT_NAME}
 COMMAND ${CMAKE_CONVERTER_EXECUTABLE} <specify converter options here>
 COMMENT "Converter:"
 VERBATIM
)

After generating these files, it is necessary to configure the toolchain information and device specific build settings in these files. The typical approach can be structured into the following steps:

Open the cross.cmake file, and configure the toolchain path.
Get the device specific build settings from e2 Studio by following the instructions below:
1. Open the desired project in e2 studio.
2. Go to [Project] => [Properties] menu.
3. In the project properties windows, navigate to [C/C++ Build] => [Settings] section.
4. In the “Tool Settings” tab, check the “Common”, “Compiler”, “Assembler”, “Linker” sections. Depending on the target device get the values of the device specific parameters. The following parameters are the most common device specific parameters:
  - -isa
  - -cpu
  - -fpu (generally either -fpu or -nofpu)
  - -rom
  - -start
5. Now, open the project in VSCode, navigate to CMakeLists.txt and configure the device specific parameters in the CMake script.
Once all the necessary files are in place, open the [Command Palette] and run the [CMake: Delete Cache and Reconfigure] operation.
To run build task, either press [CTRL+SHIFT+B] ([CMD+SHIFT+B] for macOS) or select [Terminal] → [Run Build Task…] from the menu.
Open the [Command Palette] in VSCode and click [CMake: Delete Cache and Reconfigure].
In the first time of running, a kit selection is shown. Select “[Unspecified]”.

Note

Missing the selection of the CMake Kit or wrong selection can cause build problems. If you missed the CMake Kit selection or selected a wrong kit, you can re-select the CMake Kit by running “CMake: Select a kit” command from the VSCode Command Palette.
Go to and click [Terminal] => [Run Build Task] from the menu.
Build options will be shown, select the [Build Project] option.

17.7.2. Sample Scenario: Configuring CC/RX project CMake Files

In the following example, we are going to cover step by step instructions for converting the CMakeLists.txt script, and targeting it for the CCRX toolchain and an RX66T device.

First, open your project in e2 Studio, (or create an new one using e2 Studio).
Go to [Project] => [Properties] menu.
In the project properties windows, navigate to [C/C++ Build] => [Settings] section.
In parallel, open your project in VSCode.
Navigate to [Renesas] tab, and click [Create Renesas RX Project] to start the project files generation:
Then, select the [Create CC-RX project files] and continue.
The VSCode will ask to select the project root folder, select the target project folder.
Now, VSCode will create the necessary files. Open the cross.cmake file and set the path of the toolchain as shown in the screenshot below.
Now, VSCode will create the necessary files. Open the CMakeLists.txt file.
In the e2 Studio Project Settings, navigate to [Common], take the -isa and fpu parameters, then replace them in the CmakeLists.txt in VSCode. Change the -isa=rxv1 parameter to -isa=rxv3, and replace the -nofpu parameters with -fpu.
In the e2 Studio Project Settings, navigate to [Linker], take the -rom and -cpu parameters, then replace the value of the -cpu and add the -rom parameter in the CMAKE_EXE_LINKER_FLAGS at CmakeLists.txt file.
In the e2 Studio Project Settings, navigate to [Linker] => [Section], take the -start parameter, then replace the value of the -start parameter in the CMAKE_EXE_LINKER_FLAGS at CmakeLists.txt file.
In the e2 Studio Project Settings, navigate to [Assembly], then take the -start parameter, then replace them in the CmakeLists.txt in VSCode.
Note

Please note that you may need to follow the escape character rules while setting the values, for example the -start parameter may include a $ character, which needs to be replaced with a double dollar sign $$ according to the CMake escape character usage:
```
SU,SI,B_1,R_1,B_2,R_2,B,R/04,PResetPRG,C_1,C_2,C,C$*,D*,W*,L,PIntPRG,P/0FFF80000,EXCEPTVECT/0FFFFFF80,RESETVECT/0FFFFFFFC
```
should be defined as:
```
SU,SI,B_1,R_1,B_2,R_2,B,R/04,PResetPRG,C_1,C_2,C,C$$*,D*,W*,L,PIntPRG,P/0FFF80000,EXCEPTVECT/0FFFFFF80,RESETVECT/0FFFFFFFC
```
Open the [Command Palette] in VSCode and click [CMake: Delete Cache and Reconfigure].
In the first time of running, a kit selection is shown. Select “[Unspecified]”.

Note

Missing the selection of the CMake Kit or wrong selection can cause build problems. If you missed the CMake Kit selection or selected a wrong kit, you can re-select the CMake Kit by running “CMake: Select a kit” command from the VSCode Command Palette.
Go to and click [Terminal] => [Run Build Task] from the menu.
Build options will be shown, select the [Build Project] option.

For testing the project, you can use the RX Simulator (Simulator is only available for Windows operating systems).

Go to the [Debug] tab in VSCode and generate a launch configuration for [Renesas GDB Simulator Debugging]. This will generate a sample Launch configuration in the .vscode/launch.json file.

Open the Launch configuration and set the correct parameters for your target device. For 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": "Renesas GDB Simulator Debugging",
      "target": {
        "deviceFamily": "RX",
        "device": "R5F566TE",
        "debuggerType": "SIMULATOR"
      }
    }
  ]
}

Start your debug session.

17.7.3. Sample Scenario: Using Renesas R-Car SDK

The details of some specific devices will be presented here. Sample projects can be found in the samples folder inside the SDK directory.

The package is typically installed in the default path: “C:/Renesas/rcar-xos”

Using [Create RCar CMake (Development board / SoC) project files] command, necessary files listed below are going to be created.

.vscode/settings.json
.vscode/tasks.json
cross.cmake
CMakeLists.txt
module.cmake

.vscode/settings.json

Contents of the .vscode/settings.json file:

{
    "C_Cpp.updateChannel": "Insiders",
    "workbench.iconTheme": "vs-minimal",
    //For Linux.
    //"cmake.generator": "Unix Makefiles"
    //For Window:
    "cmake.generator": "MinGW Makefiles",
    "cmake.buildDirectory": "${workspaceFolder}/build/rcar.debug.DevBoard",
    "cmake.configureArgs": [
        "-DCMAKE_TOOLCHAIN_FILE=${workspaceFolder}/cross.cmake"
    ],
    "cmake.sourceDirectory": "${workspaceFolder}",
    "cmake.configureOnOpen": true,
    "C_Cpp.intelliSenseEngineFallback": "enabled"
}

.vscode/tasks.json

Contents of the .vscode/tasks.json file

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Build Project",
            "group": "build",
            "type": "renesas-build",
            "command": "build",
            "deviceFamily": "RCAR",
            "toolchain": "gcc"
        }
    ]
}

cross.cmake

Contents of the cross.cmake file

# Set the environment root directory
# It can be used to specify the target environment location
# e.g compiler's location. This variable is most useful when crosscompiling.
#(Should avoid spaces in the path or have to escape them)

# Please modify rcar-xos platform location and its version
set (PLATFORM_FIND_ROOT_PATH  "C:/Renesas/rcar-xos")
set (VERSION_SDK "v3.24.0")

# Check rcar-xos platform
if (NOT PLATFORM_FIND_ROOT_PATH)
  message(WARNING "rcar-xos PLATFORM_FIND_ROOT_PATH is not defined\n"
                  "Builds scripts will search rcar-xos platform in environment paths.\n"
                  "Use PLATFORM_FIND_ROOT_PATH variable to set a specific platform folder.")
elseif (NOT PLATFORM_FIND_ROOT_PATH MATCHES "/$")
  set(PLATFORM_FIND_ROOT_PATH "${PLATFORM_FIND_ROOT_PATH}/")
endif()

# Check rcar-xos platform version
if (NOT VERSION_SDK)
  message(WARNING "rcar-xos VERSION_SDK is not defined\n"
                  "Builds scripts will search rcar-xos platform version in environment paths.\n"
                  "Use VERSION_SDK variable to set a specific platform version.")
elseif (NOT VERSION_SDK MATCHES "/$")
  set(VERSION_SDK "${VERSION_SDK}/")
endif()

# Include module.cmake file
include("${CMAKE_CURRENT_LIST_DIR}/module.cmake")

# Set SDKROOT
Set(SDKROOT ${PLATFORM_FIND_ROOT_PATH}/${VERSION_SDK}/tools/toolchains/poky)

# Set CMake folder
set(CMAKE_PREFIX_PATH ${PLATFORM_FIND_ROOT_PATH}/${VERSION_SDK}/cmake)

# Set Device. Example: V3U, V3H1, V3H2, V3M2,..
set(RCAR_SOC V4H2)

# Set IMP Debug level variable
# R_CAR_DEBUG_IMP_LEVEL_CPU:  Only CPU Code
# R_CAR_DEBUG_IMP_LEVEL_CVE_DEBUG: CVe (Shader) debugging
set(R_CAR_DEBUG_IMP_LEVEL_VAR R_CAR_DEBUG_IMP_LEVEL_CVE_DEBUG)

# Build target
set(R_CAR_BUILD_TARGET_VAR aarch64-gnu-linux)

# Include cmake toolchain files as following
include("${CMAKE_PREFIX_PATH}/toolchain_poky_3_1_11_adas.cmake")

Note

Information about the samples corresponding to which device is available in:

C:/Renesas/rcar-xos/<version SDK>/samples/SUPPORTED_ENVIRONMENT.html

Example:

C:/Renesas/rcar-xos/v3.24.0/samples/SUPPORTED_ENVIRONMENT.html

CMakeLists.txt and module.cmake files are overridden with their corresponding files from the project.