Commands notes

NOTE: this page is for ADVANCED USERS

Index

• clean
• verify
• sim
• build
• time
• upload

clean

Remove the previous generated files. It does not depend on apio.ini file.

Testing

$ apio clean
Using default SConstruct file
Executing: scons -Q -c -f /path/to/SConstruct
Removed hardware.blif
Removed hardware.asc
Removed hardware.bin
Removed hardware.out

verify

Verify the verilog code. It does not depend on apio.ini file.

Testing

$ apio verify
Using default SConstruct file
Executing: scons -Q verify -f /path/to/SConstruct
iverilog -B /path/to/lib/ivl -o hardware.out /path/to/vlib/system.v leds.v

sim

Launch verilog simulation. It does not depend on apio.ini file.

Testing

$ apio sim
Using default SConstruct file
Executing: scons -Q sim -f /path/to/SConstruct
gtkwave leds_tb.vcd leds_tb.gtkw

GTKWave Analyzer v3.3.66 (w)1999-2015 BSI

[0] start time.
[1000] end time.
WM Destroy

build

Synthesize the bitstream. It depends on apio.ini file.

Arguments

• board: icestick, icezum, go-board, ...
• fpga (advanced): iCE40-HX1K-TQ144, iCE40-HX1K-VQ100, ...
• size (advanced): 1k, 8k
• type (advanced): lp, hx
• pack (advanced): tq144, vq100, ...

board > fpga > size, type, pack

Full arguments list

Testing

No arguments

If no arguments are provided it will use apio.ini board if exists.

$ apio build
Info: use apio.ini board: icezum
Using default SConstruct file
[...] Processing icezum
--------------------------------------------------------------------------------
Executing: scons -Q build fpga_type=hx fpga_pack=tq144 fpga_size=1k
-f /path/to/SConstruct
FPGA_SIZE: 1k
FPGA_TYPE: hx
FPGA_PACK: tq144
...

Otherwise it will throw an error message.

$ apio build
Info: No apio.ini file
Error: insufficient arguments: missing board
You have two options:
  1) Execute your command with
       `--board <boardname>`
  2) Create an ini file using
       `apio init --board <boardname>`

If any argument is provided apio.ini file will be ignored if exists.

Correct arguments

Command executed.

$ apio build --board icestick
Using default SConstruct file
[...] Processing icestick
--------------------------------------------------------------------------------
Executing: scons -Q build fpga_type=hx fpga_pack=tq144 fpga_size=1k
-f /path/to/SConstruct
FPGA_SIZE: 1k
FPGA_TYPE: hx
FPGA_PACK: tq144
...

$ apio build --fpga iCE40-HX1K-VQ100
Using default SConstruct file
[...] Processing custom board
--------------------------------------------------------------------------------
Executing: scons -Q build fpga_type=hx fpga_pack=vq100 fpga_size=1k
-f /path/to/SConstruct
FPGA_SIZE: 1k
FPGA_TYPE: hx
FPGA_PACK: vq100
...

$ apio build --type lp --size 8k --pack cm225:4k
Using default SConstruct file
[...] Processing custom board
--------------------------------------------------------------------------------
Executing: scons -Q build fpga_type=lp fpga_pack=cm225:4k fpga_size=8k
-f /path/to/SConstruct
FPGA_SIZE: 8k
FPGA_TYPE: lp
FPGA_PACK: cm225:4k
...

Redundant arguments

Command executed with a warning message.

$ apio build --board icezum --size 1k
Warning: redundant arguments: size
Using default SConstruct file
[...] Processing icezum
--------------------------------------------------------------------------------
Executing: scons -Q build fpga_type=hx fpga_pack=tq144 fpga_size=1k
-f /path/to/SConstruct
FPGA_SIZE: 1k
FPGA_TYPE: hx
FPGA_PACK: tq144
...

$ apio build --board icezum --fpga iCE40-HX1K-TQ144 --type hx
Warning: redundant arguments: fpga, type
Using default SConstruct file
[Fri Aug 19 11:37:30 2016] Processing icezum
--------------------------------------------------------------------------------
Executing: scons -Q build fpga_type=hx fpga_pack=tq144 fpga_size=1k
-f /path/to/SConstruct
FPGA_SIZE: 1k
FPGA_TYPE: hx
FPGA_PACK: tq144
...

