CAPI2 Reference

CAPI2 (Core API version 2) describes the properties of a core as a YAML data structure.

Types

File

A File object represents a physical file. It can be a simple string, with the path to the file relative to the core root (e.g. path/to/file.v). It is also possible to assign attributes to a file, by using the file name as a dictionary key and the attributes as a map. (e.g. path/to/file.v : {is_include_file : true, file_type : systemVerilogSource}). Valid attributes are

Attribute

Type

Description

is_include_file

bool

Treats file as an include file when true

include_path

str

Explicitly set an include directory, relative to core root, instead of the directory containing the file

file_type

str

File type. Overrides the file_type set on the containing fileset

logical_name

str

Logical name, i.e. library for VHDL/SystemVerilog. Overrides the logical_name set on the containing fileset

Genparams

Genparams are private configuration for a generator. Normally specified as a map of key/value pairs

Provider

Specifies how to fetch the core. The presence of a provider section indicates this is a remote core that has its source code separated from the core description file.

String

String is an unparsed (plain) string.

StringWithUseFlags

StringWithUseFlags is a string that can contain CAPI2 expressions that are evaluated during parsing.

CAPI2 expressions are used to evaluate an expression only if a flag is set or unset. The general form is flag_is_set ? ( expression ) to evaluate expression if flag is set or !flag_is_set ? ( expression ) to evaluate expression if flag is not set.

Example Only include fileset verilator_tb when the target is used with verilator

filesets : [rtl, tb, tool_verilator? (verilator_tb)]

StringWithUseFlagsOrDict

Item is allowed to be either a StringWithUseFlags or a dict of StringWithUseFlags.

StringWithUseFlagsOrList

Item is allowed to be either a StringWithUseFlags or a list of StringWithUseFlags

Vlnv

:-separated VLNV (Vendor, Library, Name, Version) identifier

Dict

A dictionary.

Bool

A boolean.

Integer

An integer.

List

All keys that are defined as lists have a corresponding <key>_append key. The items in the <key>_append list is automatically appended to the list of the original key.

Example A target contains the following keys

filesets : [fileset_a, fileset_b]
filesets_append : [fileset_c, fileset_d]

This will be evaluated to

filesets : [fileset_a, fileset_b, fileset_c, fileset_d]

The main use case for this feature is inheritance between targets with yaml anchors as in the following example where a board-specific implementation and a simulation target inherits from the default target

targets:
  default: &base
    filesets: [core]

  myboard:
    <<: *base
    filesets_append: [myboard_files]

  sim:
    <<: *base
    filesets_append: [testbench]

Sections

The first table lists all valid keywords in the document root while the other tables are keywords for subsections of the tree

Root elements of the CAPI2 structure

Field Name

Type

Description

name

Vlnv

VLNV identifier for core

description

String

Short description of core

provider

Provider

Provider of core

CAPI=2

String

Technically a header. Must appear as the first line in the core description file

filesets

Dict of Fileset

File sets

generate

Dict of Generate

Parametrized generator configurations

generators

Dict of Generators

Generator provided by this core

scripts

Dict of Script

Scripts that are used by the hooks

targets

Dict of Target

Available targets

parameters

Dict of Parameter

Available parameters

vpi

Dict of Vpi

Available VPI modules

Fileset

A fileset represents a group of file with a common purpose. Each file in the fileset is required to have a file type and is allowed to have a logical_name which can be set for the whole fileset or individually for each file. A fileset can also have dependencies on other cores, specified in the depend section

Field Name

Type

Description

file_type

String

Default file_type for files in fileset

logical_name

String

Default logical_name (i.e. library) for files in fileset

files

List of File

Files in fileset

depend

List of StringWithUseFlags

Dependencies of fileset

Generate

The elements in this section each describe a parameterized instance of a generator. They specify which generator to invoke and any generator-specific parameters.

Field Name

Type

Description

generator

String

The generator to use. Note that the generator must be present in the dependencies of the core.

parameters

Genparams

Generator-specific parameters. fusesoc gen show $generator might show available parameters

position

String

Where to insert the generated core. Legal values are first, append or last. append will insert core after the core that called the generator

Generators

Generators are custom programs that generate FuseSoC cores. They are generally used during the build process, but can be used stand-alone too. This section allows a core to register a generator that can be used by other cores.

Field Name

Type

Description

command

String

The command to run (relative to the core root)

interpreter

String

If the command needs a custom interpreter (such as python) this will be inserted as the first argument before command when calling the generator. The interpreter needs to be on the system PATH.

description

String

Short description of the generator, as shown with fusesoc gen list

usage

String

A longer description of how to use the generator, including which parameters it uses (as shown with fusesoc gen show $generator).

Target

