1.. zephyr:board:: s32z2xxdc2
2
3Overview
4********
5
6The X-S32Z27X-DC (DC2) board is based on the NXP S32Z2 Real-Time Processor,
7which includes two Real-Time Units (RTU) composed of four ARM Cortex-R52 cores
8each, with flexible split/lock configurations.
9
10There is one Zephyr board per SoC/RTU:
11
12- ``s32z2xxdc2/s32z270/rtu0``, for S32Z270/RTU0
13- ``s32z2xxdc2/s32z270/rtu1``, for S32Z270/RTU1.
14
15Hardware
16********
17
18Information about the hardware and design resources can be found at
19`NXP S32Z2 Real-Time Processors website`_.
20
21Supported Features
22==================
23
24The boards support the following hardware features:
25
26+-----------+------------+-------------------------------------+
27| Interface | Controller | Driver/Component                    |
28+===========+============+=====================================+
29| Arm GIC   | on-chip    | interrupt_controller                |
30+-----------+------------+-------------------------------------+
31| Arm Timer | on-chip    | timer                               |
32+-----------+------------+-------------------------------------+
33| LINFlexD  | on-chip    | serial                              |
34+-----------+------------+-------------------------------------+
35| MRU       | on-chip    | mbox                                |
36+-----------+------------+-------------------------------------+
37| NETC      | on-chip    | ethernet                            |
38|           |            |                                     |
39|           |            | mdio                                |
40+-----------+------------+-------------------------------------+
41| SIUL2     | on-chip    | pinctrl                             |
42|           |            |                                     |
43|           |            | gpio                                |
44|           |            |                                     |
45|           |            | external interrupt controller       |
46+-----------+------------+-------------------------------------+
47| SPI       | on-chip    | spi                                 |
48+-----------+------------+-------------------------------------+
49| SWT       | on-chip    | watchdog                            |
50+-----------+------------+-------------------------------------+
51| CANEXCEL  | on-chip    | can                                 |
52+-----------+------------+-------------------------------------+
53| FLEXCAN   | on-chip    | can                                 |
54+-----------+------------+-------------------------------------+
55| SAR_ADC   | on-chip    | adc                                 |
56+-----------+------------+-------------------------------------+
57| LPI2C     | on-chip    | i2c                                 |
58+-----------+------------+-------------------------------------+
59| EDMA      | on-chip    | dma                                 |
60+-----------+------------+-------------------------------------+
61| DSPI      | on-chip    | spi                                 |
62+-----------+------------+-------------------------------------+
63
64Other hardware features are not currently supported by the port.
65
66Connections and IOs
67===================
68
69The SoC's pads are grouped into ports and pins for consistency with GPIO driver
70and the HAL drivers used by this Zephyr port. The following table summarizes
71the mapping between pads and ports/pins. This must be taken into account when
72using GPIO driver or configuring the pinmuxing for the device drivers.
73
74+-------------------+-------------+
75| Pads              | Port/Pins   |
76+===================+=============+
77| PAD_000 - PAD_015 | PA0 - PA15  |
78+-------------------+-------------+
79| PAD_016 - PAD_030 | PB0 - PB14  |
80+-------------------+-------------+
81| PAD_031           | PC15        |
82+-------------------+-------------+
83| PAD_032 - PAD_047 | PD0 - PD15  |
84+-------------------+-------------+
85| PAD_048 - PAD_063 | PE0 - PE15  |
86+-------------------+-------------+
87| PAD_064 - PAD_079 | PF0 - PF15  |
88+-------------------+-------------+
89| PAD_080 - PAD_091 | PG0 - PG11  |
90+-------------------+-------------+
91| PAD_092 - PAD_095 | PH12 - PH15 |
92+-------------------+-------------+
93| PAD_096 - PAD_111 | PI0 - PI15  |
94+-------------------+-------------+
95| PAD_112 - PAD_127 | PJ0 - PJ15  |
96+-------------------+-------------+
97| PAD_128 - PAD_143 | PK0 - PK15  |
98+-------------------+-------------+
99| PAD_144 - PAD_145 | PL0 - PL1   |
100+-------------------+-------------+
101| PAD_146 - PAD_159 | PM2 - PM15  |
102+-------------------+-------------+
103| PAD_160 - PAD_169 | PN0 - PN9   |
104+-------------------+-------------+
105| PAD_170 - PAD_173 | PO10 - PO13 |
106+-------------------+-------------+
107
108This board does not include user LED's or switches, which are needed for some
109of the samples such as :zephyr:code-sample:`blinky` or :zephyr:code-sample:`button`.
110Follow the steps described in the sample description to enable support for this
111board.
112
113System Clock
114============
115
116The Cortex-R52 cores are configured to run at 1 GHz.
117
118Serial Port
119===========
120
121The SoC has 12 LINFlexD instances that can be used in UART mode. The console can
122be accessed by default on the USB micro-B connector J119.
123
124Watchdog
125========
126
127The watchdog driver only supports triggering an interrupt upon timer expiration.
128Zephyr is currently running from SRAM on this board, thus system reset is not
129supported.
130
131Ethernet
132========
133
134NETC driver supports to manage the Physical Station Interface (PSI0) and/or a
135single Virtual SI (VSI). The rest of the VSI's shall be assigned to different
136cores of the system. Refer to :zephyr:code-sample:`nxp_s32_netc` to learn how to
137configure the Ethernet network controller.
138
139Controller Area Network
140=======================
141
142CANEXCEL
143--------
144
145CANEXCEL supports CAN Classic (CAN 2.0) and CAN FD modes. Remote transmission
146request is not supported.
147
148Note that this board does not currently come with CAN transceivers installed for
149the CANEXCEL ports. To facilitate external traffic, you will need to add a CAN
150transceiver. Any transceiver pin-compatible with CAN 2.0 and CAN FD protocols
151can be used.
152
153FlexCAN
154-------
155
156FlexCAN supports CAN Classic (CAN 2.0) and CAN FD modes.
157
158ADC
159===
160
161ADC is provided through ADC SAR controller with 2 instances. Each ADC SAR instance has
16212-bit resolution. ADC channels are divided into 2 groups (precision and internal/standard).
163
164.. note::
165   All channels of an instance only run on 1 group channel at the same time.
166
167EDMA
168====
169
170The EDMA modules feature four EDMA3 instances: Instance 0 with 32 channels,
171and instances 1, 4, and 5, each with 16 channels.
172
173Programming and Debugging
174*************************
175
176Applications for the ``s32z2xxdc2`` boards can be built in the usual way as
177documented in :ref:`build_an_application`.
178
179Currently is only possible to load and execute a Zephyr application binary on
180this board from the core internal SRAM.
181
182This board supports West runners for the following debug tools:
183
184- :ref:`NXP S32 Debug Probe <nxp-s32-debug-probe>` (default)
185- :ref:`Lauterbach TRACE32 <lauterbach-trace32-debug-host-tools>`
186
187Follow the installation steps of the debug tool you plan to use before loading
188your firmware.
189
190Set-up the Board
191================
192
193Connect the external debugger probe to the board's JTAG connector (``J134``)
194and to the host computer via USB or Ethernet, as supported by the probe.
195
196For visualizing the serial output, connect the board's USB/UART port (``J119``) to
197the host computer and run your favorite terminal program to listen for output.
198For example, using the cross-platform `pySerial miniterm`_ terminal:
199
200.. code-block:: console
201
202   python -m serial.tools.miniterm <port> 115200
203
204Replace ``<port>`` with the port where the board can be found. For example,
205under Linux, ``/dev/ttyUSB0``.
206
207Debugging
208=========
209
210You can build and debug the :zephyr:code-sample:`hello_world` sample for the board
211``s32z2xxdc2/s32z270/rtu0`` with:
212
213.. zephyr-app-commands::
214   :zephyr-app: samples/hello_world
215   :board: s32z2xxdc2/s32z270/rtu0
216   :goals: build debug
217
218In case you are using a newer PCB revision, you have to use an adapted board
219definition as the default PCB revision is B. For example, if using revision D:
220
221.. zephyr-app-commands::
222   :zephyr-app: samples/hello_world
223   :board: s32z2xxdc2@D/s32z270/rtu0
224   :goals: build debug
225   :compact:
226
227At this point you can do your normal debug session. Set breakpoints and then
228:kbd:`c` to continue into the program. You should see the following message in
229the terminal:
230
231.. code-block:: console
232
233   Hello World! s32z2xxdc2
234
235To debug with Lauterbach TRACE32 softare run instead:
236
237.. zephyr-app-commands::
238   :zephyr-app: samples/hello_world
239   :board: s32z2xxdc2/s32z270/rtu0
240   :goals: build debug -r trace32
241   :compact:
242
243Flashing
244========
245
246Follow these steps if you just want to download the application to the board
247SRAM and run.
248
249``flash`` command is supported only by the Lauterbach TRACE32 runner:
250
251.. zephyr-app-commands::
252   :zephyr-app: samples/hello_world
253   :board: s32z2xxdc2/s32z270/rtu0
254   :goals: build flash -r trace32
255   :compact:
256
257.. note::
258   Currently, the Lauterbach start-up scripts executed with ``flash`` and
259   ``debug`` commands perform the same steps to initialize the SoC and
260   load the application to SRAM. The difference is that ``flash`` hides the
261   Lauterbach TRACE32 interface, executes the application and exits.
262
263To imitate a similar behavior using NXP S32 Debug Probe runner, you can run the
264``debug`` command with GDB in batch mode:
265
266.. zephyr-app-commands::
267   :zephyr-app: samples/hello_world
268   :board: s32z2xxdc2/s32z270/rtu0
269   :goals: build debug --tool-opt='--batch'
270   :compact:
271
272RTU and Core Configuration
273==========================
274
275This Zephyr port can only run single core in any of the Cortex-R52 cores,
276either in lock-step or split-lock mode. By default, Zephyr runs on the first
277core of the RTU chosen and in lock-step mode (which is the reset
278configuration).
279
280To build for split-lock mode, the :kconfig:option:`CONFIG_DCLS` must be
281disabled from your application Kconfig file.
282
283By default the board configuration will set the runner arguments according to
284the build configuration. To debug for a core different than the default use:
285
286.. tabs::
287
288   .. group-tab:: lockstep configuration
289
290      .. code-block:: console
291
292         west debug --core-name='R52_<rtu_id>_<core_id>_LS'
293
294   .. group-tab:: split-lock configuration
295
296      .. code-block:: console
297
298         west debug --core-name='R52_<rtu_id>_<core_id>'
299
300Where:
301
302- ``<rtu_id>`` is the zero-based RTU index
303- ``<core_id>`` is the zero-based core index relative to the RTU on which to
304  run the Zephyr application (0, 1, 2 or 3)
305
306For example, to build the :zephyr:code-sample:`hello_world` sample for the board
307``s32z2xxdc2/s32z270/rtu0`` with split-lock core configuration:
308
309.. zephyr-app-commands::
310   :zephyr-app: samples/hello_world
311   :board: s32z2xxdc2/s32z270/rtu0
312   :goals: build
313   :gen-args: -DCONFIG_DCLS=n
314   :compact:
315
316To execute this sample in the second core of RTU0 in split-lock mode:
317
318.. code-block:: console
319
320   west debug --core-name='R52_0_1'
321
322If using Lauterbach TRACE32, all runner parameters must be overridden from command
323line:
324
325.. code-block:: console
326
327   west debug --startup-args elfFile=<elf_path> rtu=<rtu_id> core=<core_id> lockstep=<yes/no>
328
329Where ``<elf_path>`` is the path to the Zephyr application ELF in the output
330directory.
331
332References
333**********
334
335.. target-notes::
336
337.. _NXP S32Z2 Real-Time Processors website:
338   https://www.nxp.com/products/processors-and-microcontrollers/s32-automotive-platform/s32z-and-s32e-real-time-processors/s32z2-safe-and-secure-high-performance-real-time-processors:S32Z2
339
340.. _pySerial miniterm:
341   https://pyserial.readthedocs.io/en/latest/tools.html#module-serial.tools.miniterm
342