tilk/ digitaljs

(0.10.0) about 2 months ago

logic-gates

CSS

JavaScript

View on GitHub

Need help with digitaljs?

Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

tilk

451 Stars

22 Forks

BSD 2-Clause "Simplified" License

455 Commits

8 Opened issues

Description

Teaching-focused digital circuit simulator

Services available

Need anything else?

Contributors list

Marek Materzok tilk

# 261,114

verilog

lattice

logic-g...

Shell

389 commits

ialokim ialokim

# 57,831

messeng...

Kotlin

Shell

kotlin-...

35 commits

Readme

DigitalJS

Name: digitaljs
Brand: digitaljs
SKU: //tilk/digitaljs
Rating: 2.8775 (451 reviews)

This project is a digital circuit simulator implemented in Javascript. It is designed to simulate circuits synthesized by hardware design tools like Yosys, and it has a companion project yosys2digitaljs, which converts Yosys output files to DigitalJS. It is also intended to be a teaching tool, therefore readability and ease of inspection is one of top concerns for the project.

You can try it out online. The web app is a separate Github project.

Usage

You can use DigitalJS in your project by installing it from NPM:

npm install digitaljs

Or you can use the Webpack bundle directly.

To simulate a circuit represented using the JSON input format (described later) and display it on a

div

named

#paper

, you need to run the following JS code (see running example):

// create the simulation object
const circuit = new digitaljs.Circuit(input_goes_here);
// display on #paper
const paper = circuit.displayOn($('#paper'));
// activate real-time simulation
circuit.start();

Input format

Circuits are represented using JSON. The top-level object has three keys,

devices

connectors

and

subcircuits

. Under

devices

is a list of all devices forming the circuit, represented as an object, where keys are (unique and internal) device names. Each device has a number of properties, which are represented by an object. A mandatory property is

type

, which specifies the type of the device. Example device:

"dev1": {
    "type": "And",
    "label": "AND1"
}

Under

connectors

is a list of connections between device ports, represented as an array of objects with two keys,

from

and

to

. Both keys map to an object with two keys,

id

and

port

; the first corresponds to a device name, and the second -- to a valid port name for the device. A connection must lead from an output port to an input port, and the bitwidth of both ports must be equal. Example connection:

{
    "from": {
        "id": "dev1",
        "port": "out"
    },
    "to": {
        "id": "dev2",
        "port": "in"
    }
}

Under

subcircuits

is a list of subcircuit definitions, represented as an object, where keys are unique subcircuit names. A subcircuit name can be used as a

celltype

for a device of type

Subcircuit

; this instantiates the subcircuit. A subcircuit definition follows the representation of whole circuits, with the exception that subcircuits cannot (currently) define their own subcircuits. A subcircuit can include

Input

and

Output

devices, these are mapped to ports on a subcircuit instance.

Device types

Unary gates:
```
Not
```
,
```
Repeater
```
- Attributes:
```
bits
```
  (natural number)
- Inputs:
```
in
```
  (
```
bits
```
  -bit)
- Outputs:
```
out
```
  (
```
bits
```
  -bit)
N-ary gates:
```
And
```
,
```
Nand
```
,
```
Or
```
,
```
Nor
```
,
```
Xor
```
,
```
Xnor
```
- Attributes:
```
bits
```
  (natural number),
```
inputs
```
  (natural number, default 2)
- Inputs:
```
in1
```
  ,
```
in2
```
  ...
```
inN
```
  (
```
bits
```
  -bit,
```
N
```
  =
```
inputs
```
  )
- Outputs:
```
out
```
  (
```
bits
```
  -bit)
Reducing gates:
```
AndReduce
```
,
```
NandReduce
```
,
```
OrReduce
```
,
```
NorReduce
```
,
```
XorReduce
```
,
```
XnorReduce
```
- Attributes:
```
bits
```
  (natural number)
- Inputs:
```
in
```
  (
```
bits
```
  -bit)
- Outputs:
```
out
```
  (1-bit)

Bit shifts:

ShiftLeft

ShiftRight

Attributes:

bits.in1

bits.in2

and

bits.out

(natural number),

signed.in1

signed.in2

signed.out

and

fillx

(boolean)

Inputs:
```
in1
```
(
```
bits.in1
```
-bit),
```
in2
```
(
```
bits.in2
```
-bit)
Outputs:
```
out
```
(
```
bits.out
```
-bit)

Comparisons:
```
Eq
```
,
```
Ne
```
,
```
Lt
```
,
```
Le
```
,
```
Gt
```
,
```
Ge
```
- Attributes:
```
bits.in1
```
  and
