BondMachine

A .basm input file is made of directives starting with the % character. Some directive starts a block that ends with the respective %end directive. Others are single line directives. The table below lists the directives that can be used in a .basm file.

Directive	End directive	Description
%section	%endsection	Code section
%macro	%endmacro	Macro definition
%fragment	%endfragment	Code fragment
%chunk	%endchunk	Chunk of data
%meta bmdef	none	BondMachine metadatas
%meta cpdef	none	CP metadatas
%meta sodef	none	SO metadatas
%meta iodef	none	Input/Output metadatas
%meta fidef	none	Fragment Instance metadata
%meta filinkdef	none	Fragment Instance Link metadatas
%meta soatt	none	SO attach directives
%meta ioatt	none	IO attach directives
%meta filinkatt	none	Fragment Instance link attach directives

Sections

The main Basm structure is the section. A section is a block of code or data. The directive %section is used start a section and ends with the directive %endsection. The syntax is:

%section section_name section_type [section metadata]
...
%endsection

Within Basm four type of sections can be defined:

romtext: Read only code section
romdata: Read only data section
ramtext: Code section
ramdata: Data section

The section name is a valid identifier. It has to be unique in the current BasmInstance. The section type is one of the four listed above. The section metadata is a list of metadata that are associated to the section. The metadata are used to define the section properties. The list of metadata is given in the table below.

Metadata	Description
iomode	The defualt I/O mode for the section. It can be sync or async. The default is async.

Code sections

Data sections

TODO

Macros

TODO

Fragments

TODO

Chunks

TODO

%meta Directives

The %meta directives are used to define the BondMachine architecture. They are used to define the SOs, the CPs and the BM itself. The syntax is:

Basm Instructions

Instructions

Basm instructions are identified by an operation that requires operands to be processed. Operands can be registers, memory address or more generally any SOs I/O ports. Some instructions do not require an operand, whereas some other instructions may require one, two, or three operands.

The first operand is generally the destination and the second operand is the source.

Pseudo instructions

Pseudo instructions are not real instructions, they are directives that are translated into one or more real instructions. They are used in the instruction field anyway because that’s the most convenient place to put them. The most common pseudo instructions are the ones that define data and reserve storage space. They are used to define constants and variables and to reserve space for arrays and other data structures.

Declaring data

The declaration of data is done in data sections by using the syntax:

symbol directive expression [, expression]...

symbol is the name of the variable. It can be any valid identifier. It as to be unique in the current section.

directive is the name of the directive that declares the data. The list of directives is given in the table below.

expression is a constant expression that evaluates to a byte (or other types according to the directives) value. The assembler assigns the first expression to the first byte of the variable, the second expression to the second byte, and so on. The assembler automatically advances the location counter by the number of bytes declared.

The following table lists the directives that can be used to declare data:

Directive	Type	Description	Example
db	Initiatialized data	Declare byte	examplevar db 1, 2, 3

Expressing I/O

Apart from operations among internal elements, CP instructions can interact with external objects. These can be memories, like in standard processor, or more generally can be all kind of SOs. Basm has a special syntax to express such data movements. The most common instruction is mov and the general syntax for the I/O objects is:

[IO object name][object index]:[I/O port]

If the object has no port the colon can be omitted. Similarly, if the object has no index, just the name can be used alone.

Following is a list of examples of I/O objects:

Object name	Description
ram	The random access memory
rom	The read only memory
i	The input
o	The output
vtm	The video textual memory
q	The shared queue
s	The shared stack

The I/O port can be addressed in two ways:

Immediate addressing: An immediate port has a constant value or an expression.
Register addressing: In this addressing mode, a register contains the port. In this mode the register name is surrounded by brackets.
Symbol addressing: In this addressing mode, a symbol refers to a port.

Here is some examples along with theirs descriptions:

Example	Description
mov r0 5	The register r0 is filled with the decimal value of 5
mov r1 i0 or mov r1 i0:	The register r0 is filled with the value read from the input i0
mov vtm0:48 r0	Copy the value contained in the r0 register into the location 48 of the video textual memory using immediate addressing
mov vtm0:[r1] r0	Copy the value contained in the r0 register into the location of the video textual memory pointed by the r1 register using register addressing

Contexts

%macro macro_name num_of_params
%endmacro

Macros are not CP-bounded, they are assembler bounded

Every section takes a CP tag, if that is missing it means there is only 1 tag associated to CP 0

sections .romtext cp_tag
     .romdata cp_tag
     .text cp_tag
     .data cp_tag
     .bss cp_tag

Labels are CP-bounded

metas are directives specific of the BondMachine, they are used to create groups of processors or groups of groups (clusters)

%meta sodef [so name] [so definition] [so tags]

%meta cpdef [cp name] [cp tags]

%meta bmdef

Basm Internals

Phases

The assembling process in divided into phases. The first phase (phase 0) read assembly file/s and create a raw BasmInstance. Subsequent passes operate transformations on BasmInstances. Specific steps can be removed using the dedicated arguments from the command line. The table following shows all the phases along with their description.

Phase short name	Description
TemplateResolver	The templated code is found and expanded. New (untemplated) elements (section or fragment) are created
DynamicalInstructions	The dynamical instructions are found according the name convention. They are created and inserted into the instruction database
SymbolsTagger1	Map the sections and fragments symbols, creates the relative metadata within the instruction arguments
DataSections2Bytes	Compute the offsets of the data sections and convert the data into bytes
MetadataInfer1	Infer the metadata by looking at the code and matching the instructions with the instruction database
FragmentAnalyzer	Analyze the fragments resources and create the relative metadata
FragmentOptimizer	Apply several customizable optimizations to the fragments
FragmentPruner	Prune the fragments that are specified in the command line
FragmentComposer	Compose the fragments into the sections as specified in the command line
MetadataInfer2	Infer the metadata for the second time since news sections and fragments may have been created
EntryPoints	The programs entry points is detected for the sections where it is relevant
MatcherResolver	Resolv the pseudo-insructions and traslate the instructions into the real ones. If more than one instruction is matched, alternative sections are created to be evaluated in the next phases
SymbolsTagger2	Map the sections and fragments symbols, creates the relative metadata within the instruction arguments
MemComposer	Associate the memory to the sections according to the final disposition of the sections within the BondMachine. Only section relevant for the cps metadata are considered and the others are discarded
SectionCleaner	Remove the sections that are not relevant for the cps metadata
SymbolsTagger3	Map the sections and fragments symbols, creates the relative metadata within the instruction arguments
SymbolsResolver	Symbols are detected, removed from the actual code and written as locations

