18. Quick Start for Renesas RZ/N

18.1. Supported Environments

Operating System

Windows: Windows 10 / Windows 11

VS Code version

1.102.0 (minimum)

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

18.2. Installation

For the Renesas RZ/N Family, Renesas Platform provides a straightforward installation wizard to install the CMake, Ninja, Python, ARM GNU Toolchain, SEGGER J-Link and the Support Files for RZ Family. To set up your environment:

  1. Open VS Code.

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

    _images/renesas-quick-install.png

  3. Click the “Install” button for the “Renesas RZ/N” device family. The Renesas Platform will now check the dependencies required by the Renesas RZ Device Family. The Renesas Platform extension will check the local environment and CMake, Ninja, Python, ARM GNU Toolchain, SEGGER J-Link and the Support Files for RZ Family, then create an installation plan for them if necessary.

    _images/rz-install.png

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

    _images/rz-start-installation.png

Installing the latest RZ/N Smart Configurator:

Download and install the latest version of RZ/N Smart Configurator:

After installing the Renesas RZ/N Smart Configurator, you should register the Renesas Smart Configurator installation in VS Code. In order to register the Renesas RZ/N Smart Configurator, perform the following steps:

  1. Click “Manage Smart Configurators” and check the Renesas RZ/N Smart Configurators. Use the “Register SC” button to register the Smart Configurator manually by selecting the path of the Smart Configurator.

    _images/rzn-sc.png

  2. Once it is registered, the Smart Configurator will be visible in the Renesas RZ/N Smart Configurators list.

    _images/rzn-sc-registered.png

18.3. Creating a Project

For RZ/N device family projects, it is recommended to use RZ/N Smart Configurator to create a project for VS Code. Smart Configurator can be accessed via the “Create Project” view in the “Renesas” tab. Please use the following instructions to create and build a project for RZ/N device family.

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

    _images/rzn-create-project.png

  2. Select [Create RZ/N Project with Smart Configurator] option from the list.

    _images/rzn-create-project-pick.png

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

    _images/rzn-sc-pick.png

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

    _images/rzn-folder-pick.png

  5. Update the [Project name] if needed, then click [Next].

    _images/rzn-sc-step1.png

  6. Configure your board, device type and programming language, then click [Next].

    _images/rzn-sc-step2.png

  7. Choose the “Smart Bundle” configuration and continue by clicking [Next] (Skip choosing the Smart Bundle selection for the sample project).

    _images/rzn-sc-step3.png

  8. Choose the “RTOS” configuration and continue by clicking [Next] (Continue with “No RTOS” for the sample project).

    _images/rzn-sc-step4.png

  9. Choose one of the project templates then click [Finish] to complete the project creation steps.

    _images/rzn-sc-step5.png

  10. Close [RZ/N Smart Configurator] after generation of the project files completed.

    _images/rzn-sc-step6.png

18.4. Building the Project

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

  1. When the project is opened for the first time, CMake configure and the CMake Kit selection operations must be performed. In order to do these operations, open the “Command Palette” in VSCode and select “CMake: Configure” from the commands.

    _images/rzn-build-step1.png

  2. Then, a kit selection menu will be shown. Select “Renesas Platform: Arm GNU Toolchain …” from the menu if the project is generated for GCC toolchain. It is important to use the “Renesas Platform: …” kits since they contain Renesas-specific configuration parameters for Renesas projects.

    _images/rzn-build-step2.png

    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.

    _images/rasc-cmake-select-a-kit.png

  3. Now, go to and click “Terminal” => “Run Build Task” from the menu.

    _images/rzn-build-step3.png

  4. Build options will be shown, select the “Build Project” option.

    _images/rzn-build-step4.png

    Note

    Alternatively, you can directly use the “Build” button to start the build operation via the VS Code toolbar.

    _images/rzn-build-step5.png

  5. After the build operation, you will see the progress completed successfully. By default, build output (<project name>.elf) can be found in “build/<Build Type>/CMakeFiles/<project name>.elf.dir/” folder.

    _images/rzn-build-step6.png

