Blueprint

The blueprint is a file containing a list of files required for a particular back end. This single file is the main method Orbit uses to communicate information to a target's process.

When the blueprint is created, it is saved to the local ip's target output directory.

Plans

The blueprint can be created in different formats, also called plans. A target can configure which plans to accept by specifying the plans field. A supported plan can be generated by Orbit from the build or test entry point by using the --plan command-line option.

The currently supported formats are:

You can check which plan was used for the current build during a target's execution process by reading the ORBIT_BLUEPRINT_PLAN environment variable that was set by Orbit during the planning stage.

Specifications

Each blueprint format may contain different information and store it in a different way. Refer to each specification to see exactly how the data is communicated through their blueprint.

Attributes that are consistent across all formats are the fileset, library, and filepath.

The fileset is the group name for the file pattern that matched the given rule's file.

The library is the hdl defined library for the ip which the given file at this particular step was found.

The filepath is the absolute file system path to the given rule's file.

Built-in Filesets

The following filesets are already recognized by Orbit and are used for identifying hdl source code:

Plan: tsv

The tsv plan use tab-separated values to list the ordered set of source files.

• Advantages:
  • Simple and easy to parse for backends
• Disadvantages:
  • Limited information is sent

The file is divided into a series of ordered entries, each separated by a newline character (\n). The list of entries is in topologically sorted order.

ENTRY
ENTRY
...

Each entry contains information about a source file. Every entry always has 3 components: a fileset, a library, and a filepath. Each component in an entry is separated by a tab character (\t).

FILESET	LIBRARY	FILEPATH

Example

The following text represents what a blueprint that is formatted with the tsv plan might look like:

PYMDL	lc3b	/Users/chase/projects/lc3b/sim/models/alu_tb.py
VHDL	lc3b	/Users/chase/projects/lc3b/rtl/const_pkg.vhd
VHDL	mmry	/Users/chase/.orbit/cache/mmry-1.0.0-aac9159285/src/ram.vhd
VHDL	lc3b	/Users/chase/projects/lc3b/rtl/alu.vhd
VHDL	lc3b	/Users/chase/projects/lc3b/sim/alu_tb.vhd

Plan: json

The json plan uses json to serialize the list of entries.

• Advantages:
  • Simple to parse with existing json parsing libraries

The file is serialized into a single list, with each item in the list considered an entry, which is a json dictionary. The list of entries is in topologically sorted order.

[
    ENTRY,
    ENTRY,
    ...
]

Each entry contains information about a source file. Every each entry always has the following fields: fileset, library, filepath, dependencies. The dependencies field contains the filepaths that the current entry directly depends on. If the entry does not depend on any other source files or the entry is from a custom fileset, then the field stores an empty list.

{
  "fileset": "string",
  "library": "string",
  "filepath": "string",
  "dependencies": [
    "string"
  ]
}

Example

The following text represents what a blueprint that is formatted with the json plan might look like:

[
  {
    "fileset": "PYMDL",
    "library": "lc3b",
    "filepath": "/Users/chase/projects/lc3b/sim/models/alu_tb.py",
    "dependencies": []
  },
  {
    "fileset": "VHDL",
    "library": "lc3b",
    "filepath": "/Users/chase/projects/lc3b/rtl/const_pkg.vhd",
    "dependencies": []
  },
  {
    "fileset": "VHDL",
    "library": "mmry",
    "filepath": "/Users/chase/.orbit/cache/mmry-1.0.0-aac9159285/src/ram.vhd",
    "dependencies": []
  },
  {   
    "fileset": "VHDL",
    "library": "lc3b",
    "filepath": "/Users/chase/projects/lc3b/rtl/alu.vhd",
    "dependencies": [
        "/Users/chase/projects/lc3b/rtl/const_pkg.vhd",
        "/Users/chase/.orbit/cache/mmry-1.0.0-aac9159285/src/ram.vhd"
    ]
  },
  {
    "fileset": "VHDL",
    "library": "lc3b",
    "filepath": "/Users/chase/projects/lc3b/sim/alu_tb.vhd",
    "dependencies": [
        "/Users/chase/projects/lc3b/rtl/alu.vhd"
    ]
  }
]