1.. zephyr:board:: imx93_evk 2 3Overview 4******** 5 6The i.MX93 Evaluation Kit (MCIMX93-EVK board) is a platform designed to show 7the most commonly used features of the i.MX 93 Applications Processor in a 8small and low cost package. The MCIMX93-EVK board is an entry-level development 9board, which helps developers to get familiar with the processor before 10investing a large amount of resources in more specific designs. 11 12i.MX93 MPU is composed of one cluster of 2x Cortex-A55 cores and a single 13Cortex®-M33 core. Zephyr OS is ported to run on one of the Cortex®-A55 core. 14 15- Board features: 16 17 - RAM: 2GB LPDDR4 18 - Storage: 19 20 - SanDisk 16GB eMMC5.1 21 - microSD Socket 22 - Wireless: 23 24 - Murata Type-2EL (SDIO+UART+SPI) module. It is based on NXP IW612 SoC, 25 which supports dual-band (2.4 GHz /5 GHz) 1x1 Wi-Fi 6, Bluetooth 5.2, 26 and 802.15.4 27 - USB: 28 29 - Two USB 2.0 Type C connectors 30 - Ethernet 31 - PCI-E M.2 32 - Connectors: 33 34 - 40-Pin Dual Row Header 35 - LEDs: 36 37 - 1x Power status LED 38 - 2x UART LED 39 - Debug 40 41 - JTAG 20-pin connector 42 - MicroUSB for UART debug, two COM ports for A55 and M33 43 44 45Supported Features 46================== 47 48The Zephyr mimx93_evk board Cortex-A Core configuration supports the following 49hardware features: 50 51+-----------+------------+-------------------------------------+ 52| Interface | Controller | Driver/Component | 53+===========+============+=====================================+ 54| GIC-v4 | on-chip | interrupt controller | 55+-----------+------------+-------------------------------------+ 56| ARM TIMER | on-chip | system clock | 57+-----------+------------+-------------------------------------+ 58| CLOCK | on-chip | clock_control | 59+-----------+------------+-------------------------------------+ 60| PINMUX | on-chip | pinmux | 61+-----------+------------+-------------------------------------+ 62| UART | on-chip | serial port | 63+-----------+------------+-------------------------------------+ 64| GPIO | on-chip | GPIO | 65+-----------+------------+-------------------------------------+ 66| I2C | on-chip | i2c | 67+-----------+------------+-------------------------------------+ 68| SPI | on-chip | spi | 69+-----------+------------+-------------------------------------+ 70| CAN | on-chip | can | 71+-----------+------------+-------------------------------------+ 72| TPM | on-chip | TPM Counter | 73+-----------+------------+-------------------------------------+ 74| ENET | on-chip | ethernet port | 75+-----------+------------+-------------------------------------+ 76 77The Zephyr imx93_evk board Cortex-M33 configuration supports the following 78hardware features: 79 80+-----------+------------+-------------------------------------+ 81| Interface | Controller | Driver/Component | 82+===========+============+=====================================+ 83| NVIC | on-chip | interrupt controller | 84+-----------+------------+-------------------------------------+ 85| SYSTICK | on-chip | systick | 86+-----------+------------+-------------------------------------+ 87| CLOCK | on-chip | clock_control | 88+-----------+------------+-------------------------------------+ 89| PINMUX | on-chip | pinmux | 90+-----------+------------+-------------------------------------+ 91| UART | on-chip | serial port | 92+-----------+------------+-------------------------------------+ 93| GPIO | on-chip | GPIO | 94+-----------+------------+-------------------------------------+ 95 96Devices 97======== 98System Clock 99------------ 100 101This board configuration uses a system clock frequency of 24 MHz. 102Cortex-A55 Core runs up to 1.7 GHz. 103Cortex-M33 Core runs up to 200MHz in which SYSTICK runs on same frequency. 104 105Serial Port 106----------- 107 108This board configuration uses a single serial communication channel with the 109CPU's UART2 for A55 core and M33 core. 110 111Board MUX Control 112----------------- 113 114This board configuration uses a series of digital multiplexers to switch between 115different board functions. The multiplexers are controlled by a GPIO signal called 116``EXP_SEL`` from onboard GPIO expander ADP5585. It can be configured to select 117function set "A" or "B" by dts configuration if board control module is enabled. 118The following dts node is defined: 119 120.. code-block:: dts 121 122 board_exp_sel: board-exp-sel { 123 compatible = "imx93evk-exp-sel"; 124 mux-gpios = <&gpio_exp0 4 GPIO_ACTIVE_HIGH>; 125 mux = "A"; 126 }; 127 128Following steps are required to configure the ``EXP_SEL`` signal: 129 1301. Enable Kconfig option ``CONFIG_BOARD_MIMX93_EVK_EXP_SEL_INIT``. 1312. Select ``mux="A";`` or ``mux="B";`` in ``&board_exp_sel`` devicetree node. 132 133Kconfig option ``CONFIG_BOARD_MIMX93_EVK_EXP_SEL_INIT`` is enabled if a board 134function that requires configuring the mux is enabled. The MUX option is 135automatically selected if certain board function is enabled, and takes precedence 136over dts config. For instance, if ``CONFIG_CAN`` is enabled, MUX A is selected 137even if ``mux="B";`` is configured in dts, and an warning would be reported in 138the log. 139 140User Button GPIO Option 141-------------------------- 142 143The user buttons RFU_BTN1 and RFU_BTN2 is connected to i.MX 93 GPIO by default, 144but can be changed to connect to onboard GPIO expander PCAL6524 with on-board DIP 145switches. To do this, switch SW1006 to 0000, then switch SW1005 to 0101. An devicetree 146overlay is included to support this. 147 148Run following command to test user buttons on PCAL6524: 149 150.. zephyr-app-commands:: 151 :zephyr-app: samples/basic/button 152 :host-os: unix 153 :board: imx93_evk/mimx9352/a55 154 :goals: build 155 :gen-args: -DEXTRA_DTC_OVERLAY_FILE=imx93_evk_mimx9352_exp_btn.overlay 156 157Run the app, press RFU_BTN1 and the red LED turns on accordingly. 158 159Note: The overlay only supports ``mimx9352/a55``, but can be extended to support 160``mimx9352/m33`` if I2C and PCAL6524 is enabled. 161 162Programming and Debugging (A55) 163******************************* 164 165U-Boot "cpu" command is used to load and kick Zephyr to Cortex-A secondary Core, Currently 166it is supported in : `Real-Time Edge U-Boot`_ (use the branch "uboot_vxxxx.xx-y.y.y, 167xxxx.xx is uboot version and y.y.y is Real-Time Edge Software version, for example 168"uboot_v2023.04-2.9.0" branch is U-Boot v2023.04 used in Real-Time Edge Software release 169v2.9.0), and pre-build images and user guide can be found at `Real-Time Edge Software`_. 170 171.. _Real-Time Edge U-Boot: 172 https://github.com/nxp-real-time-edge-sw/real-time-edge-uboot 173.. _Real-Time Edge Software: 174 https://www.nxp.com/rtedge 175 176Copy the compiled ``zephyr.bin`` to the first FAT partition of the SD card and 177plug the SD card into the board. Power it up and stop the u-boot execution at 178prompt. 179 180Use U-Boot to load and kick zephyr.bin to Cortex-A55 Core1: 181 182.. code-block:: console 183 184 fatload mmc 1:1 0xd0000000 zephyr.bin; dcache flush; icache flush; cpu 1 release 0xd0000000 185 186 187Or use the following command to kick zephyr.bin to Cortex-A55 Core0: 188 189.. code-block:: console 190 191 fatload mmc 1:1 0xd0000000 zephyr.bin; dcache flush; icache flush; go 0xd0000000 192 193 194Use this configuration to run basic Zephyr applications and kernel tests, 195for example, with the :zephyr:code-sample:`synchronization` sample: 196 197.. zephyr-app-commands:: 198 :zephyr-app: samples/synchronization 199 :host-os: unix 200 :board: imx93_evk/mimx9352/a55 201 :goals: build 202 203This will build an image with the synchronization sample app, boot it and 204display the following console output: 205 206.. code-block:: console 207 208 *** Booting Zephyr OS build Booting Zephyr OS build v3.7.0-2055-g630f27a5a867 *** 209 thread_a: Hello World from cpu 0 on imx93_evk! 210 thread_b: Hello World from cpu 0 on imx93_evk! 211 thread_a: Hello World from cpu 0 on imx93_evk! 212 thread_b: Hello World from cpu 0 on imx93_evk! 213 214System Reboot (A55) 215=================== 216 217Currently i.MX93 only support cold reboot and doesn't support warm reboot. 218Use this configuratiuon to verify cold reboot with :zephyr:code-sample:`shell-module` 219sample: 220 221.. zephyr-app-commands:: 222 :zephyr-app: samples/subsys/shell/shell_module 223 :host-os: unix 224 :board: imx93_evk/mimx9352/a55 225 :goals: build 226 227This will build an image with the shell sample app, boot it and execute 228kernel reboot command in shell command line: 229 230.. code-block:: console 231 232 uart:~$ kernel reboot cold 233 234Programming and Debugging (M33) 235******************************* 236 237Copy the compiled ``zephyr.bin`` to the first FAT partition of the SD card and 238plug the SD card into the board. Power it up and stop the u-boot execution at 239prompt. 240 241Use U-Boot to load and kick zephyr.bin to Cortex-M33 Core: 242 243Boot with code from TCM 244======================= 245 246.. code-block:: console 247 248 load mmc 1:1 0x80000000 zephyr.bin;cp.b 0x80000000 0x201e0000 0x30000;bootaux 0x1ffe0000 0 249 250Boot with code from DDR 251======================= 252 253.. code-block:: console 254 255 load mmc 1:1 0x84000000 zephyr.bin;dcache flush;bootaux 0x84000000 0 256 257Note: Cortex M33 need execute permission to run code from DDR memory. In order 258to enable this, `imx-atf`_ can to be modified in "plat/imx/imx93/trdc_config.h". 259 260.. _imx-atf: 261 https://github.com/nxp-imx/imx-atf 262 263Use this configuration to run basic Zephyr applications and kernel tests, 264for example, with the :zephyr:code-sample:`synchronization` sample: 265 266.. zephyr-app-commands:: 267 :zephyr-app: samples/synchronization 268 :host-os: unix 269 :board: imx93_evk/mimx9352/m33 270 :goals: run 271 272This will build an image with the synchronization sample app, boot it and 273display the following console output: 274 275.. code-block:: console 276 277 *** Booting Zephyr OS build v3.7.0-684-g71a7d05ba60a *** 278 thread_a: Hello World from cpu 0 on imx93_evk! 279 thread_b: Hello World from cpu 0 on imx93_evk! 280 thread_a: Hello World from cpu 0 on imx93_evk! 281 thread_b: Hello World from cpu 0 on imx93_evk! 282 283To make a container image flash.bin with ``zephyr.bin`` for SD/eMMC programming and booting 284from BootROM. Refer to user manual of i.MX93 `MCUX SDK release`_. 285 286.. _MCUX SDK release: 287 https://mcuxpresso.nxp.com/ 288 289References 290========== 291 292More information can refer to NXP official website: 293`NXP website`_. 294 295.. _NXP website: 296 https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/i-mx-applications-processors/i-mx-9-processors/i-mx-93-applications-processor-family-arm-cortex-a55-ml-acceleration-power-efficient-mpu:i.MX93 297 298 299Using the SOF-specific variant 300****************************** 301 302Purpose 303======= 304 305Since this board doesn't have a DSP, an alternative for people who might be interested 306in running SOF on this board had to be found. The alternative consists of running SOF 307on an A55 core using Jailhouse as a way to "take away" one A55 core from Linux and 308assign it to Zephyr with `SOF`_. 309 310.. _SOF: 311 https://github.com/thesofproject/sof 312 313What is Jailhouse? 314================== 315 316Jailhouse is a light-weight hypervisor that allows the partitioning of hardware resources. 317For more details on how this is done and, generally, about Jailhouse, please see: `1`_, 318`2`_ and `3`_. The GitHub repo can be found `here`_. 319 320.. _1: 321 https://lwn.net/Articles/578295/ 322 323.. _2: 324 https://lwn.net/Articles/578852/ 325 326.. _3: 327 http://events17.linuxfoundation.org/sites/events/files/slides/ELCE2016-Jailhouse-Tutorial.pdf 328 329.. _here: 330 https://github.com/siemens/jailhouse 331 332 333How does it work? 334================= 335Firstly, we need to explain a few Jailhouse concepts that will be referred to later on: 336 337* **Cell**: refers to a set of hardware resources that the OS assigned to this 338 cell can utilize. 339 340* **Root cell**: refers to the cell in which Linux is running. This is the main cell which 341 will contain all the hardware resources that Linux will utilize and will be used to assign 342 resources to the inmates. The inmates CANNOT use resources such as the CPU that haven't been 343 assigned to the root cell. 344 345* **Inmate**: refers to any other OS that runs alongside Linux. The resources an inmate will 346 use are taken from the root cell (the cell Linux is running in). 347 348SOF+Zephyr will run as an inmate, alongside Linux, on core 1 of the board. This means that 349said core will be taken away from Linux and will only be utilized by Zephyr. 350 351The hypervisor restricts inmate's/root's access to certain hardware resources using 352the second-stage translation table which is based on the memory regions described in the 353configuration files. Please consider the following scenario: 354 355 Root cell wants to use the **UART** which let's say has its registers mapped in 356 the **[0x0 - 0x42000000]** region. If the inmate wants to use the same **UART** for 357 some reason then we'd need to also add this region to inmate's configuration 358 file and add the **JAILHOUSE_MEM_ROOTSHARED** flag. This flag means that the inmate 359 is allowed to share this region with the root. If this region is not set in 360 the inmate's configuration file and Zephyr (running as an inmate here) tries 361 to access this region this will result in a second stage translation fault. 362 363Notes: 364 365* Linux and Zephyr are not aware that they are running alongside each other. 366 They will only be aware of the cores they have been assigned through the config 367 files (there's a config file for the root and one for each inmate). 368 369Architecture overview 370===================== 371 372The architecture overview can be found at this `location`_. (latest status update as of now 373and the only one containing diagrams). 374 375.. _location: 376 https://github.com/thesofproject/sof/issues/7192 377 378 379How to use this board? 380====================== 381 382This board has been designed for SOF so it's only intended to be used with SOF. 383 384TODO: document the SOF build process for this board. For now, the support for 385i.MX93 is still in review and has yet to merged on SOF side. 386
