YosysJS

YosysJS is a JavaScript port of Yosys done with Emscripten. It is primarily ment for building educational web applications. YosysJS is under development. A preview can be found here.

API Reference

Include yosysjs.js (not yosys.js!) in your HTML file:

<script type="text/javascript" src="path_to_yosysjs/yosysjs.js"></script>

Then initialize YosysJS:

// needed for YosysJS.dot_to_svg() and YosysJS.dot_into_svg()
YosysJS.load_viz();

// create a Yosys instance
var ys = YosysJS.create();

The created Yosys instance will reside in a hidden <iframe> in your page. You can pass the id of an iframe element or the DOM element itself as first parameter. Then this iframe will be used instead. You can also pass a <textarea> (id or DOM object). Then the textarea will be replaced by an iframe (with the same CSS style) and the value of the textarea (the text in it) will be executed as Yosys script.

There is also an optional 2nd parameter to YosysJS.create(), a callback function that is called as soon as the Yosys instance has been initialized. Set the first parameter to to an empty string if you want to use the callback function but don't want to specify an existing DOM element for the iframe.

<iframe id="ys_iframe" style="width: 100%;"></iframe>

...

var ys = YosysJS.create('ys_iframe', function() { console.log("ready."); });

Next you need to configure the new Yosys instance. Set the following member variables to configure the object (the values below reflect the default settings):

// Print all Yosys output messages to the iframe
ys.verbose = false;

// Print all Yosys output messages to the JavaScript console
ys.logprint = false;

// Echo back commands
ys.echo = false;

The virtual filesystem seen by Yosys can be accessed using the following methods:

// Create/write files
ys.write_file(filename, text);

// Read files
text = ys.read_file(filename);

// Read directory listing
listing = ys.read_dir('.');

And most importantly executing Yosys commands:

output_text = ys.run(command_string);

Creating SVG text from a DOT file (the Yosys show command per default writes to show.dot in YosysJS):

ys.run('show');
dot_text = ys.read_file('show.dot');
svg_text = YosysJS.dot_to_svg(dot_text);

Writing SVG directly into a <svg> element:

YosysJS.dot_into_svg(dot_text, svg_element_or_id);

WebWorker API Reference

The YosysJS.create()-based API described above creates a Yosys instance within the browser window main javascript thread. This means that whenever Yosys is running, the browser window becomes unresponsive. The following alternative API creates a Yosys instance within a separate WebWorker thread.

Creating a Yosys instance within a WebWorker:

function create_worker_callback() { ... }
var ys = YosysJS.create_worker(create_worker_callback);

Running a command in the Yosys WebWorker:

function run_callback(output_text, error_message() { ... }
ys.run(command_text, run_callback);

Accessing the virtual filesystem:

function write_file_callback() { ... }
ys.write_file(file_name, text_content, write_file_callback);

function read_file_callback(text_content) { ... }
ys.read_file(file_name, read_file_callback);

function read_dir_callback(file_list) { ... }
ys.read_dir(dir_name, read_dir_callback);

function remove_file_callback() { ... }
ys.remove_file(file_name, remove_file_callback);

Switching Yosys into verbose mode (i.e. write all messages to JavaScript console):

function verbose_callback() { ... }
ys.verbose(true, verbose_callback); // enable verbose mode
ys.verbose(false, verbose_callback); // disable verbose mode (default)

All callback arguments are optional. Requests are processes in-order. I.e. it is possible to issue a sequence of commands and only use a callback on the last command in the sequence. For example:

ys.write_file("input.v", verilog_input_text);
ys.run("design -reset; read_verilog input.v; synth; write_verilog output.v");
ys.read_file("output.v", (function(text){ console.log("Output: ", text); }));

Building YosysJS

The following is a step-by-step guide for building Emscripten and YosysJS. First create a build directory:

mkdir yosysjs_build
cd yosysjs_build

Optional: Remove dot-files from other/previous emsdk install:

rm -rf ~/.emscripten*

Then download and build Emscripten:

wget https://s3.amazonaws.com/mozilla-games/emscripten/releases/emsdk-portable.tar.gz
tar xvzf emsdk-portable.tar.gz
cd emsdk-portable
./emsdk install latest
./emsdk activate latest
./emsdk_env.sh
cd ..

Finally download Yosys and build YosysJS:

git clone https://github.com/YosysHQ/yosys.git
cd yosys
source ../emsdk-portable/emsdk_set_env.sh
make config-emcc
make
ls -l yosysjs-*