18.5. Debugging the Project

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

_images/vscode-debug-start5.png

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

_images/vscode-debug-start6.png

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

_images/vscode-debug-start7.png

18.6. GDB Server launch parameters for RZ/N devices

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

18.6.1. Connection Settings

18.6.1.2. Interface

Option

Details

-uInteface=
Description: Specify the connection type to be used by the emulator when communicating with the CPU on target system.
Default Values: JTAG
Emulator: J-Link
Available Values: SWD: Type SWD, JTAG: Type JTAG
Example: "serverParameters": { "-uInteface=": "SWD" }

-uIfSpeed=
Description: Specify the interface speed in kHz.
Default Values: auto
Emulator: J-Link
Available Values: auto (Selects the appropriate JTAG speed handled by the emulator), adaptive (If the target provides the RTCK signal, select the adaptive clocking function to synchronize the clock to the processor clock outside the core), From 1 to 100000 (Specify value for interface speed in kHz)
Example: "serverParameters": { "-uIfSpeed=": 4000 }
Note: “adaptive” option is just available for J-Link

18.6.1.3. JTAG Scan Chain

Option

Details

-uscIrPre=
Description: Specify the number of IR-bits of all devices which are closer to TDO than the one we want to communicate with.
Default Values: 0
Emulator: J-Link
Available Values: Valid integer number of IR-bits
Example: "serverParameters": { "-uscIrPre=": 0 }

-uscDrPre=
Description: Specify the number of devices which are closer to TDO than the one we want to communicate with.
Default Values: 0
Emulator: J-Link
Available Values: Valid integer number
Example: "serverParameters": { "-uscDrPre=": 0 }

18.6.1.4. Connection

Option

Details

-uResetCon=
Description: Specify whether to hold reset during the connection progress.
Default Values: 0
Emulator: J-Link
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uResetCon=": 1 }

-uResetBeginConnection=
Description: Specify whether the CPU should be reset at the beginning of connection.
Default Values: 1
Emulator: J-Link
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uResetBeginConnection=": 1 }

-uNoReset=
Description: Specify whether the CPU should not be reset at the end of connection.
Default Values: 1
Emulator: J-Link
Available Values: 0: Reset, 1: No Reset
Example: "serverParameters": { "-uNoReset=": 1 }

-uIdCodeBytes=
Description: Specify the ID code to unlock the device (if one has been set previously to protect connection).
Default Values: None
Emulator: J-Link
Available Values: 32 hex digits
Example: "serverParameters": { "-uIdCodeBytes=": "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF" }

-uLowPower=
Description: Specify if the program uses low power consumption mode or not.
Default Values: 0
Emulator: J-Link
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uLowPower=": 0 }

-uInitRegisters=
Description: Specify if registers should be initialized on connection.
Default Values: 0
Emulator: J-Link
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uInitRegisters=": 0 }

-uResetPreRun=
Description: Specify if an additional reset should be applied before the downloaded module is run.
Default Values: 0
Emulator: J-Link
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uResetPreRun=": 0 }

-uResetBefDownload=
Description: Specify if an additional reset should be applied before the module is downloaded.
Default Values: 0
Emulator: J-Link
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uResetBefDownload=": 0 }

-uSetArmModeAfterDownload=
Description: Specify if CPSR(5 bit) should be set to ARM mode after the module is downloaded.
Default Values: 0
Emulator: J-Link
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uSetArmModeAfterDownload=": 0 }

-uReleaseCM3=
Description: Specify whether prevent run away at launching a debug session for Cortex-M3 core.
Default Values: 1
Emulator: J-Link
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uReleaseCM3=": 0 }

-uSecureVectorAddress=
Description: Specify the Secure Vector address.
Default Values: None
Emulator: J-Link
Available Values: The valid hex address.
Example: "serverParameters": { "-uSecureVectorAddress=": "0x10010110" }

-uNonSecureVectorAddress=
Description: Specify the Non Secure Vector address.
Default Values: None
Emulator: J-Link
Available Values: The valid hex address.
Example: "serverParameters": { "-uNonSecureVectorAddress=": "0x10010110" }

