1.. _s32z270dc2_r52:
2
3NXP X-S32Z27X-DC (DC2)
4######################
5
6Overview
7********
8
9The X-S32Z27X-DC (DC2) board is based on the NXP S32Z270 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 RTU:
14
15- ``s32z270dc2_rtu0_r52``, for RTU0
16- ``s32z270dc2_rtu1_r52``, for 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 ``s32z270dc2_rtu0_r52`` and ``s32z270dc2_rtu1_r52`` boards
146can be built in the usual way as documented in :ref:`build_an_application`.
147
148Currently is only possible to load and execute a Zephyr application binary on
149this board from the internal SRAM, using `Lauterbach TRACE32`_ development
150tools and debuggers.
151
152.. note::
153   Currently, the start-up scripts executed with ``west flash`` and
154   ``west debug`` commands perform the same steps to initialize the SoC and
155   load the application to SRAM. The difference is that ``west flash`` hide the
156   Lauterbach TRACE32 interface, executes the application and exits.
157
158Install Lauterbach TRACE32 Software
159===================================
160
161Follow the steps described in :ref:`lauterbach-trace32-debug-host-tools` to
162install and set-up Lauterbach TRACE32 software.
163
164Set-up the Board
165================
166
167Connect the Lauterbach TRACE32 debugger to the board's JTAG connector (``J134``)
168and to the host computer.
169
170For visualizing the serial output, connect the board's USB/UART port (``J119``) to
171the host computer and run your favorite terminal program to listen for output.
172For example, using the cross-platform `pySerial miniterm`_ terminal:
173
174.. code-block:: console
175
176   python -m serial.tools.miniterm <port> 115200
177
178Replace ``<port>`` with the port where the board can be found. For example,
179under Linux, ``/dev/ttyUSB0``.
180
181Flashing
182========
183
184For example, you can build and run the :ref:`hello_world` sample for the board
185``s32z270dc2_rtu0_r52`` with:
186
187.. zephyr-app-commands::
188   :zephyr-app: samples/hello_world
189   :board: s32z270dc2_rtu0_r52
190   :goals: build flash
191
192In case you are using a newer PCB revision, you have to use an adapted board
193definition as the default PCB revision is B. For example, if using revision D:
194
195.. zephyr-app-commands::
196   :zephyr-app: samples/hello_world
197   :board: s32z270dc2_rtu0_r52@D
198   :goals: build flash
199
200You should see the following message in the terminal:
201
202.. code-block:: console
203
204   Hello World! s32z270dc2_rtu0_r52
205
206Debugging
207=========
208
209To enable debugging using Lauterbach TRACE32 software, run instead:
210
211.. zephyr-app-commands::
212   :zephyr-app: samples/hello_world
213   :board: s32z270dc2_rtu0_r52
214   :goals: build debug
215
216Step through the application in your debugger, and you should see the following
217message in the terminal:
218
219.. code-block:: console
220
221   Hello World! s32z270dc2_rtu0_r52
222
223RTU and Core Configuration
224==========================
225
226This Zephyr port can only run single core in any of the Cortex-R52 cores,
227either in lock-step or split-lock mode. By default, Zephyr runs on the first
228core of the RTU chosen and in lock-step mode (which is the reset
229configuration).
230
231To build for split-lock mode, the :kconfig:option:`CONFIG_DCLS` must be
232disabled from your application Kconfig file.
233
234Additionally, to run in a different core or with a different core
235configuration than the default, extra parameters must be provided to the runner
236as follows:
237
238.. code-block:: console
239
240   west <command> --startup-args elfFile=<elf_path> rtu=<rtu_id> \
241      core=<core_id> lockstep=<yes/no>
242
243Where:
244
245- ``<command>`` is ``flash`` or ``debug``
246- ``<elf_path>`` is the path to the Zephyr application ELF in the output
247  directory
248- ``<rtu_id>`` is the zero-based RTU index (0 for ``s32z270dc2_rtu0_r52``
249  and 1 for ``s32z270dc2_rtu1_r52``)
250- ``<core_id>`` is the zero-based core index relative to the RTU on which to
251  run the Zephyr application (0, 1, 2 or 3)
252- ``<yes/no>`` can be ``yes`` to run in lock-step, or ``no`` to run in
253  split-lock.
254
255For example, to build the :ref:`hello_world` sample for the board
256``s32z270dc2_rtu0_r52`` with split-lock core configuration:
257
258.. zephyr-app-commands::
259   :zephyr-app: samples/hello_world
260   :board: s32z270dc2_rtu0_r52
261   :goals: build
262   :gen-args: -DCONFIG_DCLS=n
263
264To execute this sample in the second core of RTU0 in split-lock mode:
265
266.. code-block:: console
267
268   west flash --startup-args elfFile=build/zephyr/zephyr.elf \
269      rtu=0 core=1 lockstep=no
270
271References
272**********
273
274.. target-notes::
275
276.. _NXP S32Z2 Real-Time Processors website:
277   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
278
279.. _Lauterbach TRACE32:
280   https://www.lauterbach.com
281
282.. _pySerial miniterm:
283   https://pyserial.readthedocs.io/en/latest/tools.html#module-serial.tools.miniterm
284