The Spade Hardware Description Language

Namespaces

Like most modern languages, everything you define in Spade is defined in some namespace. Namespaces are separated by ::, for example path::to::thing

There are two ways you can define namespaces, first, you can explicitly write a module with mod


mod submodule {
  pub Functions together with Entities together with fn and Defines a pipeline. The number in in the parentheses is input-to-output latency of the pipeline. are the basic building blocks of Spade circuits. Unlike fn, entity can contain registers and therefore have state and unlike Defines a pipeline. The number in in the parentheses is input-to-output latency of the pipeline., they do not have a statically known latency or Defines a pipeline. The number in in the parentheses is input-to-output latency of the pipeline. structure. and Defines a pipeline. The number in in the parentheses is input-to-output latency of the pipeline. are the basic building blocks of Spade circuits. Unlike entities and pipelines, functions have no internal state, they are combinational (pure). test() {}
}

and in the same file you can refer to that function as

submodule::test()

In addition, every file in a Spade project has its own namespace. First, the namespace of the whole project is set by the name specified in swim.toml, for example

# swim.toml
name = "documentation_example"

Every Spade project needs a main.spade file, and the content there is put directly in the namespace of the project. I.e. if main.spade contains

Functions together with Entities together with fn and Defines a pipeline. The number in in the parentheses is input-to-output latency of the pipeline. are the basic building blocks of Spade circuits. Unlike fn, entity can contain registers and therefore have state and unlike Defines a pipeline. The number in in the parentheses is input-to-output latency of the pipeline., they do not have a statically known latency or Defines a pipeline. The number in in the parentheses is input-to-output latency of the pipeline. structure. and Defines a pipeline. The number in in the parentheses is input-to-output latency of the pipeline. are the basic building blocks of Spade circuits. Unlike entities and pipelines, functions have no internal state, they are combinational (pure). free_standing() {}

mod submodule {
  pub Functions together with Entities together with fn and Defines a pipeline. The number in in the parentheses is input-to-output latency of the pipeline. are the basic building blocks of Spade circuits. Unlike fn, entity can contain registers and therefore have state and unlike Defines a pipeline. The number in in the parentheses is input-to-output latency of the pipeline., they do not have a statically known latency or Defines a pipeline. The number in in the parentheses is input-to-output latency of the pipeline. structure. and Defines a pipeline. The number in in the parentheses is input-to-output latency of the pipeline. are the basic building blocks of Spade circuits. Unlike entities and pipelines, functions have no internal state, they are combinational (pure). test() {}
}

the full path to the two functions will be

documentation_example::free_standing;
documentation_example::submodule::test;

If there are more files in the src directory, those need a corresponding mod filename; in main.spade, and the full path to anything defined in those files will be

documentation_example::filename::function_in_filename;

In main.spade you can refer to things in the submodules simply as filename::function_in_filename, but in sibling files in the same project, you need to use the full path. I.e. in other_filename.spade you need to write

// other_filename.spade
documentation_example::filename::function_in_filename;

to access the function.

NOTE: Most of the time, you don’t want to write the name of the current project in your imports, instead you can write lib to refer to the current project, i.e. you can change the last example above to

// other_filename.spade
lib::filename::function_in_filename;

Importing with use

Writing the full path to every function would get very tedious quickly, so you can import things with the use statement. For example, you can write

use lib::filename::function_in_filename;

function_in_filename()

or import the whole filename namespace:

use lib::filename;

filename::function_in_filename()

External dependencies

Spade supports adding fetching dependencies, currently from git repositories. For example, you can import an implementation of common digital protocols from https://codeberg.org/spade-lang/protocols by adding the following to swim.toml

[libraries]
protocols.git = "https://codeberg.org/spade-lang/protocols"

Everything in that project will then get placed in a protocols namespace in your project. For example, you can import the UART transmitter implementation in uart.spade from that project with

use protocols::uart::uart_tx;