1.. zephyr:board:: rzg3s_smarc
2
3Overview
4********
5
6The Renesas RZ/G3S SMARC Evaluation Board Kit (RZ/G3S-EVKIT) consists of a SMARC v2.1 module board and a carrier board.
7
8* Device: RZ/G3S R9A08G045S33GBG
9
10  * Cortex-A55 Single, Cortex-M33 x 2
11  * BGA 359-pin, 14mmSq body, 0.5mm pitch
12
13* SMARC v2.1 Module Board Functions
14
15  * LPDDR4 SDRAM: 1GB x 1pc
16  * QSPI flash memory: 128Mb x 1pc
17  * eMMC memory: 64GB x 1pc
18  * PMIC power supply RAA215300A2GNP#HA3 implemented
19  * microSD card x2
20  * I3C connector
21  * JTAG connector
22  * ADC x8 channels
23  * Current monitor (USB Micro B)
24
25* Carrier Board Functions
26
27  * Gigabit Ethernet x2
28  * USB2.0 x2ch (OTG x1ch, Host x1ch)
29  * CAN-FD x2
30  * microSD card x1
31  * Mono speaker, Stereo headphone, Mic., and Aux..
32  * PMOD x2
33  * USB-Type C for power input
34  * PCIe Gen2 4-lane slot (G3S supports only 1-lane)
35  * M.2 Key E
36  * M.2 Key B and SIM card
37  * Coin cell battery holder (3.0V support)
38
39Hardware
40********
41
42The Renesas RZ/G3S MPU documentation can be found at `RZ/G3S Group Website`_
43
44.. figure:: rzg3s_block_diagram.webp
45	:width: 600px
46	:align: center
47	:alt: RZ/G3S group feature
48
49	RZ/G3S block diagram (Credit: Renesas Electronics Corporation)
50
51Multi-OS processing
52*******************
53
54The RZ/G3S-EVKIT allows different applications to be executed in RZ/G3S SoC. With its multi-core architecture,
55each core can operate independently to perform customized tasks or exchange data using the OpenAMP framework.
56Please see :zephyr:code-sample:`rz-openamp-linux-zephyr` sample for reference.
57
58Supported Features
59==================
60
61The ``rzg3s_smarc/r9a08g045s33gbg/cm33`` board target supports the ARM Cortex-M33 System Core without FPU
62and the following hardware features:
63
64+-----------+------------+-------------------------------------+
65| Interface | Controller | Driver/Component                    |
66+===========+============+=====================================+
67| NVIC      | on-chip    | arch/arm                            |
68+-----------+------------+-------------------------------------+
69| SYSTICK   | on-chip    | arch/arm                            |
70+-----------+------------+-------------------------------------+
71| PINCTRL   | on-chip    | pinctrl                             |
72+-----------+------------+-------------------------------------+
73| ADC       | on-chip    | adc                                 |
74+-----------+------------+-------------------------------------+
75| GPIO      | on-chip    | gpio                                |
76+-----------+------------+-------------------------------------+
77| DMA       | on-chip    | dma                                 |
78+-----------+------------+-------------------------------------+
79| I2C       | on-chip    | i2c                                 |
80+-----------+------------+-------------------------------------+
81| UART      | on-chip    | serial                              |
82+-----------+------------+-------------------------------------+
83| GTM       | on-chip    | counter                             |
84+-----------+------------+-------------------------------------+
85| GPT       | on-chip    | pwm                                 |
86+-----------+------------+-------------------------------------+
87| INTC      | on-chip    | external interrupt controller       |
88+-----------+------------+-------------------------------------+
89| CLOCK     | on-chip    | clock control                       |
90+-----------+------------+-------------------------------------+
91| MHU       | on-chip    | mbox                                |
92+-----------+------------+-------------------------------------+
93
94Other hardware features are currently not supported by the port.
95
96Programming and Debugging
97*************************
98
99RZ/G3S-EVKIT is designed to start different systems on different cores.
100It uses Yocto as the build system to build Linux system and boot loaders
101to run BL2 TF-A on Cortex-A55 System Core before starting Zephyr. The minimal steps are described below.
102
103  1. Follow ''2.2 Building Images'' of `SMARC EVK of RZ/G3S Linux Start-up Guide`_ to prepare the build environment.
104
105  2. Before build, add ``PLAT_M33_BOOT_SUPPORT=1`` to meta-renesas/meta-rzg3s/recipes-bsp/trusted-firmware-a/trusted-firmware-a.bbappend.
106
107  .. code-block:: bash
108    :emphasize-lines: 6
109
110      require trusted-firmware-a.inc
111      COMPATIBLE_MACHINE_rzg3s = "(rzg3s-dev|smarc-rzg3s)"
112      PLATFORM_rzg3s-dev = "g3s"
113      EXTRA_FLAGS_rzg3s-dev = "BOARD=dev14_1_lpddr PLAT_SYSTEM_SUSPEND=vbat"
114      PLATFORM_smarc-rzg3s = "g3s"
115      EXTRA_FLAGS_smarc-rzg3s = "BOARD=smarc PLAT_SYSTEM_SUSPEND=vbat PLAT_M33_BOOT_SUPPORT=1"
116
117  3. Start the build:
118
119  .. code-block:: bash
120
121      MACHINE=smarc-rzg3s bitbake core-image-minimal
122
123  The below necessary artifacts will be located in the build/tmp/deploy/images
124
125  +---------------+-----------------------------+
126  | Artifacts     | File name                   |
127  +===============+=============================+
128  | Boot loader   | bl2_bp_spi-smarc-rzg3s.srec |
129  |               |                             |
130  |               | fip-smarc-rzg3s.srec        |
131  +---------------+-----------------------------+
132  | Flash Writer  | FlashWriter-smarc-rzg3s.mot |
133  +---------------+-----------------------------+
134
135  4. Follow ''4.2 Startup Procedure'' of `SMARC EVK of RZ/G3S Linux Start-up Guide`_ for power supply and board setting
136     at SCIF download (SW_MODE[1:4] = OFF, ON, OFF, ON) and Cortex-A55 cold boot (SW_CONFIG[1:6] = OFF, OFF, ON, OFF, OFF, OFF)
137
138  5. Follow ''4.3 Download Flash Writer to RAM'' of `SMARC EVK of RZ/G3S Linux Start-up Guide`_ to download Flash Writer to RAM
139
140  6. Follow ''4.4 Write the Bootloader'' of `SMARC EVK of RZ/G3S Linux Start-up Guide`_ to write the boot loader
141     to the target board by using Flash Writer.
142
143Applications for the ``rzg3s_smarc`` board can be built in the usual way as
144documented in :ref:`build_an_application`.
145
146Console
147=======
148
149The UART port for Cortex-M33 System Core can be accessed by connecting `Pmod USBUART <https://store.digilentinc.com/pmod-usbuart-usb-to-uart-interface/>`_
150to the upper side of ``PMOD1_3A``.
151
152Debugging
153=========
154
155It is possible to load and execute a Zephyr application binary on
156this board on the Cortex-M33 System Core from
157the internal SRAM, using ``JLink`` debugger (:ref:`jlink-debug-host-tools`).
158
159.. note::
160
161    Currently it's required Renesas BL2 TF-A to be started on Cortex-A55 System Core
162    before starting Zephyr as it configures clocks and the Cortex-M33 System Core before starting it.
163
164Here is an example for building and debugging with the :zephyr:code-sample:`hello_world` application.
165
166.. zephyr-app-commands::
167   :zephyr-app: samples/hello_world
168   :board: rzg3s_smarc/r9a08g045s33gbg/cm33
169   :goals: build debug
170
171Flashing
172========
173
174Zephyr application can be flashed to QSPI storage and then loaded by
175Renesas BL2 TF-A running on the Cortex-A55 System Core and starting binary on the Cortex-M33 System Core.
176
177The Zephyr application binary has to be converted to Motorolla S-record `SREC`_ format
178which is generated automatically in Zephyr application build directory with the extension ``s19``.
179
180.. _SREC: https://en.wikipedia.org/wiki/SREC_(file_format)
181
182.. _Flashing on QSPI:
183
184Flashing on QSPI using Flash Writer
185---------------------------------------
186
187Zephyr binary has to be converted to **srec** format.
188
189* Download and start **Flash Writer** as described in ''4.3 Download Flash Writer to RAM'' of `SMARC EVK of RZ/G3S Linux Start-up Guide`_
190* Use **XLS2** command to flash Zephyr binary
191* Input when asked:
192
193.. code-block:: console
194
195    ===== Please Input Program Top Address ============
196      Please Input : H'23000
197    ===== Please Input Qspi Save Address ===
198      Please Input : H'200000
199
200* Then send Zephyr **s19** file from terminal (use ''ascii'' mode)
201* Reboot the board in the **QSPI Boot Mode**
202
203.. code-block:: console
204
205     -- Load Program to SRAM ---------------
206
207    Flash writer for RZ/G3S Series V0.60 Jan.26,2023
208     Product Code : RZ/G3S
209    >XLS2
210    ===== Qspi writing of RZ/G2 Board Command =============
211    Load Program to Spiflash
212    Writes to any of SPI address.
213    Program size & Qspi Save Address
214    ===== Please Input Program Top Address ============
215      Please Input : H'23000
216
217    ===== Please Input Qspi Save Address ===
218      Please Input : H'200000
219    please send ! ('.' & CR stop load)
220    I Flash memory...
221    Erase Completed
222    Write to SPI Flash memory.
223    ======= Qspi  Save Information  =================
224     SpiFlashMemory Stat Address : H'00200000
225     SpiFlashMemory End Address  : H'002098E6
226    ===========================================================
227
228Flashing on QSPI using west
229---------------------------
230
231Before using ``flash`` command, the board must be set to Cortex-M33 cold boot (SW_CONFIG[1:6] = OFF, OFF, ON, OFF, OFF, ON).
232After flashing, it must be set back to Cortex-A55 cold boot to run.
233
234The minimal version of SEGGER JLink SW which can perform flashing of QSPI memory is v7.96.
235
236**Note:** It's verified that we can perform flashing successfully with SEGGER JLink SW v7.98g so please use this or later
237version.
238
239.. zephyr-app-commands::
240   :zephyr-app: samples/hello_world
241   :board: rzg3s_smarc/r9a08g045s33gbg/cm33
242   :goals: build flash
243   :compact:
244
245Troubleshooting
246===============
247
248Linux and Zephyr application should not share SoC HW resources otherwise it will cause HW corruption and unpredictable behavior.
249Therefore, HW resources assigned to Zephyr application must be disabled in Linux.
250
251The below patch shows how to prevent Linux from configuring SCIF1 which is used by Zephyr.
252
253.. code-block:: diff
254
255    diff --git a/arch/arm64/boot/dts/renesas/rzg3s-smarc.dtsi b/arch/arm64/boot/dts/renesas/rzg3s-smarc.dtsi
256    index f01801b18e8a..d9f9a0a2bb08 100644
257    --- a/arch/arm64/boot/dts/renesas/rzg3s-smarc.dtsi
258    +++ b/arch/arm64/boot/dts/renesas/rzg3s-smarc.dtsi
259    @@ -347,7 +347,7 @@ &scif1 {
260            pinctrl-0 = <&scif1_pins>;
261            pinctrl-names = "default";
262            uart-has-rtscts;
263    -       status = "okay";
264    +       status = "disabled";
265    };
266    #elif SPDIF_SEL == SW_ON
267    &spdif {
268
269References
270**********
271
272.. target-notes::
273
274.. _RZ/G3S Group Website:
275   https://www.renesas.com/us/en/products/microcontrollers-microprocessors/rz-mpus/rzg3s-general-purpose-microprocessors-single-core-arm-cortex-a55-11-ghz-cpu-and-dual-core-cortex-m33-250
276
277.. _RZG3S-EVKIT Website:
278   https://www.renesas.com/us/en/products/microcontrollers-microprocessors/rz-mpus/rzg3s-evkit-evaluation-board-kit-rzg3s-mpu
279
280.. _SMARC EVK of RZ/G3S Linux Start-up Guide:
281   https://www.renesas.com/us/en/document/gde/smarc-evk-rzg3s-linux-start-guide-rev104
282