Skip to content

2.Installation Guide for Amaranth HDL Workflow

Jump to bottom
TarikHamedovic edited this page Oct 30, 2024 · 1 revision

This guide provides two methods for setting up the tools required for the Amaranth HDL workflow:

  1. Using the OSS CAD Suite – a comprehensive, pre-packaged set of open-source tools.
  2. Installing Tools Individually from Source – for greater customization and flexibility.

While Amaranth is primarily a Python library that can be easily installed via pip, utilizing it effectively for FPGA development involves additional tools that are not Python libraries. These tools handle the three main stages required to place RTL (Register-Transfer Level) code onto an FPGA: synthesis, placement and routing, and bitstream programming. It should be noted that Amaranth has the possiblity of using different toolchains for the same FPGA vendor, for example it can use Vivado tools for synthesis and pnr or use open-source tools. I'll give a a short overview for the open-source tools.

At the end the setup used for a commercial FPGA Vendor will be shown with special emphasis on the Xilinx Vivado toolchain. Here is the link to the section.

  1. Synthesis: The universal tool for this step is Yosys, which synthesizes RTL code into a gate-level netlist.

  2. Placement and Routing: This process varies depending on the FPGA vendor, but a common tool for many FPGAs is nextpnr. Nextpnr handles the conversion of a synthesized netlist into a layout that can be programmed onto the FPGA.

  3. Bitstream Programming: Once the placement and routing are complete, the resulting bitstream needs to be uploaded to the FPGA. This is usually done with openFPGALoader, although some FPGA vendors may require different programming tools.

Specific FPGA vendors may also require additional or specialized tools, there are many other FPGA vendors I will just list a few:

  • Lattice: Uses PrjTrellis for ECP5 FPGAs.
  • GoWin: Utilizes Project Apicula for bitstream generation and programming.
  • Xilinx: Supports openXC7 for Xilinx 7-series FPGAs.
  • Altera: Requires Mistral for certain Intel FPGAs.

But if you want to use commercial tools for these FPGA vendors, you would need to download Diamond for Lattice, Vivado for Xilinx, Quartus for Altera etc and set up the paths/environment variables accordingly.

Overall, these tools complement Amaranth by covering the complete FPGA development workflow, from RTL synthesis to final bitstream programming, while also addressing vendor-specific requirements.

This guide provides installation instructions for both Linux (Ubuntu 22.04 LTS) and Windows. Linux can be run directly as the primary operating system on a computer or through Windows using Windows Subsystem for Linux (WSL) or VirtualBox. The guide covers all three approaches. Running a standard Linux distribution or using VirtualBox is straightforward and does not require any additional steps. However, using WSL involves some extra steps, which are outlined in this guide.

Method 1: Using the OSS CAD Suite

The OSS CAD Suite is a binary distribution that includes a wide range of open-source tools for digital logic design, such as RTL synthesis, formal hardware verification, place & route, FPGA programming, and testing. It supports multiple hardware description languages (HDLs), including Verilog, Migen, and Amaranth. Benefits of Using OSS CAD Suite:

  • Provides all the necessary tools in one place.
  • Ensures you have the latest versions.
  • Easy to update or remove specific tools as needed.

Create a Designated Folder

Create a folder to store all the tools. This folder will be used for the OSS CAD Suite installation and, optionally, for installing tools individually. It is recommended to clone this repository in the designated folder using git clone.

Install the OSS CAD Suite

Note: If using WSL or Linux OS run sudo apt update && sudo apt upgrade -y before doing all of these next steps.

  1. Download the OSS CAD Suite:

    • Visit the OSS CAD Suite Releases page.
    • Download the installer:
      • Windows: oss-cad-suite-windows-x64-<year_month_day>.exe
      • Linux: oss-cad-suite-linux-x64-<year_month_day>.targz

  2. Run the Installer:

    • Windows: Run the downloaded executable file as an administrator. Note: Make sure the path does not contain any spaces.
    • Linux : Extract the downloaded tar.gz file to the designated directory.

  3. Set Up the Environment:

    • Windows:

      • From an existing Command Prompt (CMD):
      <extracted_location>\oss-cad-suite\environment.bat
      • To create a new Command Prompt with the environment set:
      <extracted_location>\oss-cad-suite\start.bat

    • Linux:

      export PATH="<extracted_location>/oss-cad-suite/bin:$PATH"

      or

      source <extracted_location>/oss-cad-suite/environment