A target is the entry point to a core. It describes a single use-case and what resources that are needed from the core such as file sets, generators, parameters and specific tool options. A core can have multiple targets, e.g. for simulation, synthesis or when used as a dependency for another core. When a core is used, only a single target is active. The default target is a special target that is always used when the core is being used as a dependency for another core or when no --target= flag is set.

Field Name

Type

Description

default_tool

String

Default tool to use unless overridden with --tool=

description

String

Description of the target

hooks

Hooks

Script hooks to run when target is used

tools

Tools

Tool-specific options for target

toplevel

StringWithUseFlagsOrList

Top-level module. Normally a single module/entity but can be a list of several items

filesets

List of StringWithUseFlags

File sets to use in target

generate

List of StringWithUseFlagsOrDict

Parameterized generators to run for this target with optional parametrization

parameters

List of StringWithUseFlags

Parameters to use in target. The parameter default value can be set here with param=value

vpi

List of StringWithUseFlags

VPI modules to build and include for target

Tools

The valid subsections of the Tools section and their options are defined by what Edalize backends are available at runtime. The sections listed here are the ones that were available when the documentation was generated.

Field Name

Type

Description

ascentlint

Ascentlint

Ascentlint-specific options

diamond

Diamond

Diamond-specific options

ghdl

Ghdl

Ghdl-specific options

icarus

Icarus

Icarus-specific options

icestorm

Icestorm

Icestorm-specific options

ise

Ise

Ise-specific options

isim

Isim

Isim-specific options

modelsim

Modelsim

Modelsim-specific options

morty

Morty

Morty-specific options

quartus

Quartus

Quartus-specific options

radiant

Radiant

Radiant-specific options

rivierapro

Rivierapro

Rivierapro-specific options

spyglass

Spyglass

Spyglass-specific options

symbiflow

Symbiflow

Symbiflow-specific options

symbiyosys

Symbiyosys

Symbiyosys-specific options

trellis

Trellis

Trellis-specific options

vcs

Vcs

Vcs-specific options

veribleformat

Veribleformat

Veribleformat-specific options

veriblelint

Veriblelint

Veriblelint-specific options

verilator

Verilator

Verilator-specific options

vivado

Vivado

Vivado-specific options

vunit

Vunit

Vunit-specific options

xcelium

Xcelium

Xcelium-specific options

xsim

Xsim

Xsim-specific options

yosys

Yosys

Yosys-specific options

Hooks

Hooks are scripts that are run at different points in the build process. They are always launched from the work root

Field Name

Type

Description

pre_build

List of StringWithUseFlags

Scripts executed before the build phase

post_build

List of StringWithUseFlags

Scripts executed after the build phase

pre_run

List of StringWithUseFlags

Scrips executed before the run phase

post_run

List of StringWithUseFlags

Scripts executed after the run phase

Parameter

A parameter is a compile-time or run-time configuration of a core.

Field Name

Type

Description

datatype

String

Parameter datatype. Legal values are bool, file, int, str. file is same as str, but prefixed with the current directory that FuseSoC runs from

default

String

Default value

description

String

Description of the parameter, as can be seen with fusesoc run --target=$target $core --help

paramtype

StringWithUseFlags

