@logigator/logigator-simulation

Logigator - Simulation Code Base

Multi-Threaded Simulator for Logic Circuits as Node.JS Native C++ Module, alternatively compilable to WebAssembly.

Getting Started

Prerequisites

You need to have node and npm installed to use this module. We recommend installing it via nvm:

Debian

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.1/install.sh | bash
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
nvm install lts/*

Furthermore, python2 is required for compiling:

apt install python2

Installation

Download the contents of the repository, open the command line in that directory and install it using npm install.

Linux / Unix

git clone 'http://github.com/logigator/logigator-simulation.git' && cd ./logigator-simulation && npm install

alternatively, you can install it using npm:

npm install @logigator/logigator-simulation

To compile to WASM, use this command:

npm run wasm-install

this will download emscripten and compile into webAssembly/dist/

Usage (Node.JS)

Import the module in your Node.JS Script:

const logicsim = require('./index').logicsim;

Alternatively, if you installed the package using npm, import it with:

const logicsim = require('@logigator/logigator-simulation').logicsim;

You can also import it using typescript:

import {BoardObject, logicsim} from "@logigator/logigator-simulation";

Functions

Function	Description
logicsim.init(board);	Creates a new Board. A sample board object can be found below.
logicsim.start(threads, ticks, ms);	Runs the simulation until either the ticks were simulated or the simulation time was reached.
logicsim.stop();	Stops the simulation if running.
logicsim.getStatus();	Gets the current Status of a Board, like simulated ticks, current execution state or current simulation speed
logicsim.getLinks();	Gets states of all links
logicsim.getBoard();	Gets all components and links and their current state
logicsim.triggerInput(/*index of component*/, /*0 = set, 1 = pulse*/, /*array of states for input*/);	Triggers an input element on a board
logicsim.destroy();	Destroys current board. This is required before initializing a new board.

Sample Board Object:

{
  "links": 4,
  "components": [
  	{
  		"type": 200,
  		"inputs": [
  		],
  		"outputs": [
  			0
  		]
  	},
  	{
  		"type": 4,
  		"inputs": [
  			0, 1
  		],
  		"outputs": [
  			2
  		]
  	},
  	{
  		"type": 2,
  		"inputs": [
  			0, 2
  		],
  		"outputs": [
  			3
  		]
  	}
  ]
}

Usage (WebAssembly)

Copy the .wasm and .js file to an appropriate location on your web server. Then, import the JS file and initialize WebAssembly:

<script src="/path/to/this/file/logigator-simulation.js"></script>

Module.onRuntimeInitialized = () => {
	console.log('Yay, it worked!');
};

To initialize a board, you can do as follows:

Module.initLinks(2); // Number of links on that board.
Module.initComponents(4); // Number of components on that board.
for (let i = 0; i < 4; i++) {
  // Allocate arrays for inputs and outputs in heap - further described below
  // ...
  
  Module.initComponent
  (
    i, // index of component to initialize
    1, // type id, determines which component to initialize - a list of all type ids can be found further below
    0x00000001, // pointer to array in heap holding indexes of the links going into the component - how to get an array into the heap is further documented down below
    0x00000010, // pointer to array in heap holding indexes of the links going out of the component
    1, // length of array located in 0x00000001
    1, // length of array located in 0x00000010
    0, // op1 - used for certain component types, ignored otherwise
    0 // op2 - used for certain component types, ignored otherwise
  );
  
  // release memory from allocated arrays to avoid memory leaks
  Module._free(0x00000001);
  Module._free(0x00000010);
}

Module.initBoard(); // finally, finish initialisation

To copy an array to heap, you can do:

function _arrayToHeap(typedArray) {
	const numBytes = typedArray.length * typedArray.BYTES_PER_ELEMENT;
	const ptr = Module._malloc(numBytes);
	const heapBytes = new Uint8Array(Module.HEAPU8.buffer, ptr, numBytes);
	heapBytes.set(new Uint8Array(typedArray.buffer));
	return ptr;
}

to retrieve data from heap (e.g. current state of links from board):

Module.HEAP8.slice(0x00000001 /*address of first byte*/, 0x00000010 /*address of last byte*/);

Functions

Function	Description
Module.start(ticks, ms);	Runs the simulation until either the ticks were simulated or the simulation time was reached.
Module.stop();	Stops the simulation if running. (Probably useless in webAssembly as active simulation locks current thread anyway.)
Module.getStatus();	Returns object with data for current state of the simulation
Module.getLinks();	Returns pointer with the states of all links (1 byte per element, Array length equals number of links on board)
Module.getComponents();	Return pointer with the states of all inputs and outputs of all components. Format: (component[0] inputs)(component[0] outputs)(component[1] inputs)(component[1] outputs)...(component[n] inputs)(component[n] outputs)
Module.triggerInput(/*index of component*/, /*0 = set, 1 = pulse*/, /*pointer to array of states for inputs*/);	Triggers a user input
Module.destroy();	Destroys current board. This is required before initializing a new board.

Component Types

Type ID	Name	Inputs	Outputs	Ops
1	NOT	1	1	x
2	AND	2 - 2^32	1	x
3	OR	2 - 2^32	1	x
4	XOR	2 - 2^32	1	x
5	DELAY	1	1	x
6	CLOCK	1	1	[0] => Ticks between clock pulses
10	Half Adder	2	2	x
11	Full Adder	3	2	x
12	ROM	1 - 16	1 - 64	[0..n] => Data for ROM (1 Byte per element)
13	D Flip-Flop	2	2	x
14	JK Flip-Flop	3	2	x
15	SR Flip-Flop	3	2	x
16	Random Number Generator	1	1 - 2^32	x
17	RAM	1 - 16	1 - 64	x
18	Decoder	1 - 32	1 - 2^32	x
19	Encoder	1 - 2^32	1 - 32	x
20	Multiplexer	3 - (31 + 2^31)	1	[0] => select address size
21	Demultiplexer	2 - 32	2 - 2^31	x
200	User Input	0	1 - 2^32	x

License

This Project is licensed under the MIT License - see the LICENSE.md file for details