Git-Mirrors/tillitis-key
1
0
Fork 0
mirror of https://github.com/tillitis/tillitis-key1.git synced 2024-10-01 01:45:38 -04:00
Code Issues Packages Projects Releases Wiki Activity
b7d0698e1b
tillitis-key/doc/toolchain_setup.md
Daniel Lublin 08bde89b3d
Clarify toolchain use 
Signed-off-by: Daniel Lublin <daniel@lublin.se>
2023-01-09 10:38:20 +01:00

5.6 KiB
Raw Blame History

Toolchain setup

Here are instructions for setting up the tools required to build the project. Tested on Ubuntu 22.10.

General development environment

The following is intended to be a complete list of the packages that are required for doing all of the following:

  • building and developing TKey host programs and apps
  • building our QEMU machine (useful for apps dev)
  • building and developing firmware and FPGA gateware (which also requires building the toolchain below)
sudo apt install build-essential clang lld llvm bison flex libreadline-dev \
                 gawk tcl-dev libffi-dev git mercurial graphviz \
                 xdot pkg-config python3 libftdi-dev \
                 python3-dev libeigen3-dev \
                 libboost-dev libboost-filesystem-dev \
                 libboost-thread-dev libboost-program-options-dev \
                 libboost-iostreams-dev cmake libhidapi-dev \
                 ninja-build libglib2.0-dev libpixman-1-dev \
                 golang

Gateware: Yosys/Icestorm toolchain

If the LED of your TKey is flashing white when you plug it, then the firmware is running and it's already usable! If you want to develop TKey apps, then only the above general development environment is needed.

Compiling and installing Yosys and friends is only needed if your TKey is not already running the required firmware and FPGA gateware, or if you want to do development on these components.

These steps are used to build and install the icestorm toolchain. The binaries are installed in /usr/local. Note that if you have or install other versions of these tools locally, they could conflict (case in point: yosys installed on MacOS using brew).

git clone https://github.com/YosysHQ/icestorm
cd icestorm
make -j$(nproc)
sudo make install
cd ..

# Custom iceprog for the RPi 2040-based programmer (will be upstreamed).
git clone -b interfaces https://github.com/tillitis/icestorm tillitis--icestorm
cd tillitis--icestorm/iceprog
make
sudo make PROGRAM_PREFIX=tillitis- install
cd ../..

git clone https://github.com/YosysHQ/yosys
cd yosys
# Avoiding current issue with yosys & icebram, filed in:
# https://github.com/YosysHQ/yosys/issues/3478
git checkout 06ef3f264afaa3eaeab45cc0404d8006c15f02b1
make -j$(nproc)
sudo make install
cd ..

git clone https://github.com/YosysHQ/nextpnr
cd nextpnr
# Use nextpnr-0.4. Aa few commits later we got issues, like on f4e6bbd383f6c43.
git checkout nextpnr-0.4
cmake -DARCH=ice40 -DCMAKE_INSTALL_PREFIX=/usr/local .
make -j$(nproc)
sudo make install

References:

Firmware: riscv toolchain

The TKey implements a picorv32 soft core CPU, which is a RISC-V microcontroller with the C instructions and Zmmul extension, multiply without divide (RV32ICZmmul). You can read more about it.

The project uses the LLVM/Clang suite and version 15 or later is required. As of writing Ubuntu 22.10 has version 15 packaged. You may be able to get it installed on older Ubuntu and Debian using the instructions on https://apt.llvm.org/ . There are also binary releases here: https://github.com/llvm/llvm-project/releases

References:

If your available objcopy and size commands is anything other than the default llvm-objcopy and llvm-size define OBJCOPY and SIZE to whatever they're called on your system before calling make.

Optional

These tools are used for specific sub-components of the project, and are not required for general development

Kicad 6.0: Circuit board designs

The circuit board designs were all created in KiCad 6.0.

mta1-usb-v1-programmer: RPi 2040 toolchain

These tools are needed to build the programmer firmware for the mta1-usb-v1-programmer

FW update of programmer board

The programmer board is running a custom firmware developed by Blinkinlabs. The source code for this firnware is available on Github: https://github.com/Blinkinlabs/ice40_flasher

There is also a pre built firmware binary available for the programmer board: https://github.com/Blinkinlabs/ice40_flasher/tree/main/bin

To update the firmware on the programmer board, either build the file "main.uf2", or download the pre built file to your host computer. Then do the following:

  1. Disconnect the programming board from the host computer
  2. Press and hold the "BOOTSEL" button on the RPi2040 sub board on the programming board
  3. Reconnect the programming board to the host computer
  4. Release the "BOOTSEL" button after connecting the programming board to the host. The board should now appear to the host as a USB connected storage device
  5. Open the storage device and drop the firmware file ("main.uf2") into the storage device

The programmer will update its firmware with the file and restart itself. After reboot the storage device will automatically be disconnected.

mta1-usb-v1: ch552 USB to Serial firmware

The USB to Serial firmware runs on the CH552 microcontroller, and provides a USB CDC profile which should work with the default drivers on all major operating systems.

TODO

References: