Zircon on HiKey960 (96boards.org)

Periodically check this file as the setup workflow will change/improve.

Requirements

The following hardware is required:

  • HiKey960 board
  • Power adapter (most will require a DC plug converter -- more info here)
  • USB-C cable (to connect to workstation for flashing the board)
  • One of the following (to connect to workstation for serial console):

The following software is required:

  • fastboot

    To install on Ubuntu: sudo apt-get install android-tools-fastboot

Overview

At a high level, these are the steps for getting a HiKey development environment fully working:

  • Build a Zircon boot image
  • Enable the serial console (useful for debugging subsequent steps)
  • Flash the HiKey's low-level firmware
  • Flash the Zircon boot image onto the HiKey (this image -- specifically zedboot -- will receive and boot your subsequent Fuchsia builds)
  • Build and boot Fuchsia

Once the system is correctly configured, your development workflow should resemble a workflow on other hardware (repeated builds done with fx build, a persistent instance of fx pave to automatically update the hardware, and a persistent instance of fx log to capture console output).

Useful Information

Building the Zircon boot image

To build zircon, invoke the following command from the top level Zircon directory (ensure that you have checked out the ARM64 toolchains). For more information, see docs/getting_started.md:

gn gen build-zircon
ninja -C build-zircon

Setting up the serial console

First, get the device to show up on your dev host machine as a serial device. Following that, install and configure a console app.

Serial hardware setup

If using a mezzanine board, follow the instructions included with it. Additional tips:

  • Take care not to install the mezzanine board backwards on the connector. The micro-USB port should face outward; the corner pushbutton should be in the center of the HiKey board.

  • Some standard micro-USB cables have a button to enable/disable the data lines. When using one of these cables, ensure that these lines are enabled - the LED should be amber (not green).

  • The mezzanine board receives power through the micro-USB cable, so power need not be applied to the main HiKey board yet.

If using a FTDI-style serial adapter cable:

  • The signals are available on the 40 pin LS connector (reference)

    • Pin 1 - GND
    • Pin 11 - UART TX (HiKey960 --> Host)
    • PIN 13 - UART RX (HiKey960 <-- Host)
  • This means that for a common FTDI style adapter:

    • Black --> Pin1
    • Yellow --> Pin11
    • Orange --> Pin13
  • (Optional) an active low reset is available on pin 6 of the 40 pin LS connector. A jumper wire intermittently shorted from this pin to GND (shields of the connectors are all grounded) can provide an easy way to reset the board and place it in fastboot mode.

Once you have correctly configured the hardware (via either method), the device should appear to your host machine as a USB-connected UART, listed in your /dev directory as /dev/ttyUSB0 (or USB1, etc). If this is not the case, you may have forgotten to enable the data lines (LED should be amber), or you may have a bad micro-USB cable or mezzanine board. Regardless, do not proceed until your HiKey board is detected and enumerated in the /dev directory as a tty device.

Serial console software

Use a host application such as screen or putty to connect to the serial port and provide console functionality. Use a baud rate of 115200.

Example commands using screen: + screen /dev/ttyUSB0 115200,-ixoff + Ctrl-a, Esc to enable scrolling (then k-up, j-down, q-done scrolling) + Ctrl-a, d to detach from the session (screen -r -d to reattach) + `Ctrl-a, ` to kill all screen sessions.

If you receive an error when connecting to your tty/USBn, you may need to run your serial console application as sudo. Alternately, you can add a udev rule that allows applications to connect to this device:

  • Create file /etc/udev/rules.d/99-ttyusb.rules containing the following:

    SUBSYSTEM=="tty", GROUP="dialout"

  • Then sudo udevadm control --reload-rules

Entering fastboot mode

(needed for flashing low-level firmware and/or Zircon)

Connect the power supply if you have not already. If the power plug doesn't seem to fit, you may have forgotten to get a DC adapter. The power plug for the HiKey boards has a 4.75mm diameter and 1.7mm center pin, whereas most DC power supplies in this class have a 5.5mm diameter and 2.1mm center pin.

