Skip to content

Files

Latest commit

 

History

History
75 lines (51 loc) · 7.12 KB

systems.md

File metadata and controls

75 lines (51 loc) · 7.12 KB

FINS Systems Development

Introduction

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.

Description

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.

Workflow

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:

  1. A unique and descriptive value for the name key.
  2. The parameters key contains constants that can be used elsewhere in the JSON file. The parameters schema is located here.
  3. The nodes key lists the IPs and Nodes which are being described by this System. See the Nodes JSON section for more information.
  4. 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.
  5. The properties_offset key is the offset for a particular node in the nodes array. It can be set manually or can be set to the filepath of the block design file to auto-infer the offset.
  6. The ports_consumer_name key is set for the element of the nodes array that consumes data from a processor through a DMA module. At most one element of the nodes array can have this key set.
  7. The ports_producer_name key is set for the element of the nodes array that produces data to a processor through a DMA module. At most one element of the nodes 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.

System JSON Schema

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.

System JSON Schema: Nodes

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.

RETURN TO TOP LEVEL README