Firmware Intellectual Property (IP) Node Specification (FINS) is an innovative software tool chain from Geon Technologies that defines a programmable logic processing module and automates the firmware design, verification, and integration workflows. The foundation of FINS is the definition of a modular IP (intellectual property) node with a human-readable JSON schema. The schema specification is the launching point for code generators to accelerate embedded systems development. Programmable logic development is automated for the following areas:

1. IP Build and Simulation Workflows. TCL and Makefile scripts generated by FINS automate the build and simulation of IP. IP modules can be built for compatibility with Xilinx Vivado IP Integrator or Intel Quartus Platform Designer which enables rapid insertion of IP in platform code and vendor reference designs.
2. Rapid Reconfiguration. FINS consolidates parameterization of IP into a single location and distributes these parameters across design tools with code generation of header-like package files.
3. Properties and Ports Interfaces. FINS generates HDL source code for a properties interface that enables repeatable software control of firmware and for a ports interface that standardizes firmware to firmware movement of data.

License

The license for FINS source code is LGPLv3.0, but code generated by FINS does not assume this license. Generated code can be explicitly defined as proprietary when setting the license_file key of the FINS JSON file.

Prerequisites

The software packages required to use FINS are:

• Xilinx Vivado (Tested with 2019.2) and/or Intel Quartus Prime Pro (Tested with 19.4)
• GNU Make
• Python 3.6 with setuptools 41.2.0
• Jinja2
• [Optional] GNU Octave and/or Mathworks MATLAB

Installation

Run the following commands from the root of this repository to install the FINS Python package:

NOTE: You may need to upgrade your version of pip and setuptools before installing FINS. To perform this upgrade, execute the command: sudo python3 -m pip install --upgrade pip setuptools.

# Install the FINS software and "core" generator
$ python3 -m pip install .
# Install the "vivado" generator plugin
$ python3 -m pip install ./vivado
# Install the "quartus" generator plugin
$ python3 -m pip install ./quartus

NOTE: You may not have permissions to run these python3 -m pip commands. To resolve this you can either use a python virtual environment, the --user option (python3 -m pip install --user), or sudo.

To uninstall FINS, run the following commands:

$ python3 -m pip uninstall fins fins-quartus fins-vivado

NOTE: Again, you may not have permissions to run these python3 -m pip commands. To resolve this you can either use a python virtual environment, the --user option, or sudo.

To verify your installation and run an example of a FINS Node, execute the following commands to build and simulate the test IP with Vivado:

NOTE: Make sure you have sourced the Xilinx "settings64.sh" script for the version of Vivado you are using. This test requires GNU Octave or Mathworks MATLAB.

# Enter the test IP directory
$ cd ./test/node/
# Run the fins executable to generate the Vivado backend
$ fins -b quartus fins.json
# Run the simulation in command line mode
$ make sim

The log files below contain the details of operations in the FINS execution process:

• ./test/node/log/ip_create.log: This log file contains the details of each step executed to build the "test_top" IP.
• ./test/node/log/ip_simulate.log: This log file contains the details of each step executed to simulate the "test_top" IP.

Learning FINS

A FINS "Node" is a single modular, resuable firmware Intellectual Property (IP). A Node serves as the foundation of FINS. See the link below for more information on development of a "Node".

• Node Development

To follow a tutorial on how to create a simple "power_converter" FINS Node, see the link below.

• Power Converter Tutorial

See the links below for detailed documentation on elements of a FINS Node.

• Node Parameters
• Node Properties
• Node Ports
• Node Filesets
• Node Sub-IP

There are two important FINS constructs used for integration: Applications and Systems. These are elaborated on in FINS Integration, but to get started follow the tutorial on how to create a simple "power_application" FINS Application.

• Power Converter Application Tutorial

Notes

Here are a few things to keep in mind when developing FINS IP:

• Xilinx's AXI Interconnect only supports 32bit data widths for AXI4-Lite, but Intel's AXI Interconnect supports both 32bit and 64bit data widths of the AXI4-Lite standard.
• Xilinx's AXI Interconnect creates slave AXI4-Lite byte-indexed buses, whereas Intel's AXI Interconnect creates slave AXI4-Lite word-indexed buses.
• FINS currently generates only VHDL for all HDL code. Verilog user code may require a translation layer of properties and ports records.
• When switching between vendors, you will need to change the part specified in the FINS Node JSON file. You may also find it convenient to specify a top-level FINS parameter to define the vendor that can be used in the HDL in "generate" statements.
• The "quartus" backend does not support a Verilog file as its top-level source file.
• No directory paths should have spaces. For example, /home/user/Documents/project 1/ is invalid.

The AXI4-Lite buses and AXI4-Stream buses used in the top-level source file have strict requirements for their signals used and their naming. Every bus must have both clock and reset with signal names aclk and aresetn, respectively. The naming conventions are listed below.

• AXI4-Lite: ["m" or "s"][OPTIONAL_DECIMAL_NUMBER]_axi_[OPTIONAL_BUS_NAME]_[SIGNAL_NAME]
• AXI4-Stream: ["m" or "s"][OPTIONAL_DECIMAL_NUMBER]_axis_[PORT_NAME]_[SIGNAL_NAME]

Contributing to FINS

To develop FINS templates or Python code, it is strongly recommended to use a virtual environment with an "editable" install:

$ python3 -m pip install virtualenv
$ python3 -m venv env
$ source env/bin/activate
$ python3 -m pip install -e .
$ python3 -m pip install -e ./vivado
$ python3 -m pip install -e ./quartus

Testing Changes to FINS

A few tests must be run through in order to validate changes to FINS. These tests cover FINS Nodes, Applications and Systems, and exercise both the Vivado and Quartus backends.

NOTE: These tests require both Octave and MATLAB. Make sure Quartus is in your $PATH environmental variable and the Vivado "settings64.sh" script is sourced!

Testing FINS Nodes

Test that FINS can successfully parse Node JSON, generate an IP and testbench, and simulate the result:

$ cd ./test/node/
$ fins -b vivado fins.json
$ make sim
$ make clean-all
$ fins -b quartus fins.json
$ make sim
$ make clean-all

Testing FINS Applications

Test that FINS can successfully parse Application JSON, instantiate Nodes in an Application, and generate and simulate a testbench:

$ cd ./test/application/
$ fins -b quartus application_test.json
$ make sim
$ make clean-all

NOTE: FINS Applications are not yet implemented in the Vivado backend.

Testing FINS Systems

Test that FINS can successfully parse a System JSON file:

$ cd ./test/system/
$ make
$ fins quartus_system.json

Additional Testing

Additional FINS Nodes and an Application live in tutorials/ and can be useful for testing.