1.. zephyr:board:: udoo_neo_full
2
3Overview
4********
5
6UDOO Neo Full is an open source Arduino Uno compatible single board computer.
7It is equipped with an NXP |reg| i.MX 6SoloX hybrid multicore processor
8composed of one ARM |reg| Cortex-A9 core running up to 1 GHz and one Cortex-M4
9core running up to 227 MHz for high CPU performance and real-time response.
10Zephyr was ported to run on the Cortex-M4 core only. In a future release, it
11will also communicate with the Cortex-A9 core (running Linux) via OpenAMP.
12
13Hardware
14********
15
16- MCIMX6X MCU with a single Cortex-A9 (1 GHz) core and single Cortex-M4 (227 MHz) core
17
18- Memory
19
20  - 1 GB RAM
21  - 128 KB OCRAM
22  - 256 KB L2 cache (can be switched into OCRAM instead)
23  - 16 KB OCRAM_S
24  - 32 KB TCML
25  - 32 KB TCMU
26  - 32 KB CAAM (secure RAM)
27
28- A9 Boot Devices
29
30  - NOR flash
31  - NAND flash
32  - OneNAND flash
33  - SD/MMC
34  - Serial (I2C/SPI) NOR flash and EEPROM
35  - QuadSPI (QSPI) flash
36
37- Display
38
39  - Micro HDMI connector
40  - LVDS display connector
41  - Touch (I2C signals)
42
43- Multimedia
44
45  - Integrated 2d/3d graphics controller
46  - 8-bit parallel interface for analog camera supporting NTSC and PAL
47  - HDMI audio transmitter
48  - S/PDIF
49  - I2S
50
51- Connectivity
52
53  - USB 2.0 Type A port
54  - USB OTG (micro-AB connector)
55  - 10/100 Mbit/s Ethernet PHY
56  - Wi-Fi 802.11 b/g/n
57  - Bluetooth 4.0 Low Energy
58  - 3x UART ports
59  - 2x CAN Bus interfaces
60  - 8x PWM signals
61  - 3x I2C interface
62  - 1x SPI interface
63  - 6x multiplexable signals
64  - 32x GPIO (A9)
65  - 22x GPIO (M4)
66
67- Other
68
69  - MicroSD card slot (8-bit SDIO interface)
70  - Power status LED (green)
71  - 2x user LED (red and orange)
72
73- Power
74
75  - 5 V DC Micro USB
76  - 6-15 V DC jack
77  - RTC battery connector
78
79- Debug
80
81  - pads for soldering of JTAG 14-pin connector
82
83- Sensor
84
85  - 3-Axis Accelerometer
86  - 3-Axis Magnetometer
87  - 3-Axis Digital Gyroscope
88  - 1x Sensor Snap-In I2C connector
89
90- Expansion port
91
92  - Arduino interface
93
94For more information about the MCIMX6X SoC and UDOO Neo Full board,
95see these references:
96
97- `NXP i.MX 6SoloX Website`_
98- `NXP i.MX 6SoloX Datasheet`_
99- `NXP i.MX 6SoloX Reference Manual`_
100- `UDOO Neo Website`_
101- `UDOO Neo Getting Started`_
102- `UDOO Neo Documentation`_
103- `UDOO Neo Datasheet`_
104- `UDOO Neo Schematics`_
105
106Supported Features
107==================
108
109The UDOO Neo Full board configuration supports the following hardware
110features:
111
112+-----------+------------+-------------------------------------+
113| Interface | Controller | Driver/Component                    |
114+===========+============+=====================================+
115| NVIC      | on-chip    | nested vector interrupt controller  |
116+-----------+------------+-------------------------------------+
117| SYSTICK   | on-chip    | systick                             |
118+-----------+------------+-------------------------------------+
119| UART      | on-chip    | serial port-polling;                |
120|           |            | serial port-interrupt               |
121+-----------+------------+-------------------------------------+
122| GPIO      | on-chip    | general purpose input/output        |
123+-----------+------------+-------------------------------------+
124| COUNTER   | on-chip    | counter                             |
125+-----------+------------+-------------------------------------+
126
127The default configuration can be found in the defconfig file:
128
129	:zephyr_file:`boards/udoo/udoo_neo_full/udoo_neo_full_mcimx6x_m4_defconfig`
130
131Other hardware features are not currently supported by the port.
132
133Connections and IOs
134===================
135
136The UDOO Neo Full board was tested with the following pinmux
137controller configuration.
138
139+---------------+-----------------+---------------------------+
140| Board Name    | SoC Name        | Usage                     |
141+===============+=================+===========================+
142| J4 RX         | UART5_RX_DATA   | UART Console              |
143+---------------+-----------------+---------------------------+
144| J4 TX         | UART5_TX_DATA   | UART Console              |
145+---------------+-----------------+---------------------------+
146
147System Clock
148============
149
150The MCIMX6X SoC is configured to use the 24 MHz external oscillator
151on the board with the on-chip PLL to generate core clock.
152PLL settings for M4 core are set via code running on the A9 core.
153
154Serial Port
155===========
156
157The MCIMX6X SoC has six UARTs. UART5 is configured for the M4 core and the
158remaining are used by the A9 core or not used.
159
160Programming and Debugging
161*************************
162
163The M4 core does not have a flash memory and is not provided a clock
164at power-on-reset. Therefore it needs to be started by the A9 core.
165The A9 core is responsible to load the M4 binary application into the RAM,
166put the M4 in reset, set the M4 Program Counter and Stack Pointer, and get
167the M4 out of reset. The A9 can perform these steps at the bootloader level
168or after the Linux system has booted.
169
170The M4 core can use up to 5 different RAMs (some other types of memory like
171a secure RAM are not currently implemented in Zephyr).
172These are the memory mappings for A9 and M4:
173
174+------------+-----------------------+-----------------------+-----------------------+
175| Region     | Cortex-A9             | Cortex-M4             | Size                  |
176+============+=======================+=======================+=======================+
177| TCML       | 0x007F8000-0x007FFFFF | 0x1FFF8000-0x1FFFFFFF |   32 KB               |
178+------------+-----------------------+-----------------------+-----------------------+
179| TCMU       | 0x00800000-0x00807FFF | 0x20000000-0x20007FFF |   32 KB               |
180+------------+-----------------------+-----------------------+-----------------------+
181| OCRAM_S    | 0x008F8000-0x008FBFFF | 0x208F8000-0x208FBFFF |   16 KB               |
182+------------+-----------------------+-----------------------+-----------------------+
183| OCRAM      | 0x00900000-0x0091FFFF | 0x20900000-0x2091FFFF |  128 KB               |
184+------------+-----------------------+-----------------------+-----------------------+
185| DDR        | 0x80000000-0xFFFFFFFF | 0x80000000-0xDFFFFFFF | 2048 MB (1536 for M4) |
186+------------+-----------------------+-----------------------+-----------------------+
187
188References
189==========
190
191- `NXP i.MX 6SoloX Reference Manual`_ Chapter 2 - Memory Maps
192
193You have to choose which RAM will be used at compilation time. This configuration
194is done in the file :zephyr_file:`boards/udoo/udoo_neo_full/udoo_neo_full_mcimx6x_m4.dts`.
195
196If you want to have the code placed in the subregion of a memory, which will
197likely be the case when using DDR, select "zephyr,flash=&flash" and set the
198DT_FLASH_SIZE macro to determine the region size and DT_FLASH_ADDR to determine
199the address where the region begins.
200
201If you want to have the data placed in the subregion of a memory, which will
202likely be the case when using DDR, select "zephyr,sram = &sram", which sets the
203CONFIG_SRAM_SIZE macro to determine the region size and
204CONFIG_SRAM_BASE_ADDRESS to determine the address where the region begins.
205
206Otherwise set "zephyr,flash" and/or "zephyr,sram" to one of the predefined
207regions:
208
209.. code-block:: none
210
211   "zephyr,flash"
212   - &tcml
213   - &ocram_s
214   - &ocram
215   - &ddr
216
217   "zephyr,sram"
218   - &tcmu
219   - &ocram_s
220   - &ocram
221   - &ddr
222
223Below you will find the instructions how a Linux user space application running
224on the A9 core can be used to load and run Zephyr application on the M4 core.
225
226The UDOOBuntu Linux distribution contains a `udooneo-m4uploader`_ utility,
227but its purpose is to load UDOO Neo "Arduino-like" sketches, so it doesn't
228work with Zephyr applications in most cases. The reason is that there is
229an exchange of information between this utility and the program running on the
230M4 core using hardcoded shared memory locations. The utility writes a flag which
231is read by the program running on the M4 core. The program is then supposed to
232end safely and write the status to the shared memory location for the main core.
233The utility then loads the new application and reads its status from the shared
234memory location to determine if it has successfully launched. Since this
235functionality is specific for the UDOO Neo "Arduino-like" sketches, it is not
236implemented in Zephyr. However Zephyr applications can support it on their own
237if planned to be used along with the UDOOBuntu Linux running on the A9 core.
238The udooneo-uploader utility calls another executable named
239mqx_upload_on_m4SoloX which can be called directly to load Zephyr applications.
240Copy the Zephyr binary image into the Linux filesystem and invoke the utility
241as a root user:
242
243.. code-block:: console
244
245   mqx_upload_on_m4SoloX zephyr.bin
246
247If the output looks like below, the mqx_upload_on_m4SoloX could not read
248the status of the stopped application. This is expected if the previously
249loaded application is not a UDOO Neo "Arduino-like" sketch and ignores the
250shared memory communication:
251
252.. code-block:: console
253
254   UDOONeo - mqx_upload_on_m4SoloX 1.1.0
255   UDOONeo - Waiting M4 Stop, m4TraceFlags: 00000000
256   UDOONeo - Waiting M4 Stop, m4TraceFlags: 00000000
257   UDOONeo - Waiting M4 Stop, m4TraceFlags: 00000000
258   UDOONeo - Waiting M4 Stop, m4TraceFlags: 00000000
259   UDOONeo - Failed to Stop M4 sketch: reboot system !
260
261In such situation, the mqx_upload_on_m4SoloX utility has reset the trace flags,
262so it will succeed when called again. Then it can have this output below:
263
264.. code-block:: console
265
266   UDOONeo - mqx_upload_on_m4SoloX 1.1.0
267   UDOONeo - FILENAME = zephyr.bin; loadaddr = 0x84000000
268   UDOONeo - start - end (0x84000000 - 0x84080000)
269   UDOONeo - Waiting M4 Run, m4TraceFlags: 000001E0
270   UDOONeo - M4 sketch is running
271
272Or the one below, if the utility cannot read the status flag that the M4 core
273applications has started. It can be ignored as the application should be
274running, the utility just doesn't know it:
275
276.. code-block:: console
277
278   UDOONeo - mqx_upload_on_m4SoloX 1.1.0
279   UDOONeo - FILENAME = zephyr.bin; loadaddr = 0x84000000
280   UDOONeo - start - end (0x84000000 - 0x84080000)
281   UDOONeo - Waiting M4 Run, m4TraceFlags: 00000000
282   UDOONeo - Waiting M4 Run, m4TraceFlags: 00000000
283   UDOONeo - Waiting M4 Run, m4TraceFlags: 00000000
284   UDOONeo - Waiting M4 Run, m4TraceFlags: 00000000
285   UDOONeo - Failed to Start M4 sketch: reboot system !
286
287The stack pointer and the program counter values are read from the binary.
288The memory address where binary will be placed is calculated from the program
289counter as its value aligned to 64 KB down, or it can be provided as a second
290command line argument:
291
292.. code-block:: console
293
294   mqx_upload_on_m4SoloX zephyr.bin 0x84000000
295
296It is necessary to provide the address if the binary is copied into a memory
297region which has different mapping between the A9 and the M4 core. The address
298calculated from the stack pointer value in the binary file would be wrong.
299
300It is possible to modify the mqx_upload_on_m4SoloX utility source code
301to not exchange the information with the M4 core application using shared
302memory.
303
304It is also possible to use the `imx-m4fwloader`_ utility to load the M4 core
305application.
306
307One option applicable in UDOOBuntu Linux is to copy the binary file into the
308file /var/opt/m4/m4last.fw in the Linux filesystem. The next time the system is
309booted, Das U-Boot will load it from there.
310
311Another option is to directly use Das U-Boot to load the code.
312
313Debugging
314=========
315
316The UDOO Neo Full board includes pads for soldering the 14-pin JTAG
317connector. Zephyr applications running on the M4 core have only been
318tested by observing UART console output.
319
320References
321==========
322
323.. target-notes::
324
325.. _UDOO Neo Website:
326   https://www.udoo.org/udoo-neo/
327
328.. _UDOO Neo Getting Started:
329   https://www.udoo.org/get-started-neo/
330
331.. _UDOO Neo Documentation:
332   https://www.udoo.org/docs-neo
333
334.. _UDOO Neo Datasheet:
335   https://www.udoo.org/download/files/datasheets/datasheet_udoo_neo.pdf
336
337.. _UDOO Neo Schematics:
338   https://www.udoo.org/download/files/schematics/UDOO_NEO_schematics.pdf
339
340.. _Udoo Neo Linux or Android Images for the A9 Core:
341   https://www.udoo.org/downloads/
342
343.. _udooneo-m4uploader:
344   https://github.com/ektor5/udooneo-m4uploader
345
346.. _imx-m4fwloader:
347   https://github.com/codeauroraforum/imx-m4fwloader
348
349.. _NXP i.MX 6SoloX Website:
350   https://www.nxp.com/products/processors-and-microcontrollers/applications-processors/i.mx-applications-processors/i.mx-6-processors/i.mx-6solox-processors-heterogeneous-processing-with-arm-cortex-a9-and-cortex-m4-cores:i.MX6SX
351
352.. _NXP i.MX 6SoloX Datasheet:
353   https://www.nxp.com/docs/en/data-sheet/IMX6SXCEC.pdf
354
355.. _NXP i.MX 6SoloX Reference Manual:
356   https://www.nxp.com/docs/en/reference-manual/IMX6SXRM.pdf
357
358.. _Loading Code on Cortex-M4 from Linux for the i.MX 6SoloX and i.MX 7Dual/7Solo Application Processors:
359   https://www.nxp.com/docs/en/application-note/AN5317.pdf
360