After the last phase the BasmInstance is ready to be translated into a BondMachine or to a BCOF file. The structure of the BondMachine is defined by the SOs and CPs metas. While the code is processed, the assembler keeps track of the SOs and CPs that are used. At the end of the process, the assembler creates the BondMachine structure and fills it with the data collected during the process.

Bell State on a Zedboard

Bell State

There should have been a video here but your browser does not seem to support it.

The tutorial is built with the tool Handsome Hands-on - Alongside the video a demo script has been built and can be downloaded from here.

bmnumbers

bmnumbers is part of BondMachine project. bmnumbers is both a command line tool to convert or cast numbers to and from different formats and a library to do the same. It is used within the BondMachine every time numbers are handled.

Supported number types

The supported number types are listed in the following table.

Type Name	Prefixes	Description	Static	Lenght
unsigned	none 0u 0d	Unsigned integer	yes	any
signed	0s 0sd	Signed integer	yes	any
bin	0b 0b<s>	Binary number	yes	any s bits
hex	0x	Hexadecimal number	yes	any
float16	0f<16>	IEEE 754 half precision floating point number	yes	16 bits
float32	0f 0f<32>	IEEE 754 single precision floating point number	yes	32 bits
lqs[s]t[t]	0lq<s.t>	Linear quantized number with size s and type t	no	s bits
fps[s]f[f]	0fp<s.f>	Fixed point number with size s and fraction f	no	s bits
flp[e]f[f]	0flp<e.f>	FloPoCo floating point number with exponent e and mantissa f	no	e+f+3 bits

bmstack

bmstack is part of BondMachine project. Within the project It is used to create stacks and queues distributed among several BondMachine cores. due to its generality it can also be used as standalone tool to produce HDL shared stacks and queues to be used in other projects. The HDL code is build using golang templates that creates the code starting from the following data structure. The comments describe the meaning of each field.

type Push struct {
  Agent string // The name of the agent that is pushing
  Tick  uint64 // The tick at which the push occurs
  Value string // The value that is pushed
}

type Pop struct {
  Agent string // The name of the agent that is popping
  Tick  uint64 // The tick at which the pop occurs
}

type TestBenchData struct {
  Pops         []Pop    // List of pops
  Pushes       []Push   // List of pushes
  TestSequence []string // Pushes and pops in order
}

type BmStack struct {
  ModuleName string   // The name of the module
  DataSize   int      // The size of the data bus
  Depth      int      // The depth of the stack
  Senders    []string // The names of the agents that can send data to the stack
  Receivers  []string // The names of the agents that can receive data from the stack
  MemType    string   // "LIFO" for a stack or "FIFO" for a queue
  funcMap    template.FuncMap

  // TestBench data
  TestBenchData
}

Usage

Usage: API

The library can be used in two ways. The first one is from a go program. After creating a BmStack structure, the user can call the WriteHDL function to produce the HDL code. An example on how the library can be used this way can be seen in the go test file (bmstack_test.go).