To flash the board, it must be connected to your workstation via the USB-C OTG connection on the HiKey960 main board. Additionally, the HiKey960 must be in fastboot mode. You can enter fastboot in one of two ways:

  • DIP Switch method Use the switches on the back of the board. (Older HiKeys may have jumpers instead of DIP switches.) To boot into fastboot mode, the switches should be in the following positions:

    Auto Power up(Switch 1)   closed/ON
    Recovery(Switch 2)        open/OFF
    Fastboot(Switch 3)        closed/ON
    

    Once the switches are in these positions, unplug/plug power or reset the board. It will then boot into fastboot mode, awaiting commands from the host. If you are using the serial adapter cable, just a reminder that this can be done with the jumper wire on pin 6, as mentioned earlier.

  • Double-Reset method Using the button on the mezzanine board, reset the board, then reset it again after seeing the following console messages:

    C3R,V0x00000016 e:113
    C0R,V0x00000017 e:66
    C1R,V0x00000017 e:66
    C2R,V0x00000017 e:66
    C3R,V0x00000017 e:66
    

    The second reset instructs the board to restart into fastboot for the next boot cycle only. The timing on this double-reset is a little tricky, but you will know you got the timing right if you see the following console messages at the end of the boot spew:

    usbloader: bootmode is 4
    usb: [USBFINFO]USB RESET
    usb: [USBFINFO]USB CONNDONE, highspeed
    usb: [USBFINFO]USB RESET
    usb: [USBFINFO]USB CONNDONE, highspeed
    usbloader: usb: online (highspeed)
    usb: [USBFINFO]usb enum done
    

    These messages confirm that the device has restarted into fastboot mode. If you do not see these messages, use the button to reset the board and try again until you are successful.

    As a reminder, with this method, the DIP switches on the HiKey should remain in normal mode (closed/ON open/OFF open/OFF), not the 'fastboot' mode mentioned in the previous option.

Once the board is in fastboot mode (regardless of which method you use), it is ready to be flashed with firmware updates and/or the Zircon boot image.

Install Firmware

We have run into inconsistent behavior between different HiKey 960 boards, depending on the low level firmware came installed on the device. We recommend setting up your board with known good firmware from the Android AOSP project.

To install firmware, put your board in fastboot mode and run the following:

  ./scripts/flash-hikey -f

Recover the device

If the hikey gets into a bad state you can try the recovery mechanism. The script should automate the process, including reinstalling the firmware. You first need to put the device into recovery mode:

    Auto Power up(Switch 1)   closed/ON
    Recovery(Switch 2)        closed/ON
    Fastboot(Switch 3)        open/OFF

Then run:

  ./scripts/flash-hikey -r

The recovery process communicates with the device over the USB-C cable, but it can be a bit flaky at times. If the script complains that it can't open the serial device first check what serial devices are connected (ls /dev/serial/by-id/) and make sure the script is using the correct device. You can specify which serial port to use with -p. Sometimes you just need to try a few times or power cycle the device. Occasionally the script will fail when attempting to install firmware, which can usually be fixed by starting again.

Installing Zircon

Once the HiKey board is in fastboot mode, run the following script from the zircon root directory to flash the necessary files onto the board:

  ./scripts/flash-hikey

Zedboot

If you would like to boot future kernels via the network, instead of flashing them directly, then run the script with the -m option.

  ./scripts/flash-hikey -m

This is the last flash update, and all subsequent boots should use normal mode (not fastboot or recovery). If you used the DIP Switch method to place the board in fastboot mode, you should flip the fastboot switch (switch 3) back to open/OFF before running this script, so that it will boot into Zircon after flashing (otherwise, it will boot back into fastboot mode).

If you used the double-tap reset method to place the board into fastboot mode, no further reconfiguration is needed: the board will boot into the kernel after it completes flashing.

For now, the ethernet connectivity needed for zedboot is actually provided by zircon via USB. This is automatically enabled on the HiKey USB-C connector, if it is changed from host mode into device mode. If all flash steps appear to complete successfully, but the device does not restart into Zedboot, you may need to manually place the device into USB 'device' mode. Enter the following command in your console:

  usbctl mode device

This step must be repeated each time the device is fully powered-down/up. At some point in the near future, the Fuchsia build will include support for USB NICs via USB-A, at which time this usbctl step will be unnecessary.

Once your device restarts and displays 'Zedboot' in the console, the setup process is complete. You can now use your usual build, boot and log commands. When powering up (not simply resetting) the device, you may need to press the reset button for the device to show up again as /dev/ttyUSBn. Recall that this is needed before connecting the serial console and interacting with the device.

Manually Installing Low-Level Firmware

To install firmware, put your board in fastboot mode and run the following:

  git clone https://android.googlesource.com/device/linaro/hikey hikey-firmware
  git -C hikey-firmware checkout 972114436628f874ac9ca28ef38ba82862937fbf
  fastboot flash ptable hikey-firmware/installer/hikey960/ptable.img
  fastboot flash xloader hikey-firmware/installer/hikey960/sec_xloader.img
  fastboot flash fastboot hikey-firmware/installer/hikey960/fastboot.img
  fastboot flash nvme hikey-firmware/installer/hikey960/nvme.img
  fastboot flash fw_lpm3 hikey-firmware/installer/hikey960/lpm3.img
  fastboot flash trustfirmware hikey-firmware/installer/hikey960/bl31.bin

This installs all the AOSP firmware except Android itself. To use a different bootloader altogether (not the one from AOSP), first complete the above commands and then install your bootloader.

Device support

The console is especially important because the HiKey builds of Fuchsia do not yet support the HDMI port. Related to this, only USB is supported for audio input/output. NOTE: all USB audio devices must be High-Speed (not just USB 2.0 compatible, which might be Full-Speed or High-Speed). If the USB audio device is enumerated as 12Mb/s, then it is Full-Speed.