```
bits.in2
```
  (natural number),
```
signed.in1
```
  and
```
signed.in2
```
  (boolean)
- Inputs:
```
in1
```
  (
```
bits.in1
```
  -bit),
```
in2
```
  (
```
bits.in2
```
  -bit)
- Outputs:
```
out
```
  (1-bit)
Number constant:
```
Constant
```
- Attributes:
```
constant
```
  (binary string)
- Outputs:
```
out
```
  (
```
constant.length
```
  -bit)
Unary arithmetic:
```
Negation
```
,
```
UnaryPlus
```
- Attributes:
```
bits.in
```
  and
```
bits.out
```
  (natural number),
```
signed
```
  (boolean)
- Inputs:
```
in
```
  (
```
bits.in
```
  -bit)
- Outputs:
```
out
```
  (
```
bits.out
```
  -bit)

Binary arithmetic:

Addition

Subtraction

Multiplication

Division

Modulo

Power

Attributes:

bits.in1

bits.in2

and

bits.out

(natural number),

signed.in1

and

signed.in2

(boolean)

Inputs:
```
in1
```
(
```
bits.in1
```
-bit),
```
in2
```
(
```
bits.in2
```
-bit)
Outputs:
```
out
```
(
```
bits.out
```
-bit)

Multiplexer:
```
Mux
```
- Attributes:
```
bits.in
```
  ,
```
bits.sel
```
  (natural number)
- Inputs:
```
in0
```
  ...
```
inN
```
  (
```
bits.in
```
  -bit,
```
N
```
  = 2**
```
bits.sel
```
  -1),
```
sel
```
  (
```
bits.sel
```
  -bit)
- Outputs:
```
out
```
  (
```
bits.in
```
  -bit)
One-hot multiplexer:
```
Mux1Hot
```
- Attributes:
```
bits.in
```
  ,
```
bits.sel
```
  (natural number)
- Inputs:
```
in0
```
  ...
```
inN
```
  (
```
bits.in
```
  -bit,
```
N
```
  =
```
bits.sel
```
  ),
```
sel
```
  (
```
bits.sel
```
  -bit)
- Outputs:
```
out
```
  (
```
bits.in
```
  -bit)
Sparse multiplexer:
```
MuxSparse
```
- Attributes:
```
bits.in
```
  ,
```
bits.sel
```
  (natural number),
```
inputs
```
  (list of natural numbers),
```
default_input
```
  (optional boolean)
- Inputs:
```
in0
```
  ...
```
inN
```
  (
```
bits.in
```
  -bit,
```
N
```
  =
```
inputs.length
```
  , +1 if
```
default_input
```
  is true)
- Outputs:
```
out
```
  (
```
bits.in
```
  -bit)
D flip-flop:
```
Dff
```
- Attributes:
```
bits
```
  (natural number),
```
polarity.clock
```
  ,
```
polarity.arst
```
  ,
```
polarity.srst
```
  ,
```
polarity.set
```
  ,
```
polarity.clr
```
  ,
```
polarity.enable
```
  ,
```
enable_srst
```
  (optional booleans),
```
initial
```
  (optional binary string),
```
arst_value
```
  ,
```
srst_value
```
  (optional binary string),
```
no_data
```
  (optional boolean)
- Inputs:
```
in
```
  (
```
bits
```
  -bit),
```
clk
```
  (1-bit, if
```
polarity.clock
```
  is present),
```
arst
```
  (1-bit, if
```
polarity.arst
```
  is present),
```
en
```
  (1-bit, if
```
polarity.enable
```
  is present)
- Outputs:
```
out
```
  (
```
bits
```
  -bit)
Memory:
```
Memory
```
- Attributes:
```
bits
```
  ,
```
abits
```
  ,
```
words
```
  ,
```
offset
```
  (natural number),
```
rdports
```
  (array of read port descriptors),
```
wrports
```
  (array of write port descriptors),
```
memdata
```
  (memory contents description)
- Read port descriptor attributes:
```
enable_polarity
```
  ,
```
clock_polarity
```
  ,
```
arst_polarity
```
  ,
```
srst_polarity
```
  (optional booleans),
```
init_value
```
  ,
```
arst_value
```
  ,
```
srst_value
```
  (optional binary strings),
```
transparent
```
  ,
```
collision
```
  (optional booleans or arrays of booleans)
- Write port descriptor attributes:
```
enable_polarity
```
  ,
```
clock_polarity
```
  ,
```
no_bit_enable
```
  (optional booleans)