Specifies type of parameter. Legal values are cmdlinearg for command-line arguments directly added when running the core, generic for VHDL generics, plusarg for verilog plusargs, vlogdefine for Verilog `` define` or vlogparam for verilog top-level parameters. All paramtypes are not valid for every backend. Consult the backend documentation for details.

scope

String

Not used : Kept for backwards compatibility

Script

A script specifies how to run an external command that is called by the hooks section together with the actual files needed to run the script. Scripts are alway executed from the work root

Field Name

Type

Description

env

Dict of String

Map of environment variables to set before launching the script

cmd

List of String

List of command-line arguments

filesets

List of String

Filesets needed to run the script

Vpi

A VPI (Verilog Procedural Interface) library is a shared object that is built and loaded by a simulator to provide extra Verilog system calls. This section describes what files and external libraries to use for building a VPI library

Field Name

Type

Description

libs

List of String

External libraries to link against

filesets

List of String

Filesets containing files to use when compiling the VPI library

Ascentlint

Real Intent Ascent Lint backend

Ascent Lint performs static source code analysis on HDL code and checks for common coding errors or coding style violations.

Field Name

Type

Description

ascentlint_options

List of String

Additional run options for ascentlint

Diamond

Backend for Lattice Diamond

Field Name

Type

Description

part

String

FPGA part number (e.g. LFE5U-45F-6BG381C)

Ghdl

GHDL is an open source VHDL simulator, which fully supports IEEE 1076-1987, IEEE 1076-1993, IEE 1076-2002 and partially the 1076-2008 version of VHDL

Field Name

Type

Description

analyze_options

List of String

Options to use for the import (ghdl -i) and make (ghdl -m) phases

run_options

List of String

Options to use for the run (ghdl -r) phase

Icarus

Icarus Verilog is a Verilog simulation and synthesis tool. It operates as a compiler, compiling source code written in Verilog (IEEE-1364) into some target format

Field Name

Type

Description

timescale

String

Default timescale

iverilog_options

List of String

Additional options for iverilog

Icestorm

Open source toolchain for Lattice iCE40 FPGAs. Uses yosys for synthesis and arachne-pnr or nextpnr for Place & Route

Field Name

Type

Description

pnr

String

Select Place & Route tool. Legal values are arachne for Arachne-PNR or next for nextpnr. Default is arachne

arch

String

Target architecture. Legal values are xilinx, ice40 and ecp5

output_format

String

Output file format. Legal values are json, edif, blif

yosys_as_subtool

bool

Determines if Yosys is run as a part of bigger toolchain, or as a standalone tool

makefile_name

String

Generated makefile name, defaults to $name.mk

script_name

String

Generated tcl script filename, defaults to $name.mk

arachne_pnr_options

List of String

Additional options for Arachnhe PNR

nextpnr_options

List of String

Additional options for nextpnr

yosys_synth_options

List of String

Additional options for the synth_ice40 command

Ise

Xilinx ISE Design Suite

Field Name

Type

Description

family

String

FPGA family (e.g. spartan6)

device

String

FPGA device (e.g. xc6slx45)

package

String

FPGA package (e.g. csg324)

speed

String

FPGA speed grade (e.g. -2)

Isim

Xilinx ISim simulator from ISE design suite

Field Name

Type

Description

fuse_options

List of String

Additional options for compilation with FUSE

isim_options

List of String

Additional run options for ISim

Modelsim

ModelSim simulator from Mentor Graphics

Field Name

Type

Description

vcom_options

List of String

Additional options for compilation with vcom

vlog_options

List of String

Additional options for compilation with vlog

vsim_options

List of String

Additional run options for vsim

Morty

Run the (System-) Verilog pickle tool called morty.

Field Name

Type

Description

morty_options

List of String

Run-time options passed to morty.

Quartus

The Quartus backend supports Intel Quartus Std and Pro editions to build systems and program the FPGA

Field Name

Type

Description

family

String

FPGA family (e.g. Cyclone V)

device

String

FPGA device (e.g. 5CSXFC6D6F31C8ES)

cable

String

Specifies the FPGA’s JTAG programming cable. Use the tool jtagconfig to determine the available cables.

board_device_index

String

Specifies the FPGA’s device number in the JTAG chain. The device index specifies the device where the flash programmer looks for the Nios® II JTAG debug module. JTAG devices are numbered relative to the JTAG chain, starting at 1. Use the tool jtagconfig to determine the index.

pnr

String

P&R tool. Allowed values are quartus (default), dse (to run Design Space Explorer) and none (to just run synthesis)

dse_options

List of String

Options for DSE (Design Space Explorer)

quartus_options

List of String

Additional options for Quartus

Radiant

Backend for Lattice Radiant

Field Name

Type

Description

part

String

FPGA part number (e.g. LIFCL-40-9BG400C)

Rivierapro

Riviera Pro simulator from Aldec

Field Name

Type

Description

compilation_mode

String

Common or separate compilation, sep - for separate compilation, common - for common compilation

vlog_options

List of String

Additional options for compilation with vlog

vsim_options

List of String

Additional run options for vsim

Spyglass

Synopsys (formerly Atrenta) Spyglass Backend

Spyglass performs static source code analysis on HDL code and checks for common coding errors or coding style violations.

Example snippet of a CAPI2 description file

spyglass:
  methodology: "GuideWare/latest/block/rtl_handoff"
  goals:
    - lint/lint_rtl
  spyglass_options:
    # prevent error SYNTH_5273 on generic RAM descriptions
    - handlememory yes
  rule_parameters:
    # Allow localparam to be used in case labels (e.g. in state machines)
    - handle_static_caselabels yes

Field Name

Type

Description

methodology

String

goals

List of String

spyglass_options

List of String

rule_parameters

List of String

Symbiflow

The Symbiflow backend executes Yosys sythesis tool and VPR place and route. It can target multiple different FPGA vendors

Field Name

Type

Description

package

String

FPGA chip package (e.g. clg400-1)

part

String

FPGA part type (e.g. xc7a50t)

vendor

String

Target architecture. Currently only “xilinx” is supported

pnr

String

Place and Route tool. Currently only “vpr” is supported

vpr_options

String

Additional vpr tool options. If not used, default options for the tool will be used

environment_script

String

Optional bash script that will be sourced before each build step.

Symbiyosys

SymbiYosys formal verification wrapper for Yosys

Field Name

Type

Description

tasknames

List of String

A list of the .sby file’s tasks to run. Passed on the sby command line.

Trellis

Project Trellis enables a fully open-source flow for ECP5 FPGAs using Yosys for Verilog synthesis and nextpnr for place and route

Field Name

Type

Description

arch

String

Target architecture. Legal values are xilinx, ice40 and ecp5

output_format

String

Output file format. Legal values are json, edif, blif

yosys_as_subtool

bool

Determines if Yosys is run as a part of bigger toolchain, or as a standalone tool

makefile_name

String

Generated makefile name, defaults to $name.mk

script_name

String

Generated tcl script filename, defaults to $name.mk

nextpnr_options

List of String

Additional options for nextpnr

yosys_synth_options

List of String

Additional options for the synth_ecp5 command

Vcs

Synopsys VCS Backend

VCS is one of the “Big 3” simulators.

Example snippet of a CAPI2 description file for VCS:

vcs:
  vcs_options:
    # Compile-time options passed to the vcs command
    - -debug_access+pp
    - -debug_access+all
  run_options:
    # Run-time options passed to the simulation itself
    - -licqueue

Field Name

Type

Description

vcs_options

List of String

run_options

List of String

Veribleformat

Verible format backend (verible-verilog-format)

Field Name

Type

Description

verible_format_args

List of String

Extra command line arguments passed to the Verible tool

Veriblelint

Verible lint backend (verible-verilog-lint)

Field Name

Type

Description

ruleset

String

Ruleset: [default|all|none]

verible_lint_args

List of String

Extra command line arguments passed to the Verible tool

rules

List of String

What rules to use. Prefix a rule name with “-” to disable it.

Verilator

Verilator is the fastest free Verilog HDL simulator, and outperforms most commercial simulators

Field Name

Type

Description

mode

String

Select compilation mode. Legal values are cc for C++ testbenches, sc for SystemC testbenches or lint-only to only perform linting on the Verilog code

cli_parser

String

Deprecated: Use run_options instead : Select whether FuseSoC should handle command-line arguments (managed) or if they should be passed directly to the verilated model (raw). Default is managed

libs

List of String

Extra libraries for the verilated model to link against

verilator_options

List of String

Additional options for verilator

make_options

List of String

Additional arguments passed to make when compiling the simulation. This is commonly used to set OPT/OPT_FAST/OPT_SLOW.

run_options

List of String

Additional arguments directly passed to the verilated model

Vivado

The Vivado backend executes Xilinx Vivado to build systems and program the FPGA

Field Name

Type

Description

vivado-settings

String

Path to vivado settings (e.g. /opt/Xilinx/Vivado/2017.2/settings64.sh)

part

String

FPGA part number (e.g. xc7a35tcsg324-1)

synth

String

Synthesis tool. Allowed values are vivado (default) and yosys.

pnr

String

P&R tool. Allowed values are vivado (default) and none (to just run synthesis)

jtag_freq

Integer

The frequency for jtag communication

hw_target

`Description`_

Board identifier (e.g. */xilinx_tcf/Digilent/123456789123A

Vunit

VUnit testing framework

Field Name

Type

Description

vunit_runner

String

Name of the Python file exporting a “VUnitRunner” class that is used to configure and execute test

add_libraries

List of String

A list of framework libraries to add. Allowed values include “array_util”, “com”, “json4hdl”, “osvvm”, “random”, “verification_components”

vunit_options

List of String

Options to pass to the VUnit test runner

Xcelium

Xcelium simulator from Cadence Design Systems

Field Name

Type

Description

xmvhdl_options

List of String

Additional options for compilation with xmvhdl

xmvlog_options

List of String

Additional options for compilation with xmvlog

xmsim_options

List of String

Additional run options for xmsim

xrun_options

List of String

Additional run options for xrun

Xsim

XSim simulator from the Xilinx Vivado suite

Field Name

Type

Description

xelab_options

List of String

Additional options for compilation with xelab

xsim_options

List of String

Additional run options for XSim

Yosys

Open source synthesis tool targeting many different FPGAs

Field Name

Type

Description

arch

String

Target architecture. Legal values are xilinx, ice40 and ecp5

output_format

String

Output file format. Legal values are json, edif, blif

yosys_as_subtool

bool

Determines if Yosys is run as a part of bigger toolchain, or as a standalone tool

makefile_name

String

Generated makefile name, defaults to $name.mk

script_name

String

Generated tcl script filename, defaults to $name.mk

yosys_synth_options

List of String

Additional options for the synth command