The FINS System JSON is used to aggregate the Node information so that the FINS software package may control properties and communicate with ports in the programmable logic build.
Illustrating the FINS System construct, the diagram below depicts a programmable logic block design that gets built into a bitstream. A System is used to describe the design in its entirety. The labeled information is required for software control and data communication with a processor, and this information is defined in the FINS System JSON Schema.
Systems are used to describe and expose the contents of an existing programmable-logic design to enable software communication to properties and ports. In particular, a System generally describes the contents of an programmable-logic block design or HDL design. The block design tool is IP Integrator for Xilinx Vivado and Platform Designer for Intel Quartus. Reference the Intel and Xilinx user guides for the step-by-step details of creating new block designs.
More explicitly, FINS Systems tell software what address offsets to use for each IP/Node in the programmable-logic design. Additionally, they inform software as to which ports in the design communicate data to/from the processor via DMA. The important file generated by FINS for a System is ./gen/core/nodeset.json. This generated JSON file is used by FINS Software to ascertain important information about the contents of a bitstream.
NOTE: FINS does not generate HDL nor a block design for a FINS System, only for an Application.
The first step in developing a FINS System is to integrate any Application code with a "Platform". A Platform is a set of HDL code or a block design that is responsible for interacting with the hardware interfaces on the target circuit board. Platforms are often provided by the vendors as reference designs or I/O wrappers. A robust Platform has standard interfaces to interact with Application modules.
Once you have a bitstream that integrates Application content with a Platform, you are ready to develop a FINS System JSON file. The details of the FINS System JSON schema are in the section below.
To get started developing a FINS System, create a JSON file with the following:
- A unique and descriptive value for the
name
key. - The
parameters
key contains constants that can be used elsewhere in the JSON file. Theparameters
schema is located here. - The
nodes
key lists the IPs and Nodes which are being described by this System. See the Nodes JSON section for more information. - The
base_offset
key is the global offset for the bus that controls the AXI4-Lite Properties interface. For many architectures this is 0, but some specify this base address at the bus level. - The
properties_offset
key is the offset for a particular node in thenodes
array. It can be set manually or can be set to the filepath of the block design file to auto-infer the offset. - The
ports_consumer_name
key is set for the element of thenodes
array that consumes data from a processor through a DMA module. At most one element of thenodes
array can have this key set. - The
ports_producer_name
key is set for the element of thenodes
array that produces data to a processor through a DMA module. At most one element of thenodes
array can have this key set.
The fins
executable is used with the FINS System to run code generation. The standard "core" backend location is ./gen/core/. The fins
executable automatically detects differences in FINS System schemas. To generate the FINS System, execute the following commands:
NOTE: This example assumes your FINS System JSON file is called system.json.
$ fins system.json
The generated ./gen/core/nodeset.json file should be copied to the target hardware host with the filepath /etc/fins/nodeset.json. This filepath is the default location that the FINS Software package uses for a System that describes the programmable logic bitstream.
The JSON schema for a FINS System is composed of the following top-level fields:
Key | Type | Required | Default Value | Description |
---|---|---|---|---|
name | string | YES | The name of the System | |
description | string | NO | The description of the System | |
version | string | NO | 1.0 | The version of the System |
company_name | string | NO | The name of the company which created the System | |
company_url | string | NO | user.org | The base URL of the company which created the System. Quartus uses this field as the AUTHOR. |
license_file | string | NO | The relative filepath of the license file containing the string to be inserted in all files generated by FINS. | |
base_offset | uint | YES | 0 | The base address offset of the bus used to communicate with the FINS nodes. |
params | dict[] | NO | An array of parameter definitions. See the parameters documentation here. | |
nodes | dict[] | YES | A dictionary array that contains a description of each node. See Nodes JSON section. |
An example of a FINS System JSON file can be found here.
Each dictionary element of the nodes
array has the following fields:
Key | Type | Mode | Required | Default Value | Description |
---|---|---|---|---|---|
fins_path | string | BOTH | YES | The path to the generated FINS Node JSON file of the IP node. | |
module_name | string | BOTH | YES | The name of this module when instantiated in the Block Design. | |
interface_name | string | BOTH | NO | If properties_offset is a dictionary, this field is used to infer the offset. The name of the AXI4-Lite bus interface used to control and status the properties. |
|
properties_offset | uint -OR- string | SYS | YES | The base offset of the address region used to access this node. If a string type, this field is a path to the block design in which the decode of the properties interface is located. This path must end in .qsys for Intel Platform Designer or .bd for Vivado IP Integrator, and it used to infer the offset. |
|
ports_producer_name | string | SYS | NO | The name of the AXI4-Stream bus interface that sends data to the processor through a DMA module. | |
ports_consumer_name | string | SYS | NO | The name of the AXI4-Stream bus interface that receives data from the processor through a DMA module. |