-
Notifications
You must be signed in to change notification settings - Fork 6
/
Copy pathyosysjs.in
155 lines (119 loc) · 5.18 KB
/
yosysjs.in
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
@header VlogHammer@
<h1>YosysJS</h1>
<p>YosysJS is a JavaScript port of Yosys done with <a href="http://emscripten.org/">Emscripten</a>.
It is primarily ment for building educational web applications. YosysJS is under development. A
preview can be found <a href="nogit/YosysJS/snapshot/">here</a>.</p>
<h2>API Reference</h2>
<p>Include <tt>yosysjs.js</tt> (not <tt>yosys.js</tt>!) in your HTML file:<pre>
<script type="text/javascript" src="<i>path_to_yosysjs</i>/yosysjs.js"></script>
</pre></p>
<p>Then initialize YosysJS:<pre>
// needed for YosysJS.dot_to_svg() and YosysJS.dot_into_svg()
YosysJS.load_viz();
// create a Yosys instance
var ys = YosysJS.create();
</pre></p>
<p>The created Yosys instance will reside in a hidden <tt><iframe></tt> 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 <tt><textarea></tt> (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.</p>
<p>There is also an optional 2nd parameter to <tt>YosysJS.create()</tt>, 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.<pre>
<iframe id="ys_iframe" style="width: 100%;"></iframe>
...
var ys = YosysJS.create('ys_iframe', function() { console.log("ready."); });
</pre></p>
<p>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):<pre>
// 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;
</pre></p>
<p>The virtual filesystem seen by Yosys can be accessed using the following methods:<pre>
// Create/write files
ys.write_file(filename, text);
// Read files
text = ys.read_file(filename);
// Read directory listing
listing = ys.read_dir('.');
</pre></p>
<p>And most importantly executing Yosys commands:<pre>
output_text = ys.run(command_string);
</pre></p>
<p>Creating SVG text from a DOT file (the Yosys <tt>show</tt> command per default
writes to <tt>show.dot</tt> in YosysJS):<pre>
ys.run('show');
dot_text = ys.read_file('show.dot');
svg_text = YosysJS.dot_to_svg(dot_text);
</pre></p>
<p>Writing SVG directly into a <tt><svg></tt> element:<pre>
YosysJS.dot_into_svg(dot_text, svg_element_or_id);
</pre></p>
<h2>WebWorker API Reference</h2>
<p>The <tt>YosysJS.create()</tt>-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.</p>
<p>Creating a Yosys instance within a WebWorker:<pre>
function create_worker_callback() { ... }
var ys = YosysJS.create_worker(create_worker_callback);
</pre></p>
<p>Running a command in the Yosys WebWorker:<pre>
function run_callback(output_text, error_message() { ... }
ys.run(command_text, run_callback);
</pre></p>
<p>Accessing the virtual filesystem:<pre>
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);
</pre></p>
<p>Switching Yosys into verbose mode (i.e. write all messages to JavaScript console):<pre>
function verbose_callback() { ... }
ys.verbose(true, verbose_callback); // enable verbose mode
ys.verbose(false, verbose_callback); // disable verbose mode (default)
</pre></p>
<p>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:<pre>
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); }));
</pre></p>
<h2>Building YosysJS</h2>
<p>The following is a step-by-step guide for building Emscripten and YosysJS. First
create a build directory:<pre>
mkdir yosysjs_build
cd yosysjs_build
</pre></p>
<p>Optional: Remove dot-files from other/previous emsdk install:<pre>
rm -rf ~/.emscripten*
</pre></p>
<p>Then download and build Emscripten:<pre>
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 ..
</pre></p>
<p>Finally download Yosys and build YosysJS:<pre>
git clone https://github.com/YosysHQ/yosys.git
cd yosys
source ../emsdk-portable/emsdk_set_env.sh
make config-emcc
make
ls -l yosysjs-*
</pre></p>
@footer@