$ apio build --fpga iCE40-HX1K-TQ144 --pack tq144
Warning: redundant arguments: pack
Using default SConstruct file
[...] Processing custom board
--------------------------------------------------------------------------------
Executing: scons -Q build fpga_type=hx fpga_pack=tq144 fpga_size=1k
-f /path/to/SConstruct
FPGA_SIZE: 1k
FPGA_TYPE: hx
FPGA_PACK: tq144
...

Contradictory arguments

Command not executed. Print an error message.

$ apio build --board icezum --size 8k
Error: contradictory arguments: size

$ apio build --board icezum --fpga iCE40-HX1K-TQ144 --type lp
Warning: redundant arguments: fpga
Error: contradictory arguments: type

$ apio build --fpga iCE40-HX1K-TQ144 --type lp --size 8k
Error: contradictory arguments: type, size

Insufficient arguments

Command not executed. Print an error message.

$ apio build --size 8k
Error: insufficient arguments: missing type, pack

$ apio build --type lp --size 8k
Error: insufficient arguments: missing pack

Unknown board

Command not executed. Print an error message.

$ apio build --board icefake
Error: unknown board: icefake

$ apio build --board icefake --fpga iCE40-HX1K-TQ144
Error: unknown board: icefake

Unknown fpga

Command not executed. Print an error message.

$ apio build --fpga iCE40-FAKE
Error: unknown fpga: iCE40-FAKE

$ apio build --fpga iCE40-FAKE --size 8k
Error: unknown fpga: iCE40-FAKE

$ apio build --board icezum --fpga iCE40-FAKE
Error: unknown fpga: iCE40-FAKE

time

Bitstream timing analysis. Same arguments and behavior that build.

Testing

$ apio time --board icezum
Using default SConstruct file
[...] Processing icezum
--------------------------------------------------------------------------------
Executing: scons -Q time fpga_type=hx fpga_pack=tq144 fpga_size=1k
-f /path/to/SConstruct
FPGA_SIZE: 1k
FPGA_TYPE: hx
FPGA_PACK: tq144
...

upload

Upload bitstream to FPGA. Same arguments and behavior that build + device <int> argument.

Testing

Board not connected

If the correct board is not connected an error message will be thrown.

Nothing connected:

$ apio upload --device 0 --board icezum
Number of FTDI devices found: 0
Error: board not detected

Icezum connected:

$ apio upload --device 0 --board icestick
Number of FTDI devices found: 1
Checking device: 0
Manufacturer: bqlabs, Description: IceZUM Alhambra - 5 (bqlabs)

Error: board not detected

Icestick connected:

$ apio upload --device 1 --board icestick
Number of FTDI devices found: 1
Checking device: 0
Manufacturer: Lattice, Description: Lattice FTUSB Interface Cable

Error: board not detected

No arguments

If no arguments are provided it will use apio.ini board if exists.

$ apio upload
Info: use apio.ini board: icezum
Number of FTDI devices found: 1
Checking device: 0
Manufacturer: bqlabs, Description: IceZUM Alhambra - 5 (bqlabs)

Using default SConstruct file
[...] Processing icezum
--------------------------------------------------------------------------------
Executing: scons -Q upload fpga_type=hx fpga_pack=tq144 fpga_size=1k device=0
-f /path/to/SConstruct
FPGA_SIZE: 1k
FPGA_TYPE: hx
FPGA_PACK: tq144
DEVICE: 0
iceprog -d i:0x0403:0x6010:0 hardware.bin
...

Otherwise it will throw an error message.

$ apio upload
Info: No apio.ini file
Error: insufficient arguments: missing board
You have two options:
  1) Execute your command with
       `--board <boardname>`
  2) Create an ini file using
       `apio init --board <boardname>`

If any argument is provided apio.ini file will be ignored if exists.

If device argument is not provided the first compatible found board will be automatically selected.

If device argument is provided it will try to upload the bitstream to this device id. Also, if board information is provided, using --board or apio.ini, a FTDI validation will be done.

Note:

build and unpload commands must have the same arguments to ensure the desired behavior.