| # Khadas VIM3 development guide | |
| The [Khadas VIM3] is an ARM64-based single board computer. It is possible to run | |
| Fuchsia on the VIM3. This guide shows Fuchsia [contributors] how to [install | |
| Fuchsia on a VIM3] and do other common development tasks. | |
| See [Appendix: Feature support](#features) for details on which VIM3 features | |
| Fuchsia supports. | |
| ## Audience {#audience} | |
| This guide assumes you're comfortable with: | |
| * Tinkering with electronics and hardware. | |
| * Building Fuchsia from source and other CLI workflows. | |
| ## Install Fuchsia on a Khadas VIM3 board {#install} | |
| See [Troubleshooting](#troubleshooting) and [Appendix: Support](#support) if you | |
| have any trouble completing the installation process. | |
| ### Prerequisites {#prerequisites} | |
| You'll need all of the following hardware and software: | |
| * A Khadas VIM3 single-board computer. Googlers should request a board through | |
| the Fuchsia Ops team. | |
| Caution: Fuchsia is primarily focused on supporting the Pro model VIM3. The | |
| Basic model may work but is less of a priority. | |
| * A desktop or laptop computer that's running Linux and has 2 USB ports | |
| available. This computer is called the **host**. | |
| * A power supply of at least 24W to your host. The VIM3 can draw that much power | |
| when [DVFS] is enabled. | |
| * A working Fuchsia development environment on your host. In other words, you | |
| should be able to [build Fuchsia] from its source code on your host. | |
| * A [USB to TTL serial cable]. | |
| * A USB-C to USB-A cable that supports both data and power delivery. The USB-C | |
| side is for the VIM3. The other side is for your host. | |
| Caution: Other USB cable types, like USB-C to USB-C, may work, but appear to | |
| have power delivery issues more frequently than USB-C to USB-A. See | |
| [Troubleshooting: Bootloops]. | |
| The following is optional: | |
| * A [heatsink]. This enables running 2 CPU cores on the VIM3 at full speed | |
| without reaching 80°C, the critical temperature beyond which cores are | |
| throttled down. | |
| See the [VIM3 collection] in the Khadas shop for examples of compatible | |
| accessories. | |
| Note: All the links in this section are only for your convenience. You don't | |
| need to buy from these exact stores or these exact parts. | |
| ### Build Fuchsia {#build} | |
| If you don't already have an [in-tree][glossary.in-tree] environment set up, | |
| you should start the process now because it can take a while to complete: | |
| 1. [Download the Fuchsia source code]. | |
| 1. [Configure and build Fuchsia]. | |
| * When configuring the build, use `fx set core.vim3`. | |
| Note: The rest of this guide assumes that your Fuchsia source code directory is | |
| located at `~/fuchsia`. This guide assumes that you run all `fx` commands from | |
| `~/fuchsia`. | |
| You'll use the Fuchsia development environment to build the Fuchsia image for | |
| VIM3 and run an in-tree CLI tool for flashing the Fuchsia image onto the VIM3. | |
| ### Set up the hardware {#hardware} | |
| Set up the VIM3 to communicate with your host: | |
| 1. Connect the VIM3 and your host to each other with the USB-C to USB-\* cable. | |
| The white LED on the VIM3 should turn on. | |
| Caution: Don't put a [USB hub] between the VIM3 and your host. The hub may | |
| make it harder for your VIM3 and host to detect and communicate with each | |
| other. | |
| This connection is used to power and flash the VIM3 with [`fastboot`]. | |
| 1. Connect the serial cable wires to the VIM3's GPIOs: | |
| * GND to pin 17. | |
| * TX (out from VIM3) to pin 18. | |
| * RX (into VIM3) to pin 19. | |
| * Don't connect the power wire of your serial cable to any VIM3 GPIO. | |
| The VIM3 is getting power through the USB cable. | |
| Tip: Pins 1, 20, 21, and 40 are labeled on the circuit board. | |
| Caution: In general the colors for TX and RX wires are not standardized. | |
| For example your RX wire may be blue or green. If your host is unable to see | |
| the serial logs, power off the VIM3 board and swap the TX and RX connections. | |
| Some USB-to-serial adapters have their wires improperly labeled. | |
| See [Serial Debugging Tool] for an example image of how your serial wires | |
| should be connected to the VIM3. | |
| 1. Connect the USB end of the serial cable to your host. | |
| #### Verify the serial connection {#serial} | |
| Make sure that you can view the serial logs: | |
| 1. Open Fuchsia's serial console: | |
| ```posix-terminal | |
| fx serial | |
| ``` | |
| Tip: If `fx serial` detects multiple USB devices and you don't know which one | |
| to use, try disconnecting the serial cable from your host, running | |
| `ls /dev/ttyUSB*`, then re-connecting the serial cable and running the | |
| command again. If you see no difference when running `ls /dev/ttyUSB*` try | |
| `ls /dev/tty*` or `ls /dev/*` instead. | |
| 1. Press the reset button on the VIM3. The reset button is the one with the | |
| **R** printed next to it on the circuit board. See [VIM3/3L Hardware] for a | |
| diagram. In your serial console you should see human-readable logs. | |
| See [Troubleshooting: Bootloops] if your VIM3 seems to keep rebooting. | |
| ### Erase the eMMC {#emmc} | |
| Before you can install Fuchsia, you need to get the VIM3 firmware and software | |
| to a known-good state. The first step is to erase the eMMC. | |
| 1. Press the reset button on your VIM3. | |
| 1. Right after you press the reset button, start repeatedly pressing the | |
| <kbd>Space</kbd> key as your VIM3 boots up. Make sure that your cursor is | |
| focused on your serial console. The bootloader process should pause and your | |
| serial console should show a `kvim3#` prompt. Your serial console is now | |
| providing you access to the **U-Boot shell**. | |
| 1. Run the following command in the U-Boot shell: | |
| ```posix-terminal | |
| store init 3 | |
| ``` | |
| Your serial console logs should verify that the eMMC was correctly erased. | |
| See [Erase eMMC] for more details. | |
| ### Update the Android image on the VIM3 {#android} | |
| <!-- Context: https://forum.khadas.com/t/unable-to-change-bootloader-for-vim3/12708/6 --> | |
| Now you need to get the VIM3 firmware and software to a known-good state: | |
| 1. Click the following URL to download an Android image that is known to work | |
| well with subsequent Fuchsia installations: | |
| <https://dl.khadas.com/products/vim3/firmware/Android/VIM3_Pie_V211220.7z> | |
| 1. Extract the compressed archive file (`VIM3_Pie_V211220.7z`). After the | |
| extraction you should have a `VIM3_Pie_V211220` directory with an | |
| `update.img` file in it. | |
| 1. Follow the instructions in [Install OS into eMMC]. When running | |
| `aml-burn-tool` the value for the `-i` flag should be the path to your | |
| `update.img` file. Your command should look similar to this: | |
| ```posix-terminal | |
| aml-burn-tool -b VIM3 -i ~/Downloads/VIM3_Pie_V211220/update.img | |
| ``` | |
| Tip: The `TST Mode` workflow is probably the easiest and fastest way to get | |
| your VIM3 into Upgrade Mode. | |
| 1. If the white and red LEDs on your VIM3 are off and the blue LED is on, it | |
| means that your VIM3 is in sleep mode. Try putting your VIM3 back into | |
| [Upgrade Mode] and then pressing the reset button again. | |
| At this point the white LED on your VIM3 should be on and you should see logs in | |
| your serial console after you press the reset button on your VIM3. | |
| ### Update the bootloader {#bootloader} | |
| This section explains how to flash a prebuilt version of Fuchsia's modified | |
| U-Boot onto the VIM3. See the following link if you would prefer to build the | |
| modified U-Boot from source: | |
| <https://third-party-mirror.googlesource.com/u-boot/+/refs/heads/vim3> | |
| 1. Access the U-Boot shell again by pressing the reset button and then | |
| repeatedly pressing the <kbd>Space</kbd> key in your serial console. When | |
| your serial console shows the `kvim3#` prompt, you're in the U-Boot shell. | |
| 1. In your U-Boot shell run the following command: | |
| ```posix-terminal | |
| fastboot | |
| ``` | |
| You should see the following logs in your serial console: | |
| ``` | |
| g_dnl_register: g_dnl_driver.name = usb_dnl_fastboot | |
| USB RESET | |
| SPEED ENUM | |
| USB RESET | |
| SPEED ENUM | |
| ``` | |
| If you see the first line | |
| (`g_dnl_register: g_dnl_driver.name = usb_dnl_fastboot`) but not the lines | |
| after that, try using a different USB-C to USB-\* cable and make sure that | |
| it supports both data and power delivery. | |
| 1. Open a new terminal window in your host and run the following commands: | |
| ```posix-terminal | |
| cd ~/fuchsia/prebuilt/third_party/fastboot | |
| ./fastboot flashing unlock | |
| ./fastboot flashing unlock_critical | |
| ./fastboot flash bootloader ~/fuchsia/prebuilt/third_party/firmware/vim3/u-boot.bin.unsigned | |
| ./fastboot reboot bootloader | |
| ``` | |
| Important: When working with Fuchsia, remember to use the | |
| [in-tree][glossary.in-tree] version of `fastboot` at | |
| `~/fuchsia/prebuilt/third_party/fastboot/fastboot`. The `fastboot` protocol | |
| allows arbitrary vendor protocol extensions and Fuchsia may rely on this | |
| functionality in the future. | |
| ### Flash Fuchsia into the eMMC (one-time only) {#fuchsia} | |
| Use this workflow only the first time you flash Fuchsia onto the VIM3. If you've | |
| already got Fuchsia running on the VIM3, use the [Update your Fuchsia image] | |
| workflow because it's faster. | |
| 1. If you just ran the `./fastboot reboot bootloader` command from the last | |
| section then your VIM3 should already be in `fastboot` mode. You can check | |
| your `fx serial` logs to confirm. Otherwise press the reset button and then | |
| repeatedly press the <kbd>f</kbd> key in your `fx serial` console until you | |
| see `USB RESET` and `SPEED ENUM` again. | |
| Caution: You have to press the <kbd>f</kbd> key now to enter | |
| <code>fastboot</code> mode. Previously you pressed the <kbd>Space</kbd> key. | |
| 1. From a separate terminal on your host run the following command: | |
| ```posix-terminal | |
| fx flash | |
| ``` | |
| Your VIM3 is now running Fuchsia! | |
| ## Update your Fuchsia image {#update} | |
| Complete these steps when you already have Fuchsia running on your VIM3 and want | |
| to update the Fuchsia image. | |
| 1. Run the following command from a terminal on your host: | |
| ```posix-terminal | |
| fx serve | |
| ``` | |
| Leave this command running. | |
| 1. Make some changes in your in-tree Fuchsia checkout and build the changes. | |
| 1. Open a new terminal window and perform an OTA update of the Fuchsia image on | |
| your VIM3: | |
| ```posix-terminal | |
| fx ota | |
| ``` | |
| ## Reduce VIM3 noise by disabling its fan {#fan} | |
| If the VIM3 fan's loud noise is bothering you, you can disable it with any | |
| of the following workflows: | |
| * Add `--args vim3_mcu_fan_default_level=0` to your `fx set` invocation. | |
| * Add `vim3_mcu_fan_default_level=0` to `~/fuchsia/local/args.gn` if you use | |
| [persistent local build arguments]. | |
| Caution: Disabling the fan interferes with thermal throttling, which will impact | |
| performance modeling and benchmarking. | |
| Experimental: This GN flag will get disabled at some point. Your local build | |
| will break when that happens. | |
| ## Ensure that VIM3 tryjobs run {#tryjobs} | |
| Include the following line in your commit message to ensure that VIM3 tryjobs run: | |
| ``` | |
| Cq-Include-Trybots: luci.turquoise.global.try:bringup.vim3-debug,core.vim3-debug,core.vim3-vg-debug | |
| ``` | |
| ## Troubleshooting {#troubleshooting} | |
| This section explains workarounds for common issues. | |
| ### Troubleshooting: Bootloops {#bootloops} | |
| Problem: | |
| You're looking at the VIM3 serial logs. The logs suggest that the VIM3 | |
| keeps rebooting. | |
| Root cause: | |
| Unknown. There appears to be an underlying bug in Khada's power delivery | |
| implementation. Fuchsia addressed the bug in [issue 122113]. | |
| Workaround 1: | |
| Un-plug and re-plug the USB cable. Repeat 2-3 times if necessary. | |
| Workaround 2: | |
| Always use a USB-C to USB-A cable. | |
| ### Troubleshooting: Hardware mismatch {#mismatch} | |
| Problem: | |
| This error when flashing fuchsia: `Hardware mismatch! Trying to flash images | |
| built for vim3 but have 0` | |
| Solution: | |
| Go back to [Update the Android image](#android) step. | |
| ## Appendix: Fix a bricked VIM3 {#brickfix} | |
| Do these steps if you've [bricked] your VIM3 and need to "factory reset" it: | |
| 1. [Erase the eMMC](#emmc). | |
| 1. [Update the Android image](#android). | |
| 1. [Update the bootloader](#bootloader). | |
| 1. [Flash Fuchsia into the eMMC (one-time only)](#fuchsia). | |
| ## Appendix: Support {#support} | |
| * For issues that seem related to VIM3 hardware or firmware, try the | |
| [VIM3 official docs](https://docs.khadas.com/linux/vim3/index.html) and | |
| [Khadas VIM3 official forum](https://forum.khadas.com/c/khadas-vim3/30). | |
| * For issues that seem related to Fuchsia, try the | |
| [Fuchsia mailing lists and chat rooms](/docs/contribute/community/mailing-lists.md). | |
| ## Appendix: Feature support {#features} | |
| Fuchsia currently supports these features of the VIM3: | |
| * UART Serial Debugger | |
| * Paving over ethernet and USB | |
| * Storage (eMMC) | |
| * HDMI Display and Framebuffer | |
| * GPU (Mali) and Vulkan graphics | |
| * Ethernet | |
| * SDIO | |
| * I2C | |
| * GPIO | |
| * Temperature Sensors and DVFS | |
| * RTC | |
| * Clock | |
| * Fan | |
| * NNA | |
| * USB-C in peripheral mode | |
| * USB-A | |
| * Audio[^1] | |
| [^1]: VIM3 does not include transducers like speakers and microphones, | |
| in addition to the transducers, external hardware including DACs/ADCs | |
| need to be added and integrated via the GPIO header to be able to | |
| playback and capture audio this way. | |
| These features are under development and may not be supported: | |
| * Video decoder | |
| * SPI | |
| The following features are not supported, but might be added by future | |
| contributions: | |
| * SPI Flash | |
| * USB-C in host mode | |
| * Power management and PMIC | |
| * Wake on LAN | |
| * UART BT | |
| These features are not supported and are unlikely to be added: | |
| * Video encoding (due to non-public firmware) | |
| * Trusted Execution Environment / secure boot | |
| ## Appendix: Update the boot splash screen {#splash} | |
| To update the boot splash screen to be the Fuchsia logo, run the following | |
| command from a host terminal while the VIM3 is in `fastboot` mode: | |
| ```posix-terminal | |
| ~/fuchsia/prebuilt/third_party/fastboot/fastboot flash logo \ | |
| ~/fuchsia/zircon/kernel/target/arm64/board/vim3/firmware/logo.img | |
| ``` | |
| [Khadas VIM3]: https://www.khadas.com/vim3 | |
| [install Fuchsia on a VIM3]: #install | |
| [contributors]: /docs/contribute/community/contributor-roles.md#member | |
| [DVFS]: https://en.wikipedia.org/wiki/Dynamic_frequency_scaling | |
| [build Fuchsia]: #build | |
| [USB to TTL serial cable]: https://www.adafruit.com/product/954 | |
| [heatsink]: https://www.khadas.com/product-page/new-vim-heatsink | |
| [VIM3 collection]: https://www.khadas.com/shop?Collection=VIM3&sort=price_descending | |
| [Download the Fuchsia source code]: /docs/get-started/get_fuchsia_source.md | |
| [Configure and build Fuchsia]: /docs/get-started/build_fuchsia.md | |
| [USB hub]: https://en.wikipedia.org/wiki/USB_hub | |
| [`fastboot`]: https://en.wikipedia.org/wiki/Fastboot | |
| [Serial Debugging Tool]: https://docs.khadas.com/products/sbc/vim3/development/setup-serial-tool | |
| [VIM3/3L Hardware]: https://docs.khadas.com/products/sbc/vim3/hardware/start | |
| [Erase eMMC]: https://docs.khadas.com/products/sbc/vim3/development/erase-emmc | |
| [Install OS into eMMC]: https://docs.khadas.com/products/sbc/vim3/install-os/install-os-into-emmc-via-usb-tool#install-on-ubuntu-pc | |
| [Upgrade Mode]: https://docs.khadas.com/products/sbc/vim3/install-os/boot-into-upgrade-mode | |
| [bricked]: https://en.wikipedia.org/wiki/Brick_(electronics) | |
| [Erase the eMMC]: #emmc | |
| [Update the Android image]: #android | |
| [Update the bootloader]: #bootloader | |
| [Flash Fuchsia into the eMMC (one-time only)]: #fuchsia | |
| [VIM3 official docs]: https://docs.khadas.com/linux/vim3/index.html | |
| [Khadas VIM3 official forum]: https://forum.khadas.com/c/khadas-vim3/30 | |
| [Fuchsia mailing lists and chat rooms]: /docs/contribute/community/mailing-lists.md | |
| [persistent local build arguments]: /docs/development/build/fx.md#defining_persistent_local_build_arguments | |
| [Update your Fuchsia image]: #update | |
| [Troubleshooting: Bootloops]: #bootloops | |
| [issue 122113]: https://bugs.fuchsia.dev/p/fuchsia/issues/detail?id=122113 | |
| [bricked]: https://en.wikipedia.org/wiki/Brick_(electronics) |