¶

Note

NOTE: This documentation is for Apio 1.0.0 and later. For documentation of Apio 0.9.5 and older please see https://github.com/FPGAwars/apio/wiki

Apio is an easy-to-install and easy-to-use open-source toolbox that simplifies FPGA development. It provides simple commands such as:

apio lint – to verify the code
apio sim – to simulate the design
apio upload – to build the design and program the FPGA board

Apio runs on macOS, Linux, and Windows, and currently supports:

3 FPGA architectures
70+ FPGAs
70+ FPGA boards

…and the list continues to grow.

This page offers a showcase of some of Apio's features, detailed further in the sidebar sections. After reviewing this introduction, we recommend starting with the Quick start section.

The examples here use the Alhambra-II FPGA board, though other supported boards should work similarly.

Some logs in the examples below have been truncated for clarity.

Apio project examples¶

Currently there are 60+ project examples that are included with Apio. To list them, run the following command:

$ apio examples

Apio Examples
┌──────────────────────────────┬───────┬───────────────────────┐
│ BOARD/EXAMPLE                │ ARCH  │ DESCRIPTION           │
├──────────────────────────────┼───────┼───────────────────────┤
...
│ alhambra-ii/bcd-counter      │ ice40 │ Verilog example...    │
│ alhambra-ii/blinky           │ ice40 │ Blinking led          │
│ alhambra-ii/getting-started  │ ice40 │ Example for Apio...   │
│ alhambra-ii/ledon            │ ice40 │ Turning on a led      │
...
└──────────────────────────────┴───────┴───────────────────────┘
Total of 63 examples

Let's fetch the getting-started example of the alhambra-ii board.

$ mkdir example
$ cd example

# Fetch the example's files.
example$ apio examples fetch alhambra-ii/getting-started

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

Now let's build the example and program our Alhambra-II FPGA board.

example$ apio upload

And Voilà! - the design is now running on the FPGA board.

Analyzing utilization and speed.¶

To check how many FPGA resources the design uses and how fast it can run, use the apio report command

example$ apio report

FPGA Resource Utilization
┌────────────────┬────────┬──────────┬─────────┐
│  RESOURCE      │  USED  │   TOTAL  │  UTIL.  │
├────────────────┼────────┼──────────┼─────────┤
│  ICESTORM_LC   │    69  │    7680  │     0%  │
│  ICESTORM_PLL  │        │       2  │         │
│  ICESTORM_RAM  │        │      32  │         │
│  SB_GB         │     2  │       8  │    25%  │
│  SB_IO         │     3  │     256  │     1%  │
│  SB_WARMBOOT   │        │       1  │         │
└────────────────┴────────┴──────────┴─────────┘

Clock Information
┌─────────┬───────────────────┐
│  CLOCK  │  MAX SPEED [Mhz]  │
├─────────┼───────────────────┤
│  CLK    │           101.93  │
└─────────┴───────────────────┘

Formatting the source code¶

Formatting the source code is as simple as running the apio format command.

work2$ apio format

Using env default (alhambra-ii)
Formatting main.v
Formatting main_tb.v
Processed 2 files.

Verifying the source code¶

The command apio lint performs 'nitpicking' verification of the code and reports any issues it finds, like the one we intentionally created for this example.

work2$ apio lint
...
Testbench main_tb.v
...
%Warning-NULLPORT: main.v:8:1: Null port on module (perhaps extraneous comma)
    8 | );
      | ^
                   ... For warning description see https://verilator.org/warn/NULLPORT?v=5.037
                   ... Use "/* verilator lint_off NULLPORT */" and lint_on around source to disable this message.

Simulating the design¶

The command apio sim runs a simulation of a selected testbench and shows its result in an interactive graphical window.

work$ apio sim main_tb.v

Testing the design¶

The command apio test simulates all the testbenches in batch mode and fails if any assertions fail with a call to $fatal.

work2$ apio test
...
vvp _build/default/main_tb.out -dumpfile=_build/default/main_tb.vcd
VCD info: dumpfile _build/default/main_tb.vcd opened for output.
main_tb.v:47: $finish called at 966000 (1ps)

Commands help¶

Every apio command accepts the --help or -h flag, which prints a short description of the command. When a command has multiple levels, the help flag can be used at any level, for example: apio -h, apio examples -h, and apio examples list -h.

$ apio clean -h
Usage: apio clean [OPTIONS]

  The command 'apio clean' removes all the output files previously
  generated by apio commands.

  Example:
    apio clean

Options:
  -p, --project-dir path  Set the root directory for the project.
  -h, --help              Show this message and exit.

This concludes Apio's overview. We suggest continuing to the Quick Start guide or jump to the Installation or