Once the environment is correctly set up, you will see [OSS CAD-Suite] before the terminal commands like this for WSL:

image

Like this for Linux:

image

Or like this for Windows: (ADD WINDOWS CMD PICTURE)

  1. Verify the Installation:

To check if the tools are installed correctly just take a look at some of the executables found in the OSS CAD Suite binaries and add the --version flag like this:

python --version
yosys --version
...

Running a Blinky Example

  1. Set the environment using the command as explained above.

  2. Navigate to the example directory:

    cd SDR-HLS/2.HLSImplementation/Examples/Blinky

  3. Run the example using:

    python3 Blinky.py

    If you do not see an error message stating that Python couldn't import Amaranth, then Amaranth is installed correctly.

  4. To build for a specific board, such as the ULX3S, run:

    python3 Blinky.py -b -p amaranth_boards.ulx3s.ULX3S_85F_Platform

Note: Different boards may require changes to some lines in the Blinky.py file or additional tools.

  1. To program the board, add the -dp flag:

    python3 Blinky.py -b -p amaranth_boards.ulx3s.ULX3S_85F_Platform -dp

  2. Use the -h flag to see all available options:

    python3 Blinky.py -h

Issues/Added Steps for Programming the Board

Zadig Installation and Setting the Drivers for Windows or WSL

If programming doesn't work, you may need to install a driver using Zadig.

  1. Download Zadig from this link.
  2. Connect your FPGA board directly to the USB port (do not use a USB hub).
  3. Open Zadig:
    • Select Options in the toolbar and select List All Devices.
    • Deselect Ignore Hubs or Composite Parents
    • Find your FPGA board in the list of devices.
    • Choose WinUSB as the driver (if that does not work, try libusb).
    • Click Replace Driver.
    • Wait for it to finish replacing the driver and exit Zadig

image

The picture above shows how the window should look like, where you replace the driver with WinUSB driver.

Programming the board through WSL

To program the board using WSL instead of a Linux OS directly on the computer, additional steps are needed:

  1. Install the usbipd tool:

    • Go to the latest release page for the usbipd-win project.
    • Select the .msi file and run the installer. NOTE: Run the installer in Windows.

  2. After installing usbipd, connect your board to the USB port. List all of the USB devices connected to Windows by opening PowerShell in administrator mode and entering the following command:

usbipd list

You should see output similar to:

<busid>  0403:6015  ULX3S FPGA 85K v3.0.8  Not Shared
  1. Share the device using the usbipd bind command:
usbipd bind --busid <busid>

Verify the device is shared:

usbipd list
  1. Attach the USB device in WSL:
usbipd attach --wsl --busid <busid>
  1. Open WSL and list the attached USB devices:
lsusb

You should see output like:

Bus 00y Device 00x: ID 0403:6015 Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)
  1. Change permissions for the USB device file:
sudo chmod 666 /dev/bus/usb/00x

Now you can program the board using openFPGALoader or another tool that can program that specific board.

Troubleshooting possible problems

If you are having problems with any of the tools from OSS CAD Suite, try deleting the binary executable from the OSS CAD Suite folder and installing the tool individually but while the environment is still set. The installing of some individual tools will be discussed in the next part.

Method 2: Installing all of the tools individually.

This method is more complex and time-consuming, but it offers the advantage of installing only the necessary tools on your PC. Additionally, this approach allows you to install the tools separately from the OSS CAD Suite binary distribution, which can be useful if certain tools are not functioning correctly and you want to try a different version.

Amaranth install

Detailed Amaranth Installation can be found here. If using other distributions take a look at the Installation guide.

Installing prerequisites

First off it is recommended to upgrade pip, which is a Python package installer tool with the following command:

  • For Windows:
 pip install --upgrade pip
  • For Linux:

If pip is not installed:

sudo apt-get install python3-pip