-uHotPlug=
Description: Specify if connecting to an already running target system.
Default Values: 0
Emulator: J-Link
Available Values: 0: Disabled, 1: Enabled
Example: "serverParameters": { "-uHotPlug=": 1 }

-uDisconnectionMode=
Description: Specify the disconnection mode to control the target state after disconnecting.
Default Values: 2
Emulator: J-Link
Available Values: 0: No change mode, 1: Stop mode, 2: Continue mode
Example: "serverParameters": { "-uDisconnectionMode=": 1 }

18.6.1.5. SWV

Option

Details

-uSWOcoreClock=
Description: Specify the core clock speed in Hz.
Default Values: 0
Emulator: J-Link
Available Values: Valid frequency value in Hz
Example: With 8 MHz: "serverParameters": { "-uSWOcoreClock=": 8000000 }

18.6.1.6. TrustZone

Option

Details

-uEnableSciBoot=
Description: Specify whether the boundaries of memory regions need to be set to separate each memory region when a debugging connection is initiated.
Default Values: 0
Emulator: J-Link
Available Values: 0: Disabled, 1: Enabled
Example: "serverParameters": { "-uEnableSciBoot=": 1 }

-uTz=
Description: Specify the debugging type of TrustZone.
Default Values: None
Emulator: J-Link
Available Values: SSD: Secure Software Development, NSECSD: Non Secure Software Development
Example: "serverParameters": { "-uTz=": "NSECSD" }

-uAuthLevel=
Description: Specify the authentication level.
Default Values: 0
Emulator: J-Link
Available Values: 0 (AL0: Ignores the key and connect without authentication), 1 (AL1: Authenticate device with key to AL1), 3 (AL2: Authenticate device with key to AL2), 255 (ALERASE: Initialize device back to AL2)
Example: "serverParameters": { "-uAuthLevel=": 3 }
Note: Use this parameter only with TrustZone devices that support Authentication Level

-uAuthKey=
Description: Specify the Authentication Key.
Default Values: None
Emulator: J-Link
Available Values: Key for Authentication
Example: "serverParameters": { "-uAuthKey=": "ACD6B31BF68FE9AE07AEF6B3C3870730" }
Note: Use this parameter only with TrustZone devices that support Authentication Level

18.6.2. Debug Tool Settings

18.6.2.1. Break

Option

Details

-uFlashBp=
Description: Specify whether to use software breakpoints to flash memory or not.
Default Values: 0
Emulator: J-Link
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uFlashBp=": 0 }
Note: This parameter does not need to be specified if -uProgReWriteIRom or -uProgReWriteDFlash is sent with value 1.

-uSimulation=
Description: Specify if Instruction Set simulation will be used or not.
Default Values: 0
Emulator: J-Link
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uSimulation=": 0 }
Note: This parameter does not need to be specified if -uProgReWriteIRom or -uProgReWriteDFlash is sent with value 1.

18.6.2.2. Flash

Option

Details

-ueraseRomOnDownload=
Description: Specify whether or not to erase the flash ROM (program ROM) before a download.
Default Values: 0
Emulator: J-Link
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-ueraseRomOnDownload=": 0 }

-ueraseDataRomOnDownload=
Description: Specify whether or not to erase the data flash ROM before a download.
Default Values: 0
Emulator: J-Link
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-ueraseDataRomOnDownload=": 0 }

-ucfiFlashWorkStart=
Description: Specify the start address of the Working RAM area which is used by JLink during flash programming.
Default Values: 0
Emulator: J-Link
Available Values: Valid address
Example: "serverParameters": { "-ucfiFlashWorkStart=": "0x20001000" }
Note: Start address and end address of Working RAM area have to be set together and start address have to be smaller than end address.

-ucfiFlashWorkEnd=
Description: Specify the end address of the Working RAM area which is used by JLink during flash programming.
Default Values: None
Emulator: J-Link
Available Values: Valid address
Example: "serverParameters": { "-ucfiFlashWorkEnd=": "0x20004000" }
Note: Start address and end address of Working RAM area have to be set together and end address have to be bigger than start address

