1.. zephyr:board:: verdin_imx8mm
2
3Overview
4********
5
6The Verdin iMX8M Mini is a System on Module based on the NXP® i.MX 8M Mini family of
7embedded System on Chips (SoCs). The i.MX 8M Mini family consists of the i.MX 8M Mini Quad,
8i.MX 8M Mini QuadLite, i.MX 8M Mini Dual, i.MX 8M Mini DualLite, i.MX 8M Mini Solo, and i.MX
98M Mini SoloLite. The top-tier i.MX 8M Mini Quad features four Cortex-A53 cores as the main
10processor cluster. The cores provide complete 64-bit Armv8-A support while maintaining seamless
11backwards compatibility with 32-bit Armv7-A software. The main cores run at up to 1.8 GHz for
12commercial graded products and 1.6 GHz for industrial temperature range products.
13
14In addition to the main CPU complex, the i.MX 8M Mini features a Cortex-M4F processor which
15peaks up to 400 MHz. This processor is independent of the main complex and features its own
16dedicated interfaces while still being able to access the regular interfaces. This heterogeneous
17multicore system allows for the running of additional real-time operating systems on the M4 cores
18for time- and security-critical tasks.
19
20- Board features:
21
22  - RAM: 1GB - 2GB (LPDDR4)
23  - Storage:
24
25    - 4GB - 17GB eMMC
26    - 2KB I²C EEPROM
27  - Wireless:
28
29    - WiFi Dual-band 802.11 ac/a/b/g/n 2.4/5 GHz
30    - Bluetooth 5/BLE
31  - USB:
32
33    - 1x USB2.0 Host
34    - 1x USB2.0 OTG
35  - Ethernet Gigabit
36  - Interfaces:
37
38    - MIPI DSI 1x4 Data Lanes
39    - PCIe Gen 2
40    - MIPI CSI-2
41    - SPI
42    - QSPI
43    - UART
44    - I²C
45    - I²S
46    - SD/SDIO/MMC
47    - GPIOs
48    - CAN
49    - ADC
50    - S/PDIF
51  - Debug
52
53    - JTAG 10-pin connector
54
55More information about the board can be found at the
56`Toradex website`_.
57
58Supported Features
59==================
60
61The Zephyr ``verdin_imx8mm/mimx8mm6/m4`` board target supports the following hardware
62features:
63
64+-----------+------------+-------------------------------------+
65| Interface | Controller | Driver/Component                    |
66+===========+============+=====================================+
67| NVIC      | on-chip    | nested vector interrupt controller  |
68+-----------+------------+-------------------------------------+
69| SYSTICK   | on-chip    | systick                             |
70+-----------+------------+-------------------------------------+
71| CLOCK     | on-chip    | clock_control                       |
72+-----------+------------+-------------------------------------+
73| PINMUX    | on-chip    | pinmux                              |
74+-----------+------------+-------------------------------------+
75| UART      | on-chip    | serial port-polling;                |
76|           |            | serial port-interrupt               |
77+-----------+------------+-------------------------------------+
78| GPIO      | on-chip    | GPIO output                         |
79|           |            | GPIO input                          |
80+-----------+------------+-------------------------------------+
81
82The default configuration can be found in the defconfig file:
83:zephyr_file:`boards/toradex/verdin_imx8mm/verdin_imx8mm_mimx8mm6_m4_defconfig`.
84
85It is recommended to disable peripherals used by the M4 core on the Linux host.
86
87Other hardware features are not currently supported by the port.
88
89Connections and IOs
90===================
91
92UART:
93
94Zephyr is configured to use the UART4 by default, which is connected to the FTDI
95USB converter on most Toradex carrier boards.
96
97This is also the UART connected to WiFi/BT chip in modules that have the WiFi/BT
98chip. Therefore, if UART4 is used, WiFI/BT will not work properly.
99
100If the WiFi/BT is needed, then another UART should be used for Zephyr (UART2 for
101example). You can change the UART by changing the ``zephyr,console`` and
102``zephyr,shell-uart`` in the :zephyr_file:`boards/toradex/verdin_imx8mm/verdin_imx8mm_mimx8mm6_m4.dts` file.
103
104+---------------+-----------------+---------------------------+
105| Board Name    | SoC Name        | Usage                     |
106+===============+=================+===========================+
107| UART_1        | UART2           | General purpose UART      |
108+---------------+-----------------+---------------------------+
109| UART_2        | UART3           | General purpose UART      |
110+---------------+-----------------+---------------------------+
111| UART_3        | UART1           | Cortex-A53 debug UART     |
112+---------------+-----------------+---------------------------+
113| UART_4        | UART4           | Cortex-M4 debug UART      |
114+---------------+-----------------+---------------------------+
115
116GPIO:
117
118All the GPIO banks are enabled in the :zephyr_file:`dts/arm/nxp/nxp_imx8m_m4.dtsi`.
119
120LED:
121
122There is no LED in the module itself, this is dependent on the carrier board that
123is being used with the module. The device tree is configured to use the GPIO3_IO1,
124which can be connected to the LED of the Verdin Development Board or changed in the
125:zephyr_file:`boards/toradex/verdin_imx8mm/verdin_imx8mm_mimx8mm6_m4.dts` if needed.
126
127System Clock
128============
129
130The M4 Core is configured to run at a 400 MHz clock speed.
131
132Programming and Debugging
133*************************
134
135The i.MX8MM doesn't have QSPI flash for the M4 and it needs
136to be started by the A53 core. The A53 core is responsible to load the M4 binary
137application into the RAM, putting the M4 in reset, setting the M4 Program Counter and
138Stack Pointer, and get the M4 out of reset. The A53 can perform these steps at the
139bootloader level or after the Linux system has booted via RemoteProc.
140
141The M4 can use up to 3 different RAMs. These are the memory mapping for A53 and M4:
142
143+------------+-------------------------+------------------------+-----------------------+----------------------+
144| Region     | Cortex-A53              | Cortex-M4 (System Bus) | Cortex-M4 (Code Bus)  | Size                 |
145+============+=========================+========================+=======================+======================+
146| OCRAM      | 0x00900000-0x0093FFFF   | 0x20200000-0x2023FFFF  | 0x00900000-0x0093FFFF | 256KB                |
147+------------+-------------------------+------------------------+-----------------------+----------------------+
148| TCMU       | 0x00800000-0x0081FFFF   | 0x20000000-0x2001FFFF  |                       | 128KB                |
149+------------+-------------------------+------------------------+-----------------------+----------------------+
150| TCML       | 0x007E0000-0x007FFFFF   |                        | 0x1FFE0000-0x1FFFFFFF | 128KB                |
151+------------+-------------------------+------------------------+-----------------------+----------------------+
152| OCRAM_S    | 0x00180000-0x00187FFF   | 0x20180000-0x20187FFF  | 0x00180000-0x00187FFF | 32KB                 |
153+------------+-------------------------+------------------------+-----------------------+----------------------+
154
155For more information about memory mapping see the
156`i.MX 8M Applications Processor Reference Manual`_  (section 2.1.2 and 2.1.3)
157
158At compilation time you have to choose which RAM will be used. This
159configuration is done in the file :zephyr_file:`boards/toradex/verdin_imx8mm/verdin_imx8mm_mimx8mm6_m4.dts`
160with "zephyr,flash" (when CONFIG_XIP=y) and "zephyr,sram" properties.
161The available configurations are:
162
163.. code-block:: none
164
165   "zephyr,flash"
166   - &tcml_code
167   - &ocram_code
168   - &ocram_s_code
169
170   "zephyr,sram"
171   - &tcmu_sys
172   - &ocram_sys
173   - &ocram_s_sys
174
175Starting the Cortex-M4 via U-Boot
176=================================
177
178Load and run Zephyr on M4 from A53 using u-boot by copying the compiled
179``zephyr.bin`` to the eMMC (can be the FAT or EXT4 partition). You can do it
180by using a USB stick or through the ethernet with the scp command, for example.
181Power it up and stop at the u-boot prompt.
182
183Load the M4 binary onto the desired memory and start its execution using:
184
185.. code-block:: console
186
187   fatload mmc 0:1 ${loadaddr} zephyr.bin
188   cp.b ${loadaddr} 0x7e0000 <size_of_binary_in_bytes>
189   bootaux 0x7e0000
190
191Or if the binary is on the ext4 partition:
192
193.. code-block:: console
194
195   ext4load mmc 0:2 ${loadaddr} /path/to/zephyr.bin
196   cp.b ${loadaddr} 0x7e0000 <size_of_binary_in_bytes>
197   bootaux 0x7e0000
198
199If you are using `TorizonCore`_ OS, then you should use partition 1:
200
201.. code-block:: console
202
203   ext4load mmc 0:1 ${loadaddr} /path/to/zephyr.bin
204   cp.b ${loadaddr} 0x7e0000 <size_of_binary_in_bytes>
205   bootaux 0x7e0000
206
207Starting the Cortex-M4 via RemoteProc
208=====================================
209
210Copy the ``zepyhr.elf`` to ``/lib/firmware`` on the target.
211
212.. note::
213   In order to use remoteproc you have to add ``imx8mm-verdin_hmp_overlay.dtbo`` at
214   the end of the line in the ``/boot/overlays.txt``, then reboot the target. If
215   you are using `TorizonCore`_, then this file is located at
216   ``/boot/ostree/torizon-<hash>/dtb/overlays.txt``.
217
218To load and start a firmware use these commands:
219
220.. code-block:: console
221
222   verdin-imx8mm:~# echo zepyhr.elf > /sys/class/remoteproc/remoteproc0/firmware
223   verdin-imx8mm:~# echo start > /sys/class/remoteproc/remoteproc0/state
224   [   94.714498] remoteproc remoteproc0: powering up imx-rproc
225   [   94.720481] remoteproc remoteproc0: Booting fw image zephyr.elf, size 473172
226   [   94.727713] remoteproc remoteproc0: No resource table in elf
227   [   94.733615] remoteproc remoteproc0: remote processor imx-rproc is now up
228
229The M4-Core is now started up and running. You can see the output from Zephyr
230on UART4.
231
232Debugging
233=========
234
235MIMX8MM EVK board can be debugged by connecting an external JLink
236JTAG debugger to the J902 debug connector and to the PC. Then
237the application can be debugged using the usual way.
238
239Here is an example for the :zephyr:code-sample:`hello_world` application.
240
241.. zephyr-app-commands::
242   :zephyr-app: samples/hello_world
243   :board: verdin_imx8mm/mimx8mm6/m4
244   :goals: debug
245
246Open a serial terminal, step through the application in your debugger, and you
247should see the following message in the terminal:
248
249.. code-block:: console
250
251   *** Booting Zephyr OS build zephyr-v3.4.0-1251-g43c549305bdb ***
252   Hello World! verdin_imx8mm_m4
253
254.. _Toradex website:
255   https://developer.toradex.com/hardware/verdin-som-family/modules/verdin-imx8m-mini/
256
257.. _i.MX 8M Applications Processor Reference Manual:
258   https://www.nxp.com/webapp/Download?colCode=IMX8MMRM
259
260.. _TorizonCore:
261   https://developer.toradex.com/torizon/
262