1# Zircon on HiKey960 (96boards.org) 2Periodically check this file as the setup workflow will change/improve. 3 4 5## Requirements 6 7__The following hardware is required:__ 8 9+ HiKey960 board 10+ Power adapter (most will require a DC plug converter -- more info 11 [here](http://www.96boards.org/product/hikey960/)) 12+ USB-C cable (to connect to workstation for flashing the board) 13+ One of the following (to connect to workstation for serial console): 14 + (Recommended) 15 [Mezzanine board](https://www.seeedstudio.com/96Boards-UART-p-2525.html), 16 plus a micro-USB cable (not included with mezzanine board), or 17 + (Alternate) [1.8v FTDI Serial Adapter 18 cable](https://www.digikey.com/products/en?keywords=768-1070-ND) 19 20__The following software is required:__ 21 22+ `fastboot` 23 24 To install on Ubuntu: `sudo apt-get install android-tools-fastboot` 25 26## Overview 27 28At a high level, these are the steps for getting a HiKey development environment 29fully working: 30 31+ Build a Zircon boot image 32+ Enable the serial console (useful for debugging subsequent steps) 33+ Flash the HiKey's low-level firmware 34+ Flash the Zircon boot image onto the HiKey (this image -- specifically 35 zedboot -- will receive and boot your subsequent Fuchsia builds) 36+ Build and boot Fuchsia 37 38Once the system is correctly configured, your development workflow should 39resemble a workflow on other hardware (repeated builds done with `fx build`, 40a persistent instance of `fx pave` to automatically update the hardware, and a 41persistent instance of `fx log` to capture console output). 42 43 44## Useful Information 45 46+ [HiKey960 Development Board User Manual](https://www.96boards.org/documentation/ConsumerEdition/HiKey960/HardwareDocs/HardwareUserManual.md.html) 47+ [96boards-hikey github page](https://github.com/96boards-hikey) 48+ [96boards Getting Started page](https://www.96boards.org/documentation/ConsumerEdition/HiKey960/GettingStarted/) 49+ [SoC Reference](https://github.com/96boards/documentation/raw/master/ConsumerEdition/HiKey960/HardwareDocs/HiKey960_SoC_Reference_Manual.pdf) 50+ [AOSP HiKey960 Information](https://source.android.com/source/devices#hikey960) 51+ [HiKey960 Schematic](http://www.lemaker.org/product-hikeysecond-download-62.html) 52 53## Building the Zircon boot image 54 55To build zircon, invoke the following command from the top level Zircon 56directory (ensure that you have checked out the ARM64 toolchains). For more 57information, see `docs/getting_started.md`: 58 59 make arm64 60 61 62## Setting up the serial console 63 64First, get the device to show up on your dev host machine as a serial device. 65Following that, install and configure a console app. 66 67#### Serial hardware setup 68 69If using a __mezzanine board__, follow the instructions included with it. 70Additional tips: 71 72 + Take care not to install the mezzanine board backwards on the connector. The 73 micro-USB port should face outward; the corner pushbutton should be in the 74 center of the HiKey board. 75 76 + Some standard micro-USB cables have a button to enable/disable the data 77 lines. When using one of these cables, ensure that these lines are enabled - 78 the LED should be _amber_ (not green). 79 80 + The mezzanine board receives power through the micro-USB cable, so power 81 need not be applied to the main HiKey board yet. 82 83If using a __FTDI-style serial adapter cable__: 84 85 + The signals are available on the 40 pin LS connector 86([reference](https://raw.githubusercontent.com/96boards/documentation/master/ConsumerEdition/HiKey960/AdditionalDocs/Images/Images_HWUserManual/HiKey960_Numbered_Front2.png)) 87 + Pin 1 - GND 88 + Pin 11 - UART TX (HiKey960 --> Host) 89 + PIN 13 - UART RX (HiKey960 <-- Host) 90 91 92 + This means that for a common [FTDI style adapter](https://www.digikey.com/products/en?keywords=768-1070-ND): 93 + Black --> Pin1 94 + Yellow --> Pin11 95 + Orange --> Pin13 96 97 98 + (Optional) an active low reset is available on pin 6 of the 40 pin LS 99 connector. A jumper wire intermittently shorted from this pin to GND (shields 100 of the connectors are all grounded) can provide an easy way to reset the board 101 and place it in fastboot mode. 102 103Once you have correctly configured the hardware (via either method), the device 104should appear to your host machine as a USB-connected UART, listed in your /dev 105directory as `/dev/ttyUSB0` (or USB1, etc). If this is _not_ the case, you may 106have forgotten to enable the data lines (LED should be amber), or you may have a 107bad micro-USB cable or mezzanine board. Regardless, do not proceed until your 108HiKey board is detected and enumerated in the `/dev` directory as a tty device. 109 110#### Serial console software 111 112Use a host application such as screen or putty to connect to the serial port and 113provide console functionality. Use a baud rate of 115200. 114 115Example commands using **screen**: 116 + `screen /dev/ttyUSB0 115200,-ixoff` 117 + `Ctrl-a, Esc` to enable scrolling (then k-up, j-down, q-done scrolling) 118 + `Ctrl-a, d` to detach from the session (`screen -r -d` to reattach) 119 + `Ctrl-a, \` to kill all screen sessions. 120 121If you receive an error when connecting to your tty/USBn, you may need to run 122your serial console application as `sudo`. Alternately, you can add a udev rule 123that allows applications to connect to this device: 124 125 + Create file `/etc/udev/rules.d/99-ttyusb.rules` containing the following: 126 127 `SUBSYSTEM=="tty", GROUP="dialout"` 128 129 + Then `sudo udevadm control --reload-rules` 130 131 132## Entering fastboot mode 133##### (needed for flashing low-level firmware and/or Zircon) 134 135Connect the power supply if you have not already. If the power plug doesn't 136seem to fit, you may have forgotten to get a DC adapter. The power plug for the 137HiKey boards has a 4.75mm diameter and 1.7mm center pin, whereas most DC power 138supplies in this class have a 5.5mm diameter and 2.1mm center pin. 139 140To flash the board, it must be connected to your workstation via the USB-C OTG 141connection on the HiKey960 main board. Additionally, the HiKey960 must be in 142fastboot mode. You can enter fastboot in one of two ways: 143 144+ __DIP Switch method__ Use the switches on the back of the board. (Older 145 HiKeys may have jumpers instead of DIP switches.) To boot into fastboot mode, 146 the switches should be in the following positions: 147 148 Auto Power up(Switch 1) closed/ON 149 Recovery(Switch 2) open/OFF 150 Fastboot(Switch 3) closed/ON 151 152 Once the switches are in these positions, unplug/plug power or reset the 153 board. It will then boot into _fastboot_ mode, awaiting commands from the 154 host. If you are using the serial adapter cable, just a reminder that this can 155 be done with the jumper wire on pin 6, as mentioned earlier. 156 157 Note: after you have performed the last of your flash operations, you want the 158 device to boot normally going forward, so you should open (turn OFF) DIP 159 switch 3 _before_ your final boot (once firmware and Zircon updates are 160 complete, before booting into Zircon for the first time). 161 162+ __Double-Reset method__ Using the button on the mezzanine board, reset the 163 board, then reset it _again_ after seeing the following console messages: 164 165 C3R,V0x00000016 e:113 166 C0R,V0x00000017 e:66 167 C1R,V0x00000017 e:66 168 C2R,V0x00000017 e:66 169 C3R,V0x00000017 e:66 170 171 The second reset instructs the board to restart into fastboot __for the next 172 boot cycle only__. The timing on this double-reset is a little tricky, but you 173 will know you got the timing right if you see the following console messages 174 at the end of the boot spew: 175 176 usbloader: bootmode is 4 177 usb: [USBFINFO]USB RESET 178 usb: [USBFINFO]USB CONNDONE, highspeed 179 usb: [USBFINFO]USB RESET 180 usb: [USBFINFO]USB CONNDONE, highspeed 181 usbloader: usb: online (highspeed) 182 usb: [USBFINFO]usb enum done 183 184 These messages confirm that the device has restarted into fastboot mode. If 185 you do not see these messages, use the button to reset the board and try again 186 until you are successful. 187 188 As a reminder, with this method, the DIP switches on the HiKey should remain 189 in _normal_ mode (closed/ON open/OFF open/OFF), not the 'fastboot' mode 190 mentioned in the previous option. 191 192Once the board is in fastboot mode (regardless of which method you use), it is 193ready to be flashed with firmware updates and/or the Zircon boot image. 194 195## Install Firmware 196 197We have run into inconsistent behavior between different HiKey 960 boards, 198depending on the low level firmware came installed on the device. We recommend 199setting up your board with known good firmware from the Android AOSP project. 200 201To install firmware, put your board in fastboot mode and run the following: 202 203 ./scripts/flash-hikey -f 204 205## Recover the device 206 207If the hikey gets into a bad state you can try the recovery mechanism. 208The script should automate the process, including reinstalling the firmware. You 209first need to put the device into recovery mode: 210 211 Auto Power up(Switch 1) closed/ON 212 Recovery(Switch 2) closed/ON 213 Fastboot(Switch 3) open/OFF 214 215Then run: 216 217 ./scripts/flash-hikey -r 218 219The recovery process communicates with the device over the USB-C cable, but it 220can be a bit flaky at times. If the script complains that it can't open the 221serial device first check what serial devices are connected (`ls 222/dev/serial/by-id/`) and make sure the script is using the correct device. You 223can specify which serial port to use with `-p`. Sometimes you just need to try a 224few times or power cycle the device. Occasionally the script will fail when 225attempting to install firmware, which can usually be fixed by starting again. 226 227## Installing Zircon 228 229Once the HiKey board is in fastboot mode, run the following script from the 230zircon root directory to flash the necessary files onto the board: 231 232 ./scripts/flash-hikey 233 234## Zedboot 235 236If you would like to boot future kernels via the network, instead of flashing 237them directly, then run the script with the `-m` option. 238 239 ./scripts/flash-hikey -m 240 241This is the last flash update, and all subsequent boots should use normal mode 242(not fastboot or recovery). If you used the DIP Switch method to place the board 243in fastboot mode, you should flip the fastboot switch (switch 3) back to 244open/OFF _before_ running this script, so that it will boot into Zircon after 245flashing (otherwise, it will boot back into fastboot mode). 246 247If you used the double-tap reset method to place the board into fastboot mode, 248no further reconfiguration is needed: the board will boot into the kernel after 249it completes flashing. 250 251For now, the ethernet connectivity needed for zedboot is actually provided by 252zircon via USB. This is automatically enabled on the HiKey USB-C connector, if 253it is changed from host mode into device mode. If all flash steps appear to 254complete successfully, but the device does not restart into Zedboot, you may 255need to manually place the device into USB 'device' mode. Enter the following 256command in your console: 257 258 usbctl mode device 259 260This step must be repeated each time the device is fully powered-down/up. At 261some point in the near future, the Fuchsia build will include support for USB 262NICs via USB-A, at which time this `usbctl` step will be unnecessary. 263 264Once your device restarts and displays 'Zedboot' in the console, the setup 265process is complete. You can now use your usual build, boot and log commands. 266When powering up (not simply resetting) the device, you may need to press the 267reset button for the device to show up again as /dev/ttyUSBn. Recall that this 268is needed before connecting the serial console and interacting with the device. 269 270 271## Manually Installing Low-Level Firmware 272 273Note: the following requires fastboot in your execution path. 274 275To install firmware, put your board in fastboot mode and run the following: 276 277 git clone https://android.googlesource.com/device/linaro/hikey hikey-firmware 278 git -C hikey-firmware checkout 972114436628f874ac9ca28ef38ba82862937fbf 279 fastboot flash ptable hikey-firmware/installer/hikey960/ptable.img 280 fastboot flash xloader hikey-firmware/installer/hikey960/sec_xloader.img 281 fastboot flash fastboot hikey-firmware/installer/hikey960/fastboot.img 282 fastboot flash nvme hikey-firmware/installer/hikey960/nvme.img 283 fastboot flash fw_lpm3 hikey-firmware/installer/hikey960/lpm3.img 284 fastboot flash trustfirmware hikey-firmware/installer/hikey960/bl31.bin 285 286This installs all the AOSP firmware except Android itself. To use a different 287bootloader altogether (not the one from AOSP), first complete the above commands 288and then install your bootloader. 289 290## Device support 291 292The console is especially important because the HiKey builds of Fuchsia do not 293yet support the HDMI port. Related to this, only USB is supported for audio 294input/output. NOTE: all USB audio devices must be High-Speed (not just USB 2.0 295compatible, which might be Full-Speed or High-Speed). If the USB audio device 296is enumerated as 12Mb/s, then it is Full-Speed. 297
)){kind=link}