Before continuing, make sure you have the latest version of pip installed by running:

pip3 install --user --upgrade pip

Installing Amaranth

To install the latest version of Amaranth run the following command:

pip3 install --user 'amaranth[builtin-yosys] @ git+https://github.com/amaranth-lang/amaranth.git'

Installing Amaranth Boards

To be able to use Amaranth with a FPGA board, it is needed to have amaranth-boards installed with the following command:

pip3 install --user 'amaranth-boards @ git+https://github.com/amaranth-lang/amaranth-boards.git'

Open-Source FPGA Tools

Yosys installation

Yosys Installation Details can be found here.

Nextpnr installation

Nextpnr installation details can be found here.

Note: Different FPGA Vendors require also installation of added tools with nextpnr, read the installation carefully that is specific to the FPGA vendor you are using.

OpenFPGALoader installation

OpenFPGALoader can be installed following the instructions found here on the official github repository, it is very simple to install on Linux, but Windows is a bit more complex. Follow the steps done in this tutorial.

Commercial FPGA Tools

Setting up a commercial tool for a specific FPGA Vendor is the simple. You just need to download that specific tool and export its path accordingly, whether it be Windows or Linux, so that Amaranth can access the tool from the terminal(CMD or Linux terminal).

**Note: ** Amaranth needs to be installed individually, so before advancing do these steps.

Xilinx Vivado

Everything important about setting up Amaranth with Vivado is located here.

Vivado installation

Install Vivado from this link for your OS.

Running a Blinky example

Navigate to the Blinky folder:

cd SDR-HLS/2.HLSImplementation/Examples/Blinky

Run the example for one of the supported boards you can find in amaranth-boards using this command:

python3 Blinky.py -b -p amaranth_boards.arty_a7.ArtyA7_35Platform

This command runs synthesis and place and route using Xilinx Vivado. You can also use it with Xilinx ISE, Symbiflow and XRay Toolchain all explained in the Amaranth Xilinx platform section.

Interesting Amaranth Projects:

  • Litex: A flexible and open-source hardware description library for constructing and controlling FPGA SoCs. Useful for creating custom FPGA-based systems, including soft-core CPUs and peripherals.

  • CFU-Playground: A framework developed by Google to design, test, and optimize custom function units (CFUs) for TensorFlow Lite Micro. Aimed at enhancing machine learning model performance on FPGAs.

  • minerva-cpu: An open-source RISC-V CPU core written in Python using the Amaranth HDL (formerly nMigen). This project is intended for educational purposes and as a base for experimentation.

  • learn-fpga-amaranth: A repository focused on teaching FPGA programming using Amaranth HDL, covering a range of tutorials and example projects.

  • luna: A USB stack and hardware development framework for FPGAs, enabling the creation of custom USB peripherals and hosts. It is designed for high-performance and low-latency USB development.

  • icebreaker-amaranth-examples: Examples and demos using Amaranth HDL for the iCEBreaker FPGA development board, covering basic to advanced FPGA concepts.

  • amaranth-farm: A collection of libraries and reusable modules for Amaranth HDL, designed to extend its capabilities with various hardware blocks, peripherals, and utilities.

  • mtkcpu: A project that implements a CPU core and various peripherals, focusing on creating a system-level design using Amaranth HDL.

  • hexastorm: A project focused on FPGA-based hardware development, particularly in relation to digital signal processing (DSP) applications.

  • rv-thunder: A repository for a RISC-V-based project, which may include CPU cores, peripherals, and other hardware components.

  • amaranth-examples: A collection of examples demonstrating how to use Amaranth HDL for various digital designs, ranging from basic modules to more complex systems.

  • ECP5-PCIE: A repository providing a PCIe implementation targeting the ECP5 FPGA series, offering hardware and software tools for developing PCIe-enabled FPGA applications.

  • amranth-rfcs: The repository for Requests for Comments (RFCs) related to the Amaranth HDL, where community members propose and discuss changes or additions to the language.

  • dsp-sandbox: A collection of digital signal processing (DSP) projects and experiments using Amaranth HDL, aimed at exploring different DSP algorithms and architectures on FPGA platforms.

Clone this wiki locally