The Book of Orbit

Archive

The archive is a location in the catalog where compressed snapshots of a specific ip's version exist. The compressed ip files are unable to be referenced as dependencies, but they are able to be installed to the cache for usage. The ip's in the archvie are considered downloaded.

Blueprint

A blueprint is a single file that lists all the required source files and auxiliary files for the build process of a particular target. The source files are listed in topologically-sorted order. The blueprint is generated by Orbit during the planning stage of the build process, and the blueprint is typically used as input to the execution stage of the build process.

A blueprint can store the information collected from the planning stage in different file formats, called plans. The default plan is tab-separated values (TSV).

Cache

The cache is a location in the catalog where where immutable references to a specific ip's version exist. An ip's dependencies are referenced from the cache. The ip that are found at the cache level are considered installed.

Catalog

The catalog is the user's entire space of currently known ip to Orbit. It consists of 3 main levels: cache, archive, and channels. The cache stores the most details of an ip, while the channels store the least details of an ip.

Channels

The channels are a set of decentralized registries that store the manifests for versions of ip. In other words, a channel is simply a directory that stores the "Orbit.toml" files for published ips. No source code is stored in a channel, however, Orbit is able to use the manifest as a means to download that ip to the archive for local filesystem access. The ip that are found at the channels level are considered available. Users must configure their own channels as their are no default channels.

Configuration

A configuration is a collection of user-defined settings intended to extend and modify Orbit's functionality. Among these settings may include user-defined targets, protocols, and channels. Configurations are stored in files called "config.toml" and have varying precedence depending on where they are processed relative to the local ip.

Fileset

A fileset is a collection of related files under a given name. A glob-style file pattern is used to discover the files of a given fileset. Filesets are used to group common files together into the blueprint during the planning stage of the build process. Orbit comes with built-in filesets for VHDL, Verilog, and SystemVerilog files. In addition, a target can configure its own custom filesets.

Intellectual Property (IP)

An ip is a project with a manifest file at its root directory. At a minimum, an ip has two attributes: a name and a uuid. The name is a human-friendly identifier for the ip, while the uuid is a machine-friendly identifier for the ip used to help reduce ambiguity when potentially introducing ips of the same name into the catalog.

Ip Specification (spec)

The ip specification, or spec, describes the format for identifying and referencing an ip. Each ip in the user's catalog must have a unique spec. The format of a ip's spec is: <name>[+<uuid>][:<version>].

Local Ip

The local ip, which also may be referred to as the current ip, is the ip detected from the current working directory on the command-line. Some commands can only be executed from the local ip, such as orbit lock and orbit build.

Lockfile

A lockfile is a file that precisely describes an ip all of its resolved dependencies. A lockfile called "Orbit.lock" is generated and maintained by Orbit. The lockfile should be checked into your version control system for reproducible builds. It is not to be manually edited by the user.

With the lockfile, Orbit is able to download missing dependencies, install missing dependencies, and verify the data integrity of installed dependencies.

Manifest

A manifest is a configuration file that decscribes an ip recognized by Orbit. Manifest files are exactly named Orbit.toml. The manifest is intended to be edited by the user. The manifest is used as input for Orbit to generate the lockfile.

Orbit.lock

See lockfile.

Orbit.toml

See manifest.

Package

See IP.

Project

A project is a collection of HDL source files and any other required files related to a specific application or library. Placing a manifest in a project makes it an ip.

Protocol

A protocol is a process configured by the user that Orbit may use to download an ip from the internet.

The default protocol for Orbit assumes the url for an ip points to a zip file and uses the curl library to download it to the archive. An ip's manifest must explicitly specify an different protocol configured by the user to override the default protocol.

SystemVerilog

SystemVerilog is a hardware description and hardware verification language used to model, design, simulate, test, and implement electronic systems.

Target

A target is a process configured by the user that Orbit invokes during the execution stage of the build process. A target is given a name such that it can be identified throughout the system and may be comprised of a command, arguments, and custom filesets.

A target's behavio during the execution stage typically follows 3 steps:

1. Accept the blueprint file and environment variables set by Orbit from the planning stage
2. Perform backend processing on the list of source files using an EDA tool
3. Save the results of the processing, whether it be a simulation log, bitstream, or synthesis report

Users must configure their own targets; no default targets are included with Orbit.

VHDL

VHSIC Hardware Design Language (VHDL) is a hardware descrption language to model the behavior of digitally electronic circuits.

Verilog

Verilog is a hardware description language to model electronic systems. The final standard (IEEE 1364-2005) for Verilog merged into the SystemVerilog standard. Today, Verilog has been officially part of the SystemVerilog language.

config.toml

See Configuration