Environment

Setting up the environment

Step 1 - If your board requires a proprietary toolchain, install that.

• Spartan 6 based boards require Xilinx ISE. Xilinx ISE is a proprietary toolchain which must be installed manually.

  This is most boards, including

  • MimasV2,
  • Opsis,
  • Atlys,
  • Pipistrello,
  • minispartan6/minispartan6+

• "Series 7" based boards require Xilinx Vivado. Xilinx Vivado is a proprietary toolchain which must be installed manually.

  These boards include;

  • NeTV2,
  • Nexys_Video,
  • Arty

• TODO: Cyclone V based boards require Quartus Prime

  Intel Quartus Prime (was Altera Quatrus II) is a proprietary toolchain which must be installed manually.

  These boards include;

  • De0 Nano

• TODO: ICE40 based boards require Yosys, Anancr-PNR. [XXXX] is an open source toolchain which can be installed automatically.

  These boards include;

  • IceStick?
  • ???

Step 2 - Install required system packages

• download-env-root.sh does this.

Bunch of packages are needed;

• Libraries for talking to USB - libftdi, libusb, fxload

• udev rules.

• Kernel modules for some boards. Mostly not needed....

Step 3 - Setup a self contained environment.

• download-env.sh does this.

The steps are;

• Get conda. Conda is a self contained Python install, kind of like virtualenv but includes the ability to install precompiled binary packages.

• Install precompiled C compiler toolchain from TimVideos Conda repo. This includes; binutils, gcc and gdb.

  • The C compiler toolchain is needed for compiling the BIOS and firmware.

• Install precompiled JTAG tool from from TimVideos Conda repo. The tool we use is openocd.

• Install dependent Python packages (from pip/conda/elsewhere). Things like pyserial and stuff.

• Install tools for simulation and testing. Things like verilator.

• Install tools for helping manage FPGA boards. Things like HDMI2USB-mode-switch, MimasV2Config.py, flterm.

• Initialising submodules and install litex packages from third_party/.

This is completely contained in the build/conda directory. Removing that directory will totally remove the installed environment.

Step 4 - Enter self contained environment & set environment variables.

• If you installed Xilinx to anywhere other than /opt/Xilinx/, run export XILINX_DIR=<path>. This must be set before entering the environment, as it is not updated from within it.

• source scripts/enter-env.sh - enter-env checks that your environment is setup correctly and contains all the dependencies you need.

• export PLATFORM=<platform> - Default is Opsis

• export TARGET=<targetname> - Default is dependent on the platform.

After entering environment

Build gateware for the FPGA

• make gateware

Load or Flash gateware onto the FPGA

• make load - Load firmware temporarily onto your board. Should come back from a power cycle in the previous state.
• make flash - Permanently write firmware onto your board. After a power cycle the board will come up with your flashed configuration.

Updating the Environment

From time to time you may need to update your environment to get the latest changes from the upstream git or conda repositories. This is generally done by running the ./scripts/download-env.sh script again.

Running the ./scripts/download-env.sh script on an existing environment will:

• Update python and utilities
• Update conda on its packages
• Update git submodules

Updating git submodules

If you have made changes to any git submodules and are now trying to update you may find that running ./scripts/download-env.sh or git submodules update --init does not pick up the latest changes as expected.

To force an update of submodules you can do git reset --hard in the submodule directory. Note, this will cause you to loose any uncommitted changes. To avoid this it is best to develop git submodule changes on a feature branch.