drom / reqack Goto Github PK

View Code? Open in Web Editor NEW

29.0 4.0 4.0 280 KB

🔁 elastic circuit toolchain

Home Page: https://observablehq.com/collection/@drom/reqack

License: MIT License

JavaScript 92.92% Verilog 6.77% HTML 0.31%

hardware-description-language verilog hdl hacktoberfest

reqack's Introduction

TUTORIAL

REQuest ⇄ ACKnowledge

JavaScript Tool set to construct, transform and analyze digital circuits based on elastic transactional protocol and Request-Acknowledge handshake.

User describes circuit JavaScript API, add standard components from the library, or create new componets.

Several standard controllers provided.

User can transform constructed circuit by changing buffer capacity or performing other correct by construction transformations.

Usage

The package can be installed from npm:

npm i reqack

and imported into your JavaScript code:

const reqack = require('reqack');

A circuit can be constructed this way:

const g = reqack.circuit('circuit_name');

A node can be constructed by calling the circuit function. Optional node_label string will be used as standard or custom operation or as a root of a signal name.

const node1 = g('node_label');

A edge can be constructed by calling the node function. Optional argument is an Object with two major properties (width, capacity).

const edge1 = node1({width: 32, capacity: 1});

One node can be connected to another node by calling edge with a destination node.

edge1(node2); // -> edge1

Resulted Verilog RTL can be produced by calling

const verilogString = reqack.verilog(g, {});

SVG image can be rendered by calling

const svg = reqack.svg(g);

Testing

npm i
npm test

License

MIT LICENSE

reqack's People

Contributors

Stargazers

Watchers

Forkers

universal-it-systems thbjohnson ameetgohil esromneb

reqack's Issues

Use React DevTools to inspect design hierarchy

capacity: 3+ support with elastic fifo

edge capacity rules:

0 = wire
1 = EB1
2 = EB2 (should be 1.5 = EB1.5?)
3+ = EFIFO. async ack?
3.5 = 3 + sync ack?

declare public parameters for the custom blocks

define node/edge label semantics

node

undefined:
null:
number:
string:
object:
function:

edge

undefined:
null:
number:
string:
object:
function:

multigraph support

The following example creates multiple connections from edge:1 to node:2

c1 = {
  const g = reqack.circuit();
  const n = {a: g(), b: g(), c: g('+'), d: g()};
  n.a()(n.b);
  const eb = n.b();
  [0, 1, 2].map(_ => eb(n.c));
  n.c()(n.d);
  g.edges.map(e => Object.assign(e.label, {width: 8}));
  return g;
}

Generated Verilog has multiple asignements to ack1_0

...
// node:2 join +
// join:3, fork:1
assign req2 = req1_0 & req1_0 & req1_0;
assign ack1_0 = ack2 & req1_0 & req1_0;
assign ack1_0 = ack2 & req1_0 & req1_0;
assign ack1_0 = ack2 & req1_0 & req1_0;
// node:3 initiator
...

Dagre renderer renders only one connection:

Full test case:

https://beta.observablehq.com/@drom/reqack-multigraph

incorrect pin names in the manifest

separate each test output into subfolder

node string type to be RPN expression

basic tests verilator lint clean

pass in-edges during node creation

If g() function called with more then 1 argument, these additional arguments should be treated as in-edges.

equality node

node with:

no label
1 target socket
1 initiator socket
same with?

need to create edge trees

5 year plan

