Documentation/mainboard/sifive/hifive-unleashed.md

   1 # SiFive HiFive Unleashed
   2
   3 This page describes how to run coreboot on the [HiFive Unleashed] development
   4 board from [SiFive], the first RISC-V board on the market with enough resources
   5 to run a multiuser operating system.
   6
   7 For general setup instructions, please refer to the [Getting Started Guide].
   8
   9
  10 ## TODO
  11
  12 The following things are still missing from this coreboot port:
  13
  14 - Support running romstage from flash (fix stack) to support boot mode 1
  15 - Starting the U54 cores
  16 - FU540 PIN configuration and GPIO access macros
  17 - Provide serial number to payload (e.g. in device tree)
  18 - Implement instruction emulation
  19 - Support for booting Linux on RISC-V
  20 - SMP support in trap handler
  21
  22 ## Configuration
  23
  24 Run `make menuconfig` and select _SiFive_/_HiFive Unleashed_ in the _Mainboard_
  25 menu.
  26
  27
  28 ### Boot modes
  29
  30 A total of 16 boot modes can be configured using the switches labeled `MSEL0`
  31 through `MSEL3`. The most important ones are as follows:
  32
  33 - **MSEL=1**: Jump directly into the SPI flash, bypassing ROM1
  34 - **MSEL=11**: Load FSBL from SD-card
  35 - **MSEL=15**: Default boot mode; Load FSBL/coreboot from a GPT partition on
  36   SPI flash
  37
  38
  39 ## Flashing coreboot
  40
  41 The HiFive Unleashed has an 32 MiB SPI flash (**ISSI IS25WP256D**), that can be
  42 programmed from within Linux running on the board, via USB/JTAG, or directly
  43 with an SPI programmer.
  44
  45 ### Internal programming
  46
  47 The SPI flash can be accessed as `/dev/mtd0` from Linux.
  48
  49 ### USB/JTAG
  50
  51 To program the flash via USB/JTAG, connect the USB port to a computer. If the
  52 board is powered on, two new serial ports, for example `/dev/ttyUSB0` and
  53 `/dev/ttyUSB1` will appear. The first is JTAG, and the second is connected to
  54 the SoC's UART.
  55
  56 - Download and build the [RISC-V fork of OpenOCD].
  57 - Download the [OpenOCD script] for Freedom Unleashed.
  58 - Start OpenOCD with `openocd -f openocd.cfg`
  59 - Connect to OpenOCD's command interface (via telnet) and enter the line
  60   marked with `> `:
  61 ```
  62 > flash write_image erase unlock build/coreboot.rom 0x20000000
  63 auto erase enabled
  64 auto unlock enabled
  65 wrote 33554432 bytes from file build/coreboot.rom in 1524.943848s (21.488 KiB/s)
  66 ```
  67   Note that programming the whole flash with OpenOCD isn't fast. In this
  68   example it took just over 25 minutes. This process can be sped up
  69   considerably by building/flashing a smaller image; OpenOCD does not check if
  70   the image and the flash have the same size.
  71
  72
  73 ### External programming
  74
  75 External programming with an SPI adapter and [flashrom] may work, but has not
  76 been tested. Please study the [schematics] before going this route.
  77
  78
  79 ## Error codes
  80
  81 The zeroth-stage bootloader (ZSBL) in ROM1 can print error codes on the serial
  82 console in certain situations.
  83
  84 ```
  85 // Error codes are formatted as follows:
  86 // [63:60]    [59:56]  [55:0]
  87 // bootstage  trap     errorcode
  88 // If trap == 1, then errorcode is actually the mcause register with the
  89 // interrupt bit shifted to bit 55.
  90 ```
  91 (--- from the [SiFive forum](https://forums.sifive.com/t/loading-fsbl-from-sd/1156/4))
  92
  93
  94 [HiFive Unleashed]: https://www.crowdsupply.com/sifive/hifive-unleashed
  95 [SiFive]: https://www.sifive.com/
  96 [Getting Started Guide]: https://sifive.cdn.prismic.io/sifive%2Ffa3a584a-a02f-4fda-b758-a2def05f49f9_hifive-unleashed-getting-started-guide-v1p1.pdf
  97 [RISC-V fork of OpenOCD]: https://github.com/riscv/riscv-openocd
  98 [OpenOCD script]: https://github.com/sifive/freedom-u-sdk/blob/057a47f657fa33e2c60df7f183884a68e90381cc/bsp/env/freedom-u500-unleashed/openocd.cfg
  99 [flashrom]: https://flashrom.org/Flashrom
 100 [schematics]: https://sifive.cdn.prismic.io/sifive%2Ff7173056-bf37-4407-87cb-d5ab76abf61a_hifive-unleashed-a00-schematics.pdf