2022-09-19 06:51:11 +00:00
|
|
|
# Toolchain setup
|
|
|
|
|
2022-12-01 18:10:13 +00:00
|
|
|
Here are instructions for setting up the tools required to build the
|
|
|
|
project. Tested on Ubuntu 22.10.
|
2022-09-19 06:51:11 +00:00
|
|
|
|
2022-12-01 18:10:13 +00:00
|
|
|
## General development environment
|
2022-09-19 06:51:11 +00:00
|
|
|
|
2022-12-01 18:10:13 +00:00
|
|
|
The following is intended to be a complete list of the packages that
|
2023-01-09 09:38:20 +00:00
|
|
|
are required for doing all of the following:
|
2022-09-19 06:51:11 +00:00
|
|
|
|
2023-01-09 09:38:20 +00:00
|
|
|
- building and developing [TKey host programs and
|
|
|
|
apps](https://github.com/tillitis/tillitis-key1-apps)
|
|
|
|
- building our [QEMU machine](https://github.com/tillitis/qemu/tree/tk1)
|
|
|
|
(useful for apps dev)
|
|
|
|
- building and developing firmware and FPGA gateware (which also
|
|
|
|
requires building the toolchain below)
|
2022-09-19 06:51:11 +00:00
|
|
|
|
2023-01-09 09:38:20 +00:00
|
|
|
```
|
|
|
|
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 \
|
2023-02-16 15:12:30 +00:00
|
|
|
libboost-iostreams-dev cmake libusb-1.0-0-dev \
|
2023-01-09 09:38:20 +00:00
|
|
|
ninja-build libglib2.0-dev libpixman-1-dev \
|
2023-03-08 21:32:33 +00:00
|
|
|
golang clang-format \
|
2023-03-27 08:01:40 +00:00
|
|
|
gcc-arm-none-eabi libnewlib-arm-none-eabi \
|
|
|
|
libstdc++-arm-none-eabi-newlib
|
2023-01-09 09:38:20 +00:00
|
|
|
```
|
|
|
|
|
2023-02-16 15:10:07 +00:00
|
|
|
## Device permissions
|
|
|
|
|
|
|
|
To allow sudo-less programming, you can install a udev rule that will
|
|
|
|
assign the tkey programmer, and also an unprogrammed CH552, to the
|
|
|
|
dialout group. You will also need to add your user to this group:
|
|
|
|
|
|
|
|
```
|
|
|
|
sudo cp contrib/99-tillitis.rules /etc/udev/rules.d
|
2023-03-08 22:41:33 +00:00
|
|
|
sudo udevadm control --reload-rules
|
2023-02-16 15:10:07 +00:00
|
|
|
sudo usermod -aG dialout ${USER}
|
|
|
|
```
|
|
|
|
|
|
|
|
To apply the new group, log out and then log back in.
|
|
|
|
|
|
|
|
You can check the device permissions to determine if the group was
|
|
|
|
successfully applied. First, use lsusb to find the location of the
|
|
|
|
programmer:
|
|
|
|
|
|
|
|
```
|
2023-03-08 22:41:33 +00:00
|
|
|
lsusb -d 1209:8886
|
|
|
|
Bus 001 Device 023: ID 1209:8886 Generic TP-1
|
2023-02-16 15:10:07 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
Then, you can check the permissions by using the bus and device
|
|
|
|
number reported above. Note that this pair is ephimeral and may
|
|
|
|
change after every device insertion:
|
|
|
|
|
|
|
|
```
|
|
|
|
ls -l /dev/bus/usb/001/023
|
|
|
|
crw-rw---- 1 root dialout 189, 22 Feb 16 14:58 /dev/bus/usb/001/023
|
|
|
|
```
|
|
|
|
|
2023-01-09 09:38:20 +00:00
|
|
|
## Gateware: Yosys/Icestorm toolchain
|
|
|
|
|
2023-03-01 10:50:24 +00:00
|
|
|
If the LED of your TKey is steady white when you plug it, then the
|
2023-01-09 09:38:20 +00:00
|
|
|
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.
|
2022-12-01 18:10:13 +00:00
|
|
|
|
|
|
|
These steps are used to build and install the
|
2023-01-09 09:38:20 +00:00
|
|
|
[icestorm](http://bygone.clairexen.net/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).
|
2022-12-01 18:10:13 +00:00
|
|
|
|
2022-09-19 06:51:11 +00:00
|
|
|
git clone https://github.com/YosysHQ/icestorm
|
|
|
|
cd icestorm
|
2023-03-02 11:03:33 +00:00
|
|
|
git checkout 45f5e5f3889afb07907bab439cf071478ee5a2a5
|
2022-09-19 06:51:11 +00:00
|
|
|
make -j$(nproc)
|
|
|
|
sudo make install
|
|
|
|
cd ..
|
|
|
|
|
|
|
|
# Custom iceprog for the RPi 2040-based programmer (will be upstreamed).
|
2023-03-27 08:01:40 +00:00
|
|
|
# Note: install dependencies for building tillitis-iceprog on Ubuntu:
|
|
|
|
# sudo apt install libftdi-dev libusb-1.0-0-dev
|
|
|
|
git clone -b interfaces https://github.com/tillitis/icestorm tillitis--icestorm
|
2022-09-19 06:51:11 +00:00
|
|
|
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
|
2022-09-23 09:34:39 +00:00
|
|
|
# Use nextpnr-0.4. Aa few commits later we got issues, like on f4e6bbd383f6c43.
|
|
|
|
git checkout nextpnr-0.4
|
2022-09-19 06:51:11 +00:00
|
|
|
cmake -DARCH=ice40 -DCMAKE_INSTALL_PREFIX=/usr/local .
|
|
|
|
make -j$(nproc)
|
|
|
|
sudo make install
|
2023-03-02 11:03:33 +00:00
|
|
|
cd ..
|
2022-09-19 06:51:11 +00:00
|
|
|
|
|
|
|
References:
|
|
|
|
* http://bygone.clairexen.net/icestorm/
|
|
|
|
|
|
|
|
## Firmware: riscv toolchain
|
|
|
|
|
2022-12-01 15:15:27 +00:00
|
|
|
The TKey implements a [picorv32](https://github.com/YosysHQ/picorv32)
|
|
|
|
soft core CPU, which is a RISC-V microcontroller with the C
|
|
|
|
instructions and Zmmul extension, multiply without divide
|
|
|
|
(RV32ICZmmul). You can read
|
2022-09-19 06:51:11 +00:00
|
|
|
[more](https://www.sifive.com/blog/all-aboard-part-1-compiler-args)
|
|
|
|
about it.
|
|
|
|
|
2022-11-28 14:56:56 +00:00
|
|
|
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
|
2022-09-19 06:51:11 +00:00
|
|
|
|
|
|
|
References:
|
|
|
|
* https://github.com/YosysHQ/picorv32
|
|
|
|
|
2022-12-01 15:15:27 +00:00
|
|
|
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`.
|
|
|
|
|
2023-02-15 10:45:42 +00:00
|
|
|
## Circuit board designs: KiCad 6.0
|
2022-09-19 06:51:11 +00:00
|
|
|
|
|
|
|
The circuit board designs were all created in [KiCad
|
|
|
|
6.0](https://www.kicad.org/).
|
|
|
|
|
2023-02-15 10:45:42 +00:00
|
|
|
## MTA1-USB-V1 and TP-1 programming board firmware
|
2022-09-21 12:30:16 +00:00
|
|
|
|
2023-02-15 10:45:42 +00:00
|
|
|
The programmer boards are running a custom firmware developed by
|
|
|
|
Blinkinlabs. The source code for this firnware is available on
|
|
|
|
Github: https://github.com/Blinkinlabs/ice40_flasher
|
2022-10-19 13:59:42 +00:00
|
|
|
|
2023-02-15 10:45:42 +00:00
|
|
|
There is also a pre built firmware binary available for the
|
|
|
|
programmer board:
|
2022-09-21 12:30:16 +00:00
|
|
|
https://github.com/Blinkinlabs/ice40_flasher/tree/main/bin
|
|
|
|
|
2023-02-15 10:45:42 +00:00
|
|
|
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:
|
2022-09-21 12:30:16 +00:00
|
|
|
|
2022-10-19 13:59:42 +00:00
|
|
|
1. Disconnect the programming board from the host computer
|
2023-02-15 10:45:42 +00:00
|
|
|
2. Press and hold the "BOOTSEL" button on the RPi2040 sub board on
|
|
|
|
the programming board
|
2022-10-19 13:59:42 +00:00
|
|
|
3. Reconnect the programming board to the host computer
|
2023-02-15 10:45:42 +00:00
|
|
|
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
|
2022-09-19 06:51:11 +00:00
|
|
|
|
2023-02-15 10:45:42 +00:00
|
|
|
The programmer will update its firmware with the file and restart
|
|
|
|
itself. After reboot the storage device will automatically be
|
|
|
|
disconnected.
|
2022-09-19 06:51:11 +00:00
|
|
|
|
2023-03-08 16:28:58 +00:00
|
|
|
The firmware requires the Raspberry Pi Pico SDK:
|
|
|
|
|
|
|
|
cd ~
|
|
|
|
git clone --branch 1.5.0 https://github.com/raspberrypi/pico-sdk.git
|
|
|
|
cd pico-sdk
|
|
|
|
git submodule update --init
|
|
|
|
|
|
|
|
Note that the Docker image places the pico-sdk directory in
|
|
|
|
/usr/local. For normal development, it is usually left in the
|
|
|
|
users home directory.
|
|
|
|
|
2022-09-19 06:51:11 +00:00
|
|
|
|
2023-02-15 10:45:42 +00:00
|
|
|
## CH552 USB to Serial firmware
|
2022-09-19 06:51:11 +00:00
|
|
|
|
|
|
|
The USB to Serial firmware runs on the CH552 microcontroller, and
|
|
|
|
provides a USB CDC profile which should work with the default drivers
|
2023-02-15 10:45:42 +00:00
|
|
|
on all major operating systems. MTA1-USB-V1 and TK-1 devices come
|
|
|
|
with the CH552 microcontroller pre-programmed.
|
2022-09-19 06:51:11 +00:00
|
|
|
|
2023-02-15 10:45:42 +00:00
|
|
|
Toolchain setup and build instructions for this firmware are detailed
|
|
|
|
in the
|
2023-03-02 11:03:33 +00:00
|
|
|
[ch552_fw directory](../hw/boards/mta1-usb-v1/ch552_fw/README.md)
|