Good Front End
- graph API
- ???
- HLS
Key Example [#9]
- pipeline-able
- memories
- cyclic
transformation API
- low level
- graph wide
  - algo
  - feedback
simulate graph
auto tb [#10]
back end
- verilog
- graphviz

back annotate graph with critical path timing information

parse timing report : https://github.com/drom/sta
add edge / node attributes for
- req 🔴
- ack 💙
- dat 💚
propose elastic transformation to fix timing issues

provide proper socket description to the ctrl2data bundle generator

set elastic buffer during reset

Important for FIR filter design

node object type

Similar to React Components, reqack should be able to take primitive component types or complex component types. Complex component provided as the factory function.

wire test fail

https://github.com/drom/elastic/blob/master/test/basic.js#L11

drom@drom:~/work/github/drom/elastic> verilator --lint-only build/wire.v 
%Error-ASSIGNIN: build/wire.v:16: Assigning to input variable: i_1_dat
%Error: Exiting due to 1 error(s)
%Error: See the manual and http://www.veripool.org/verilator for more assistance.
%Error: Command Failed /usr/local/bin/verilator_bin --lint-only build/wire.v

ac_int<W,S>

W - width of the number (non-negative interger number)
S - signed number (bool flag)

Type	Numerical range	Quantum
`{W: 1, S: false}`	0..1	1
`{W: 1, S: true}`	-1..0	1
`{W: 4, S: false}`	0..15	1
`{W: 4, S: true}`	-8..7	1

ac_int<W, S> === ac_fixed<W, W, S>

ac_fixed<W, I, S, Q, O>

W - width of the number (non-negative interger number)
I - integer width (non-negative interger number)
S - signed number (bool flag)
Q - rounding (bool flag)
O - overflow (bool flag)

Type	Numerical range	Quantum
`{W: 4, I: 4, S: false}`	0..15	1
`{W: 4, I: 4, S: true}`	-8..7	1
`{W: 4, I: 6, S: false}`	0..60	4
`{W: 4, I: 6, S: true}`	-32..28	4
`{W: 4, I: 0, S: false}`	0..15/16	1/16
`{W: 4, I: 0, S: true}`	-1/2..7/16	1/16
`{W: 4, I: -1, S: false}`	0..15/32	1/32
`{W: 4, I: -1, S: true}`	-0.25..7/32	1/32

ac_float<W, I, E, Q>

W - width of mantissa (non-negative interger number)
I - integer width (non-negative interger number)
E - exponent (non-negative interger number)
Q - rounding (bool flag)

Type	Numerical range	Quantum
`{W: 54, I: 2, E: 11}`	IEEE 754 double
`{W: 25, I: 2, E: 8}`	IEEE 754 float
`{W: 12, I: 2, E: 5}`	IEEE 754 half

❓ should width be W+E-1 ❓

ac_complex

C: true flag makes two part complex number.

Type	Numerical range	Quantum
`{W: 8, I: 4, S: false, C: true}`	0..15	1

provide edge width to the custom datapath declarator

Edge has undefined label by default

node number on hover over node

generate NAPI wrapper with every verilator TB

Replace join-fork control chains with MIMO controller

construct control graph from the main graph
render control graph
find all join-fork chains
replace with MIMO controllers
estimate area / timing improvements

Add option for having the last signal

how do you create a circuit with two inputs and one output?

for reciprocal the expression looked like this: reciprocal: (g)(g()(s16))(g())
what if I want to have two inputs one is s16 and the other is s4?

add elastic transformation example for the stack

change code to V2k

logic -> wire, req
always_ff -> always
always_comb -> always @*

Directed- Cyclic- Multi- Hyper- Graph

Graph

A graph is an ordered pair G := (V, E) where:

V is set of nodes;
E is set of edges.

Digraph (Directed graph)

In Digraph edges have direction.

Directed Cyclic Graph

A directed cyclic graph is a digraph that may have directed cycles.

Multigraph

Multigraph permits multiple edges with the same source and target nodes.

Hypergraph

In Hypergraph hyperedge (edge) is set of nodes.

Broadcast Directed- Hyper- Graph

1 source node s and set of (1 or more) target nodes T.

References

Directed hypergraphs: Introduction and fundamental algorithms—A survey. Giorgio Ausiello, Luigi Laura

name prefix

Ability to specify name prefix to the group of signals.
Good way to query, select, constraint elements with different properties

independent target / initiator port enumeration

t_0, t_1,...
i_0, i_1,...

export arbitrary wires from custom datapath module

Require use case

robust controllers

Reimplement controllers to ignore ack when no req.

eb15 buffer output req is straight output of input req (not flopped)

This causes the req to appear before valid data

spec handshake protocol.

https://github.com/drom/reqack/blob/master/docs/protocol.md

headlabel, taillabel for edges

const a = g(), b = g();
const a_edge0 = a({width: 8}, 'taillabel');
a_edge0(b, 'headlabel');

references

@incollection{peeters2005implementation,
  title={Implementation of handshake components},
  author={Peeters, Ad},
  booktitle={Communicating Sequential Processes. The First 25 Years},
  pages={98--132},
  year={2005},
  publisher={Springer}
}

ftp://nozdr.ru/biblio/kolxo3/Cs/CsLn/Communicating%20Sequential%20Processes..%20The%201th%2025%20Years,%20Symposium%20on%20the%20Occasion%20of%2025%20Years%20of%20CSP(LNCS3525,%20Springer,%202005)(ISBN%203540258132)(334s)_CsLn_.pdf#page=111

render elastic graphs

Rendering engines