Getting started with Opensource FPGA tool-chain (APIO, Yosys and OSS-CAD)

In this article we will look into getting started with the open source FPGA Toolchain . Using the APIO and the ICEStrom Project .

Although these software works best in a Linux based distribution or a WSL but here we will be doing everything me windows (10) .

Step-0. Getting the system ready.

To get started with the tools chain the system should contain python 3.5 or above you can check the python version on your system using the command.

$ python --version

You should get a output like this .

If not you can downlode both python and pip on the system you can easily.

Step1. Getting the apio on system

Once our system is ready now we have to get apio on our system . This can be easily done using this command in windows terminal.

pip install -U apio 

This command will downlode the apio on your system the apio works as a manager for the all the project and tools we are going to use for our FPGA development.

Step2. Installing all the software ( Yosys, GTKwave ,nxtpnr)

The Fpga Development uses various tools along the path these are the needed onces

1. OSS CAD -Yosys ( Verification)
2. Gtkwave ( Simulation )
3. IceStrom

Till now if you haven't downloaded the terminal app I recommend you to do it because it would be very helpful in our journey. You can simply downlode it from windows store.

These software can be downloaded separately , but we will downlode the complete package using the command .

apio install --all

The apio will start downloading all the support files this might take some time depending on you network speed .

You can read the apio documentation on this doc page

/https://apiodoc.readthedocs.io/en/stable/source/quick_start.html

Once Downloaded you can check the version using this Command .

apio --version 

This is show the apio version present on the system .

These are all the various apio command we will use along the way .

$ apio
Usage: apio [OPTIONS] COMMAND [ARGS]...

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Project commands:
  build      Synthesize the bitstream.
  clean      Clean the previous generated files.
  lint       Lint the verilog code.
  sim        Launch the verilog simulation.
  time       Bitstream timing analysis.
  upload     Upload the bitstream to the FPGA.
  verify     Verify the verilog code.

Setup commands:
  drivers    Manage FPGA boards drivers.
  init       Manage apio projects.
  install    Install packages.
  uninstall  Uninstall packages.

Utility commands:
  boards     Manage FPGA boards.
  config     Apio configuration.
  examples   Manage verilog examples.
  raw        Execute commands using Apio packages.
  system     System tools.
  upgrade    Check the latest Apio version.

You can read about all these commands in details on The apio's Documentaion

After installing the apio and all the packages required to it we would enable the serial and ftdi drivers in our system we will need to open the windows cmd prompt in administrator mode .

And then run this commands.

apio drivers --ftdi-enable

The Zadig window will pop up .

Now we would have to connect our FPGA Dev Board to the PC (system) and them select it from dropdown. It will be listed as your boards and our as FTDI you can check the list before and after connecting the device to figure out the name .

After that you should should select the libusbk drivers and then press on replace drivers button.

Once you are done close the administrator prompt.

Till now if your board is supported by the apio project or not you can use this command to find out list off all supported board.

apio boards --list

You should get a list like this .

---

Step3. Creating our first project.

Now we will look into how to create our first project .

Now open or create the folder of your choice wherever you would like to save the projects in terminal you can use command chain to do so or you can go to desired location and then open in terminal.

once you do it would look like this . It will show your desired location.

One of the cool thing about the apio is that it comes with example for all the supported boards now we will use the inbuild example files on the apio project. Using this command we can list all the examples

apio examples -l

You should get a list like this .

Now we can use the example from the list for you particular board. For me its ULX3S- 12f .

So I will use the command to use the example you can modify it acording to you board.

apio examples -f ulx3s-12f\Blinky

If you example is successfully created you will see the output like this

This example file contains all the needed Verilog , Testbench , Simulation and the Constraints file .

Now after this we will have to do the basic steps

1. Verify the Verilog code using the command

apio verify 

If all your syntax are correct you will get the output like this Since this is a example there is a less (almost 0 ) chance of syntax error.

After verifying we would have to simulate the code for this our folder must contain a testbench file. We would use this command to simulate this will use Icarus veriog and GTKwave for this simulation we would be able to see the waveforms .

apio sim 

The next step is to build the bitstream for the project this can be done using the following command .

apio build

Now onces the bitstream is generated . We will upload this bitstream to our dev board for this first we would need to connect the board to our pc using this command and then run this command .

apio upload

In my case I got a error that the jtag was not recognized I solved it by updating the driver for the device manager .

If everything is going well you will get this output .

Congratulation you have successfully installed the opensource apio project and toolchain and created a example project . You can confirm the same by blinking led on the board .