func TestWriteHDL(t *testing.T) {
  // Create a new stack with 4 agents
  stack := BmStack{
    ModuleName: "test",
    DataSize:   32,
    Depth:      8,
    Senders:    []string{"sender1", "sender2"},
    Receivers:  []string{"receiver1", "receiver2"},
    MemType:    "LIFO"
  }

  // write the HDL code
  stack.WriteHDL()

The second part of the struct can be filled with test data. These data are used to produce a test bench for the stack. Using the test bench the user can verify the correctness of the stack. The test bench is produced by calling the WriteTestBench function.

func TestWriteTestBench(t *testing.T) {
  stack := BmStack{
  // ...
    s.Pushes = []Push{
      Push{"sender1", 200, "32'd1"},
    }
    s.Pops = []Pop{
      Pop{"receiver1", 60},
    }
  }
  // write the test bench
  stack.WriteTestBench()
}

The two functions (WriteHDL and WriteTestBench) return a string that contains the HDL code or an error if something went wrong (string, error). The provided go test file (bmstack_test.go) shows how the library can be used in this way. When invoked (go test), it produces the two files (bmstack.v and bmstack_tb.v). This kind of usage is useful when the user needs to create a stack or a queue in HDL and then use it in a bigger project like it is done in the BondMachine project.

Usage: CLI

The library also came with a companion CLI executable called bmstack that provides the basic interface to the library. This is the second Possible way to use it. With the -h flag the user can see the available options and their meaning.

$ bmstack -h
Usage of bmstack:
  -d    Verbose
  -data-width int
        Width of the data bus (default 32)
  -depth int
        Depth of the stack/queue (default 8)
  -hdl-file string
        Name of the file to write the HDL to (empty string to disable) (default "stack.v")
  -memory-type string
        Memory type, either stack or queue (default "queue")
  -random-stimulus int
        Generate random stimulus including N pushes and pops for every agent (0 to disable)
  -receivers string
        Comma separated list of names of signal tags that will receive data from the stack/queue
  -senders string
        Comma separated list of names of signal tags that will send data to the stack/queue
  -sim-length int
        Length of the simulation in clock cycles (default 1000)
  -stimulus-file string
        Name of the JSON file to load the stimulus from (empty string to disable)
  -tb-file string
        Name of the file to write the testbench to (empty string to disable)
  -v    Verbose

Examples

Within the BondMachine project, the library is used to create stacks and queues in HDL whenever needed. Some example of this are:

The queue used by the thread manager in the CP cores to store the CP threads state
The stack used to store the return addresses in the call instruction
The queue used to get data for the keyboard

To further see how the library is used in the BondMachine project, please refer to the BondMachine examples directory that contains many examples of BondMachines using stacks and queues. Instead, here we provide a simple example of how to use the library as standalone tool.

Example: API

The provided go test file (bmstack_test.go) shows how the library can be used in this way. When invoked (go test), it produces the two files (bmstack.v and bmstack_tb.v).

$ go test
$ ls *.v
bmstack_tb.v  bmstack.v

This example sets up a stack with 5 agents (3 senders and 2 receivers) and then produces the HDL code and the test bench for the stack. The test bench contains a sequence of pushes and pops that are used to verify the correctness of the stack. In detail the 3 senders push 6 values (2 each) to the stack at different times, while the 2 receivers pop the 6 values (3 each) from the stack at different times. The 6 values are distributed among the 2 receivers.

Example: CLI

The CLI can be used to produce the HDL code and the test bench for the stack. The following command produces the exact same file (bmsta.v) as the API example above.

$ bmstack -senders sender1,sender2,sender3 -receivers receiver1,receiver2 -hdl-file bmstack.v

To also produce the (same) test bench, the user can use the following command.

$ bmstack -senders sender1,sender2,sender3 -receivers receiver1,receiver2 -hdl-file bmstack.v -tb-file bmstack_tb.v -stimulus-file stimulus.json

Where stimulus.json is a JSON file that contains the test bench data. The JSON file has the following format.

{
  "Pops": [
    {"Agent": "receiver1","Tick": 110},
    {"Agent": "receiver2","Tick": 160},
    {"Agent": "receiver1","Tick": 210},
    {"Agent": "receiver2","Tick": 260},
    {"Agent": "receiver1","Tick": 310},
    {"Agent": "receiver2","Tick": 360}
  ],
  "Pushes": [
    {"Agent": "sender1","Tick": 100,"Value": "32'd1"},
    {"Agent": "sender2","Tick": 150,"Value": "32'd2"},
    {"Agent": "sender3","Tick": 200,"Value": "32'd3"},
    {"Agent": "sender1","Tick": 250,"Value": "32'd4"},
    {"Agent": "sender2","Tick": 300,"Value": "32'd5"},
    {"Agent": "sender3","Tick": 350,"Value": "32'd6"}
  ],
  "TestSequence": null
}

The JSON file contains the same data as the test bench data in the API example above. The user can use the JSON file to provide his own test bench data to the CLI. With -random-stimulus the user can also generate random stimulus data for the test bench. The CLI can be used to produce the HDL code and the test bench for a custom distributed stack/queue to use in other projects.

Warning: If the simulation prints a message like

Warning: impulse while request is active, the impulse will be ignored

it is due to the fact that the test bench data is not correct. Some pops/pushes are fired while the stack has already a request active from the same agent. In a real scenario, the agent would wait for the ack signal before sending another request. The test bench provided in the example is correct.

Simulation

Whether the HDL code is produced using the API or the CLI, the user can simulate the stack/queue using the provided test bench. The test bench is written in Verilog and can be simulated using any Verilog simulator. Here we provide an example using the Icarus Verilog simulator to run the simulation. The simulation produces a vcd file that can be viewed using gtkwave.

Following the API example above, the user can simulate the stack using the following commands.

$ iverilog -o bmstack.vvp *.v
$ vvp bmstack.vvp
VCD info: dumpfile bmstack.vcd opened for output.
stack_tb.v:142: $finish called at 1304000 (1ps)
$ gtkwave bmstack.vcd

The simulation shows the stack in action. The stack is filled with 6 values and then the values are popped by the receivers. The values are distributed among the two receivers as expected. Alongside the values pushed and popped, the simulation also shows some internal signals of the stack.

Interface

To use the generated HDL code, the user needs to connect the stack/queue to the agents that send and receive data. The stack/queue has the following interface.

Senders

The senders need to connect the following signals to the stack/queue.

clk: The clock signal
reset: The reset signal
[sendername]Data: The data to be pushed to the stack/queue
[sendername]Write: The write signal to push the data to the stack/queue
[sendername]Ack: The acknowledge signal to confirm the data has been pushed to the stack/queue

So, for example, if the user has a sender agent called sender1, the user needs to write the data to be pushed to the stack/queue in the sender1Data signal, then set the sender1Write signal to 1 to push the data to the stack/queue. The sender1Ack signal will be set to 1 when the data has been pushed to the stack/queue.

Sendername is the name of the sender agent chosen by the user.

Receivers

Similarly, the receivers need to connect the following signals to the stack/queue.

clk: The clock signal
reset: The reset signal
[receivername]Data: The data to be popped from the stack/queue
[receivername]Read: The read signal to pop the data from the stack/queue
[receivername]Ack: The acknowledge signal to confirm the data has been popped from the stack/queue

So, for example, if the user has a receiver agent called receiver1, the user needs to set the receiver1Read signal to 1 to pop the data from the stack/queue. The receiver1Data signal will contain the data popped from the stack/queue. The receiver1Ack signal will be set to 1 when the data has been popped from the stack/queue and is available in the receiver1Data signal.

Bondgo

BondMachine Builder

BondMachine to BASM

call

Instruction Group: call

chc

Instruction: chc

chw

Instruction: chw

cil

Instruction: cil

cilc

Instruction: cilc

cir

Instruction: cir

cirn

Instruction: cirn

clc

Instruction: clc

clr

Instruction: clr

cmpr

Instruction: cmpr

cmprlt

Instruction: cmprlt

cmpv

Instruction: cmpv

cpy

Instruction: cpy

cset

Instruction: cset

dec

Instruction: dec

div

Instruction: div

divf

Instruction: divf

divf16

Instruction: divf16

divp

Instruction: divp

dpc

Instruction: dpc

expf

Instruction: expf

fixed

fixed_point

Instruction Group: fixed_point

flopoco

Instruction Group: flopoco

Framework Installation

Binary

Pre-requisites

To use the BondMachine framework, you need to have the following tools installed on your system:

curl: to download the tools

Installation

To install the framework use the installer script downloadable from the web site. It contains all the tools and can be used on every system.

To get the framework choose the directory where the binaries have to be installed. The directory has to be writable and inserted in the user’s $PATH. There is no need of superuser access but the user has to have the rights to use the specific FPGA tools and board programming. Set the environment variable BONDMACHINE_DIR to point to this directory:

export BONDMACHINE_DIR=[the choosen directory]

and execute the install script with the bash shell:

bash <(curl -fsSL https://bondmachinehq.github.io/installer/install)

A similar uninstall script exists:

bash <(curl -fsSL https://bondmachinehq.github.io/installer/uninstall)

The install/uninstall script just copy/remove the framework executables, no other files are needed.

From sources

Pre-requisites

If you want to compile the framework from sources, you need to install the following tools:

Go (version 1.21 or higher) is needed to compile the framework. The go language is used to write the framework and to compile the tools.
Nodejs (version 16 or higher) is needed to compile the bmhelper tool. The bmhelper tool is used to assist the user in the creation of the BondMachine projects.
SDL2 development libraries are needed to compile the brvgasdl tool. The brvgasdl tool is used to simulate the BondMachine projects.

Installation

The installation of the framework from sources is a two-step process. First, you need to compile the bmhelper tool, and then you need to compile the BondMachine framework.

bmhelper

Clone the bmhelper repo at https://github.com/BondMachineHQ/bmhelper and compile the tool.

git clone https://github.com/BondMachineHQ/bmhelper.git

Move within the newly create bmhelper directory and execute npm to install the dependencies and compile the tool.

cd bmhelper
npm i 
npm run compile && npm run build

The bmhelper tool is now available in the pkg_out directory.

BondMachine framework

Clone the main repo at https://github.com/BondMachineHQ/BondMachine.git and compile the tools.

git clone https://github.com/BondMachineHQ/BondMachine.git

Move within the newly create BondMachine directory and execute make to build all the tools.

cd BondMachine/cmd ; make

Environment

The check that the framework is correctly installed and that all the needed tools are available, execute the command bmhelper doctor. It should print an output similar to the following:

$ bmhelper doctor
 [ OK ]          Mandatory dependency found: make
 [ OK ]          Mandatory dependency found: dot
 [ OK ]          Mandatory dependency found: curl
 [ OK ]          BondMachine tool basm found
 [ OK ]          BondMachine tool bmanalysis found
 [ OK ]          BondMachine tool bmnumbers found
 [ OK ]          BondMachine tool bmstack found
 [ OK ]          BondMachine tool bondgo found
 [ OK ]          BondMachine tool bondmachine found
 [ OK ]          BondMachine tool melbond found
 [ OK ]          BondMachine tool neuralbond found
 [ OK ]          BondMachine tool procbuilder found
 [ OK ]          BondMachine tool simbox found
 [ OK ]          All BondMachine tools has been found.
 [ WARNING ]     Optional tool found: vivado
 [ WARNING ]     Optional tool found: icepack
 [ WARNING ]     Optional tool not found: yosys
 [ WARNING ]     Optional tool not found: quartus
 [ OK ]          Dependencies checked

If some of the prerequisites are missing, the framework will not work correctly. Install the missing ones according to the distro you are using and repeat the check. The optional tools are needed only for specific boards, so if you don’t have the board, you can ignore the warning. At this point the framework is ready to be used.

hit

Instruction: hit

hlt

Instruction: hlt

i2r

Instruction: i2r

i2rw

Instruction: i2rw

inc

Instruction: inc

Length: opBits + regBits

Description:

The INC instruction increments a register by 1. It assumes that the register is a positive integer and it will overflow to 0 if the maximum value is reached. The length of the register is defined by the architecture.

Snippet:

%section code .romtext
        entry _start    ; Entry point
_start:

        clr     r0
loop:
        inc	r0
	r2o	r0,o0
        j	loop

%endsection

%meta cpdef	cpu	romcode: code, ramsize:8
%meta ioatt     testio cp: cpu, index:0, type:output
%meta ioatt     testio cp: bm, index:0, type:output
%meta bmdef	global registersize:8

INC example

incc

Instruction: incc

j

Instruction: j

ja

Instruction: ja

jc

Instruction: jc

jcmpa

Instruction: jcmpa

jcmpl

Instruction: jcmpl

jcmpo

Instruction: jcmpo

jcmpria

Instruction: jcmpria

jcmprio

Instruction: jcmprio

je

Instruction: je

jgt0f

Instruction: jgt0f

jo

Instruction: jo

jri

Instruction: jri

jria

Instruction: jria

jrio

Instruction: jrio

jz

Instruction: jz

k2r

Instruction: k2r

lfsr82r

Instruction: lfsr82r

linear

linear_quantizer

Instruction Group: linear_quantizer

m2r

Instruction: m2r

m2rri

Instruction: m2rri

Machine Learning

Maxpool Generator

The maxpool generator is a generator that generates a maxpool layer in the neural network. The maxpool layer is a layer that is used to downsample the input data. It works by taking the maximum value of a set of values in a window and outputting that value. The maxpool layer is used to reduce the size of the input data, which can help to reduce the number of parameters in the network and speed up training.

mod

Instruction: mod

mulc

Instruction: mulc

mult

Instruction: mult

multf

Instruction: multf

multf16

Instruction: multf16

multp

Instruction: multp

nand

Instruction: nand

nop

Instruction: nop

nor

Instruction: nor

not

Instruction: not

or

Instruction: or

Papers

This section contains all the technical information about the project in the form of papers and articles.

2021 - Parallel Computing Article

The article describes in detail the BondMachine project, its architecture, and the results obtained in the experiments. The article was published in the Parallel Computing journal.

2019 - ISGC 2019 Conference paper

This paper was presented at the ISGC 2019 conference in Taipei, Taiwan. It describes the early stages of the project used as a proof of concept for the FPGA-based Machine Learning Inference Engine.

2018 - Innovate FPGA Design paper

This paper was submitted to the Innovate FPGA Design contest in 2018. It describes the architecture of the BondMachine project in its early stages.

Processor Builder

The main purpose of the procbuilder command is to provide a command-line interface for interacting with the procbuilder package. The procbuilder package is the library that contains the core functionality for building and interacting with a CP processor architecture. The command accepts various flags that control its behavior and perform different operations based on those flags. This document provides an overview of the command’s functionality, the flags it accepts, and the operations it performs based on those flags.

This command performs various operations based on the provided flags. It can create a new CP, add instructions to the CP, assemble a program, disassemble a program and produce the HDL code for the CP.

Usage

The two main workflows for the procbuilder command are:

Loading an existing CP and program from JSON files, inspecting the CP and program. Using the CP to generate HDL code.
Creating a new CP, adding instructions to the CP, assembling a program, disassembling the program and saving the machine state to a JSON file

Loading an Existing CP and Program

The flag to load an existing CP and program is load-machine. If this flag is set to a non-empty string, the command checks if a file with the specified name exists. If the file exists, the command reads the machine state from the file and initializes the CP and program with the read data. If any errors occur during file operations or JSON unmarshaling, the command panics.

TODO - Finish this section

Creating a New CP and Program

The flags to create a new CP and program are save-machine. It is used to save the machine state to a JSON file. If this flag is set to a non-empty string, the command saves the machine state to a JSON file with the specified name.

TODO - Finish this section

Projects

A BondMachine project is a directory that contains all the necessary files to generate the firmware for a specific board. The project is created with the bmhelper create command line tool, which is installed with the BondMachine framework. It is configured using a Kconfig file, with commands similar to the Linux kernel (for example: make menuconfig). It is then validated and completed with the bmhelper validate and bmhelper apply commands. Once the project is applied, it is possible to generate the firmware and make all the other operations with the make command and several targets.

Project workflow

The project workflow is divided into several steps:

project creation
project configuration
project validation
project apply
make targets execution

Project creation

An enpty project can be created with the following command:

bmhelper create --project_name project_test

This command will create a project with the name project_test in the current directory. The project will be created with the default configuration. The default configuration is defined in the bmhelper tool and can be changed with the make menuconfig command (or any other command that can be used to configure the Kconfig file).

Additionally, the bmhelper create command can be used to create a project starting from a working example. To get the list of available examples, use the following command:

bmhelper create --list-examples

To duplicate an example, use the following command:

bmhelper create --project_name project_test --example example_name

where example_name is the name of an example in the list of examples.

Project configuration

The project configuration is defined in the Kconfig file. The Kconfig file is a text file that defines the configuration possibilities of the project. It is similar to the Kconfig file used in the Linux kernel. With a kconfig compatible tool the Kconfig file can be used to generate the specific configuration.

For example, the make menuconfig command will open a menu that allows you to configure the project. The menu is similar to the menu used to configure the Linux kernel. The menu is divided into several sections. Each section contains a set of configuration. The details of each configuration are described in the help of the menu. The menu is used to configure the .config file. The .config file is used by the project Makefile to configure the project and carry out the operations.

make menuconfig

If preffered, it is possible to use a local.mk file to configure the project. The local.mk file is a text file that defines the configuration of the project directly specifying the variables. The project Makefile created by bmhelper will either use the .config file or the local.mk file to configure the project. The .config file has priority over the local.mk file. The local.mk file is useful when you want to configure the project with a script or with a tool that does not support the .config file.

Details on the configuration variables are described in the Configuration variables section.

Project validation

The bmhelper tool can be used to validate the project configuration. The validation is performed with the following command:

make validate

The validation process checks the configuration variables and the project files. For each one of them the following color codes are used:

green : the variable or file is present and valid
yellow : the (optional) variable or file is not present
magenta : the (mandatory) variable or file is not present but bmhelper can create it with default values
red : the (mandatory) variable or file is either not present or invalid

Project apply

The project configuration is applied with the following command:

make apply

The apply process creates the project files and directories. The files and directories are created in the working directory. The working directory is defined by the WORKING_DIR variable. The default working directory is the current directory. For the items marked as magenta in the validation process, the apply process will ask for confirmation before creating the file or directory with the default values. For the items marked as red in the validation process, the apply process will fail.

Generic targets

After creating and appling a project, you can use the make command to generate firmware and perform other operations. The make command can be used with several targets. The targets are defined in the Makefile file and are described in the following sections.

The following targets are available for any type of project independently of the board/toolchain:

Command	Description
`make bondmachine`	Create the Bondmachine and all its connecting processors. Starting from the specific source file and source tool, the Bondmachine is created and save as JSON file.
`make clean`	Clean the project directory.
`make show`	Use graphviz to visualize the architecture generated.
`make hdl`	Generate the source HDL code (i.e. working_dir/bondmachine.sv, working_dir/bondmachine.vhd)

Staring from the hdl target, several workflow are available depending on several factors like the board, the toolchain, the use as accelerator or as stand-alone project.

Stand-alone workflow

Stand-alone projects only require the FPGA board to run. The following targets are available for stand-alone projects:

Command	Description
`make synthesis`	Start the project synthesis
`make implementation`	Start the project implementation
`make bitstream`	Start the project bitstream generation
`make program`	Program the board if connected

SoC Accelerator workflow

SoC Accelerator projects require a board with a SoC processor to run. The SoC processor is connected to the FPGA fabric and can be used to run the BondMachine. Examples of SoC processors are the ARM processors in the Zynq SoC or the Cyclone V SoC.

The following targets are available for SoC accelerator projects:

Command	Description
`make design_synthesis`	Start the project synthesis
`make design_implementation`	Start the project implementation
`make design_bitstream`	Start the project bitstream generation
`make kernel_module`	Create the kernel module which runs on custom buildroot linux distribution
`make buildroot`	Create the custom buildroot linux sdcard-image
`make deploy`	Deploy the bitstream, kernel module and eventually the application on the board

PCie Accelerator workflow (Xilinx)

PCie Accelerator projects require a board with a PCie interface to run. The PCie interface is used to connect the FPGA to the host PC. The host PC can be used to run the BondMachine. Examples of PCie boards are the Xilinx Alveo boards.

The following targets are available for PCie accelerator projects:

Command	Description
`make xclbin`	Create the xclbin file
`make deploy_xclbin`	Deploy the xclbin file and eventually the application on the host

Configuration variables

Wether you are reading variables from the Kconfig file or from the .mk files, the syntax is the same. The following is the list of the most commonly used variables:

Variable	type	description
`ALTERA_BOARD_MAX1000`	KConfig Only	Board selection max1000
`ALTERA_BOARD_DE0NANO`	KConfig Only	Board selection de0nano
`BASM_DEBUG`	boolean	enable or not debug of basm
`BM_REGRESSION`	KConfig Only	missing
`BOARD`	KConfig Only	Board type
`BOARDLESS_PROJECT`	KConfig only	enable or not debug of basm
`GENERAL_TYPE`	KConfig only	general project type
`GENERAL_TYPE_BOARDLESS`	KConfig only	project without board
`GENERAL_TYPE_BOARD`	KConfig only	project with board
`HDL_REGRESSION`	filename	missing
`PROJECT_TYPE_BONDGO`	KConfig Only	BondGo project
`PROJECT_TYPE_NEURALBOND`	KConfig Only	Neural Network project
`PROJECT_TYPE_MELBOND`	KConfig Only	Melbond project
`PROJECT_TYPE_BASM`	KConfig Only	sBASM project
`PROJECT_TYPE_MULTI`	KConfig Only	Root project aggregator for multiple project
`MULTI_TARGET`	string	Target to exec in case of multiple projects
`MULTI_TYPE`	string	Type of aggregation
`MULTI_TEMPLATE_DIR`	directory	directory of template to clone
`MULTI_TEMPLATE_DESC`	filename	multifilename description json file
`LATTICE_BOARD_ICE40LP1K`	Kconfig Only	Board selection Lattice ice40lp1k
`LATTICE_BOARD_ICEFUN`	Kconfig Only	Board selection Lattice icefun
`LATTICE_BOARD_ICEBREAKER`	Kconfig Only	Board selection Lattice icebreaker
`LATTICE_BOARD_ICESUGARNANO`	Kconfig Only	Board selection Lattice icesugarnano
`SELECT_PROJECT_TYPE`	KConfig Only	select project type
`SELECT_TOOLCHAIN`	KConfig Only	select toolchain
`SELECT_XILINX_BOARD`	KConfig Only	select board
`REGRESSION_TEST`	KConfig Only	missing description
`REGRESSION_TEST_BM`	KConfig Only	missing
`REGRESSION_TEST_HDL`	KConfig Only	missing
`REGRESSION_TEST_SIM`	KConfig Only	missing
`ROOTDIR`	string	Directory storing the board-specific files
`SIM_REGRESSION`	KConfig Only	missing
`SOURCE_GO`	filename	bondgo source
`SOURCE_NEURALBOND`	filename	neuralbond source file
`SOURCE_MELBOND`	filename	melnond source file
`SOURCE_BASM`	filenames	basm source file
`TOOLCHAIN`	string	FPGA tools
`TOOLCHAIN_ALTERA`	Kconfig Only	select altera toolchain
`TOOLCHAIN_LATTICE`	Kconfig Only	select lattice toolchain
`TOOLCHAIN_XILINX`	Kconfig Only	select xilinx toolchain
`UART_MAPFILE`	filename	support for UART
`UART_SUPPORT`	boolean	support for UART
`WORKING_DIR`	directory	Working directory path
`XILINX_BOARD_BASYS3`	Kconfig Only	Board selection basys3
`XILINX_BOARD_ZEDBOARD`	KConfig Only	Board selection zedboard
`XILINX_BOARD_ZC702`	KConfig Only	Board selection zc702
`XILINX_BOARD_KC705`	KConfig Only	Board selection kc705
`XILINX_BOARD_EBAZ4205`	KConfig Only	Board selection ebaz4205

q2r

Instruction: q2r

Quantum

bmqsim is part of BondMachine project. It is a library and a CLI tool to produce HDL code and test benches to simulate a quantum computer on FPGA using the BondMachine architecture framework. It also provides a sotfware simulator to be used in a CPU. The installation of bmqsim is part of the standard installation of BondMachine framework. Please refer to the BondMachine quick start for the instructions.

Usage

To use the bmqsim CLI tool, you have to choose two things: the backend and the quantum algorithm to simulate. The backend creates target hardware architecture of a specific type and its flavor (the subtype as for example the only real numbers or the complex numbers flavor) if applicable. The quantum algorithm is a file containing the quantum circuit to simulate. Let’s begin the latter.

Quantum algorithm

The quantum circuit is a file containing the quantum algorithm to simulate. The file is written in the the same format as the one used by the Basm assembler and has the bmq extension. The file is a sequence of instructions, each one in a line inserted in a block section. To instruct the simulator, outside the block section, you can use the %meta directive to specify the simulator metadata.

The following is an example (program.bmq) of a quantum algorithm file implementing the Bell state:

%block code1 .sequential
	qbits	q0,q1
	zero	q0,q1
	h	q0
	cx	q0,q1
%endblock

%meta bmdef global main:code1

Backend

Once you have the quantum algorithm, you can choose the backend to use. The backend creates the target hardware architecture of a specific type and flavor. The subsequent tables show the available backend and architectures types, their flavors and the relevant command line options:

Architecture type (backend)	Command line option	Description	Flavors
`Software`	`--software-simulation`	Software simulator	`None`
`MatrixSeqHardcoded`	`--build-matrix-seq-hardcoded`	Sequence of matrices hardcoded in the FPGA	`seq_hardcoded_real`, `seq_hardcoded_complex`
`MatrixSeq`	`--build-matrix-seq`	Sequence of matrices in the FPGA	Not yet implemented
`FullHardwareHardcoded`	`--build-full-hardware-hardcoded`	Full hardware with hardcoded matrices	Not yet implemented

Each architecture type is associated to a different set of command line options and activates a different simulator backend. Some of the options are common to all the backends, while others are specific to a single backend. The following sections describe the possible backends and the options.

Common options

Option	Description
`-hw-flavor-list`	List the available flavors for the chosen hardware architecture.
`-hw-flavor`	Choose the flavor of the hardware architecture.
`-save-basm`	Save the BondMachine Assembly code for the Basm assembler.
`-build-app`	Build the application template to use the selected hardware architecture.
`-app-flavor-list`	List the available flavors for the chosen application template.
`-app-flavor`	Choose the flavor of the application template.
`-app-file`	Choose the file name of the application template.

Software simulator

The software simulator backend is used to simulate the quantum algorithm on a CPU. The program accept a json input file and produces a json output file. The following table shows the command line options specific to the software simulator:

Option	Description
`-software-simulation-input`	Choose the input file for the software simulator.
`-software-simulation-output`	Choose the output file for the software simulator.

An example of usage of the software simulator with the Bell state algorithm previously described (program.bmq) is the following:

bmqsim --software-simulation --software-simulation-input input.json --software-simulation-output output.json program.bmq

where input.json, the input file for the software simulator, is:

{
	{"Vector":[{"Real":1,"Imag":0},{"Real":0,"Imag":0},{"Real":0,"Imag":0},{"Real":0,"Imag":0}]}
}

and output.json, the output file produced by the simulator, is:

{
	{"Vector":[{"Real":0.7071067,"Imag":0},{"Real":0,"Imag":0},{"Real":0,"Imag":0},{"Real":0.7071067,"Imag":0}]}
}

Hardcoded sequence of matrices

Loadable sequence of matrices

Full hardware with hardcoded matrices

Other options

Alongside these main options, there are other options that does not depend on the backend chosen. These options are listed in the following table:

Option	Description

Examples

Quickstart

Pre-requisites

To use the BondMachine framework, you need to have the following tools installed on your system:

curl: to download the tools and the examples

Installation

To install the framework use the installer script downloadable from the web site. It contains all the tools and can be used on every system.

export BONDMACHINE_DIR=[the choosen directory]

and execute the install script with the bash shell:

bash <(curl -fsSL https://bondmachinehq.github.io/installer/install)

A similar uninstall script exists:

bash <(curl -fsSL https://bondmachinehq.github.io/installer/uninstall)

The install/uninstall script just copy/remove the framework executables, no other files are needed.

Environment

The check that the framework is correctly installed and that all the needed tools are available, execute the command bmhelper doctor. It should print an output similar to the following:

$ bmhelper doctor
 [ OK ]          Mandatory dependency found: make
 [ OK ]          Mandatory dependency found: dot
 [ OK ]          Mandatory dependency found: curl
 [ OK ]          BondMachine tool basm found
 [ OK ]          BondMachine tool bmanalysis found
 [ OK ]          BondMachine tool bmnumbers found
 [ OK ]          BondMachine tool bmstack found
 [ OK ]          BondMachine tool bondgo found
 [ OK ]          BondMachine tool bondmachine found
 [ OK ]          BondMachine tool melbond found
 [ OK ]          BondMachine tool neuralbond found
 [ OK ]          BondMachine tool procbuilder found
 [ OK ]          BondMachine tool simbox found
 [ OK ]          All BondMachine tools has been found.
 [ WARNING ]     Optional tool found: vivado
 [ WARNING ]     Optional tool found: icepack
 [ WARNING ]     Optional tool not found: yosis
 [ WARNING ]     Optional tool not found: quartus
 [ OK ]          Dependencies checked

Basic examples

To test that framework is working correctly, clone the examples repository:

git clone https://github.com/BondMachineHQ/bmexamples

and move into the directory:

cd bmexamples

The directory contains a set of examples that can be used to test the framework.

r2m

Instruction: r2m

r2mri

Instruction: r2mri

r2o

Instruction: r2o

r2owa

Instruction: r2owa

r2owaa

Instruction: r2owaa

r2q

Instruction: r2q

r2s

Instruction: r2s

r2t

Instruction: r2t

r2u

Instruction: r2u

r2v

Instruction: r2v

r2vri

Instruction: r2vri

Repositories

The BondMachine project source file are hosted on GitHub as the BondMachineHQ organization.

The two most important repositories are the BondMachine repository that contains the project source code.

And the Projects repository that contains tested examples of BondMachine that can be built for specific devices.

Other public repositories are:

Repository	Description
BMBuildkit
BMBuildkit-dagger
BondMachineHQ.github.io	Website code
bmapiaximmtransceiver	Transceiver-like module for AXI Memory Mapped BMAPI
bmapiuarttransceiver	Transceiver-like module for UART BMAPI
bmexamples	BondMachine examples, demos and tutorials
bmhelper	A tool to help users in creating and configuring projects using the BondMachine framework
bmmltests	Examples and tests for the machine learning tools with the BM. code to train, convert and handle ML models
bmqsimtests	Examples and tests for the bmqsim quantum simulator. Comparison among other simulators and so on
bmregressiondata	Regression tests data
bmresources	Resources used by bmhelper internally
bondmachine_ebaz4205_buildroot	BR2 directory for ebaz4205, the repo is not meant to be used directly. It is used internally by the BondMachine makefilles to create images with buildroot
bondmachine_ebaz4205_buildroot_example	Buildroot on Ebaz4205. How to create from scratch a complete BondMachine accelerated buildroot image for the Ebaz4205 board
bondmachine_zedboard_buildroot	BR2 directory for zedboard. the repo is not meant to be used directly. It is used internally by the BondMachine makefilles to create images with buildroot
bondmachine_zedboard_buildroot_example	Buildroot on Zedboard. How to create from scratch a complete BondMachine accelerated buildroot image for the Zedboard
kserve-bond-extension	Project that extends KServe predictors
kserve-ui	Dynamic KServe User Interface
ml-ebaz4205	Machine Learning with HLS4ML and BM on ebaz4205
ml-zedboard	Machine Learning with HLS4ML and BM on zedboard
pybondmachine	pybondmachine is the Python library designed to streamline the development of FPGA accelerators through the use of the BondMachine framework.

ro2r

Instruction: ro2r

ro2rri

Instruction: ro2rri

rsc

Instruction: rsc

rset

Instruction: rset

rsets

Instruction Group: rsets

s2r

Instruction: s2r

saj

Instruction: saj

sbc

Instruction: sbc

sic

Instruction: sic

stack

Instruction Group: stack

sub

Instruction: sub

Support Matrix

The following tables show the feature state in term of level of development for each instruction and instruction group. For each of them the support of the features is shown.

The features are the following:

Feature	Description
hdl	The instruction can be translated to hardware description language
asm	The instruction can be assembled by the assembler
disasm	The instruction can be disassembled by the disassembler
hlasm	The instruction can be assembled by the high-level assembler (Basm)
asmmeta	The instruction has metadata for the assembler
gosim	The instruction can be simulated in the Go-based simulator
hdlsim	The instruction can be simulated in the hardware description language simulator
mt	Instruction thread support

The possible support values are shown below:

Value	Meaning
	The feature is fully implemented
	The feature is not yet implemented
	The feature is being tested
	The feature is partially implemented
	The feature is not applicable to the instruction

Support Matrix for Static Instructions

Instruction	disasm	gosim	mt	hlasm	hdl	asmeta	asm
adc	-	-	-	-	-	-	-
add	-	-	-	-	-	-	-
addf	-	-	-	-	-	-	-
addf16	-	-	-	-	-	-	-
addi	-	-	-	-	-	-	-
addp	-	-	-	-	-	-	-
and	-	-	-	-	-	-	-
chc	-	-	-	-	-	-	-
chw	-	-	-	-	-	-	-
cil	-	-	-	-	-	-	-
cilc	-	-	-	-	-	-	-
cir	-	-	-	-	-	-	-
cirn	-	-	-	-	-	-	-
clc	-	-	-	-	-	-	-
clr	-	-	-	-	-	-	-
cmpr	-	-	-	-	-	-	-
cmprlt	-	-	-	-	-	-	-
cmpv	-	-	-	-	-	-	-
cpy	-	-	-	-	-	-	-
cset	-	-	-	-	-	-	-
dec	-	-	-	-	-	-	-
div	-	-	-	-	-	-	-
divf	-	-	-	-	-	-	-
divf16	-	-	-	-	-	-	-
divp	-	-	-	-	-	-	-
dpc	-	-	-	-	-	-	-
expf	-	-	-	-	-	-	-
hit	-	-	-	-	-	-	-
hlt	-	-	-	-	-	-	-
i2r	-	-	-	-	-	-	-
i2rw	-	-	-	-	-	-	-
inc
incc	-	-	-	-	-	-	-
j	-	-	-	-	-	-	-
ja	-	-	-	-	-	-	-
jc	-	-	-	-	-	-	-
jcmpa	-	-	-	-	-	-	-
jcmpl	-	-	-	-	-	-	-
jcmpo	-	-	-	-	-	-	-
jcmpria	-	-	-	-	-	-	-
jcmprio	-	-	-	-	-	-	-
je	-	-	-	-	-	-	-
jgt0f	-	-	-	-	-	-	-
jo	-	-	-	-	-	-	-
jri	-	-	-	-	-	-	-
jria	-	-	-	-	-	-	-
jrio	-	-	-	-	-	-	-
jz	-	-	-	-	-	-	-
k2r	-	-	-	-	-	-	-
lfsr82r	-	-	-	-	-	-	-
m2r	-	-	-	-	-	-	-
m2rri	-	-	-	-	-	-	-
mod	-	-	-	-	-	-	-
mulc	-	-	-	-	-	-	-
mult	-	-	-	-	-	-	-
multf	-	-	-	-	-	-	-
multf16	-	-	-	-	-	-	-
multp	-	-	-	-	-	-	-
nand	-	-	-	-	-	-	-
nop	-	-	-	-	-	-	-
nor	-	-	-	-	-	-	-
not	-	-	-	-	-	-	-
or	-	-	-	-	-	-	-
q2r	-	-	-	-	-	-	-
r2m	-	-	-	-	-	-	-
r2mri	-	-	-	-	-	-	-
r2o	-	-	-	-	-	-	-
r2owa	-	-	-	-	-	-	-
r2owaa	-	-	-	-	-	-	-
r2q	-	-	-	-	-	-	-
r2s	-	-	-	-	-	-	-
r2t	-	-	-	-	-	-	-
r2u	-	-	-	-	-	-	-
r2v	-	-	-	-	-	-	-
r2vri	-	-	-	-	-	-	-
ro2r	-	-	-	-	-	-	-
ro2rri	-	-	-	-	-	-	-
rsc	-	-	-	-	-	-	-
rset	-	-	-	-	-	-	-
s2r	-	-	-	-	-	-	-
saj	-	-	-	-	-	-	-
sbc	-	-	-	-	-	-	-
sic	-	-	-	-	-	-	-
sub	-	-	-	-	-	-	-
t2r	-	-	-	-	-	-	-
tsp	-	-	-	-	-	-	-
u2r	-	-	-	-	-	-	-
wrd	-	-	-	-	-	-	-
wwr	-	-	-	-	-	-	-
xnor	-	-	-	-	-	-	-
xor	-	-	-	-	-	-	-

Support Matrix for Dynamical Instructions

Instruction
call
fixed_point
flopoco
linear_quantizer
rsets
stack

t2r

Instruction: t2r

The INC istruction

%section code .romtext
        entry _start    ; Entry point
_start:

        clr     r0
loop:
        inc	r0
	r2o	r0,o0
        j	loop

%endsection

%meta cpdef	cpu	romcode: code, ramsize:8
%meta ioatt     testio cp: cpu, index:0, type:output
%meta ioatt     testio cp: bm, index:0, type:output
%meta bmdef	global registersize:8

INC example

tsp

Instruction: tsp

u2r

Instruction: u2r

wrd

Instruction: wrd

wwr

Instruction: wwr

xnor

Instruction: xnor

xor

Instruction: xor