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