1.. zephyr:board:: imx8mp_evk
2
3Overview
4********
5
6i.MX8M Plus LPDDR4 EVK board is based on NXP i.MX8M Plus applications
7processor, composed of a quad Cortex®-A53 cluster and a single Cortex®-M7 core.
8Zephyr OS is ported to run on the Cortex®-A53 core.
9
10- Board features:
11
12  - RAM: 2GB LPDDR4
13  - Storage:
14
15    - SanDisk 16GB eMMC5.1
16    - Micron 32MB QSPI NOR
17    - microSD Socket
18  - Wireless:
19
20    - WiFi: 2.4/5GHz IEEE 802.11b/g/n
21    - Bluetooth: v4.1
22  - USB:
23
24    - OTG - 2x type C
25  - Ethernet
26  - PCI-E M.2
27  - Connectors:
28
29    - 40-Pin Dual Row Header
30  - LEDs:
31
32    - 1x Power status LED
33    - 1x UART LED
34  - Debug
35
36    - JTAG 20-pin connector
37    - MicroUSB for UART debug, two COM ports for A53 and M4
38
39More information about the board can be found at the
40`NXP website`_.
41
42Supported Features
43==================
44
45The Zephyr mimx8mp_evk_a53 board configuration supports the following hardware
46features:
47
48+-----------+------------+-------------------------------------+
49| Interface | Controller | Driver/Component                    |
50+===========+============+=====================================+
51| GIC-v3    | on-chip    | interrupt controller                |
52+-----------+------------+-------------------------------------+
53| ARM TIMER | on-chip    | system clock                        |
54+-----------+------------+-------------------------------------+
55| CLOCK     | on-chip    | clock_control                       |
56+-----------+------------+-------------------------------------+
57| PINMUX    | on-chip    | pinmux                              |
58+-----------+------------+-------------------------------------+
59| RDC       | on-chip    | Resource Domain Controller          |
60+-----------+------------+-------------------------------------+
61| UART      | on-chip    | serial port                         |
62+-----------+------------+-------------------------------------+
63| ENET      | on-chip    | ethernet port                       |
64+-----------+------------+-------------------------------------+
65
66The Zephyr mimx8mp_evk_m7 board configuration supports the following hardware
67features:
68
69+-----------+------------+-------------------------------------+
70| Interface | Controller | Driver/Component                    |
71+===========+============+=====================================+
72| NVIC      | on-chip    | nested vector interrupt controller  |
73+-----------+------------+-------------------------------------+
74| SYSTICK   | on-chip    | systick                             |
75+-----------+------------+-------------------------------------+
76| CLOCK     | on-chip    | clock_control                       |
77+-----------+------------+-------------------------------------+
78| PINMUX    | on-chip    | pinmux                              |
79+-----------+------------+-------------------------------------+
80| UART      | on-chip    | serial port-polling;                |
81|           |            | serial port-interrupt               |
82+-----------+------------+-------------------------------------+
83
84Devices
85========
86System Clock
87------------
88
89This board configuration uses a system clock frequency of 8 MHz.
90
91The M7 Core is configured to run at a 800 MHz clock speed.
92
93Serial Port
94-----------
95
96This board configuration uses a single serial communication channel with the
97CPU's UART4.
98
99Programming and Debugging (A53)
100*******************************
101
102U-Boot "cpu" command is used to load and kick Zephyr to Cortex-A secondary Core, Currently
103it is supported in : `Real-Time Edge U-Boot`_ (use the branch "uboot_vxxxx.xx-y.y.y,
104xxxx.xx is uboot version and y.y.y is Real-Time Edge Software version, for example
105"uboot_v2023.04-2.9.0" branch is U-Boot v2023.04 used in Real-Time Edge Software release
106v2.9.0), and pre-build images and user guide can be found at `Real-Time Edge Software`_.
107
108.. _Real-Time Edge U-Boot:
109   https://github.com/nxp-real-time-edge-sw/real-time-edge-uboot
110.. _Real-Time Edge Software:
111   https://www.nxp.com/rtedge
112
113Copy the compiled ``zephyr.bin`` to the first FAT partition of the SD card and
114plug the SD card into the board. Power it up and stop the u-boot execution at
115prompt.
116
117Use U-Boot to load and kick zephyr.bin to Cortex-A53 Core0:
118
119.. code-block:: console
120
121    fatload mmc 1:1 0xc0000000 zephyr.bin; dcache flush; icache flush; go 0xc0000000
122
123Or kick zephyr.bin to the other Cortex-A53 Core, for example Core2:
124
125.. code-block:: console
126
127    fatload mmc 1:1 0xc0000000 zephyr.bin; dcache flush; icache flush; cpu 2 release 0xc0000000
128
129Use this configuration to run basic Zephyr applications and kernel tests,
130for example, with the :zephyr:code-sample:`synchronization` sample:
131
132.. zephyr-app-commands::
133   :zephyr-app: samples/synchronization
134   :host-os: unix
135   :board: imx8mp_evk/mimx8ml8/a53
136   :goals: run
137
138This will build an image with the synchronization sample app, boot it and
139display the following console output:
140
141.. code-block:: console
142
143    *** Booting Zephyr OS build zephyr-v3.1.0-3575-g44dd713bd883  ***
144    thread_a: Hello World from cpu 0 on mimx8mp_evk_a53!
145    thread_b: Hello World from cpu 0 on mimx8mp_evk_a53!
146    thread_a: Hello World from cpu 0 on mimx8mp_evk_a53!
147    thread_b: Hello World from cpu 0 on mimx8mp_evk_a53!
148    thread_a: Hello World from cpu 0 on mimx8mp_evk_a53!
149
150Use Jailhouse hypervisor, after root cell linux is up:
151
152.. code-block:: console
153
154    #jailhouse enable imx8mp.cell
155    #jailhouse cell create imx8mp-zephyr.cell
156    #jailhouse cell load 1 zephyr.bin -a 0xc0000000
157    #jailhouse cell start 1
158
159Programming and Debugging (M7)
160******************************
161
162The MIMX8MP EVK board doesn't have QSPI flash for the M7, and it needs
163to be started by the A53 core. The A53 core is responsible to load the M7 binary
164application into the RAM, put the M7 in reset, set the M7 Program Counter and
165Stack Pointer, and get the M7 out of reset. The A53 can perform these steps at
166bootloader level or after the Linux system has booted.
167
168The M7 can use up to 3 different RAMs (currently, only two configurations are
169supported: ITCM and DDR). These are the memory mapping for A53 and M7:
170
171+------------+-------------------------+------------------------+-----------------------+----------------------+
172| Region     | Cortex-A53              | Cortex-M7 (System Bus) | Cortex-M7 (Code Bus)  | Size                 |
173+============+=========================+========================+=======================+======================+
174| OCRAM      | 0x00900000-0x0098FFFF   | 0x20200000-0x2028FFFF  | 0x00900000-0x0098FFFF | 576KB                |
175+------------+-------------------------+------------------------+-----------------------+----------------------+
176| DTCM       | 0x00800000-0x0081FFFF   | 0x20000000-0x2001FFFF  |                       | 128KB                |
177+------------+-------------------------+------------------------+-----------------------+----------------------+
178| ITCM       | 0x007E0000-0x007FFFFF   |                        | 0x00000000-0x0001FFFF | 128KB                |
179+------------+-------------------------+------------------------+-----------------------+----------------------+
180| OCRAM_S    | 0x00180000-0x00188FFF   | 0x20180000-0x20188FFF  | 0x00180000-0x00188FFF | 36KB                 |
181+------------+-------------------------+------------------------+-----------------------+----------------------+
182| DDR        | 0x80000000-0x803FFFFF   | 0x80200000-0x803FFFFF  | 0x80000000-0x801FFFFF | 2MB                  |
183+------------+-------------------------+------------------------+-----------------------+----------------------+
184
185For more information about memory mapping see the
186`i.MX 8M Applications Processor Reference Manual`_  (section 2.1 to 2.3)
187
188At compilation time you have to choose which RAM will be used. This
189configuration is done based on board name (imx8mp_evk/mimx8ml8/m7 for ITCM and
190imx8mp_evk/mimx8ml8/m7/ddr for DDR).
191
192There are two methods to load M7 Core images: U-Boot command and Linux remoteproc.
193
194Load and Run M7 Zephyr Image from U-Boot
195========================================
196
197Load and run Zephyr on M7 from A53 using u-boot by copying the compiled
198``zephyr.bin`` to the first FAT partition of the SD card and plug the SD
199card into the board. Power it up and stop the u-boot execution at prompt.
200
201Load the M7 binary onto the desired memory and start its execution using:
202
203ITCM
204====
205
206.. code-block:: console
207
208   fatload mmc 0:1 0x48000000 zephyr.bin
209   cp.b 0x48000000 0x7e0000 20000
210   bootaux 0x7e0000
211
212DDR
213===
214
215.. code-block:: console
216
217   fatload mmc 0:1 0x80000000 zephyr.bin
218   dcache flush
219   bootaux 0x80000000
220
221Load and Run M7 Zephyr Image by using Linux remoteproc
222======================================================
223
224Prepare device tree:
225
226The device tree must inlcude CM7 dts node with compatible string "fsl,imx8mn-cm7",
227and also need to reserve M4 DDR memory if using DDR code and sys address, and also
228need to put "m4_reserved" in the list of memory-region property of the cm7 node.
229
230.. code-block:: console
231
232   reserved-memory {
233            #address-cells = <2>;
234            #size-cells = <2>;
235            ranges;
236
237            m7_reserved: m4@80000000 {
238                  no-map;
239                  reg = <0 0x80000000 0 0x1000000>;
240            };
241            ...
242   }
243
244
245   imx8mp-cm7 {
246            compatible = "fsl,imx8mn-cm7";
247            rsc-da = <0x55000000>;
248            clocks = <&clk IMX8MP_CLK_M7_DIV>,
249                     <&audio_blk_ctrl IMX8MP_CLK_AUDIO_BLK_CTRL_AUDPLL_ROOT>;
250            clock-names = "core", "audio";
251            mbox-names = "tx", "rx", "rxdb";
252            mboxes = <&mu 0 1
253                     &mu 1 1
254                     &mu 3 1>;
255            memory-region = <&vdevbuffer>, <&vdev0vring0>, <&vdev0vring1>, <&rsc_table>, <&m7_reserved>;
256            status = "okay";
257            fsl,startup-delay-ms = <500>;
258   };
259
260Extra Zephyr Kernel configure item for DDR Image:
261
262If use remotepoc to boot DDR board (imx8mp_evk/mimx8ml8/m7/ddr), also need to enable
263"CONFIG_ROMSTART_RELOCATION_ROM" in order to put romstart memory section into ITCM because
264M7 Core will get the first instruction from zero address of ITCM, but romstart relocation
265will make the storage size of zephyr.bin too large, so we don't enable it by default in
266board defconfig.
267
268.. code-block:: console
269
270   diff --git a/boards/nxp/imx8mp_evk/imx8mp_evk_mimx8ml8_m7_ddr_defconfig b/boards/nxp/imx8mp_evk/imx8mp_evk_mimx8ml8_m7_ddr_defconfig
271   index 17542cb4eec..8c30c5b6fa3 100644
272   --- a/boards/nxp/imx8mp_evk/imx8mp_evk_mimx8ml8_m7_ddr_defconfig
273   +++ b/boards/nxp/imx8mp_evk/imx8mp_evk_mimx8ml8_m7_ddr_defconfig
274   @@ -12,3 +12,4 @@ CONFIG_CONSOLE=y
275   CONFIG_XIP=y
276   CONFIG_CODE_DDR=y
277   +CONFIG_ROMSTART_RELOCATION_ROM=y
278
279Then use the following steps to boot Zephyr kernel:
280
2811. In U-Boot command line execute prepare script:
282
283.. code-block:: console
284
285   u-boot=> run prepare_mcore
286
2872. Boot Linux kernel with specified dtb and then boot Zephyr by using remoteproc:
288
289.. code-block:: console
290
291   root@imx8mp-lpddr4-evk:~# echo zephyr.elf > /sys/devices/platform/imx8mp-cm7/remoteproc/remoteproc0/firmware
292   root@imx8mp-lpddr4-evk:~# echo start  > /sys/devices/platform/imx8mp-cm7/remoteproc/remoteproc0/state
293   [   39.195651] remoteproc remoteproc0: powering up imx-rproc
294   [   39.203345] remoteproc remoteproc0: Booting fw image zephyr.elf, size 503992
295   [   39.203388] remoteproc remoteproc0: No resource table in elf
296   root@imx8mp-lpddr4-evk:~# [   39.711380] remoteproc remoteproc0: remote processor imx-rproc is now up
297
298   root@imx8mp-lpddr4-evk:~#
299
300Debugging
301=========
302
303MIMX8MP EVK board can be debugged by connecting an external JLink
304JTAG debugger to the J24 debug connector and to the PC. Then
305the application can be debugged using the usual way.
306
307Here is an example for the :zephyr:code-sample:`hello_world` application.
308
309.. zephyr-app-commands::
310   :zephyr-app: samples/hello_world
311   :board: imx8mp_evk/mimx8ml8/m7
312   :goals: debug
313
314Open a serial terminal, step through the application in your debugger, and you
315should see the following message in the terminal:
316
317.. code-block:: console
318
319   *** Booting Zephyr OS build v2.7.99-1310-g2801bf644a91  ***
320   Hello World! imx8mp_evk
321
322References
323==========
324
325.. _NXP website:
326   https://www.nxp.com/design/development-boards/i-mx-evaluation-and-development-boards/evaluation-kit-for-the-i-mx-8m-plus-applications-processor:8MPLUSLPD4-EVK
327
328.. _i.MX 8M Applications Processor Reference Manual:
329   https://www.nxp.com/webapp/Download?colCode=IMX8MPRM
330