1.. zephyr:board:: imx8mm_evk
2
3Overview
4********
5
6i.MX8M Mini LPDDR4 EVK board is based on NXP i.MX8M Mini applications
7processor, composed of a quad Cortex®-A53 cluster and a single Cortex®-M4 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 imx8mm_evk board for Cortex-A53 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| GPT       | on-chip    | timer                               |
64+-----------+------------+-------------------------------------+
65| ENET      | on-chip    | ethernet port                       |
66+-----------+------------+-------------------------------------+
67
68The Zephyr imx8mm_evk board for Cortex-M4 supports the following hardware
69features:
70
71+-----------+------------+-------------------------------------+
72| Interface | Controller | Driver/Component                    |
73+===========+============+=====================================+
74| NVIC      | on-chip    | nested vector interrupt controller  |
75+-----------+------------+-------------------------------------+
76| SYSTICK   | on-chip    | systick                             |
77+-----------+------------+-------------------------------------+
78| CLOCK     | on-chip    | clock_control                       |
79+-----------+------------+-------------------------------------+
80| PINMUX    | on-chip    | pinmux                              |
81+-----------+------------+-------------------------------------+
82| UART      | on-chip    | serial port-polling;                |
83|           |            | serial port-interrupt               |
84+-----------+------------+-------------------------------------+
85| GPIO      | on-chip    | GPIO output                         |
86|           |            | GPIO input                          |
87+-----------+------------+-------------------------------------+
88
89The default configuration can be found in the defconfig file:
90:zephyr_file:`boards/nxp/imx8mm_evk/imx8mm_evk_mimx8mm6_m4_defconfig`
91
92It is recommended to disable peripherals used by the M4 core on the Linux host.
93
94Other hardware features are not currently supported by the port.
95
96Devices
97========
98System Clock
99------------
100
101This board configuration uses a system clock frequency of 8 MHz.
102
103The M4 Core is configured to run at a 400 MHz clock speed.
104
105Serial Port
106-----------
107
108This board configuration uses a single serial communication channel with the
109CPU's UART4. This is used for the M4 and A53 core targets.
110
111Programming and Debugging (A53)
112*******************************
113
114U-Boot "cpu" command is used to load and kick Zephyr to Cortex-A secondary Core, Currently
115it is supported in : `Real-Time Edge U-Boot`_ (use the branch "uboot_vxxxx.xx-y.y.y,
116xxxx.xx is uboot version and y.y.y is Real-Time Edge Software version, for example
117"uboot_v2023.04-2.9.0" branch is U-Boot v2023.04 used in Real-Time Edge Software release
118v2.9.0), and pre-build images and user guide can be found at `Real-Time Edge Software`_.
119
120.. _Real-Time Edge U-Boot:
121   https://github.com/nxp-real-time-edge-sw/real-time-edge-uboot
122.. _Real-Time Edge Software:
123   https://www.nxp.com/rtedge
124
125Copy the compiled ``zephyr.bin`` to the first FAT partition of the SD card and
126plug the SD card into the board. Power it up and stop the u-boot execution at
127prompt.
128
129Use U-Boot to load and kick zephyr.bin to Cortex-A53 Core0:
130
131.. code-block:: console
132
133    fatload mmc 1:1 0x93c00000 zephyr.bin; dcache flush; icache flush; go 0x93c00000
134
135Or kick zephyr.bin to the other Cortex-A53 Core, for example Core2:
136
137.. code-block:: console
138
139    fatload mmc 1:1 0x93c00000 zephyr.bin; dcache flush; icache flush; cpu 2 release 0x93c00000
140
141
142Use this configuration to run basic Zephyr applications and kernel tests,
143for example, with the :zephyr:code-sample:`synchronization` sample:
144
145.. zephyr-app-commands::
146   :zephyr-app: samples/synchronization
147   :host-os: unix
148   :board: imx8mm_evk/mimx8mm6/a53
149   :goals: run
150
151This will build an image with the synchronization sample app, boot it and
152display the following ram console output:
153
154.. code-block:: console
155
156    *** Booting Zephyr OS build zephyr-v3.1.0-3575-g44dd713bd883  ***
157    thread_a: Hello World from cpu 0 on mimx8mm_evk_a53!
158    thread_b: Hello World from cpu 0 on mimx8mm_evk_a53!
159    thread_a: Hello World from cpu 0 on mimx8mm_evk_a53!
160    thread_b: Hello World from cpu 0 on mimx8mm_evk_a53!
161    thread_a: Hello World from cpu 0 on mimx8mm_evk_a53!
162
163Use Jailhouse hypervisor, after root cell linux is up:
164
165.. code-block:: console
166
167    #jailhouse enable imx8mm.cell
168    #jailhouse cell create imx8mm-zephyr.cell
169    #jailhouse cell load 1 zephyr.bin -a 0x93c00000
170    #jailhouse cell start 1
171
172Programming and Debugging (M4)
173******************************
174
175The MIMX8MM EVK board doesn't have QSPI flash for the M4 and it needs
176to be started by the A53 core. The A53 core is responsible to load the M4 binary
177application into the RAM, put the M4 in reset, set the M4 Program Counter and
178Stack Pointer, and get the M4 out of reset. The A53 can perform these steps at
179bootloader level or after the Linux system has booted.
180
181The M4 can use up to 3 different RAMs. These are the memory mapping for A53 and M4:
182
183+------------+-------------------------+------------------------+-----------------------+----------------------+
184| Region     | Cortex-A53              | Cortex-M4 (System Bus) | Cortex-M4 (Code Bus)  | Size                 |
185+============+=========================+========================+=======================+======================+
186| OCRAM      | 0x00900000-0x0093FFFF   | 0x20200000-0x2023FFFF  | 0x00900000-0x0093FFFF | 256KB                |
187+------------+-------------------------+------------------------+-----------------------+----------------------+
188| TCMU       | 0x00800000-0x0081FFFF   | 0x20000000-0x2001FFFF  |                       | 128KB                |
189+------------+-------------------------+------------------------+-----------------------+----------------------+
190| TCML       | 0x007E0000-0x007FFFFF   |                        | 0x1FFE0000-0x1FFFFFFF | 128KB                |
191+------------+-------------------------+------------------------+-----------------------+----------------------+
192| OCRAM_S    | 0x00180000-0x00187FFF   | 0x20180000-0x20187FFF  | 0x00180000-0x00187FFF | 32KB                 |
193+------------+-------------------------+------------------------+-----------------------+----------------------+
194
195For more information about memory mapping see the
196`i.MX 8M Applications Processor Reference Manual`_  (section 2.1.2 and 2.1.3)
197
198At compilation time you have to choose which RAM will be used. This
199configuration is done in the file
200:zephyr_file:`boards/nxp/imx8mm_evk/imx8mm_evk_mimx8mm6_m4.dts`
201with "zephyr,flash" (when CONFIG_XIP=y) and "zephyr,sram" properties.
202The available configurations are:
203
204.. code-block:: none
205
206   "zephyr,flash"
207   - &tcml_code
208   - &ocram_code
209   - &ocram_s_code
210
211   "zephyr,sram"
212   - &tcmu_sys
213   - &ocram_sys
214   - &ocram_s_sys
215
216Load and run Zephyr on M4 from A53 using u-boot by copying the compiled
217``zephyr.bin`` to the first FAT partition of the SD card and plug the SD
218card into the board. Power it up and stop the u-boot execution at prompt.
219
220Load the M4 binary onto the desired memory and start its execution using:
221
222.. code-block:: console
223
224   fatload mmc 0:1 0x7e0000 zephyr.bin;bootaux 0x7e0000
225
226Debugging
227=========
228
229MIMX8MM EVK board can be debugged by connecting an external JLink
230JTAG debugger to the J902 debug connector and to the PC. Then
231the application can be debugged using the usual way.
232
233Here is an example for the :zephyr:code-sample:`hello_world` application.
234
235.. zephyr-app-commands::
236   :zephyr-app: samples/hello_world
237   :board: imx8mm_evk/mimx8mm6/m4
238   :goals: debug
239
240Open a serial terminal, step through the application in your debugger, and you
241should see the following message in the terminal:
242
243.. code-block:: console
244
245   ***** Booting Zephyr OS build zephyr-v2.0.0-1859-g292afe8533c0 *****
246   Hello World! imx8mm_evk
247
248References
249==========
250
251.. _NXP website:
252   https://www.nxp.com/design/development-boards/i.mx-evaluation-and-development-boards/evaluation-kit-for-thebr-i.mx-8m-mini-applications-processor:8MMINILPD4-EVK
253
254.. _i.MX 8M Applications Processor Reference Manual:
255   https://www.nxp.com/webapp/Download?colCode=IMX8MMRM
256