View source for R-Car/Boards/Zephyr-Gen3/2.7

== SW Release information ==

{| class="wikitable"
|-
! Supported board
! Zephyr Version
! BSP Release date
|-
| rowspan="2" | H3ULCB
| [[R-Car/Boards/Zephyr-Gen3/2.7|2.7 LTS]] <span style="color:#ff0000;">[New!!]</span>
| 2021/10/22
|-
| [[R-Car/Boards/Zephyr-Gen3/2.6|2.6]]
| 2021/06/11
|}

== Introduction ==

This is the Wiki for the Zephyr support for Renesas R-Car Gen3 embedded Cortex-R7. Refer to the [[R-Car]] page for information about Renesas’ R-Car SoC family.

This wiki describes the current support of H3ULCB Cortex-R7 on Zephyr from multiple sources. You will also find a step by step tutorial on how to prepare your Ubuntu host then build and test Zephyr OS on an R-Car Gen3 board.

'''Important''': It is important to understand that the Zephyr port has been designed to be executed exclusively on the Cortex-R7 that exists in some of the R-Car Gen3 boards.There is no plan to replace other software such as U-Boot or Linux that are running on the A57/53 cores by Zephyr.

== Tutorial ==

This tutorial is based on the official Zephyr 2.7 guide, commands are appended here to allow you a quick copy and paste. You can also follow the installation steps (1 to 4) directly from the official guide [https://docs.zephyrproject.org/2.7.0/getting_started/index.html here].

This guide only supports Ubuntu but the official one also describes steps for macOS and windows. This tutorial is based on Zephyr 2.7 version and is using the Iot.bzh’s Renesas 2.7 BSP in order to provide a much more user friendly tutorial.

You can see Zephyr 2.7’s H3ULCB supported features [https://docs.zephyrproject.org/2.7.0/boards/arm/rcar_h3ulcb/doc/rcar_h3ulcb.html#supported-features here].

=== Prepare your bootloaders ===

In order for Zephyr or any other RTOS running on the H3ULCB’s Cortex-R7 to work well, “ARM Trusted Firmware” needs to be patched and re-flashed. This patch enables access to GIC generated interrupts from the CR7 core on R-Car Gen3 boards.

'''Warning''': By applying this patch and giving secure access to the CR7 core you expose yourself to unintended uses that may compromise the security of your system.

==== Build “ARM Trusted Firmware” (BL2) ====

In order to build your “ARM Trusted Firmware” with the needed patch, you have to add a Yocto layer when building your BSP with Yocto. The following instructions are tested in order to be used with the [https://elinux.org/R-Car/Boards/Yocto-Gen3/v5.9.0#Building_the_BSP_for_Renesas_H3_Starter_Kit.2C_M3_Starter_Kit official guide] for BSPs 5.9.0 and earlier.

You can apply BL2 patch by adding these lines to the script or manual steps :

<ul>
<li><p>“Clone basic Yocto layers in parallel” section :</p>
<source lang="diff">git clone https://github.com/renesas-rcar/meta-renesas &
+git clone https://github.com/iotbzh/meta-rcar-zephyr &</source></li>
<li>“Switch to proper branches/commits” section :
<ul>
<li><p>For BSP 5.1.0 and earlier</p>
<source lang="diff">cd ${WORK}/meta-renesas
git checkout -b tmp ${META_RENESAS_COMMIT}
+cd ${WORK}/meta-rcar-zephyr
+git checkout -b tmp origin/cr7_5.1.0_and_earlier</source></li>
<li><p>For BSP 5.5.0 and later</p>
<source lang="diff">cd ${WORK}/meta-renesas
git checkout -b tmp ${META_RENESAS_COMMIT}
+cd ${WORK}/meta-rcar-zephyr
+git checkout -b tmp origin/cr7_5.5.0_and_later</source></li></ul>
</li>
<li><p>Case 1 : You want to build a complete image Before <code>bitbake core-image-weston</code> :</p>
<source lang="diff">+bitbake-layers add-layer ../../meta/meta-rcar-zephyr/
bitbake core-image-weston</source></li>
<li><p>Case 2 : You only want to rebuild “ARM Trusted Firmware” with the patch Replace <code>bitbake core-image-weston</code> by :</p>
<source lang="diff">-bitbake core-image-weston
+bitbake-layers add-layer ../../meta/meta-rcar-zephyr/
+bitbake arm-trusted-firmware</source></li></ul>

==== Flash bootloaders ====

Once you have built your new “ARM Trusted Firmware” bootloader, you may flash it by following the official [https://elinux.org/R-Car/Boards/H3SK#Flashing_firmware flashing guide].

You may choose to only re-flash the “ARM Trusted Firmware” or re-flash all your bootloaders if you are running old versions of these.

=== Install dependencies ===

First, update your host:

<source lang="bash">sudo apt update
sudo apt upgrade</source>
Then, install the required dependencies:

<source lang="bash">sudo apt install --no-install-recommends git cmake ninja-build gperf \
  ccache dfu-util device-tree-compiler wget \
  python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \
  make gcc gcc-multilib g++-multilib libsdl2-dev</source>
Please also make sure that your <code>cmake</code>, <code>python</code> and <code>dtc</code> tools version are matching required minimal version [https://docs.zephyrproject.org/2.7.0/getting_started/index.html#install-dependencies here].

=== Get Zephyr and install Python dependencies ===

In order to clone Zephyr, you should first install the [https://docs.zephyrproject.org/2.7.0/guides/west/index.html West] tool, a swiss-army knife command line tool used by the Zephyr project for the whole process from cloning sources to flashing a board.

<source lang="bash">pip3 install --user -U west
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc</source>
Clone the complete Zephyr project, use Iot.bzh’s latest Renesas BSP and update all the project:

<source lang="bash">cd ~
west init -m  https://github.com/iotbzh/zephyr.git --manifest-rev renesas-v2.7 ~/zephyrproject
cd ~/zephyrproject
west update</source>
Export a Zephyr CMake package:

<source lang="bash">west zephyr-export</source>
Then, install the Python dependencies:

<source lang="bash">pip3 install --user -r ~/zephyrproject/zephyr/scripts/requirements.txt</source>
=== Install a toolchain ===

To build Zephyr OS binaries, you need a cross-toolchain. The Zephyr OS project provides all the binary files you need to build your project.

<source lang="bash">cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.13.1/zephyr-sdk-0.13.1-linux-x86_64-setup.run
chmod a+x zephyr-sdk-0.13.1-linux-x86_64-setup.run
./zephyr-sdk-0.13.1-linux-x86_64-setup.run -- -d ~/zephyr-sdk-0.13.1</source>
Then, apply the provided udev rule allowing the flash of most Zephyr boards:

<source lang="bash">sudo cp ~/zephyr-sdk-0.13.1/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
sudo udevadm control --reload</source>
=== Build demos ===

Now you are ready to build your first Zephyr project programs, we are going to start with a bunch of basic demos:

* '''Blinky demo''' is making a LED blink (LED5 output LED).
* '''Button demo''' is turning on output LED when receiving button input (SW3 input button).

<source lang="bash">cd ~/zephyrproject/zephyr

west build -p auto -b rcar_h3ulcb_cr7 samples/basic/blinky --build-dir build-h3ulcb-blinky
west build -p auto -b rcar_h3ulcb_cr7 samples/basic/button --build-dir build-h3ulcb-button</source>
=== Build a custom app ===

As an example, we will clone the [https://github.com/iotbzh/zephyr-shell zephyr-shell] demo that we prepared to demonstrate all the currently supported features for R-Car Gen3 H3ULCB on Zephyr.

You can clone your app anywhere on your host, for the clarity of this tutorial, we will store apps near to the Zephyr sources:

<source lang="bash">mkdir ~/zephyrproject/user_app
cd ~/zephyrproject/user_app
git clone https://github.com/iotbzh/zephyr-shell.git</source>
Then, you can build it at the same location as demos previously built:

<source lang="bash">cd  ~/zephyrproject/zephyr
west build -b rcar_h3ulcb_cr7 ../user_app/zephyr-shell --build-dir build-h3ulcb-zephyr-shell</source>
=== Hardware setup ===

Now that your binaries are ready, it’s time to prepare your hardware setup allowing you to flash the program you just built.

First, the BSP we are using is currently only supporting the Olimex ARM-USB-OCD-H JTAG probe, we then encourage you to use this probe to flash H3ULCB board.

Depending on the hardware configuration you use, you will not need the same setup:

'''ULCB''': To connect the JTAG probe to a ULCB board, you will need a TET SICA20I2P adapter. You will then be able to connect your probe to the CN3 JTAG connector of the board. Unless your CN10 connector is welded, secondary UART is not available on this board.

'''ULCB+KF''': When connected to a Kingfisher board, you can use JTAG and access secondary UART. You are able to access the secondary UART through KF CN4 connector (be careful, the pinout of the connector depends on your KF revision). See “Know issues” to be sure that your Kingfisher revision let you use the JTAG connector.

If you are able to access the secondary UART (depending on yor hardware setup), you can link your host to it with a USB-TTL adapter with 115200 8N1 settings.

=== Deploy a Zephyr binary on board ===

Now that your hardware setup is ready, you are able to flash any of your Zephyr binary:

'''Blinky demo:'''

<source lang="bash">cd  ~/zephyrproject/zephyr/build-h3ulcb-blinky
west flash</source>
LED5 of H3ULCB should blink.

'''Button demo:'''

<source lang="bash">cd  ~/zephyrproject/zephyr/build-h3ulcb-button
west flash</source>
LED5 of H3ULCB should turn on if SW3 button is pushed.

'''Zephyr Shell demo:'''

<source lang="bash">cd ~/zephyrproject/zephyr/build-h3ulcb-zehyr-shell
west flash</source>
Zephyr shell prompt should appear on H3ULCB+KF secondary UART (KF CN4/SCIF1). You can then test subsystems support as explained in Zephyr Shell app Readme [https://github.com/iotbzh/zephyr-shell here].