Facedancer SoC Firmware Compilation

Prerequisites

Before proceeding, please ensure you have followed the prerequisites in the Setting up a Development Environment section.

Install Rust Dependencies

You will need to install RISC-V embedded target support to compile the firmware:

rustup target add riscv32imac-unknown-none-elf
rustup component add llvm-tools-preview
cargo install cargo-binutils

Optionally, to use gdb for firmware debugging over JTAG, you will need a RISC-V GNU tool chain:

# debian
apt install gcc-riscv64-unknown-elf

# arch
pacman -S riscv-gnu-toolchain-bin

# macos brew - https://github.com/riscv-software-src/homebrew-riscv
brew tap riscv-software-src/riscv
brew install riscv-gnu-toolchain

Building and Running

Firmware for the Cynthion SoC can be found in the firmware/moondancer/ sub-directory.

You can rebuild the firmware using cargo as follows:

# change to the Cynthion firmware directory
cd firmware/moondancer/

# rebuild the firmware
cargo build --release

To upload the firmware binary to Cynthion and flash the SoC bitstream you can run:

# change to the Cynthion firmware directory
cd firmware/moondancer/

# upload firmware and run it
cargo run --release

Note

By default the firmware’s flash script will look for the SoC UART on /dev/ttyACM0, if this is not the case on your machine you will need to specify the correct path using the UART environment variable, for example:

UART=/dev/cu.usbmodem22401 cargo run --release

By default the SoC bitstream is obtained from the latest build in cynthion/python/build/top.bit but you can override it with:

BITSTREAM=path/to/bitstream.bit cargo run --release

Running Firmware Unit Tests

Once the firmware is running on the SoC you can execute some unit tests to exercise the firmware.

In order to do this you will need to connect both the CONTROL and AUX ports of the Cynthion to the host and then run:

# change to the Cynthion firmware directory
cd firmware/moondancer/

# run firmware unit tests
python -m unittest

Firmware Examples

There are a number of firmware examples in the firmware/moondancer/examples/ sub-directory.

# change to the Cynthion firmware directory
cd firmware/moondancer/

# run example
cargo run --release --example <example name>