Awesome
sancus-main
This top-level repository contains a build script (Makefile) and Docker setup to create a working Sancus development environment by resolving system dependencies, and installing the latest sub-projects. The resulting Sancus distribution offers a complete development environment, including simulator, compiler/toolchain, support libraries, and example programs.
Quickstart with Docker
To get started quickly, we provide prebuilt sancus-devel
Docker containers
with the latest, "nightly" Sancus toolchain. This is the easiest way to get
started immediately if you do not care about modifying the Sancus core itself
but just wish to work with the existing toolchain. The sancus-devel
containers should always provide you with a working, out-of-the-box toolchain
that has been tested against the latest
CI tests.
Install docker
Quick installation guide (Debian GNU/Linux and Ubuntu), loosely based on https://docs.docker.com/get-started/
-
Install docker
# apt-get install docker.io
-
Configure user access
# usermod -aG docker $(whoami) # add users to docker group, then re-login.
-
Check your docker installation
$ docker run hello-world [...] This message shows that your installation appears to be working correctly. [...]
Docker run Sancus simulator
Proceed as follows to pull the latest sancus-devel
container and run example
programs or start your own experiments in the sancus-sim
cycle-accurate
Verilog simulator:
# Pull latest Sancus image for 128 bit security
$ docker pull ghcr.io/sancus-tee/sancus-main/sancus-devel-128:latest
# Run Docker interactively
$ docker run -it ghcr.io/sancus-tee/sancus-main/sancus-devel-128:latest
# Alternatively, run Docker as follows to attach directory ~/project into the Docker file system
$ docker run -it -v ~/project:/sancus/project ghcr.io/sancus-tee/sancus-main/sancus-devel-128:latest
# Try simulating one of the examples
$ cd /sancus/sancus-examples/hello-world/
$ make sim
Docker run Sancus FPGA
First start Docker with access to the /dev/ttyUSB0
FPGA uplink:
# Run Docker and attach above directory but also forward USB UART0 to the container
$ docker run -it -v ~/project:/sancus/project --device /dev/ttyUSB0 ghcr.io/sancus-tee/sancus-main/sancus-devel-128:latest
Next, to load the FPGA image on the board from within Docker. Download the latest released flash files from sancus-core and flash them onto the board.
# Flash FPGA image file
$ xsload --flash <mcs file>
# !! Manually press the reset button on the board once to reset it
# Now in a terminal outside of the Docker container, open a screen session to see the future output on the UART 1:
$ screen /dev/ttyUSB1 115200
# Now you are ready to load the elf file from inside the docker via UART0:
# The docker image comes with sancus-examples pulled.
$ cd /sancus/sancus-examples
$ cd hello-world
$ make load SANCUS_SECURITY=128
# Or alternatively, to perform these steps manually:
$ make clean
$ make all SANCUS_SECURITY=128
$ sancus-loader -device /dev/ttyUSB0 main.elf
Building the Sancus toolchain from scratch
Note (reproducible build) The nightly sancus-devel
containers are built
automatically by our CI scripts and subsequently pushed to our GitHub packages
page. In case you want to build
Docker images yourself, or reproduce our builds, we provide the Docker script
that uses the Makefile to automatically build an Ubuntu 18.04-based
'sancus-devel' container. Simply execute make docker
to build and run the
Docker container, or see the docker subdirectory for detailed
instructions.
Requirements and Dependencies
Note: The build script was developed to work on a fresh Ubuntu 18.04/20.04/22.04 LTS installation, but it should be fairly straightforward to port to other GNU/Linux distribution.
The following dependencies are automatically installed when invoking make install_deps
:
- cmake >= 3.4.3
- pyelftools (Python 3+)
- msp430-gcc >= 4.6
- msp430-elf-gcc >= 6.0 provided by Texas Instruments (Debian package provided, see below)
- iverilog >= 0.9 (if you want to use the simulator)
- Clang/LLVM >= 3.4.3 (needs to be patched, Debian package provided; see below)
- xstools (see below)
While developing the Sancus compiler, we found a bug in Clang that has not yet
been merged upstream, and thus needs to be patched before being able to use our
compiler. The easiest way to do this is to install the provided Debian
package for AMD64 and ARMHF. This
package is called clang-sancus and will be installed in /usr/local/. If you
want to patch and build LLVM/Clang manually, use/check make llvm-inst
(you need 35GB of free disk space, most of this is for temporary files created by LLVM/Clang during the build
process and can be cleaned up afterwards).
From msp430-elf-gcc we need the latest binutils
for the MSP430. As for Cland, we provide these pre-packaged for Debian-based Linux distributions on AMD64 and ARMHF. Use or check make ti-mspgcc-inst
to build msp430-elf-gcc from source.
Building Instructions:
$ git clone https://github.com/sancus-tee/sancus-main.git
$ cd sancus-main
# 1. Install prerequisites
$ sudo make install_deps # default installation directory for Clang and \
# msp430-elf-gcc is /usr/local
# 2. Clone relevant Sancus project git repositories
$ make
# 3. Build and install Sancus toolchain
$ sudo make install # to override default security level (64 bits), use \
# SANCUS_SECURITY=128 \
# SANCUS_KEY=deadbeefcafebabec0defeeddefec8ed \
# use SANCUS_INSTALL_PREFIX=dir to override default \
# installation directory /usr/local
XSTOOLS Installation
Only needed when programming a physical FPGA board:
$ sudo pip2 install PyPubSub==3.3.0
$ sudo pip2 install xstools
$ sudo xstest # to test the connected FPGA boards
$ sudo xsload -b xula2-lx25 --flash path/to/image.mcs # program the FPGA
Example Programs
To test your newly installed Sancus distribution, run the example programs/test suite in the simulator (might take a long time since the hardware design is simulated at the gate-level).
$ make examples
$ make examples-sim
Cleanup and Uninstall
To remove temporary files:
$ sudo make clean
To remove temporary files, including all source code and example programs:
$ sudo make distclean
To remove the Sancus installation directory system-wide:
$ sudo make uninstall