-ucfiFlashStart=
Description: Specify the start address of CFI Flash Area.
Default Values: 0
Emulator: J-Link
Available Values: Any valid hex address.
Example: "serverParameters": { "-ucfiFlashStart=": "&DebugMon_Handler" }
Note: Start address and end address of CFI flash have to be set together and start address have to be smaller than end address.
The CFI flash address will not be set in Renesas GDB server if Work RAM address is not set before.

-ucfiFlashEnd=
Description: Specify the end address of CFI Flash Area.
Default Values: 0
Emulator: J-Link
Available Values: Any valid hex address.
Example: "serverParameters": { "-ucfiFlashEnd=": "&PendSV_Handler" }
Note: Start address and end address of CFI flash have to be set together and end address have to be bigger than start address. The CFI flash address will not be set in Renesas GDB server if Work RAM address is not set before.

-uExcludeFlashCacheRange=
Description: Specify whether enable and exclude the Flash Cache for a address range.
Default Values: If this parameter is not sent, this feature will be disabled.
Emulator: J-Link
Available Values: Set of address value with below formats: <Start address>,<End address> or <Start address>-<End address>
Example: "serverParameters": { "-uExcludeFlashCacheRange=": "0x10000000,0x100FFFFF" } or "serverParameters": { "-uExcludeFlashCacheRange=": "0x10000000-0x100FFFFF" }

-uflashMemoryType=
Description: Specify the Flash Memory type.
Default Values: None
Emulator: J-Link
Available Values: SerialFlash, HyperFlash, or OctaFlash
Example: "serverParameters": { "-uflashMemoryType=": "SerialFlash" }

-uflashBusType=
Description: Specify the Flash Bus type.
Default Values: None
Emulator: J-Link
Available Values: SPIBSC, HyperBus, or OctaBus
Example: "serverParameters": { "-uflashBusType=": "SPIBSC" }

18.6.2.3. RTOS

Option

Details

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

18.6.2.4. System

Option

Details

-uAllowCachingFlash=
Description: Specify whether the flash contents are cached by J-Link or not.
Default Values: 0
Emulator: J-Link
Available Values: 0: Yes, 1: No
Example: "serverParameters": { "-uAllowCachingFlash=": 0 }
Note: "-uAllowCachingFlash=": 0: Enable caching for the flash contents, "-uAllowCachingFlash=": 1: Disable caching for the flash contents

18.6.2.5. Time Measurement

Option

Details

-uCECycle=
Description: For Renesas RZ targets, this will set the value for bit[3] of the PMCR register to 0.
Default Values: 1
Emulator: J-Link
Available Values: 0: No, 1: Yes
Example: "serverParameters": { "-uCECycle=": 1 }

-uCPUFrequency=
Description: Specify the operating frequency (ICLK) in Hz. It is used to calculate the timestamp of SWO trace.
Default Values: None
Emulator: J-Link
Available Values: The frequency in Hz in range 1000 - 999999000
Example: "serverParameters": { "-uCPUFrequency=": 120000000 }

18.6.2.6. Reset Behaviour

Option

Details

-uResetBehavior=
Description: Specify the behaviour for the reset command.
Default Values: Reset
Emulator: J-Link
Available Values: Reset, ChangePC
Example: "serverParameters": { "-uResetBehavior=": "Reset" }

-uPcOnReset=
Description: Specify the value which is set to PC.
Default Values: None
Emulator: J-Link
Available Values: Any valid address or symbol
Example: "serverParameters": { "-uPcOnReset=": "&main" }
Note: If PC value is not specified, it will be set to the entry point value.

-uSetCpsrOnReset=
Description: Specify the value which is set to CPSR.
Default Values: None
Emulator: J-Link
Available Values: Any valid address
Example: "serverParameters": { "-uSetCpsrOnReset=": 0x1da }
Note: If CPSR value is not specified, it will keep the original value.