Apio quick start

In this page we will go through the steps of creating, validating, and uploading an design to an FPAG board. We will use the Alhambra-ii FPGA board but the process would be the same for all supported boards.

---

Step 1: Installing Apio.

The first step of using Apio is installing it. You can use either Python based installation or Standalone installation. When done, continue to step 2 below.

---

Step 2: Creating an Apio project

Let's make an empty directory and populate it with the example alhambra-ii/getting-started.

For more information about apio examples type apio examples -h.

# Make an empty project directory
$ mkdir project
$ cd project

# Fetch example files
project$ apio examples fetch alhambra-ii/getting-started

# List the project files
project$ tree .
.
├── apio.ini
├── main_tb.gtkw
├── main_tb.v
├── main.v
└── pinout.pcf

The files in this Apio project are:

Name	Description
apio.ini	The Apio project file.
main.v	Verilog source code.
pinout.pcf	ICE40 pin assignments.
main_tb.v	A verilog testbench for testing main.v
main_tb.gtkw	Saved GTKWAVE configuration for simulating main_tb.v.

---

Step 3: [Optional] Verifying the source code

To verify the source code with use two commands apio lint and apio build. The first scans the code for various errors and 'nitpicking' the second actually building it.

For more information about the commands type apio lint -h and apio build -h.

project$ apio lint

project$ apio build

If you encounter any problem with the code fix it and repeat.

---

Step 4: [Optional] Simulating the design

To simulate the design we use the command apio sim which runs a simulation of the testbench and shows its results in a graphical GTKWAVE windows. The main_tb.gtkwcontains the GTKWAVE configuration and you want to save it each time you make changes in GTKWAVE that you want to keep.

For more information about apio sim type `apio sim -h``.

project$ apio sim

---

Step 5: [Optional] Running tests

The command apio test run all the testbenches it finds in the project in a batch mode without graphical view like apio sim. The command fails if any of the testbenches has an error or exists with the $fatal function, typically due to a failing assertion.

For more information about apio test type apio test -h.

project$ apio test

Testbench main_tb.v
...
main_tb.v:45: $finish called at 966000 (1ps)

---

Step 6: Programming the FPGA board

In this step we build the project if needed and upload it to the FPGA board. With some systems and board this require driver installation using the apio drivers install command while other work out of the box. To test if the board is accessible we will try to list it with the apio devices command and since Alhambra-ii uses plain USB rather than a serial port, we will try to list it using the command apio devices usb.

project$ apio devices usb

USB Devices                                                                      
┌───────────┬─────────┬──────────────┬───────────────────┬────────────┬─────────┐
│ VID:PID   │ BUS:DEV │ MANUFACTURER │ DESCRIPTION       │ SERIAL-NUM │ TYPE    │
├───────────┼─────────┼──────────────┼───────────────────┼────────────┼─────────┤
│ 0403:6010 │   0:3   │ AlhambraBits │ Alhambra II v1.0A │            │ FT2232H │
└───────────┴─────────┴──────────────┴───────────────────┴────────────┴─────────┘
Found 1 USB device

We are in luck, the device's manufacturer and description string are listed correctly which means that the device is accessible to Apio and doesn't require an additional driver. We are ready to program the FPGA.

project$ apio upload
...
Selecting USB device:
- FILTER [VID=0403, PID=6010, REGEX="^Alhambra II.*"]
- DEVICE [0403:6010, 0:3], [AlhambraBits] [Alhambra II v1.0A] []
...
Erasing: [==================================================] 100.00%
Writing: [==================================================] 100.00%
Read flash : [==================================================] 100.00%

Done

The example now runs on the FPGA board and two LEDs should be flashing alternatively.

---

This concludes the Apio quick start guide. We suggest to review the documentation on the sidebar and watch the tutorial videos in the Video tutorial section.