- Inputs (per read port):
```
rdKaddr
```
  (
```
abits
```
  -bit),
```
rdKen
```
  (1-bit, if
```
enable_polarity
```
  is present),
```
rdKclk
```
  (1-bit, if
```
clock_polarity
```
  is present),
```
rdKarst
```
  (1-bit, if
```
arst_polarity
```
  is present),
```
rdKsrst
```
  (1-bit, if
```
srst_polarity
```
  is present)
- Outputs (per read port):
```
rdKdata
```
  (
```
bits
```
  -bit)
- Inputs (per write port):
```
wrKaddr
```
  (
```
abits
```
  -bit),
```
wrKdata
```
  (
```
bits
```
  -bit),
```
wrKen
```
  (1-bit (when
```
no_bit_enable
```
  is true) or
```
bits
```
  -bit (otherwise), if
```
enable_polarity
```
  is present),
```
wrKclk
```
  (1-bit, if
```
clock_polarity
```
  is present)
Clock source:
```
Clock
```
- Outputs:
```
out
```
  (1-bit)
Button input:
```
Button
```
- Outputs:
```
out
```
  (1-bit)
Lamp output:
```
Lamp
```
- Inputs:
```
in
```
  (1-bit)
Number input:
```
NumEntry
```
- Attributes:
```
bits
```
  (natural number),
```
numbase
```
  (string)
- Outputs:
```
out
```
  (
```
bits
```
  -bit)
Number output:
```
NumDisplay
```
- Attributes:
```
bits
```
  (natural number),
```
numbase
```
  (string)
- Inputs:
```
in
```
  (
```
bits
```
  -bit)
Subcircuit input:
```
Input
```
- Attributes:
```
bits
```
  (natural number)
- Outputs:
```
out
```
  (
```
bits
```
  -bit)
Subcircuit output:
```
Output
```
- Attributes:
```
bits
```
  (natural number)
- Inputs:
```
in
```
  (
```
bits
```
  -bit)
Bus grouping:
```
BusGroup
```
- Attributes:
```
groups
```
  (array of natural numbers)
- Inputs:
```
in0
```
  (
```
groups[0]
```
  -bit) ...
```
inN
```
  (
```
groups[N]
```
  -bit)
- Outputs:
```
out
```
  (sum-of-
```
groups
```
  -bit)
Bus ungrouping:
```
BusUngroup
```
- Attributes:
```
groups
```
  (array of natural numbers)
- Inputs:
```
in
```
  (sum-of-
```
groups
```
  -bit)
- Outputs:
```
out0
```
  (
```
groups[0]
```
  -bit) ...
```
outN
```
  (
```
groups[N]
```
  -bit)

Bus slicing:

BusSlice

Attributes:
```
slice.first
```
,
```
slice.count
```
,
```
slice.total
```
(natural number)
Inputs:
```
in
```
(
```
slice.total
```
-bit)
Outputs:
```
out
```
(
```
slice.count
```
-bit)

Zero- and sign-extension:
```
ZeroExtend
```
,
```
SignExtend
```
- Attributes:
```
extend.input
```
  ,
```
extend.output
```
  (natural number)
- Inputs:
```
in
```
  (
```
extend.input
```
  -bit)
- Outputs:
```
out
```
  (
```
extend.output
```
  -bit)
Finite state machines:
```
FSM
```
- Attributes:
```
bits.in
```
  ,
```
bits.out
```
  ,
```
states
```
  ,
```
init_state
```
  ,
```
current_state
```
  (natural number),
```
trans_table
```
  (array of transition descriptors)
- Transition descriptor attributes:
```
ctrl_in
```
  ,
```
ctrl_out
```
  (binary strings),
```
state_in
```
  ,
```
state_out
```
  (natural numbers)
- Inputs:
```
clk
```
  (1-bit),
```
arst
```
  (1-bit),
```
in
```
  (
```
bits.in
```
  -bit)
- Outputs:
```
out
```
  (
```
bits.out
```
  -bit)

TODO

Some ideas for further developing the simulator.

Use JointJS elementTools for configuring/removing gates.
RAM/ROM import/export for Verilog format and Intel HEX.
Framebuffer element with character/bitmap display.
More editing capability: adding and removing blocks, modifying some of blocks' properties.
Undo-redo capability.
Saving and loading circuits, including layout and state.
Generic handling of negation for unary/binary gates (negation on inputs/outputs) for better clarity.
Zooming in/out on schematics.
SVG export.
Verilog export.
Smartphone and tablet compatible UI.