Pink Squirrel Labs: Posts tagged 'racket'urn:http-www-pinksquirrellabs-com:-tags-racket-html2019-04-23T20:27:04ZFairylog : Multiplexer Macrosurn:http-www-pinksquirrellabs-com:-blog-2019-04-23-fairylog-multiplexer-macros2019-04-23T20:27:04Z2019-04-23T20:27:04Zpezi
<p>Multiplexers and demultiplexers are common tools in digital logic design. In Verilog, they are fairly simple to create whilst the amount of signals are small. In this post we’ll look at how Fairylog’s macros can make short work of generating mux/demux of any complexity, greatly reducing the amount of work and scope for hard-to-find bugs</p>
<div class="figure"><img src="http://www.pinksquirrellabs.com/img/fairylog/mux.png" alt="" />
<p class="caption"></p></div>
<!-- more-->
<h3 id="mux">MUX</h3>
<p>A mutliplexer in its most basic form takes in a bunch of inputs, and based on a selection input, outputs one of them.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="kn">#lang </span><span class="nn">fairylog</span>
<span class="c1">;2:1 mux</span>
<span class="p">(</span><span class="n">vmod</span> <span class="n">mux</span>
<span class="p">([</span><span class="n">sel</span> <span class="kd">#:input</span> <span class="kd">#:wire</span><span class="p">]</span>
<span class="p">[</span><span class="n">in_a</span> <span class="kd">#:input</span> <span class="kd">#:wire</span><span class="p">]</span>
<span class="p">[</span><span class="n">in_b</span> <span class="kd">#:input</span> <span class="kd">#:wire</span><span class="p">]</span>
<span class="p">[</span><span class="n">out</span> <span class="kd">#:output</span> <span class="kd">#:wire</span><span class="p">])</span>
<span class="p">(</span><span class="n">assign</span> <span class="n">out</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/case.html#(form._((lib._racket/private/more-scheme..rkt)._case))" style="color: inherit">case</a></span> <span class="n">sel</span>
<span class="p">[</span><span class="mi">0</span> <span class="n">in_a</span><span class="p">]</span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span> <span class="n">in_b</span><span class="p">])))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>This is about as simple as it gets. A 1 bit selection line that toggles the output between <code>in_a</code> and <code>in_b</code>. It produces this code and synths correctly to a MUX.</p>
<div class="brush: verilog">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6
7</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="k">module</span> <span class="n">mux</span> <span class="p">(</span>
<span class="k">input</span> <span class="kt">wire</span> <span class="n">sel</span> <span class="p">,</span>
<span class="k">input</span> <span class="kt">wire</span> <span class="n">in_a</span> <span class="p">,</span>
<span class="k">input</span> <span class="kt">wire</span> <span class="n">in_b</span> <span class="p">,</span>
<span class="k">output</span> <span class="kt">wire</span> <span class="n">out</span> <span class="p">);</span>
<span class="k">assign</span> <span class="n">out</span> <span class="o">=</span> <span class="p">((</span><span class="n">sel</span> <span class="o">==</span> <span class="mh">0</span><span class="p">)</span> <span class="o">?</span> <span class="n">in_a</span> <span class="o">:</span> <span class="n">in_b</span><span class="p">);</span>
<span class="k">endmodule</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>In real world scenarios, we are typically moving lots more data around. Often it is nice to compact the data in arrays (vectors).</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="kn">#lang </span><span class="nn">fairylog</span>
<span class="c1">;2:1 mux</span>
<span class="p">(</span><span class="n">vmod</span> <span class="n">mux</span>
<span class="p">([</span><span class="n">sel</span> <span class="kd">#:input</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="mi">1</span><span class="p">]]</span>
<span class="p">[</span><span class="n">in</span> <span class="kd">#:input</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="mi">2</span><span class="p">]]</span>
<span class="p">[</span><span class="n">out</span> <span class="kd">#:output</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="mi">1</span><span class="p">]])</span>
<span class="p">(</span><span class="n">assign</span> <span class="n">out</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/case.html#(form._((lib._racket/private/more-scheme..rkt)._case))" style="color: inherit">case</a></span> <span class="n">sel</span>
<span class="p">[</span><span class="mi">0</span> <span class="p">(</span><span class="n">in</span> <span class="mi">0</span><span class="p">)]</span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span> <span class="p">(</span><span class="n">in</span> <span class="mi">1</span><span class="p">)])))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Here we pass the bits in using the same port, and then select them out again in the <code>case</code> using the range selection syntax. You might think you can replace <code>case</code> with <code>(assign out (in sel))</code> but alas, this will not syth correctly to a MUX. For the tools to correctly infer a MUX you must supply a terminal case such as the <code>else</code> here, which Fairylog compiles out to a ternary expression.</p>
<div class="brush: verilog">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="k">module</span> <span class="n">mux</span> <span class="p">(</span>
<span class="k">input</span> <span class="kt">wire</span> <span class="n">sel</span> <span class="p">,</span>
<span class="k">input</span> <span class="kt">wire</span> <span class="n">in</span> <span class="p">,</span>
<span class="k">output</span> <span class="kt">wire</span> <span class="n">out</span> <span class="p">);</span>
<span class="k">assign</span> <span class="n">out</span> <span class="o">=</span> <span class="p">((</span><span class="n">sel</span> <span class="o">==</span> <span class="mh">1</span><span class="mb">'b0</span><span class="p">)</span> <span class="o">?</span> <span class="n">in</span><span class="p">[</span><span class="mh">0</span><span class="p">]</span> <span class="o">:</span> <span class="n">in</span><span class="p">[</span><span class="mh">1</span><span class="p">]);</span>
<span class="k">endmodule</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>This is ok for small switches, but in reality we often need much larger multiplexers. Not only will the sizes of the data be greater, but we often want to swtich multiple signals at the same time based on the same selector. Verilog also has no way of passing two-dimensional data, so if you want to switch between multiple sets of 8 bits of data, you have to either pass each set in explicitly, or “flatten” it all out into one vector and then switch it out appropriately using ranges. Writing all that code is very time consuming, error prone and hard to maintain. <em>note: Verilog does have some rudimentary generation capabilities of its own</em></p>
<h3 id="mux-macros">MUX macros</h3>
<p>Let’s see if we can automate the process somewhat. The ony important pieces are the names and sizes of the signals, and then how to map the output based on the selector. For example, what if we could write this to generate a mux:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">mux-gen</span>
<span class="n">my-mux</span>
<span class="p">[</span><span class="n">sel</span> <span class="mi">1</span><span class="p">]</span> <span class="c1">;1 bit selector</span>
<span class="p">[</span><span class="n">in</span> <span class="mi">2</span><span class="p">]</span> <span class="c1">;2 bit input</span>
<span class="p">[</span><span class="n">out</span> <span class="mi">1</span><span class="p">]</span> <span class="c1">;1 bit output</span>
<span class="c1">;output mapping</span>
<span class="p">([</span><span class="mi">0</span> <span class="p">(</span><span class="n">in</span> <span class="mi">0</span><span class="p">)]</span>
<span class="c1">; more cases here as you need them ...</span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span> <span class="p">(</span><span class="n">in</span> <span class="mi">1</span><span class="p">)]))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Let’s have a first go at it. <code>macro</code> is an alias for <a href="https://docs.racket-lang.org/syntax/Defining_Simple_Macros.html?q=define-syntax-parser#%28form._%28%28lib._syntax%2Fparse%2Fdefine..rkt%29._define-syntax-parser%29%29">define-syntax-parser</a> and provides all of Racket’s <a href="https://docs.racket-lang.org/syntax/stxparse-patterns.html">amazing macro system</a>.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 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</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">macro</span> <span class="n">mux-gen</span>
<span class="kd">#:datum-literals</span> <span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span><span class="p">)</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">name:id</span>
<span class="p">[</span><span class="n">selector:id</span> <span class="n">sel-size</span><span class="p">]</span>
<span class="p">[</span><span class="n">in:id</span> <span class="n">in-size</span><span class="p">]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span>
<span class="p">[</span><span class="n">out:id</span> <span class="n">out-size</span><span class="p">]</span>
<span class="p">([</span><span class="n">case-n:integer</span> <span class="n">res:expr</span><span class="p">]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span> <span class="n">else-res:expr</span><span class="p">]))</span>
<span class="o">#'</span><span class="p">(</span><span class="n">vmod</span> <span class="n">name</span>
<span class="p">([</span><span class="n">selector</span> <span class="kd">#:input</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="n">sel-size</span><span class="p">]]</span>
<span class="p">[</span><span class="n">in</span> <span class="kd">#:input</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="n">in-size</span><span class="p">]]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span>
<span class="p">[</span><span class="n">out</span> <span class="kd">#:output</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="n">out-size</span><span class="p">]])</span>
<span class="p">(</span><span class="n">assign</span>
<span class="n">out</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/case.html#(form._((lib._racket/private/more-scheme..rkt)._case))" style="color: inherit">case</a></span> <span class="n">selector</span>
<span class="p">[</span><span class="n">case-n</span> <span class="n">res</span><span class="p">]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span> <span class="n">else-res</span><span class="p">])))])</span>
<span class="p">(</span><span class="n">mux-gen</span>
<span class="n">my-mux</span>
<span class="p">[</span><span class="n">sel</span> <span class="mi">1</span><span class="p">]</span> <span class="c1">;1 bit selector</span>
<span class="p">[</span><span class="n">in</span> <span class="mi">2</span><span class="p">]</span> <span class="c1">;2 bit input</span>
<span class="p">[</span><span class="n">out</span> <span class="mi">1</span><span class="p">]</span> <span class="c1">;1 bit output</span>
<span class="c1">;output mapping</span>
<span class="p">([</span><span class="mi">0</span> <span class="p">(</span><span class="n">in</span> <span class="n">%0</span><span class="p">)]</span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span> <span class="p">(</span><span class="n">in</span> <span class="n">%1</span><span class="p">)]))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>This works and produces the same MUX as before. You can give it any amount of mappings in the case expression, as long as it ends with an <code>else</code> to ensure it gets synth’d to a MUX correctly. (in this case it doesn’t make sense to, since the input selector is only 1 bit)</p>
<p>Since we allow multiple <code>in</code> expressions you can also write this, like the first example.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6
7
8
9</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">mux-gen</span>
<span class="n">my-mux</span>
<span class="p">[</span><span class="n">sel</span> <span class="mi">1</span><span class="p">]</span> <span class="c1">;1 bit selector</span>
<span class="c1">; multiple inputs</span>
<span class="p">[</span><span class="n">in_a</span> <span class="mi">1</span><span class="p">]</span> <span class="c1">;2 bit input</span>
<span class="p">[</span><span class="n">in_b</span> <span class="mi">1</span><span class="p">]</span> <span class="c1">;2 bit input</span>
<span class="p">[</span><span class="n">out</span> <span class="mi">1</span><span class="p">]</span> <span class="c1">;1 bit output</span>
<span class="p">([</span><span class="mi">0</span> <span class="n">in_a</span><span class="p">]</span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span> <span class="n">in_b</span><span class="p">]))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>This is not very exciting at this stage. What we want is to be able to supply multiple input -> output mappings for different signals based on the same selector.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">mux-gen</span>
<span class="n">my-mux</span>
<span class="p">[</span><span class="n">sel</span> <span class="mi">1</span><span class="p">]</span> <span class="c1">;1 bit selector</span>
<span class="c1">;first input -> output mapping</span>
<span class="p">([</span><span class="n">a_signals</span> <span class="mi">2</span><span class="p">]</span> <span class="c1">;2 bit input</span>
<span class="p">[</span><span class="n">a_out</span> <span class="mi">1</span><span class="p">]</span> <span class="c1">;1 bit output</span>
<span class="c1">;output mapping</span>
<span class="p">([</span><span class="mi">0</span> <span class="p">(</span><span class="n">a_signals</span> <span class="mi">0</span><span class="p">)]</span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span> <span class="p">(</span><span class="n">a_signals</span> <span class="mi">1</span><span class="p">)]))</span>
<span class="c1">;another mapping</span>
<span class="p">([</span><span class="n">b_data</span> <span class="mi">16</span><span class="p">]</span> <span class="c1">;two sets of flattened 8 bit data</span>
<span class="p">[</span><span class="n">b_out</span> <span class="mi">8</span><span class="p">]</span> <span class="c1">;8-bit output</span>
<span class="p">([</span><span class="mi">0</span> <span class="p">(</span><span class="n">b_data</span> <span class="mi">7</span> <span class="mi">0</span><span class="p">)]</span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span> <span class="p">(</span><span class="n">b_data</span> <span class="mi">15</span> <span class="mi">8</span><span class="p">)]))</span>
<span class="c1">; ... as many mappings as we like</span>
<span class="p">)</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Really all we added here were some extra parens around the block of data after the <code>sel</code> so we can identifty it is a group, then added a new block of mappings. The change to the macro is quite simple:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">macro</span> <span class="n">mux-gen</span>
<span class="kd">#:datum-literals</span> <span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span><span class="p">)</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">name:id</span>
<span class="p">[</span><span class="n">selector:id</span> <span class="n">sel-size</span><span class="p">]</span>
<span class="p">([</span><span class="n">in:id</span> <span class="n">in-size</span><span class="p">]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span>
<span class="p">[</span><span class="n">out:id</span> <span class="n">out-size</span><span class="p">]</span>
<span class="p">([</span><span class="n">case-n:integer</span> <span class="n">res:expr</span><span class="p">]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span> <span class="n">else-res:expr</span><span class="p">]))</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)</span>
<span class="o">#'</span><span class="p">(</span><span class="n">vmod</span> <span class="n">name</span>
<span class="p">([</span><span class="n">selector</span> <span class="kd">#:input</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="n">sel-size</span><span class="p">]]</span>
<span class="p">[</span><span class="n">in</span> <span class="kd">#:input</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="n">in-size</span><span class="p">]]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span>
<span class="p">[</span><span class="n">out</span> <span class="kd">#:output</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="n">out-size</span><span class="p">]]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)</span>
<span class="p">(</span><span class="n">assign</span>
<span class="n">out</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/case.html#(form._((lib._racket/private/more-scheme..rkt)._case))" style="color: inherit">case</a></span> <span class="n">selector</span>
<span class="p">[</span><span class="n">case-n</span> <span class="n">res</span><span class="p">]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span> <span class="n">else-res</span><span class="p">]))</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>We have put in the extra parens and slapped in some additional <code>...</code> to indicate the block can be repeated. Then, a few more <code>...</code> in the syntax output where we’d like the generated code to be repeated, and we are done. Take special note of the <code>... ...</code> that now appears for the <code>in</code> ports. This is because we now have two nested layers of input ports and we wish to unwrap both of them into the port list. It produces this Verilog code:</p>
<div class="brush: verilog">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6
7
8
9</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="k">module</span> <span class="n">my</span><span class="o">-</span><span class="n">mux</span> <span class="p">(</span>
<span class="k">input</span> <span class="kt">wire</span> <span class="p">[</span><span class="mh">0</span><span class="o">:</span><span class="mh">0</span><span class="p">]</span> <span class="n">sel</span> <span class="p">,</span>
<span class="k">input</span> <span class="kt">wire</span> <span class="p">[</span><span class="mh">1</span><span class="o">:</span><span class="mh">0</span><span class="p">]</span> <span class="n">a_signals</span> <span class="p">,</span>
<span class="k">input</span> <span class="kt">wire</span> <span class="p">[</span><span class="mh">15</span><span class="o">:</span><span class="mh">0</span><span class="p">]</span> <span class="n">b_data</span> <span class="p">,</span>
<span class="k">output</span> <span class="kt">wire</span> <span class="p">[</span><span class="mh">0</span><span class="o">:</span><span class="mh">0</span><span class="p">]</span> <span class="n">a_out</span> <span class="p">,</span>
<span class="k">output</span> <span class="kt">wire</span> <span class="p">[</span><span class="mh">7</span><span class="o">:</span><span class="mh">0</span><span class="p">]</span> <span class="n">b_out</span> <span class="p">);</span>
<span class="k">assign</span> <span class="n">a_out</span> <span class="o">=</span> <span class="p">((</span><span class="n">sel</span> <span class="o">==</span> <span class="mh">0</span><span class="p">)</span> <span class="o">?</span> <span class="n">a_signals</span><span class="p">[</span><span class="mh">0</span><span class="p">]</span> <span class="o">:</span> <span class="n">a_signals</span><span class="p">[</span><span class="mh">1</span><span class="p">]);</span>
<span class="k">assign</span> <span class="n">b_out</span> <span class="o">=</span> <span class="p">((</span><span class="n">sel</span> <span class="o">==</span> <span class="mh">0</span><span class="p">)</span> <span class="o">?</span> <span class="n">b_data</span><span class="p">[</span><span class="mh">7</span> <span class="o">:</span> <span class="mh">0</span><span class="p">]</span> <span class="o">:</span> <span class="n">b_data</span><span class="p">[</span><span class="mh">15</span> <span class="o">:</span> <span class="mh">8</span><span class="p">]);</span>
<span class="k">endmodule</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>This little macro is now capable of generating huge custom MUX’s to your specifications. Rejoice!</p>
<h3 id="demux">DEMUX</h3>
<p>The demultiplexer is essentially the reverse - it takes in one input, and dispatches it to one of multiple outputs based on a selector. Like the multiplexer, we’d typically need to do this for several signals at the same time. This is silghtly more tricky to write, and there are a few ways to do it. Here is what we are aiming at:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">vmod</span> <span class="n">demux</span>
<span class="p">([</span><span class="n">sel</span> <span class="kd">#:input</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="mi">1</span><span class="p">]]</span>
<span class="p">[</span><span class="n">in</span> <span class="kd">#:input</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="mi">1</span><span class="p">]]</span>
<span class="p">[</span><span class="n">out</span> <span class="kd">#:input</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">2</span><span class="p">]])</span>
<span class="p">(</span><span class="n">always</span> <span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._*))" style="color: inherit">*</a></span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="n">out</span> <span class="mi">0</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/case.html#(form._((lib._racket/private/more-scheme..rkt)._case))" style="color: inherit">case</a></span> <span class="n">sel</span>
<span class="p">[</span><span class="mi">0</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="n">out</span> <span class="mi">0</span><span class="p">)</span> <span class="n">in</span><span class="p">]</span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="n">out</span> <span class="mi">1</span><span class="p">)</span> <span class="n">in</span><span class="p">])))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>As you would imagine, we’d like to support mutliple distinct output signals as well as combined signals like in the above example. An important point here is that we must make sure all outputs are defaulted to something (zero) otherwise it won’t synth properly.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">macro</span> <span class="n">demux-gen</span>
<span class="kd">#:datum-literals</span> <span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span><span class="p">)</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span>
<span class="n">name:id</span>
<span class="p">[</span><span class="n">selector:id</span> <span class="n">sel-size:expr</span><span class="p">]</span>
<span class="p">([</span><span class="n">in:id</span> <span class="n">in-size:expr</span><span class="p">]</span>
<span class="p">[</span><span class="n">out:id</span> <span class="n">out-size:expr</span><span class="p">]</span> <span class="n"><a href="http://docs.racket-lang.org/syntax/stxparse-patterns.html#(form._((lib._syntax/parse..rkt)._......+))" style="color: inherit">...+</a></span><span class="p">)</span>
<span class="p">([</span><span class="n">case-n:integer</span> <span class="n">targ:expr</span> <span class="n">source:expr</span><span class="p">]</span> <span class="n"><a href="http://docs.racket-lang.org/syntax/stxparse-patterns.html#(form._((lib._syntax/parse..rkt)._......+))" style="color: inherit">...+</a></span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span> <span class="n">else-targ:expr</span> <span class="n">else-source:expr</span><span class="p">]))</span>
<span class="o">#'</span><span class="p">(</span><span class="n">vmod</span> <span class="n">name</span>
<span class="p">([</span><span class="n">selector</span> <span class="kd">#:input</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="n">sel-size</span><span class="p">]]</span>
<span class="p">[</span><span class="n">in</span> <span class="kd">#:input</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="n">in-size</span><span class="p">]]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span>
<span class="p">[</span><span class="n">out</span> <span class="kd">#:output</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="n">out-size</span><span class="p">]]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)</span>
<span class="p">(</span><span class="n">always</span> <span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._*))" style="color: inherit">*</a></span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/begin.html#(form._((quote._~23~25kernel)._begin))" style="color: inherit">begin</a></span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="p">[</span><span class="n">out</span> <span class="mi">0</span><span class="p">]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/case.html#(form._((lib._racket/private/more-scheme..rkt)._case))" style="color: inherit">case</a></span> <span class="n">selector</span>
<span class="p">[</span><span class="n">case-n</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="n">targ</span> <span class="n">source</span><span class="p">)]</span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="n">else-targ</span> <span class="n">else-source</span><span class="p">)])))</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>This is similar to the MUX implementation. Here we have used <code>...+</code> meaning “at least one of the preceding” rather than <code>...</code> that means “zero or more of the preceding”. The MUX macro would also benefit from this change. Other than the actual syntax generated, the only change here is that we have multiple <code>out</code> signals for one <code>in</code> signal.</p>
<h3 id="custom-code">Custom code</h3>
<p>Whilst the generated <code>case</code> expressions are sufficient for most implementations, sometimes you might want something more custom. For example, let’s say we wanted to determine the output of the MUX by looking at a range of the input bits, or we wanted to perform some other custom comparison.</p>
<p>It would be nice then if we could choose to override the normal <code>case</code> or <code>always</code> generation and supply, <em>for that mapping</em>, our own expression to use instead. Something like this:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">mux-gen</span>
<span class="n">my_mux</span>
<span class="p">[</span><span class="n">sel</span> <span class="mi">8</span><span class="p">]</span> <span class="c1">;8 bit selector</span>
<span class="c1">;first input -> output mapping</span>
<span class="p">([</span><span class="n">a_signals</span> <span class="mi">8</span><span class="p">]</span> <span class="c1">;8 bit input</span>
<span class="p">[</span><span class="n">a_out</span> <span class="mi">4</span><span class="p">]</span> <span class="c1">;4 bit output</span>
<span class="kd">#:custom</span>
<span class="c1">;check if any of the upper 4 bits are set</span>
<span class="p">(</span><span class="n">assign</span> <span class="n">a_out</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((quote._~23~25kernel)._if))" style="color: inherit">if</a></span> <span class="p">(</span><span class="err">|</span> <span class="p">(</span><span class="n">sel</span> <span class="mi">7</span> <span class="mi">4</span><span class="p">))</span>
<span class="p">(</span><span class="n">a_signals</span> <span class="mi">7</span> <span class="mi">4</span><span class="p">)</span>
<span class="p">(</span><span class="n">a_signals</span> <span class="mi">3</span> <span class="mi">0</span><span class="p">))))</span>
<span class="c1">; ... as many mappings with auto or custom as we like</span>
<span class="p">)</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>We can achieve this fairly easily by introducing a helper macro that deals with the body of the expression, simply passing along whatever was passed in when <code>#:custom</code> is detected:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 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</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">macro</span>
<span class="n">mux-gen-inner</span>
<span class="kd">#:datum-literals</span> <span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span><span class="p">)</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span> <span class="kd">#:custom</span> <span class="n">custom-expr</span><span class="p">)</span>
<span class="o">#'</span><span class="n">custom-expr</span><span class="p">]</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">out</span> <span class="n">selector</span>
<span class="p">([</span><span class="n">case-n:integer</span> <span class="n">res:expr</span><span class="p">]</span> <span class="n"><a href="http://docs.racket-lang.org/syntax/stxparse-patterns.html#(form._((lib._syntax/parse..rkt)._......+))" style="color: inherit">...+</a></span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span> <span class="n">else-res:expr</span><span class="p">]))</span>
<span class="o">#'</span><span class="p">(</span><span class="n">assign</span>
<span class="n">out</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/case.html#(form._((lib._racket/private/more-scheme..rkt)._case))" style="color: inherit">case</a></span> <span class="n">selector</span>
<span class="p">[</span><span class="n">case-n</span> <span class="n">res</span><span class="p">]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span> <span class="n">else-res</span><span class="p">]))])</span>
<span class="p">(</span><span class="n">macro</span>
<span class="n">mux-gen</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">name:id</span>
<span class="p">[</span><span class="n">selector:id</span> <span class="n">sel-size</span><span class="p">]</span>
<span class="p">([</span><span class="n">in:id</span> <span class="n">in-size</span><span class="p">]</span> <span class="n"><a href="http://docs.racket-lang.org/syntax/stxparse-patterns.html#(form._((lib._syntax/parse..rkt)._......+))" style="color: inherit">...+</a></span>
<span class="p">[</span><span class="n">out:id</span> <span class="n">out-size</span><span class="p">]</span>
<span class="n">body-expr</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)</span>
<span class="o">#'</span><span class="p">(</span><span class="n">vmod</span> <span class="n">name</span>
<span class="p">([</span><span class="n">selector</span> <span class="kd">#:input</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="n">sel-size</span><span class="p">]]</span>
<span class="p">[</span><span class="n">in</span> <span class="kd">#:input</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="n">in-size</span><span class="p">]]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span>
<span class="p">[</span><span class="n">out</span> <span class="kd">#:output</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="n">out-size</span><span class="p">]]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)</span>
<span class="p">(</span><span class="n">mux-gen-inner</span> <span class="n">out</span> <span class="n">selector</span> <span class="n">body-expr</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>And we are done. You could take this any way you like, even creating whole new languages over the top of Fairylog.</p>
<h3 id="conclusion">Conclusion</h3>
<p>This post intended to show some of the ways that Fairylog can help generate tons of boilerplate code for you - it is merely scratching the surface, however, as the Racket macro system is vast, and definitely something you should look into!</p>Fairylogurn:http-www-pinksquirrellabs-com:-blog-2019-04-17-fairylog2019-04-17T14:02:55Z2019-04-17T14:02:55Zpezi
<p>Over the last few months I have been working on yet another new language, this time for programming FPGAs. This post will provide a short introduction to Fairylog by way of building some custom hardware to read a pair of Nintendo pads.</p>
<blockquote class="twitter-tweet" data-lang="en">
<p lang="en" dir="ltr">Realtime 24bit colour rotozoomer controlled by a NES pad. CPU, video hardware and assembler built in my various <a href="https://twitter.com/racketlang?ref_src=twsrc%5Etfw">@racketlang</a> langs. Display from <a href="https://twitter.com/adafruit?ref_src=twsrc%5Etfw">@adafruit</a>. Debugger and supporting tools <a href="https://twitter.com/hashtag/csharp?src=hash&amp;ref_src=twsrc%5Etfw">#csharp</a> & <a href="https://twitter.com/hashtag/fsharp?src=hash&amp;ref_src=twsrc%5Etfw">#fsharp</a>. Complete with dramatic music! 😃 <a href="https://twitter.com/hashtag/fpga?src=hash&amp;ref_src=twsrc%5Etfw">#fpga</a> <a href="https://t.co/8gVNfg4uLD">pic.twitter.com/8gVNfg4uLD</a></p>— Ross McKinlay (@pezi_pink) <a href="https://twitter.com/pezi_pink/status/1103716209537794048?ref_src=twsrc%5Etfw">March 7, 2019</a></blockquote>
<script async="async" src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
<!-- more-->
<h3 id="fpga">FPGA</h3>
<p>After my last foray back into some electronics (see the previous post) I decided I’d like to focus more on hardware again. This time around, I thought it was high time I examined and learned about FPGAs properly - not sure why I didn’t do this years ago, but here we are.</p>
<p>If you don’t know what an FPGA is, it is essentially a huge grid of programmable logic cells that you can arrange in any way you like. This enables you to create a custom piece of hardware that is capable of becoming any digital system you can imagine. A good introduction can be found at <a href="https://www.youtube.com/watch?v=gUsHwi4M4xE">this EEVBlog video</a></p>
<p>In order to program one of these devices, you typically write code in a hardware description language like <a href="https://en.wikipedia.org/wiki/Verilog">Verilog</a> or <a href="https://en.wikipedia.org/wiki/VHDL">VHDL</a>. Now, I have never wrote any HDL code before, but after examining Verilog for a few hours I knew we were not going to be friends.</p>
<p>Instead, I decided I would learn Verilog by writing my own source-to-source compiler and language for it. Probably not the best way to go about it, but it kept me out of trouble for a couple of weeks.</p>
<h3 id="fairylog">Fairylog</h3>
<p>And so <a href="https://github.com/pezipink/fairylog">Fairylog</a> was born. Fairylog is a <a href="https://racket-lang.org/">Racket</a> language (of course) which aims to be quite like Verilog, with less redundant syntax, Racket macros, and several additional compile-time features that Verilog seems to be lacking.</p>
<p>Fairylog <em>extends</em> Racket rather than replaces it, which means you can use all of Racket wherever you like in Fairylog code to help you generate stuff.</p>
<p>Verilog is a fairly large language, which has two not-very-distinct sides to it. Ultimately, Verilog is compiled into something that is either run through a <em>simulator</em>, or <em>sythesised</em> and programmed onto real hardware. The language itself has some blurred lines around what is synthesisable and what is not, which is not at all obvious and differs between toolchains and chips.</p>
<p>Fairylog is aimed at <em>synthesisable</em> Verilog code. I have not yet tried a simulator and don’t plan on doing so for now, since I am much more interested in getting the stuff running straight on the hardware. For that reason, you won’t find many of the simulation-only language constructs from Verilog in Fairylog. Since I didn’t (and still don’t) really understand which bits are relevant and which aren’t, the language already has some redundant stuff in it and is still missing some areas of Verilog which I have not got around to playing with yet.</p>
<p>It is fully capable, however, if still somewhat of a rough personal experiment for mostly my own use. I did manage to design and build a debuggable 32 bit computer with it, along with a 64x64 RGB LED matrix in 24 bit colour and dedicated video hardware - you can see a couple of videos here.</p>
<blockquote class="twitter-tweet" data-lang="en">
<p lang="en" dir="ltr">64x64 <a href="https://twitter.com/adafruit?ref_src=twsrc%5Etfw">@adafruit</a> RGB LED matrix running on an FPGA programmed with my new language <a href="https://twitter.com/hashtag/fairylog?src=hash&amp;ref_src=twsrc%5Etfw">#fairylog</a> - watch this space ! // <a href="https://twitter.com/racketlang?ref_src=twsrc%5Etfw">@racketlang</a> <a href="https://t.co/ekaxKVZ5cZ">pic.twitter.com/ekaxKVZ5cZ</a></p>— Ross McKinlay (@pezi_pink) <a href="https://twitter.com/pezi_pink/status/1095403160284352513?ref_src=twsrc%5Etfw">February 12, 2019</a></blockquote>
<script async="async" src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
<blockquote class="twitter-tweet" data-lang="en">
<p lang="en" dir="ltr">Realtime hardware plasma 😃3 bit colour, no cpu, no ram blocks <a href="https://twitter.com/hashtag/fpga?src=hash&amp;ref_src=twsrc%5Etfw">#fpga</a> <a href="https://twitter.com/hashtag/Fairylog?src=hash&amp;ref_src=twsrc%5Etfw">#Fairylog</a> <a href="https://t.co/9vQurYgMy2">pic.twitter.com/9vQurYgMy2</a></p>— Ross McKinlay (@pezi_pink) <a href="https://twitter.com/pezi_pink/status/1095807544457678853?ref_src=twsrc%5Etfw">February 13, 2019</a></blockquote>
<script async="async" src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
<blockquote class="twitter-tweet" data-lang="en">
<p lang="en" dir="ltr">Remember the 3-bit hardware plasma? Here's a 24-bit colour version, this time in software. Running on a custom built CPU and video hardware, outputting to a 64x64 <a href="https://twitter.com/adafruit?ref_src=twsrc%5Etfw">@adafruit</a> RGB LED matrix. Built from the ground up in my forthcoming language <a href="https://twitter.com/hashtag/fairylog?src=hash&amp;ref_src=twsrc%5Etfw">#fairylog</a> // <a href="https://twitter.com/racketlang?ref_src=twsrc%5Etfw">@racketlang</a> <a href="https://twitter.com/hashtag/FPGA?src=hash&amp;ref_src=twsrc%5Etfw">#FPGA</a> <a href="https://t.co/YDGPol2ORV">pic.twitter.com/YDGPol2ORV</a></p>— Ross McKinlay (@pezi_pink) <a href="https://twitter.com/pezi_pink/status/1100132467707707395?ref_src=twsrc%5Etfw">February 25, 2019</a></blockquote>
<script async="async" src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
<blockquote class="twitter-tweet" data-lang="en">
<p lang="en" dir="ltr">My cpu now has a working call stack and separate data stack. To celebrate, I have wrote this small but colourful and all-realtime chessboard zoomer, which uses neither of them <a href="https://t.co/txLiqY42ZH">pic.twitter.com/txLiqY42ZH</a></p>— Ross McKinlay (@pezi_pink) <a href="https://twitter.com/pezi_pink/status/1102937308771295232?ref_src=twsrc%5Etfw">March 5, 2019</a></blockquote>
<script async="async" src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
<h3 id="hello-world">Hello World</h3>
<p>To show you how Fairylog works, we need a project. Most hardware stuff gets big quite quickly, so as a small intro we’ll write a piece of hardware that can read the data from two Nintendo gamepads.</p>
<p>But first, the absolute basics. The hello world of the hardware world is, of course, flashing some LEDs. Grab your favourite FPGA and download Fairylog from the <a href="https://pkgs.racket-lang.org/package/Fairylog">Racket package manager</a>. (note: it is out of scope to try and properly teach either Racket or Verilog here, hopefully you know some of both)</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="kn">#lang </span><span class="nn">fairylog</span>
<span class="p">(</span><span class="n">vmod</span> <span class="n">blinky</span>
<span class="p">([</span><span class="n">clk_100mhz</span> <span class="kd">#:input</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="mi">1</span><span class="p">]]</span> <span class="c1">; master clock signal</span>
<span class="p">[</span><span class="n">board_leds</span> <span class="kd">#:output</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">4</span><span class="p">]</span> <span class="mi">0</span><span class="p">])</span> <span class="c1">; leds on FPGA board</span>
<span class="p">(</span><span class="n">locals</span>
<span class="p">[</span><span class="n">counter</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">24</span><span class="p">]])</span>
<span class="p">(</span><span class="n">always</span> <span class="p">([</span><span class="kd">#:posedge</span> <span class="n">clk_100mhz</span><span class="p">])</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/begin.html#(form._((quote._~23~25kernel)._begin))" style="color: inherit">begin</a></span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="n">counter</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="n">counter</span> <span class="mi">1</span><span class="p">))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/when_unless.html#(form._((lib._racket/private/letstx-scheme..rkt)._when))" style="color: inherit">when</a></span> <span class="p">(</span><span class="n">&</span> <span class="n">counter</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="n">board_leds</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="n">board_leds</span> <span class="mi">1</span><span class="p">))))))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>A Fairylog program is represented by a bunch of .rkt files, each of which may have several Verilog modules in it. By default, when you compile the program (usually from the REPL) Fairylog will produce a .v file for each .rkt file that it finds containing module code, into the same directory. You can then use these files as part of your project in the huge toolchain from whichever vendor’s FPGA you own.</p>
<p>As you can see, <code>vmod</code> creates a named module. It is followed by a list of input and output <em>ports</em>. Each port must be marked as <code>#:input</code>, <code>#:output</code> or <code>#:inout</code>. A port must also have a type - all of the standard Verilog ones are supported - here we are using the most common types of <code>#:wire</code> and <code>#:reg</code>. Finally, you are able to specify the size of the port in bits, along with a default value if it is of type <code>#:reg</code></p>
<p>Verilog requires that you specify sizes for everything in the awkward syntax of <code>[msb : lsb]</code>. Since 95% of the time you simply want <em>n</em> bits, Fairylog provides the shorthand you see in the above code. However, it does support the full Verilog syntax as well should you want it:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="c1">;these definitions are equivalent and define a 4-bit reg</span>
<span class="p">[</span><span class="n">board_leds</span> <span class="kd">#:output</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">4</span><span class="p">]]</span>
<span class="p">[</span><span class="n">board_leds</span> <span class="kd">#:output</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">3</span> <span class="mi">0</span><span class="p">]]</span> <span class="c1">;verilog style</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Next up is the module body itself. The <code>locals</code> form introduces locally scoped wires and regs. The syntax is the same as the port syntax except you can’t specify directions.</p>
<p>The <code>always</code> block has a number of uses in Verilog, although it can be quite confusing at times as to which you should use. Fairylog attempts to make this a bit simpler by not allowing code that doesn’t make sense inside an <code>always</code> block.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">always</span> <span class="p">([</span><span class="kd">#:posedge</span> <span class="n">clk_100mhz</span><span class="p">])</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/begin.html#(form._((quote._~23~25kernel)._begin))" style="color: inherit">begin</a></span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="n">counter</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="n">counter</span> <span class="mi">1</span><span class="p">))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/when_unless.html#(form._((lib._racket/private/letstx-scheme..rkt)._when))" style="color: inherit">when</a></span> <span class="p">(</span><span class="n">&</span> <span class="n">counter</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="n">board_leds</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="n">board_leds</span> <span class="mi">1</span><span class="p">)</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>In this example you see <code>always</code> is followed by a Verilog <em>sensitivity list</em>. In this case it indicates that the code to follow should execute on the rising edge of the <code>clk_100mhz</code> signal. Because of this, all <em>assignments</em> that happen in the body will implicitly be <em>non-blocking</em> (the <code><=</code> operator in Verilog parlance) . The sensitivity list works as you would expect it to if you know Verilog - you can <code>or</code> stuff together and use <code>#:negedge</code> as well as <code>#:posedge</code>.</p>
<p>If you want to use Verilog’s other <code>always</code> form, <code>always @(*)</code>, you can use Fairylog’s <code>(always * expressions ...)</code>. When inside this form, all <em>assignments</em> are implictitly <em>blocking</em> (using the <code>=</code> operator)</p>
<p><strong><em>It is not possible to use incorrect mixed blocking/non-blocking operators in a Fairylog program</em></strong></p>
<p>Finally, the body contains some familiar Racket forms like <code>begin</code>, <code>when</code> and <code>set</code>. You can also use other Racket style flow control such as <code>cond</code> <code>if</code> <code>unless</code> <code>case</code> and so on, as we will see. <code>(& counter)</code> is an example of using one of Verilog’s special unary operators known as a <em>reduction operator</em>. This one in particular, <code>&</code>, tests if all the bits are set on the given operand. The whole suite of Verilog operators are supported, but in the prefix style as preferred by Lisp.</p>
<p><em>note: because Verilog and Racket share some forms with the same name, if you explicitly need a Racket one in some ad-hoc code, they have been renamed to have a r: prefix, eg <em>(r:begin …) (r:case …)</em></em></p>
<h3 id="macros">Macros</h3>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">always</span> <span class="p">([</span><span class="kd">#:posedge</span> <span class="n">clk_100mhz</span><span class="p">])</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/begin.html#(form._((quote._~23~25kernel)._begin))" style="color: inherit">begin</a></span>
<span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span>
<span class="p">))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>This code is so common in Verilog that it quickly becomes tiring to write it all the time. Thankfully we have Racket’s macro system on hand to help:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">macro</span> <span class="n">always-pos</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">clock</span> <span class="n">exprs</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)</span>
<span class="o">#'</span><span class="p">(</span><span class="n">always</span> <span class="p">([</span><span class="kd">#:posedge</span> <span class="n">clock</span><span class="p">])</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/begin.html#(form._((quote._~23~25kernel)._begin))" style="color: inherit">begin</a></span> <span class="n">exprs</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">))])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p><code>macro</code> here is simply <a href="https://docs.racket-lang.org/syntax/Defining_Simple_Macros.html?q=define-syntax-parser#%28form._%28%28lib._syntax%2Fparse%2Fdefine..rkt%29._define-syntax-parser%29%29">define-syntax-parser</a> in disguise, provided to you by Fairylog. You can of course bring in whatever Racket libraries you like and use the whole shooting match. The <code>always-pos</code> macro is already provided to you out of the non-existent box by Fairylog.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="kn">#lang </span><span class="nn">fairylog</span>
<span class="p">(</span><span class="n">vmod</span> <span class="n">blinky</span>
<span class="p">([</span><span class="n">clk_100mhz</span> <span class="kd">#:input</span> <span class="kd">#:wire</span><span class="p">]</span> <span class="c1">; master clock signal</span>
<span class="p">[</span><span class="n">board_leds</span> <span class="kd">#:output</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">4</span><span class="p">]])</span> <span class="c1">; leds on FPGA board</span>
<span class="p">(</span><span class="n">locals</span>
<span class="p">[</span><span class="n">counter</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">24</span><span class="p">]])</span>
<span class="p">(</span><span class="n">always-pos</span> <span class="n">clk_100mhz</span>
<span class="p">(</span><span class="n">inc</span> <span class="n">counter</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/when_unless.html#(form._((lib._racket/private/letstx-scheme..rkt)._when))" style="color: inherit">when</a></span> <span class="p">(</span><span class="n">&</span> <span class="n">counter</span><span class="p">)</span>
<span class="p">(</span><span class="n">inc</span> <span class="n">board_leds</span><span class="p">))))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>That’s a bit nicer. In case you were wondering, the compiled code looks like this:</p>
<div class="brush: verilog">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="k">module</span> <span class="n">blinky</span> <span class="p">(</span>
<span class="k">input</span> <span class="kt">wire</span> <span class="n">clk_100mhz</span> <span class="p">,</span>
<span class="k">output</span> <span class="kt">reg</span> <span class="p">[</span><span class="mh">3</span><span class="o">:</span><span class="mh">0</span><span class="p">]</span> <span class="n">board_leds</span> <span class="p">);</span>
<span class="kt">reg</span> <span class="p">[</span><span class="mh">23</span><span class="o">:</span> <span class="mh">0</span><span class="p">]</span> <span class="n">counter</span> <span class="p">;</span>
<span class="k">always</span> <span class="p">@(</span><span class="k">posedge</span> <span class="n">clk_100mhz</span><span class="p">)</span>
<span class="k">begin</span>
<span class="n">counter</span> <span class="o"><=</span> <span class="p">(</span><span class="n">counter</span> <span class="o">+</span> <span class="mh">1</span><span class="p">);</span>
<span class="k">if</span><span class="p">(</span><span class="o">&</span><span class="n">counter</span><span class="p">)</span>
<span class="k">begin</span>
<span class="n">board_leds</span> <span class="o"><=</span> <span class="p">(</span><span class="n">board_leds</span> <span class="o">+</span> <span class="mh">1</span><span class="p">);</span>
<span class="k">end</span>
<span class="k">end</span>
<span class="k">endmodule</span>
</pre></div>
</td></tr></tbody></table>
</div>
<h3 id="number-literals-ranges-and-arrays">Number literals, Ranges and Arrays</h3>
<p>Verilog is very picky about its numbers. It does let you use decimal literals, which are always interpreted as 32 bit integers - you must be careful with these as they can lead to many bugs. Fairylog also supports decimal literals in the same manner. If you write a number simply as <code>42</code> then expect the same behavior.</p>
<p>Other than that, Verilog expects you to fully qualify every number with both its radix and amount of bits followed by the actual literal, eg <code>8'h7</code> <code>8'b1</code> <code>10'd20</code> and so on. Fairylog supports this full syntax with the slightly more sane <code>size_radix_literal</code> eg</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">locals</span>
<span class="p">[</span><span class="n">a</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">8</span><span class="p">]</span> <span class="n">8_16_FF</span><span class="p">]</span>
<span class="p">[</span><span class="n">b</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">8</span><span class="p">]</span> <span class="n">8_2_10101010</span><span class="p">])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>These literals are checked at compile time and will error if they don’t make sense.</p>
<p>Since you are often writing binary and hex values, Fairylog offers a shorthand literal syntax where the size will be inferred from the literal itself. These are very handy and mostly eliminate the need for the fully qualified syntax:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">locals</span>
<span class="p">[</span><span class="n">a</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">8</span><span class="p">]</span> <span class="n">$FF</span><span class="p">]</span>
<span class="p">[</span><span class="n">b</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">8</span><span class="p">]</span> <span class="n">%1010_1010</span><span class="p">])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>For the hex literals, the inferred size will be the maximum based on the number of supplied characters, rather than the actual number. For example, <code>$FF</code> <code>$1f</code> and <code>$0f</code> are all inferred as a size of 8.</p>
<p>Binary literals can have any amount of underscores in them to help visually separate numbers of bits.</p>
<p>In general, most assignment expressions are compile time checked. Unlike most Verilog implementations, you will get warnings when stuff does not fit or would be truncated! Be sure to check your warnings, they will catch many a hard to spot Verilog bug. Not everything is checked yet, however …</p>
<p>To extract a range of bits from an operand, treat the operand as if it were a function:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">locals</span>
<span class="p">[</span><span class="n">a</span> <span class="kd">#:reg</span> <span class="p">[(</span><span class="n">r:*</span> <span class="mi">4</span> <span class="mi">2</span><span class="p">)]]</span> <span class="c1">; you can use any racket expressions in these!</span>
<span class="p">[</span><span class="n">b</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="p">(</span><span class="n">a</span> <span class="mi">1</span><span class="p">)]</span> <span class="c1">; bit 1 of a</span>
<span class="p">[</span><span class="n">c</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="mi">3</span><span class="p">]</span> <span class="p">(</span><span class="n">a</span> <span class="mi">7</span> <span class="mi">5</span><span class="p">)])</span> <span class="c1">; bits 7 to 5 of a</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>And finally, use the following syntax to declare and access an array. The range syntax will also work for arrays, you must specify all dimensions followed by either a single index or range pair as normal - this will be checked at compile time.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">locals</span>
<span class="p">[</span><span class="n">memory_array</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">32</span><span class="p">]</span> <span class="p">(</span><span class="n">array</span> <span class="mi">16</span><span class="p">)]</span>
<span class="p">[</span><span class="n">a</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="mi">32</span><span class="p">]</span> <span class="p">(</span><span class="n">memory_array</span> <span class="mi">0</span><span class="p">)]</span> <span class="c1">; first 32 bits</span>
<span class="p">[</span><span class="n">b</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="p">(</span><span class="n">memory_array</span> <span class="mi">0</span> <span class="mi">2</span><span class="p">)]</span> <span class="c1">; second bit of first 32 bits</span>
<span class="p">[</span><span class="n">c</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="p">(</span><span class="n">memory_array</span> <span class="mi">0</span> <span class="mi">7</span> <span class="mi">0</span><span class="p">)])</span> <span class="c1">; low byte of first 32 bits</span>
</pre></div>
</td></tr></tbody></table>
</div>
<h3 id="nintendo-pads">Nintendo Pads</h3>
<p>With the basics out of the way, let’s try to do something useful. The NES pad is basically a <a href="https://en.wikipedia.org/wiki/Shift_register">4021 shift register</a>. It takes a parallel interface (8 button signals) and turns them into a serial interface we can read using 3 pins rather than 8. The important pins are <strong>Latch</strong>, <strong>Clock</strong>, and <strong>Data</strong>. In order to read the state of the buttons, we must</p>
<ol>
<li>Pulse the <strong>Latch</strong> pin High to Low. This takes the current button states and latches them into the register.</li>
<li>The state of button 0 will now appear on the <strong>Data</strong> line where we can grab it from.</li>
<li>Pulsing the <strong>Clock</strong> line High to Low causes the next button state to appear at <strong>Data</strong></li>
<li>Repeat until all eight buttons have been read, resulting in a byte that represents the pad state.</li></ol>
<p>First, we’ll have a go implementing this largely in the way you would if you are from a software background.</p>
<p>Let’s create a new file somewhere for this lovely re-usable module, <code>lib-nes.rkt</code></p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="kn">#lang </span><span class="nn">fairylog</span>
<span class="p">(</span><span class="n">vmod</span> <span class="n">nes_pads</span>
<span class="p">([</span><span class="n">clk_100mhz</span> <span class="kd">#:input</span> <span class="kd">#:wire</span><span class="p">]</span> <span class="c1">; master clock signal</span>
<span class="p">[</span><span class="n">nes_data1</span> <span class="kd">#:input</span> <span class="kd">#:wire</span><span class="p">]</span> <span class="c1">; data line from pad 1</span>
<span class="p">[</span><span class="n">nes_data2</span> <span class="kd">#:input</span> <span class="kd">#:wire</span><span class="p">]</span> <span class="c1">; data line from pad 2</span>
<span class="p">[</span><span class="n">nes_data</span> <span class="kd">#:output</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">16</span><span class="p">]]</span> <span class="c1">; results register, both data combined in 16 bits</span>
<span class="p">[</span><span class="n">nes_clk</span> <span class="kd">#:output</span> <span class="kd">#:reg</span> <span class="mi">0</span><span class="p">]</span> <span class="c1">; the pad's CLK line</span>
<span class="p">[</span><span class="n">nes_lat</span> <span class="kd">#:output</span> <span class="kd">#:reg</span> <span class="mi">0</span><span class="p">]</span> <span class="c1">; the pad's LATCH line</span>
<span class="p">)</span>
<span class="c1">; implementation ...</span>
<span class="p">)</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>I have a small module that brings two NES pads togther under one interface. That is, the <strong>Clock</strong> and <strong>Latch</strong> lines are tied together, and you can read the two values on <strong>Data1</strong> and <strong>Data2</strong>. The idea will be to read both pads and produce one 16-bit number with the two pad states.</p>
<p>Digital electronic components are highly sensitive to accurate timing. You can find the minimum and maximum timing requirements for different operations for the various devices in their <a href="http://www.ti.com/lit/ds/symlink/cd4021b-q1.pdf">datasheets</a>. Most modern 4021 shift registers have a minimum response time of 180ns. I am using a real NES pad from the early 80s and it doesn’t seem to work at such high speeds - with some experimentation 640ns or more seems to work quite well - it can go faster but we are not in a rush.</p>
<p>Our first problem, then, is timing. The board is providing a clock signal at 100mhz which is 1 cycle every 10ns - way too fast for what the poor pad can keep up with. What we need is to divide the clock and create a new, slower signal to base our logic around.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6
7
8
9</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="p">(</span><span class="n">locals</span>
<span class="p">[</span><span class="n">counter</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">6</span><span class="p">]]</span>
<span class="p">[</span><span class="n">clk_int</span> <span class="kd">#:reg</span><span class="p">])</span>
<span class="p">(</span><span class="n">always-pos</span> <span class="n">clk_100mhz</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/when_unless.html#(form._((lib._racket/private/letstx-scheme..rkt)._when))" style="color: inherit">when</a></span> <span class="p">(</span><span class="n">&</span> <span class="n">counter</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="n">clk_int</span> <span class="p">(</span><span class="n">~</span> <span class="n">clk_int</span><span class="p">)))</span>
<span class="p">(</span><span class="n">inc</span> <span class="n">counter</span><span class="p">))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Since a 6-bit register can count up to 64 before wrapping around, this will give us the delay we need (64 * 10ns). The <code>clk_int</code> register is inverted each time the counter rolls over, giving us the new clock signal (we’ll see another way to achieve this shortly)</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 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</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="p">(</span><span class="n">enum</span> <span class="n">nes-state</span>
<span class="n">ready</span>
<span class="n">latching</span>
<span class="n">next-bits</span>
<span class="n">read-bits</span>
<span class="n">finish</span><span class="p">)</span>
<span class="p">(</span><span class="n">locals</span>
<span class="p">[</span><span class="n">state</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">3</span><span class="p">]</span> <span class="n">nes-state.ready</span><span class="p">]</span>
<span class="p">[</span><span class="n">bits_shifted</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">4</span><span class="p">]]</span>
<span class="p">[</span><span class="n">data1</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">8</span><span class="p">]]</span>
<span class="p">[</span><span class="n">data2</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">8</span><span class="p">]])</span>
<span class="p">(</span><span class="n">always-pos</span> <span class="n">clk_int</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/match.html#(form._((lib._racket/match..rkt)._match))" style="color: inherit">match</a></span> <span class="n">state</span> <span class="n">nes-state</span>
<span class="p">[</span><span class="n">ready</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="p">[</span><span class="n">nes_lat</span> <span class="mi">1</span><span class="p">]</span> <span class="c1">; latch high to grab new data</span>
<span class="p">[</span><span class="n">data1</span> <span class="mi">0</span><span class="p">]</span> <span class="c1">; zero out everything else</span>
<span class="p">[</span><span class="n">data2</span> <span class="mi">0</span><span class="p">]</span>
<span class="p">[</span><span class="n">bits_shifted</span> <span class="mi">0</span><span class="p">]</span>
<span class="p">[</span><span class="n">state</span> <span class="n">nes-state.latching</span><span class="p">])]</span>
<span class="p">[</span><span class="n">latching</span> <span class="c1">;first bit will be available</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="p">[</span><span class="n">nes_lat</span> <span class="mi">0</span><span class="p">]</span> <span class="c1">; latch low</span>
<span class="p">[</span><span class="n">data1</span> <span class="n">nes_data1</span><span class="p">]</span> <span class="c1">;grab first bits of data </span>
<span class="p">[</span><span class="n">data2</span> <span class="n">nes_data2</span><span class="p">]</span>
<span class="p">[</span><span class="n">nes_clk</span> <span class="mi">1</span><span class="p">]</span> <span class="c1">;begin clocking </span>
<span class="p">[</span><span class="n">state</span> <span class="n">nes-state.read-bits</span><span class="p">])]</span>
<span class="p">[</span><span class="n">next-bits</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="p">[</span><span class="n">nes_clk</span> <span class="mi">1</span><span class="p">]</span> <span class="c1">;end clock</span>
<span class="p">[</span><span class="n">state</span> <span class="n">nes-state.read-bits</span><span class="p">])]</span>
<span class="p">[</span><span class="n">read-bits</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="p">[</span><span class="n">data1</span> <span class="p">(</span><span class="n">concat</span> <span class="p">(</span><span class="n">data1</span> <span class="mi">6</span> <span class="mi">0</span><span class="p">)</span> <span class="n">nes_data1</span><span class="p">)]</span> <span class="c1">;concat new data in</span>
<span class="p">[</span><span class="n">data2</span> <span class="p">(</span><span class="n">concat</span> <span class="p">(</span><span class="n">data2</span> <span class="mi">6</span> <span class="mi">0</span><span class="p">)</span> <span class="n">nes_data2</span><span class="p">)]</span>
<span class="p">[</span><span class="n">nes_clk</span> <span class="mi">0</span><span class="p">]</span>
<span class="c1">;check to see if we have finished</span>
<span class="p">[</span><span class="n">bits_shifted</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="n">bits_shifted</span> <span class="mi">1</span><span class="p">)]</span>
<span class="p">[</span><span class="n">state</span> <span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((quote._~23~25kernel)._if))" style="color: inherit">if</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._~3c))" style="color: inherit"><</a></span> <span class="n">bits_shifted</span> <span class="mi">6</span><span class="p">)</span>
<span class="n">nes-state.next-bits</span>
<span class="n">nes-state.finish</span><span class="p">)])]</span>
<span class="p">[</span><span class="n">finish</span>
<span class="c1">;done, assign the final value and reset FSM</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="p">[</span><span class="n">nes_data</span> <span class="p">(</span><span class="n">concat</span> <span class="n">data2</span> <span class="n">data1</span><span class="p">)]</span>
<span class="p">[</span><span class="n">state</span> <span class="n">nes-state.ready</span><span class="p">])])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Coming from a software perspective, in hardware code there’s no such thing as loops, so we have to encode everything in state machines. Fairylog has a compile-time feature called <code>enums</code> . As you can see here, you can define an <code>enum</code> with a bunch of names (and optionally integer values). Then, <code>match</code> can be used with an enum to provide a switch-case style dispatch on the items. Most importantly, <strong><em>the compiler exhaustively checks match cases</em></strong> - that is, it will error if you do not supply all the of cases, which proves invaluable for maintenance since you’ll be using a lot of state machines.</p>
<p>It is also easy to fall into the trap here of reading the chains of <code>sets</code> as happening procedurally like they would in a language like C. This is not the case, since in hardware everything generally happens in parallel, at the same time. In this case, we are using an <code>always</code> block with our new slow clock signal <code>clk_int</code>, and everything inside is based on flip-flops that work in sync with the clock signal. New values are not available to read until the <em>next</em> clock cycle. That is why the conditional in <code>read-bits</code> that checks <code>(if (< bits_shifted 6))</code> is not <code>7</code>, because the line above that increments <code>bits-shifted</code> hasn’t actually happened yet!</p>
<p>To use the module we’ll have to instantiate it from somewhere else. Let’s create a file called top.rkt</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="kn">#lang </span><span class="nn">fairylog</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/require.html#(form._((lib._racket/private/base..rkt)._require))" style="color: inherit">require</a></span> <span class="s2">"lib-nes.rkt"</span><span class="p">)</span>
<span class="p">(</span><span class="n">vmod</span> <span class="n">top</span>
<span class="p">([</span><span class="n">clk_100mhz</span> <span class="kd">#:input</span> <span class="kd">#:wire</span><span class="p">]</span>
<span class="p">[</span><span class="n">nes_clk</span> <span class="kd">#:output</span> <span class="kd">#:wire</span><span class="p">]</span> <span class="c1">;NES pad connections</span>
<span class="p">[</span><span class="n">nes_lat</span> <span class="kd">#:output</span> <span class="kd">#:wire</span><span class="p">]</span>
<span class="p">[</span><span class="n">nes_data1</span> <span class="kd">#:input</span> <span class="kd">#:wire</span><span class="p">]</span>
<span class="p">[</span><span class="n">nes_data2</span> <span class="kd">#:input</span> <span class="kd">#:wire</span><span class="p">]</span>
<span class="p">[</span><span class="n">board_leds</span> <span class="kd">#:output</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="mi">4</span><span class="p">]])</span>
<span class="p">(</span><span class="n">locals</span>
<span class="p">[</span><span class="n">nes_data</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="mi">16</span><span class="p">]])</span>
<span class="p">(</span><span class="n">vmod</span> <span class="n">nes_pads</span>
<span class="p">[</span><span class="n">clk_100mhz</span> <span class="n">clk_100mhz</span><span class="p">]</span>
<span class="p">[</span><span class="n">nes_clk</span> <span class="n">nes_clk</span><span class="p">]</span>
<span class="p">[</span><span class="n">nes_lat</span> <span class="n">nes_lat</span><span class="p">]</span>
<span class="p">[</span><span class="n">nes_data1</span> <span class="n">nes_data1</span><span class="p">]</span>
<span class="p">[</span><span class="n">nes_data2</span> <span class="n">nes_data2</span><span class="p">]</span>
<span class="p">[</span><span class="n">nes_data</span> <span class="n">nes_data</span><span class="p">])</span>
<span class="p">(</span><span class="n">assign</span> <span class="n">board_leds</span> <span class="p">(</span><span class="n">^</span> <span class="n">$f</span> <span class="p">(</span><span class="n">nes_data</span> <span class="mi">3</span> <span class="mi">0</span><span class="p">))))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>You’ll see here we include the <code>lib-nes.rkt</code> file just like you would in a normal Racket program. The ports for the <code>top</code> module include the hard signals from the FPGA board for the various pins of the NES controller (inputs and outputs), the main system clock, and 4 LEDs that I happen to have on the board.</p>
<p>The inner <code>vmod</code> form is used for module instantiation. You must supply a list of port mappings for the target module’s ports. In this case, they all happen to be called the same thing.</p>
<p>You’ll notice here that <code>nes_data</code> is defined as a <code>wire</code> type. This is because the data is actually stored in the other module - we only want a connection to it.</p>
<p>The last form here is <code>assign</code> which we have not seen yet. This is Verilog’s <em>combinatorial</em> logic - that is, stuff that happens outside of clock signals. These signals update as soon as something that affects them changes. In this case we connect our <code>board_leds</code> output wire to the last four bits of the <code>nes_data</code> wire, and XOR it with $f. In other words, the LEDs on the board will directly represent the last four buttons from pad 1. We do not need to explictly update anything, it will happen automatically.</p>
<p>The XOR $f inverts the bits, since the pad outputs 0 for pressed and 1 for not pressed, and I’d like the LEDs to light up as the buttons are pressed.</p>
<div class="brush: verilog">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 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</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="k">module</span> <span class="n">nes_pads</span> <span class="p">(</span>
<span class="k">input</span> <span class="kt">wire</span> <span class="n">clk_100mhz</span> <span class="p">,</span>
<span class="k">output</span> <span class="kt">reg</span> <span class="n">nes_clk</span> <span class="o">=</span> <span class="mh">0</span><span class="p">,</span>
<span class="k">output</span> <span class="kt">reg</span> <span class="n">nes_lat</span> <span class="o">=</span> <span class="mh">0</span><span class="p">,</span>
<span class="k">input</span> <span class="kt">wire</span> <span class="n">nes_data1</span> <span class="p">,</span>
<span class="k">input</span> <span class="kt">wire</span> <span class="n">nes_data2</span> <span class="p">,</span>
<span class="k">output</span> <span class="kt">reg</span> <span class="p">[</span><span class="mh">15</span><span class="o">:</span><span class="mh">0</span><span class="p">]</span> <span class="n">nes_data</span> <span class="p">);</span>
<span class="kt">reg</span> <span class="p">[</span><span class="mh">2</span><span class="o">:</span> <span class="mh">0</span><span class="p">]</span> <span class="n">state</span> <span class="o">=</span> <span class="mh">0</span><span class="p">;</span>
<span class="kt">reg</span> <span class="p">[</span><span class="mh">3</span><span class="o">:</span> <span class="mh">0</span><span class="p">]</span> <span class="n">bits_shifted</span> <span class="p">;</span>
<span class="kt">reg</span> <span class="p">[</span><span class="mh">7</span><span class="o">:</span> <span class="mh">0</span><span class="p">]</span> <span class="n">data1</span> <span class="p">;</span>
<span class="kt">reg</span> <span class="p">[</span><span class="mh">7</span><span class="o">:</span> <span class="mh">0</span><span class="p">]</span> <span class="n">data2</span> <span class="p">;</span>
<span class="kt">reg</span> <span class="p">[</span><span class="mh">5</span><span class="o">:</span> <span class="mh">0</span><span class="p">]</span> <span class="n">counter</span> <span class="p">;</span>
<span class="kt">reg</span> <span class="n">clk_int</span> <span class="p">;</span>
<span class="k">always</span> <span class="p">@(</span><span class="k">posedge</span> <span class="n">clk_100mhz</span><span class="p">)</span>
<span class="k">begin</span>
<span class="k">if</span><span class="p">(</span><span class="o">&</span><span class="n">counter</span><span class="p">)</span>
<span class="k">begin</span>
<span class="n">clk_int</span> <span class="o"><=</span> <span class="o">~</span><span class="n">clk_int</span><span class="p">;</span>
<span class="k">end</span>
<span class="k">else</span>
<span class="k">begin</span>
<span class="n">counter</span> <span class="o"><=</span> <span class="p">(</span><span class="n">counter</span> <span class="o">+</span> <span class="mh">1</span><span class="p">);</span>
<span class="k">end</span>
<span class="k">end</span>
<span class="k">always</span> <span class="p">@(</span><span class="k">posedge</span> <span class="n">clk_int</span><span class="p">)</span>
<span class="k">begin</span>
<span class="k">case</span> <span class="p">(</span><span class="n">state</span><span class="p">)</span>
<span class="mh">0</span> <span class="o">:</span> <span class="c1">// ready</span>
<span class="k">begin</span>
<span class="n">nes_lat</span> <span class="o"><=</span> <span class="mh">1</span><span class="p">;</span>
<span class="n">data1</span> <span class="o"><=</span> <span class="mh">0</span><span class="p">;</span>
<span class="n">data2</span> <span class="o"><=</span> <span class="mh">0</span><span class="p">;</span>
<span class="n">bits_shifted</span> <span class="o"><=</span> <span class="mh">0</span><span class="p">;</span>
<span class="n">state</span> <span class="o"><=</span> <span class="mh">1</span><span class="p">;</span>
<span class="k">end</span>
<span class="mh">1</span> <span class="o">:</span> <span class="c1">// latching</span>
<span class="k">begin</span>
<span class="n">nes_lat</span> <span class="o"><=</span> <span class="mh">0</span><span class="p">;</span>
<span class="n">data1</span> <span class="o"><=</span> <span class="n">nes_data1</span><span class="p">;</span>
<span class="n">data2</span> <span class="o"><=</span> <span class="n">nes_data2</span><span class="p">;</span>
<span class="n">nes_clk</span> <span class="o"><=</span> <span class="mh">1</span><span class="p">;</span>
<span class="n">state</span> <span class="o"><=</span> <span class="mh">3</span><span class="p">;</span>
<span class="k">end</span>
<span class="mh">2</span> <span class="o">:</span> <span class="c1">// next-bits</span>
<span class="k">begin</span>
<span class="n">nes_clk</span> <span class="o"><=</span> <span class="mh">1</span><span class="p">;</span>
<span class="n">state</span> <span class="o"><=</span> <span class="mh">3</span><span class="p">;</span>
<span class="k">end</span>
<span class="mh">3</span> <span class="o">:</span> <span class="c1">// read-bits</span>
<span class="k">begin</span>
<span class="n">data1</span> <span class="o"><=</span> <span class="p">{</span><span class="n">data1</span><span class="p">[</span><span class="mh">6</span> <span class="o">:</span> <span class="mh">0</span><span class="p">],</span> <span class="n">nes_data1</span><span class="p">};</span>
<span class="n">data2</span> <span class="o"><=</span> <span class="p">{</span><span class="n">data2</span><span class="p">[</span><span class="mh">6</span> <span class="o">:</span> <span class="mh">0</span><span class="p">],</span> <span class="n">nes_data2</span><span class="p">};</span>
<span class="n">nes_clk</span> <span class="o"><=</span> <span class="mh">0</span><span class="p">;</span>
<span class="n">bits_shifted</span> <span class="o"><=</span> <span class="p">(</span><span class="n">bits_shifted</span> <span class="o">+</span> <span class="mh">1</span><span class="p">);</span>
<span class="n">state</span> <span class="o"><=</span> <span class="p">((</span><span class="n">bits_shifted</span> <span class="o"><</span> <span class="mh">6</span><span class="p">)</span> <span class="o">?</span> <span class="mh">2</span> <span class="o">:</span> <span class="mh">4</span><span class="p">);</span>
<span class="k">end</span>
<span class="mh">4</span> <span class="o">:</span> <span class="c1">// finish</span>
<span class="k">begin</span>
<span class="n">nes_data</span> <span class="o"><=</span> <span class="p">{</span><span class="n">data2</span><span class="p">,</span> <span class="n">data1</span><span class="p">};</span>
<span class="n">state</span> <span class="o"><=</span> <span class="mh">0</span><span class="p">;</span>
<span class="k">end</span>
<span class="k">endcase</span>
<span class="k">end</span>
<span class="k">endmodule</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Notice how, in the compiled Verilog code, Fairylog has added helpful comments related to the states from the enum. I did this because you’ll be spending a lot of time wondering what is going on in your state machines!</p>
<h3 id="nes-paradigm-shift">NES++ Paradigm Shift!</h3>
<p>Whilst the above design works, it is not very idiomatic. In hardware you generally want to stay away from lots of flip-flop based state and complex conditional logic (not that this example is very complex!). Instead, we shoud aim to exploit the massively parallel nature of the circuitry and combine the combinatorial (pun intended) and clock-based approaches. This will lead to far fewer FPGA resources being consumed and better optimisation potential.</p>
<p>Let’s first see a different way of generating the divided clock signal:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="p">(</span><span class="n">locals</span>
<span class="p">[</span><span class="n">counter</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">7</span><span class="p">]]</span>
<span class="p">[</span><span class="n">clk_int</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="p">(</span><span class="n">counter</span> <span class="mi">6</span><span class="p">)])</span>
<span class="p">(</span><span class="n">always-pos</span> <span class="n">clk_100mhz</span> <span class="p">(</span><span class="n">inc</span> <span class="n">counter</span><span class="p">))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Here we have changed counter to be 7 bits instead of 6, and <code>clk_int</code> is no longer a reg but instead a wire that is high when bit 6 (0 based, the MSB) of <code>clk_int</code> is set and low if not. <em>(note: as in Verilog, using a default expression on a wire declaration like this is the same as later using <code>assign</code> with it)</em></p>
<p>Because a 7 bit number can hold exactly double what a 6 bit number can, this has the affect of the clock signal being low right up until <code>%011_1111</code> and then high from <code>100_0000</code> to <code>111_1111</code>, effectively giving us the same clock period as before, without the extra logic to control it.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="p">(</span><span class="n">locals</span>
<span class="p">[</span><span class="n">phase</span> <span class="kd">#:reg</span> <span class="p">[</span><span class="mi">4</span><span class="p">]]</span>
<span class="p">[</span><span class="n">phase_latch</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/match.html#(form._((lib._racket/match..rkt)._~3d~3d))" style="color: inherit">==</a></span> <span class="n">phase</span> <span class="mi">0</span><span class="p">)]</span>
<span class="p">[</span><span class="n">phase_end</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/match.html#(form._((lib._racket/match..rkt)._~3d~3d))" style="color: inherit">==</a></span> <span class="n">phase</span> <span class="mi">7</span><span class="p">)]</span>
<span class="p">[</span><span class="n">phase_data</span> <span class="kd">#:wire</span> <span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/ts-reference/Experimental_Features.html#(form._((lib._typed-racket/base-env/base-types-extra..rkt)._!))" style="color: inherit">!</a></span> <span class="n">phase_latch</span><span class="p">)])</span>
<span class="p">(</span><span class="n">assign</span>
<span class="p">[</span><span class="n">nes_clk</span> <span class="p">(</span><span class="n">&&</span> <span class="n">phase_data</span> <span class="n">clk_int</span><span class="p">)]</span>
<span class="p">[</span><span class="n">nes_lat</span> <span class="n">phase_latch</span><span class="p">])</span>
<span class="p">(</span><span class="n">always-pos</span> <span class="n">clk_int</span>
<span class="p">(</span><span class="n">inc</span> <span class="n">phase</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._cond))" style="color: inherit">cond</a></span>
<span class="p">[</span><span class="n">phase_latch</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="p">[</span><span class="n">data1</span> <span class="mi">0</span><span class="p">]</span>
<span class="p">[</span><span class="n">data2</span> <span class="mi">0</span><span class="p">])]</span>
<span class="p">[</span><span class="n">phase_end</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="p">[</span><span class="n">nes_data</span> <span class="p">(</span><span class="n">concat</span> <span class="p">(</span><span class="n">concat</span> <span class="p">(</span><span class="n">data2</span> <span class="mi">6</span> <span class="mi">0</span><span class="p">)</span> <span class="n">nes_data2</span><span class="p">)</span>
<span class="p">(</span><span class="n">concat</span> <span class="p">(</span><span class="n">data1</span> <span class="mi">6</span> <span class="mi">0</span><span class="p">)</span> <span class="n">nes_data1</span><span class="p">))]</span>
<span class="p">[</span><span class="n">phase</span> <span class="mi">0</span><span class="p">])]</span>
<span class="p">[</span><span class="n">phase_data</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set))" style="color: inherit">set</a></span> <span class="p">[</span><span class="n">data1</span> <span class="p">(</span><span class="n">concat</span> <span class="p">(</span><span class="n">data1</span> <span class="mi">6</span> <span class="mi">0</span><span class="p">)</span> <span class="n">nes_data1</span><span class="p">)]</span>
<span class="p">[</span><span class="n">data2</span> <span class="p">(</span><span class="n">concat</span> <span class="p">(</span><span class="n">data2</span> <span class="mi">6</span> <span class="mi">0</span><span class="p">)</span> <span class="n">nes_data2</span><span class="p">)])]))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>This next set of changes removes the old state machine completely. It is based on the observation that we need to do 8 things in sequence, and the state of the <strong>Latch</strong> and <strong>Clock</strong> pins can be determined by a combination of the current phase, and the clock.</p>
<p>First, we setup some wires that state <code>phase_latch</code> is high when <code>phase</code> is equal to zero. <code>phase_end</code> is high when <code>phase</code> is equal to 7, and finally, <code>phase_data</code> is high whenever <code>phase_latch</code> isn’t.</p>
<p>The actual NES ports have been changed from <code>#:reg</code> to <code>#:wire</code> (not seen here) and are now driven by combinatorial expressions. <code>nes_lat</code> is now high only when <code>phase_latch</code> is. <code>nes_clk</code> is high only when both <code>phase_data</code> is AND the <code>clk_int</code> is high.</p>
<p>If you think about this you will realise it has the effect on automating the signals completely for us, cycling in each bit of data as long as it is not latching.</p>
<p>All that remains then, is to continually increase <code>phase</code>, assigning the results to <code>nes_data</code> during <code>phase_end</code> and concatenating new intermediate data during <code>phase_data</code>.</p>
<p>Setting the data back to zero in <code>phase_latch</code> could also be removed completely since it will be overwritten anyway.</p>
<p>This design leads to a 30%~ reduction in FPGA resources! Of course, in such a small design it is negligible but it soon mounts up in larger and more complex modules.</p>
<h3 id="final-thoughts">Final Thoughts</h3>
<p>Now you can write Verilog code with <strong>RACKET MACROS</strong> what more needs to be said? As an example of what is possible, the CPU I designed that was programmed to produce the videos at the top of the post, was able to <em>mostly implement its own instruction set</em> through the use of macros.</p>
<p>This led to way less problems, less code, and most importantly a lot more fun for me to program, givng me more time to work on the cool stuff (apologies Verilog programmers, if you enjoy writing all that then good for you!).</p>
<p>Fairylog is far from complete however, and there are no docs. It does not yet support Verilog Tasks, and some other stuff which I don’t know anything about yet. There might be other mistakes as well since I am new at all these HDL shenanigans.</p>
<p>At this point it is still a tool mostly designed by me, for me, so you can expect it might change quite a bit at any time. Testament to Racket though, the original working version of Fairylog took me just 2 weeks to get going.</p>
<p>As a parting entertaining anecdote, I have still managed to never write an actual Verilog program from scratch! Achievement unlocked :)</p>C64 Macro State Machineurn:http-www-pinksquirrellabs-com:-blog-2018-10-05-c64-macro-state-machine2018-10-05T10:14:05Z2018-10-05T10:14:05Zpezi
<p>In this post we will see how <a href="http://www.pinksquirrellabs.com/blog/2017/05/30/asi64/">asi64’s</a> (<a href="[https://racket-lang.org/">Racket’s</a>) macro system can massively reduce the amount of 6502 assembly code you have to write, beyond what a typical macro assembler can achieve.</p>
<!-- more-->
<h2 id="state-machines">State Machines</h2>
<p>I am currently writing my first little game for the C64. In it, the player’s sprite has fairly complex movement behaviour which is represented by a state machine that has no less than 13 different states. In order to transition between the states, the player uses some combination of joystick controls, or something outside such as collision detection forces a state change.</p>
<p>In this post we will concentrate on state changes from the joystick. Programming these state machines can be tricky due to the amount of different possible transitions from one state to another and the priority in which they are checked. To show this we will look at a reduced and simplified view using 3 of the 13 states and the interactions between them.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="c1">;some constants</span>
<span class="p">{</span>
<span class="c1">; joy masks</span>
<span class="n">joy-up</span> <span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._~3d))" style="color: inherit">=</a></span> <span class="n">%00000001</span>
<span class="n">joy-down</span> <span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._~3d))" style="color: inherit">=</a></span> <span class="n">%00000010</span>
<span class="n">joy-left</span> <span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._~3d))" style="color: inherit">=</a></span> <span class="n">%00000100</span>
<span class="n">joy-right</span> <span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._~3d))" style="color: inherit">=</a></span> <span class="n">%00001000</span>
<span class="n">joy-fire</span> <span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._~3d))" style="color: inherit">=</a></span> <span class="n">%00010000</span>
<span class="c1">;machine states</span>
<span class="n">state-standing</span> <span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._~3d))" style="color: inherit">=</a></span> <span class="n">$0</span>
<span class="n">state-walking-right</span> <span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._~3d))" style="color: inherit">=</a></span> <span class="n">$1</span>
<span class="n">state-crouching</span> <span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._~3d))" style="color: inherit">=</a></span> <span class="n">$2</span>
<span class="c1">; variables</span>
<span class="n">current-state</span> <span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._~3d))" style="color: inherit">=</a></span> <span class="n">$f0</span>
<span class="p">}</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>The above code defines some constants for the three different states, a location to store the current state, and some masks used to detect which buttons on the joysticks are pressed when reading the joystick register.</p>
<p>The states that are defined represent the player standing still, walking to the right, and crouching. A graph of these transitions looks like this :</p>
<div class="figure"><img src="http://www.pinksquirrellabs.com/img/asi/state-graph.png" alt="" />
<p class="caption"></p></div>
<p>Even in this simple example, complexity rears its head. Notice that you cannot transition from walking right into a crouch, since I don’t want the player to enter that state accidentally as they are walking along if they happen to pull the joystick down and right at the same time. Additionally, there has to be some inverse logic for button presses to make some transitions, for example, when walking right, NOT holding right puts you back into the standing state. You can imagine with 13 states this can start to get very complex.</p>
<p>Programming this in 6502 asm is not particularly difficult, it’s just long, boring and very repetitive which in turns makes it a chore to change and maintain (more on the ineffeciency of this approach in the closing thoughts…) Here’s an example for the standing state :</p>
<div class="brush: ca65">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">:</span><span class="n">update</span><span class="o">-</span><span class="n">machine</span>
<span class="k">ldy</span> <span class="n">current</span><span class="o">-</span><span class="n">state</span> <span class="c1">; load current state</span>
<span class="k">cpy</span> <span class="n">@state</span><span class="o">-</span><span class="n">standing</span> <span class="c1">; is it the standing state?</span>
<span class="k">bne</span> <span class="n">next</span><span class="o">-</span><span class="n">state</span><span class="o">+</span> <span class="c1">; if not then go to the next check...</span>
<span class="k">lda</span> <span class="mh">$dc00</span> <span class="c1">; load the joystick state</span>
<span class="k">tax</span> <span class="c1">; preserve it in X so we can look at it again later..</span>
<span class="k">and</span> <span class="n">@joy</span><span class="o">-</span><span class="n">right</span> <span class="c1">; test joystick (1 is not pressed, 0 is pressed)</span>
<span class="k">bne</span> <span class="n">skip</span><span class="o">+</span> <span class="c1">; if not, move to next joystick check</span>
<span class="k">ldx</span> <span class="n">@state</span><span class="o">-</span><span class="n">walking</span><span class="o">-</span><span class="n">right</span>
<span class="k">jsr</span> <span class="n">change</span><span class="o">-</span><span class="n">state</span><span class="o">-</span> <span class="c1">; call the function that changes the state </span>
<span class="k">rts</span> <span class="c1">; early exit from function</span>
<span class="p">:</span><span class="n">skip</span>
<span class="k">txa</span> <span class="c1">; reload the joy data</span>
<span class="c1">; repeat all the above the for next direction</span>
<span class="k">and</span> <span class="n">@joy</span><span class="o">-</span><span class="n">down</span>
<span class="k">bne</span> <span class="n">skip</span><span class="o">+</span>
<span class="k">ldx</span> <span class="n">@tstate</span><span class="o">-</span><span class="n">crouching</span>
<span class="k">jsr</span> <span class="n">change</span><span class="o">-</span><span class="n">state</span><span class="o">-</span>
<span class="p">:</span><span class="n">skip</span>
<span class="k">rts</span> <span class="c1">; return from function</span>
<span class="p">:</span><span class="n">next</span><span class="o">-</span><span class="n">state</span>
<span class="k">cpy</span> <span class="n">@state</span><span class="o">-</span><span class="n">walking</span><span class="o">-</span><span class="n">right</span>
<span class="c1">; .... repeat all the code for each state and each transition</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>You can see this is going to extremely long winded with 13 different states each with multiple transitions, sometimes with more complex trigger logic (eg, combinations of joystick button being pressed, things not being pressed and so on).</p>
<p>In addition to this, since this is the update function for the machine, this is also where logic will take place that affects the game depending on the state, e.g. the walking right section needs to actually update the player’s X co-ordinate.</p>
<p>The final salt in the wound is that some state transitions need to execute some logic after the transition actually takes effect, for example resetting some variables or switching on / off some additional sprites.</p>
<p>Whilst I enjoy writing assembly code, I don’t so much enjoy maintaining a monster like this. I takes forever to try changes or introduce new states and it is very easy to introduce subtle, silly bugs that you don’t notice until later.</p>
<h2 id="macros-to-the-resuce">Macros to the resuce!</h2>
<p>Racket’s amazing macro system can help us out here. Wherever you see replication of code, macros are ready to lend you a helping hand. In this example we won’t even see any of the really fancy stuff racket can do, just basic macros.</p>
<p>The way I like to write macros is to first write down the syntax I would like to be able to write, then work backwards from that point to make it happen. Let’s keep it simple to start with, and forget about having to execute game logic and pre-transition logic. In fact let’s also forget about the actual machine states and just concentrate of the repetitve bit in the middle which is the checking of joystick states.</p>
<p>As an inital concept, let’s say it would be nice to write this :</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="n">:update-machine</span>
<span class="n">ldy</span> <span class="n">current-state</span>
<span class="n">cpy</span> <span class="n">@state-standing</span>
<span class="n">bne</span> <span class="n">next-state+</span>
<span class="p">(</span><span class="n">generate-joy-transitions</span>
<span class="p">([</span><span class="n">joy-right</span> <span class="no">#t</span> <span class="n">state-walking-right</span><span class="p">]</span>
<span class="p">[</span><span class="n">joy-down</span> <span class="no">#t</span> <span class="n">state-crouching</span><span class="p">]))</span>
<span class="n">rts</span>
<span class="n">:next-state</span>
<span class="c1">; .....</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>The macro <code>generate-joy-transitions</code> will take a list of lists, each inner list has three elements. The first is the bit pattern to test against the joystick register, the second is a boolean that indicates if the button should be tested against being pressed or NOT being pressed, and finally the last part is the target state.</p>
<p>Let’s have a frst go at writing it :</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Defining_Simple_Macros.html#(form._((lib._syntax/parse/define..rkt)._define-syntax-parser))" style="color: inherit">define-syntax-parser</a></span> <span class="n">generate-joy-transitions</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="p">([</span><span class="n">test</span> <span class="n">is-pressed?</span> <span class="n">target</span><span class="p">]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">))</span>
<span class="o">#'</span><span class="p">{</span><span class="n">lda</span> <span class="n">$dc00</span> <span class="c1">; load joystick register</span>
<span class="n">tax</span> <span class="c1">; preserve it in x</span>
<span class="p">{</span>
<span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._and))" style="color: inherit">and</a></span> <span class="n">@test</span> <span class="c1">; test bits</span>
<span class="c1">; ?? how do we perform the branch?</span>
<span class="n">ldx</span> <span class="n">@target</span> <span class="c1">; perform state transition</span>
<span class="n">jsr</span> <span class="n">change-state-</span>
<span class="n">rts</span> <span class="c1">; exit function</span>
<span class="n">:skip</span>
<span class="n">txa</span> <span class="c1">; restore joytsick data</span>
<span class="p">}</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span>
<span class="p">}</span> <span class="c1">; repeat ...</span>
<span class="p">])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>This is not a terrible first attempt, we simply pattern match on the inner list, extracting the parameters into the names <code>test</code> <code>is-pressed?</code> and <code>target</code>, the ellipsis <code>...</code> that follows tells racket that any amount of these lists may appear here.</p>
<p>The first two asm instructions are generated only once - the inner section which is wrapped in a nested 6502 block using <code>{ }</code> is repeated for each set of arguments thanks to the <code>...</code> that follows the block.</p>
<p>A problem remains though - after the AND test, we must use a different branch instruction depending on if we are checking that the button was pressed or not pressed via the <code>is-pressed?</code> parameter (<code>bne</code> and <code>beq</code> respectively). How can we do this? We can’t simply replace <code>is-pressed?</code> in the pattern match with <code>#t</code> and then replicate the pattern and macro output with another case for <code>#f</code>, because that would mean ALL of the provided arguments would have to be same, which is no good.</p>
<h2 id="macros-in-yer-macros">Macros in yer macros..</h2>
<p>Likely there are many ways to skin this cat - Racket generally likes you to be declarative about these things, so one way is to simply define another macro that takes care of it.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Defining_Simple_Macros.html#(form._((lib._syntax/parse/define..rkt)._define-syntax-parser))" style="color: inherit">define-syntax-parser</a></span> <span class="n">joy-branch</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="no">#t</span><span class="p">)</span> <span class="o">#'</span><span class="p">{</span><span class="n">bne</span> <span class="n">skip+</span><span class="p">}]</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="no">#f</span><span class="p">)</span> <span class="o">#'</span><span class="p">{</span><span class="n">beq</span> <span class="n">skip+</span><span class="p">}])</span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Defining_Simple_Macros.html#(form._((lib._syntax/parse/define..rkt)._define-syntax-parser))" style="color: inherit">define-syntax-parser</a></span> <span class="n">generate-joy-transitions</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="p">([</span><span class="n">test</span> <span class="n">is-pressed?</span> <span class="n">target</span><span class="p">]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">))</span>
<span class="o">#'</span><span class="p">{</span><span class="n">lda</span> <span class="n">$dc00</span>
<span class="n">tax</span>
<span class="p">{</span>
<span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._and))" style="color: inherit">and</a></span> <span class="n">@test</span>
<span class="p">(</span><span class="n">joy-branch</span> <span class="n">is-presed?</span><span class="p">)</span> <span class="c1">; call the other macro here</span>
<span class="n">ldx</span> <span class="n">@target</span>
<span class="n">jsr</span> <span class="n">change-state-</span>
<span class="n">rts</span>
<span class="n">:skip</span>
<span class="n">txa</span>
<span class="p">}</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span> <span class="p">}</span>
<span class="p">])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Cool, now it works as expected. Infact, since we haven’t told Racket to expect any particular types (eg, expressions, integers) as the parameters, it is totally possible to pass expressions into <code>test</code> and <code>target</code>, which is very handy if you wanted for example to test a combined bitmask for more than one button at once:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="p">(</span><span class="n">generate-joy-transitions</span>
<span class="p">([(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._bitwise-ior))" style="color: inherit">bitwise-ior</a></span> <span class="n">joy-right</span> <span class="n">joy-down</span><span class="p">)</span> <span class="no">#t</span> <span class="n">some-state</span><span class="p">]))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Very nice! We basically got that for free. For the final piece of this section we wished to be able to execute some arbitary code after the transition has finished. However, we dont always want to do this, and Racket has just the answer by allowing us to put in an optional parameter that will be defaulted to an empty block if not supplied.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Defining_Simple_Macros.html#(form._((lib._syntax/parse/define..rkt)._define-syntax-parser))" style="color: inherit">define-syntax-parser</a></span> <span class="n">generate-joy-transitions</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="p">([</span><span class="n">test</span> <span class="n">is-pressed?</span> <span class="n">target</span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/stxparse-patterns.html#(form._((lib._syntax/parse..rkt)._~7eoptional))" style="color: inherit">~optional</a></span> <span class="n">extra</span> <span class="kd">#:defaults</span> <span class="p">([</span><span class="n">extra</span> <span class="o">#'</span><span class="p">{}</span> <span class="p">]))]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">))</span>
<span class="o">#'</span><span class="p">{</span><span class="n">lda</span> <span class="n">$dc00</span>
<span class="n">tax</span>
<span class="p">{</span>
<span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._and))" style="color: inherit">and</a></span> <span class="n">@test</span>
<span class="p">(</span><span class="n">joy-branch</span> <span class="n">is-pressed?</span><span class="p">)</span>
<span class="n">ldx</span> <span class="n">@target</span>
<span class="n">jsr</span> <span class="n">change-state-</span>
<span class="n">extra</span> <span class="c1">; stick the extra code in here</span>
<span class="n">rts</span>
<span class="n">:skip</span>
<span class="n">txa</span>
<span class="p">}</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span> <span class="p">}</span>
<span class="p">])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Now we can write</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="p">(</span><span class="n">generate-joy-transitions</span>
<span class="p">([</span><span class="n">joy-right</span> <span class="no">#t</span> <span class="n">state-walking-right</span><span class="p">]</span>
<span class="p">[</span><span class="n">joy-down</span> <span class="no">#t</span> <span class="n">state-crouching</span>
<span class="p">{</span>
<span class="c1">; some asm code...</span>
<span class="p">}]))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Of course, a 6502 block is inlined in the above example, but it could equally call a function that generates some code, calls another macro, or whatever.</p>
<h1 id="macros-in-yer-macros-in-yer-macros-">Macros in yer macros in yer macros …</h1>
<p>The final icing on the cake is to get rid of the state machine branching logic completely. To do this we need to :</p>
<ul>
<li>Create essentially the <code>switch</code> statement for each state</li>
<li>Allow some arbitary code be executed</li>
<li>Check all joystick transitions as above</li></ul>
<p>So, what we want to be able to write is :</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">generate-state-machine</span>
<span class="p">([</span><span class="n">state-standing</span>
<span class="p">{</span> <span class="p">}</span>
<span class="p">([</span><span class="n">joy-right</span> <span class="no">#t</span> <span class="n">state-walking-right</span><span class="p">]</span>
<span class="p">[</span><span class="n">joy-left</span> <span class="no">#t</span> <span class="n">state-walking-left</span><span class="p">]</span>
<span class="p">[</span><span class="n">joy-down</span> <span class="no">#t</span> <span class="n">state-crouching</span>
<span class="p">{</span> <span class="n">some</span> <span class="n">code</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span> <span class="p">}])]</span>
<span class="p">[</span><span class="n">state-walking-right</span>
<span class="p">{</span>
<span class="c1">; move sprite right</span>
<span class="n">inc</span> <span class="n">$d000</span>
<span class="n">inc</span> <span class="n">$d000</span>
<span class="p">}</span>
<span class="p">([</span><span class="n">joy-left</span> <span class="no">#t</span> <span class="n">state-walking-left</span><span class="p">]</span>
<span class="p">[</span><span class="n">joy-right</span> <span class="no">#f</span> <span class="n">state-standing</span><span class="p">])]</span>
<span class="c1">; more cases ...</span>
<span class="p">))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Following the patterns above this pretty much writes itself:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Defining_Simple_Macros.html#(form._((lib._syntax/parse/define..rkt)._define-syntax-parser))" style="color: inherit">define-syntax-parser</a></span> <span class="n">generate-state-machine</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="p">([</span><span class="n">state-number</span>
<span class="n">update-code</span>
<span class="n">joy-cases</span><span class="p">]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">))</span>
<span class="o">#'</span><span class="p">{</span>
<span class="p">{</span>
<span class="n">ldy</span> <span class="n">current-state</span> <span class="c1">;load current state</span>
<span class="n">cpy</span> <span class="n">@state-number</span>
<span class="n">bne</span> <span class="n">next-state+</span>
<span class="n">update-code</span> <span class="c1">; insert update code here</span>
<span class="c1">;call the joystick macro with the cases</span>
<span class="p">(</span><span class="n">generate-joy-transitions</span> <span class="n">joy-cases</span><span class="p">)</span>
<span class="n">:next-state</span>
<span class="p">}</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span>
<span class="p">}])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>And we are done.</p>
<h2 id="closing-thoughts">Closing Thoughts</h2>
<p>Macros are a super powerful way to help introduce new syntax over the top of the assembler, and this is really just scratching the surface of it.</p>
<p>This example is kept simple, it has some obvious problems such as the “switch” statement uses branching instructions that can only go +/– 127 bytes and it will break if there is too much code between the branch and the label. It also has to check each state until it finds what it is looking for - a nicer way would be to use a lookup table and jump to the correct address, which is totally possible with a little more macrology …</p>
<p>Happy assembling!</p>
<h2 id="additional-edit">Additional Edit!</h2>
<p>Since I posted this earlier today, I have changed the switch-statement type affair into a much more effecient lookup table, and I thought it might be interesting to show how it works, since it uses the assembler’s open architecture by directly calling into some of the functionality it provides rather than using the assembler syntax.</p>
<p>The idea is to do the following</p>
<ul>
<li>Load the current state number</li>
<li>Using the number as an index, lookup the low address byte where the code for that state lives. Store this number somewhere</li>
<li>Repeat to lookup the high address byte, store it next to the low byte</li>
<li>Use the indirect jump op-code to jump to this address.</li></ul>
<p>In order to do this we will have to know the location of each state’s code that we assemble and put their locations into lookup tables split by their low and high bytes. There are a few ways to do this, the easiest is to label each section of state code, then later extract the address details into lookup tabes. Here’s how it looks :</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 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</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Defining_Simple_Macros.html#(form._((lib._syntax/parse/define..rkt)._define-syntax-parser))" style="color: inherit">define-syntax-parser</a></span> <span class="n">generate-state-machine</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="p">([</span><span class="n">state-number</span>
<span class="n">update-code</span>
<span class="n">joy-cases</span><span class="p">]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">))</span>
<span class="o">#'</span><span class="p">{</span>
<span class="n">ldx</span> <span class="n">tc-state</span> <span class="c1">; load current state</span>
<span class="n">lda</span> <span class="n">state-machine-lo:</span> <span class="n">x</span> <span class="c1">; use lookup table and setup</span>
<span class="n">sta</span> <span class="n">jump-vector-lo+</span> <span class="c1">; 16 bit address pointer</span>
<span class="n">lda</span> <span class="n">state-machine-hi:</span> <span class="n">x</span>
<span class="n">sta</span> <span class="n">jump-vector-hi+</span>
<span class="n">jmpi</span> <span class="n">jump-vector-lo:</span> <span class="c1">; jump to target state</span>
<span class="c1">; write out the states </span>
<span class="p">{</span>
<span class="c1">;set jump location</span>
<span class="p">(</span><span class="n">set-jump-source-current</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/Writing.html#(def._((quote._~23~25kernel)._format))" style="color: inherit">format</a></span> <span class="s2">"state~a"</span> <span class="n">state-number</span><span class="p">))</span>
<span class="n">update-code</span>
<span class="p">(</span><span class="n">generate-joy-transitions</span> <span class="n">joy-cases</span><span class="p">)</span>
<span class="n">rts</span>
<span class="p">}</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">jump-labels</span>
<span class="p">(</span><span class="n">~>></span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._list))" style="color: inherit">list</a></span> <span class="n">state-number</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/private/map..rkt)._map))" style="color: inherit">map</a></span> <span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/reference/lambda.html#(form._((lib._racket/private/base..rkt)._~ce~bb))" style="color: inherit">λ</a></span> <span class="p">(</span><span class="n">n</span><span class="p">)</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/Writing.html#(def._((quote._~23~25kernel)._format))" style="color: inherit">format</a></span> <span class="s2">"state~a"</span> <span class="n">n</span><span class="p">)))</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/private/map..rkt)._map))" style="color: inherit">map</a></span> <span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/reference/lambda.html#(form._((lib._racket/private/base..rkt)._~ce~bb))" style="color: inherit">λ</a></span> <span class="p">(</span><span class="n">n</span><span class="p">)</span> <span class="p">(</span><span class="n">find-closest-label</span> <span class="n">n</span> <span class="p">(</span><span class="n">here</span><span class="p">)</span> <span class="o">'</span><span class="ss"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._-))" style="color: inherit">-</a></span><span class="p">)))))</span>
<span class="n">:state-machine-lo</span>
<span class="p">(</span><span class="n">write-values</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/private/map..rkt)._map))" style="color: inherit">map</a></span> <span class="n">lo-byte</span> <span class="n">jump-labels</span><span class="p">))</span>
<span class="n">:state-machine-hi</span>
<span class="p">(</span><span class="n">write-values</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/private/map..rkt)._map))" style="color: inherit">map</a></span> <span class="n">hi-byte</span> <span class="n">jump-labels</span><span class="p">))</span>
<span class="n">:jump-vector-lo</span> <span class="p">(</span><span class="n">data</span> <span class="n">$FF</span><span class="p">)</span>
<span class="n">:jump-vector-hi</span> <span class="p">(</span><span class="n">data</span> <span class="n">$FF</span><span class="p">)</span>
<span class="p">}])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>The first lines of code load in the current state, perfom the indexed lookups into the tables and store the address in the jump-vector. Then, the code jumps via this vector and begins executing the code for the current state.</p>
<p>The code that writes out the states directly calls the internal assembler function to add a label <code>set-jump-source-current</code>, and it names the label <code>state-n</code> where <code>n</code> is the number of the state it is processing.</p>
<p>At the bottom of the macro, we take ALL the numbers together <code>(list state-number ... )</code> re-format them into the label names, call another internal assembler function that locates a label from a given location <code>find-closest-label</code> and finally extracts the low or high bytes from it. These are then written out as lookup data.</p>
<p>Finally, the last two lines label a couple of bytes to use as a jump vector that is written to from the jumping logic.</p>
<p>This is really cool! Now the state machine is much more effecient and has no worries about branching limitations. Most importantly, you can add and remove states withouht ever having to worry about moving loads of code and numbers around, and making far less mistakes because of it.</p>C64 Sprite Previewerurn:http-www-pinksquirrellabs-com:-blog-2018-09-17-c64-sprite-previewer2018-09-17T20:05:58Z2018-09-17T20:05:58Zpezi
<p>In this post we will see how <a href="http://pinksquirrellabs.com/blog/2017/05/30/asi64/">asi64</a> is more than your average macro assembler, by combining arbitrary disk io, functional programming techniques and code generation alongside your typical 6502 assembly code. The aim is to create a very simple sprite animation viewer, that writes the resulting C64 program by interleaving file parsing and machine code generation.</p>
<p>Here’s the program displaying some sprites that <a href="https://twitter.com/silverSpoon">@silverspoon</a> has started working on :) (in different, single colours for the fun of it)</p>
<div class="figure"><img src="http://www.pinksquirrellabs.com/img/asi/tc.gif" alt="" />
<p class="caption"></p></div>
<!-- more-->
<p>To read this post it would probably help to know some 6502 (though not essential), you can read the assembler syntax over at <a href="https://github.com/pezipink/Asi64">asi64’s github</a> or from an <a href="http://pinksquirrellabs.com/blog/2017/05/30/asi64/">older post on it</a></p>
<h2 id="sprites">Sprites</h2>
<p>The C64 has 8 hardware sprites it can utilise. This means the video hardware can display up to 8 sprites at once. To animate something, you would use a series of sprites that you change between. To design these sprites there are various tools available (not like the 80s where you had to draw them manually on graph paper!). I have been using <a href="http://www.spritemate.com/">spritemate</a> which is a nice online tool.</p>
<p>Spritemate is able to save the sprites in a variety of formats, including assembly code output for two of the popular C64 assemblers (KickAss and ACME).</p>
<p>What I would like is a way whereby I can design a series of sprite animation frames in the tool, save a number of these files (each file containing n sprite-frames of animation for some entity), then have the assembler read them from disk and automatically display and animate each sprite on the C64 screen. This will provide a fast feedback loop to see what they look like on the machine, rather than having to mess around moving chunks of data and altering frame counts and animation code manually.</p>
<p>To display sprites on the C64 you need to have a number of things in place. This post is not supposed to be a tutorial on how they work, so not everything will be explained.</p>
<ul>
<li>The actual sprite data itself must live somewhere the VIC graphics chip can see it.</li>
<li>The last 8 bytes of screen memory indicate an offset into the sprite data telling the VIC which sprite to display for each of the 8 sprites.</li>
<li>Sprite colours and positions are set with bunch of memory-mapped registers on the VIC.</li></ul>
<p>The details on how to configure the VIC for this are out of the scope of this post. Suffice to say, for my needs, all the sprite data will be stored at $2000, my screen data lives at $0400, the last 8 bytes of it (the sprite pointers) are at $7fe8.</p>
<p>The sprites are used in multi-colour mode, which means they each have 4 colours. 3 of the colours are shared by all sprites (background, colour 1 and colour 2) and the last colour is individual to each sprite, set within 8 more VIC registers. For the sake of simplicty, this post ignores the individual colour, assuming they are all the same.</p>
<h2 id="file-formats">File Formats</h2>
<p>Since Asi64 extends Racket, it has the <a href="https://racket-lang.org/">full arsenal of Racket at its disposal</a>, including its ridiculous macro system, multiple programming paradigms, extensive libraries and packages. We can quite easily mix this code in with 6502 assembler to help generate code in any way you would like.</p>
<p>Let’s look at one of Spritemate’s output formats, for <a href="http://theweb.dk/KickAssembler/Main.html#frontpage">KickAss</a> (which is a fantasic assmembler, and partly the inspiration for writing Asi64!)</p>
<pre><code>// 4 sprites generated with spritemate on 9/14/2018, 9:03:32 PM
// Byte 64 of each sprite contains multicolor (high nibble) & color (low nibble) information
LDA #$04 // sprite multicolor 1
STA $D025
LDA #$06 // sprite multicolor 2
STA $D026
// sprite 1 / multicolor / color: $0e
sprite_1:
.byte $0c,$00,$30,$0f,$00,$30,$0f,$ff
.byte $f0,$03,$7d,$f0,$03,$ff,$c0,$01
.byte $eb,$40,$00,$ff,$00,$01,$3c,$40
.byte $00,$74,$00,$00,$54,$00,$00,$74
.byte $00,$00,$fc,$00,$00,$fc,$00,$03
.byte $ff,$0c,$03,$ff,$0c,$03,$ff,$0c
.byte $0f,$ff,$cc,$0e,$fe,$cc,$3e,$fe
.byte $f0,$3e,$fe,$f0,$3e,$fe,$f0,$8e
// sprite 2 / multicolor / color: $0e
sprite_2:</code></pre>
<p>The interesting bits of this file are</p>
<ul>
<li>How many sprite frames are in the file (each sprite is a frame of animation)</li>
<li>The sprite data itself, which of course is just a bunch of bytes</li>
<li>Additional colour data which we are ignoring for this post.</li></ul>
<p>Since Asi64 is also Racket, we can write a function that will extract the contents of one of these files into a little structure:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="kn">#lang </span><span class="nn">asi64</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define-struct.html#(form._((lib._racket/private/base..rkt)._struct))" style="color: inherit">struct</a></span> <span class="n">sprite-data</span> <span class="p">(</span><span class="n">frame-count</span> <span class="n">data</span><span class="p">))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">extract-sprite</span> <span class="n">filename</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/let.html#(form._((lib._racket/private/letstx-scheme..rkt)._let*))" style="color: inherit">let*</a></span> <span class="p">(</span><span class="c1">;read file as a sequence of lines</span>
<span class="p">[</span><span class="n">lines</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/Filesystem.html#(def._((lib._racket/file..rkt)._file-~3elines))" style="color: inherit">file->lines</a></span> <span class="n">filename</span><span class="p">)]</span>
<span class="c1">;count the amount of frames by looking at lines that end with :</span>
<span class="p">[</span><span class="n">frames</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._length))" style="color: inherit">length</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/private/list..rkt)._filter))" style="color: inherit">filter</a></span> <span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/reference/lambda.html#(form._((lib._racket/private/base..rkt)._~ce~bb))" style="color: inherit">λ</a></span> <span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/string..rkt)._string-suffix~3f))" style="color: inherit">string-suffix?</a></span> <span class="n">s</span> <span class="s2">":"</span><span class="p">))</span> <span class="n">lines</span><span class="p">))]</span>
<span class="c1">; extract the raw data as one big lump</span>
<span class="p">[</span><span class="n">data</span> <span class="p">(</span><span class="n">~>></span>
<span class="n">lines</span>
<span class="c1">; filter to .byte rows </span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/private/list..rkt)._filter))" style="color: inherit">filter</a></span> <span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/reference/lambda.html#(form._((lib._racket/private/base..rkt)._~ce~bb))" style="color: inherit">λ</a></span> <span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/string..rkt)._string-prefix~3f))" style="color: inherit">string-prefix?</a></span> <span class="n">s</span> <span class="s2">".byte"</span><span class="p">)))</span>
<span class="c1">; clean up text leaving raw hex values</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/private/map..rkt)._map))" style="color: inherit">map</a></span> <span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/reference/lambda.html#(form._((lib._racket/private/base..rkt)._~ce~bb))" style="color: inherit">λ</a></span> <span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/string..rkt)._string-replace))" style="color: inherit">string-replace</a></span> <span class="n">s</span> <span class="s2">".byte "</span> <span class="s2">""</span><span class="p">)))</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/private/map..rkt)._map))" style="color: inherit">map</a></span> <span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/reference/lambda.html#(form._((lib._racket/private/base..rkt)._~ce~bb))" style="color: inherit">λ</a></span> <span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/string..rkt)._string-replace))" style="color: inherit">string-replace</a></span> <span class="n">s</span> <span class="s2">"$"</span> <span class="s2">""</span><span class="p">)))</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/private/map..rkt)._map))" style="color: inherit">map</a></span> <span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/reference/lambda.html#(form._((lib._racket/private/base..rkt)._~ce~bb))" style="color: inherit">λ</a></span> <span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/string..rkt)._string-split))" style="color: inherit">string-split</a></span> <span class="n">s</span> <span class="s2">","</span><span class="p">)))</span>
<span class="c1">; flatten into one big list of numbers</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/list..rkt)._flatten))" style="color: inherit">flatten</a></span><span class="p">)</span>
<span class="c1">; parse hex </span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/private/map..rkt)._map))" style="color: inherit">map</a></span> <span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/reference/lambda.html#(form._((lib._racket/private/base..rkt)._~ce~bb))" style="color: inherit">λ</a></span> <span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._string-~3enumber))" style="color: inherit">string->number</a></span> <span class="n">s</span> <span class="mi">16</span><span class="p">))))])</span>
<span class="p">(</span><span class="n">sprite-data</span> <span class="n">frames</span> <span class="n">data</span><span class="p">)))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>And now we can quite easily scan the sprites directory for all files (we’ll assume there’s no more than 8) and pass them through this function to yield a bunch of structures containing the sprite data that can be used to help write the assembly code.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">sprites</span>
<span class="p">(</span><span class="n">~>></span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/Filesystem.html#(def._((lib._racket/private/base..rkt)._directory-list))" style="color: inherit">directory-list</a></span> <span class="s2">"..</span><span class="se">\\</span><span class="s2">sprites"</span> <span class="kd">#:build?</span> <span class="no">#t</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/private/map..rkt)._map))" style="color: inherit">map</a></span> <span class="nb"><a href="http://docs.racket-lang.org/reference/Manipulating_Paths.html#(def._((quote._~23~25kernel)._path-~3estring))" style="color: inherit">path->string</a></span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/private/list..rkt)._filter))" style="color: inherit">filter</a></span> <span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/reference/lambda.html#(form._((lib._racket/private/base..rkt)._~ce~bb))" style="color: inherit">λ</a></span> <span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/string..rkt)._string-suffix~3f))" style="color: inherit">string-suffix?</a></span> <span class="n">s</span> <span class="s2">".txt"</span><span class="p">)))</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/private/map..rkt)._map))" style="color: inherit">map</a></span> <span class="n">extract-sprite</span><span class="p">)))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<h2 id="6502">6502</h2>
<p>Now we can start to write the actual program. Before we do anything else, we want to dump the raw sprite data that was collected from all the files into memory starting at $2000.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">C64</span><span class="p">{</span>
<span class="c1">; raw sprite data starts at $2000</span>
<span class="n">*=</span> <span class="n">$2000</span>
<span class="p">(</span><span class="n">write-values</span>
<span class="p">(</span><span class="n">~>></span>
<span class="n">sprites</span>
<span class="c1">; extract the "data" field from the struct</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/private/map..rkt)._map))" style="color: inherit">map</a></span> <span class="n">sprite-data-data</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/list..rkt)._flatten))" style="color: inherit">flatten</a></span><span class="p">)))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>We simply extract out the “data” field from the structs created earlier, and flatten it all into one big list. The “write-values” here is an asi64 form that simply instructs the assembler to write whatever numbers it is given to the current location.</p>
<p>The next part is a lot more interesting. We need to setup each of the sprite pointers to point at the first frame of animation for each file that was loaded (we assume in this example there were a maximum of 8 sprites - there are multiplexing techniques you can use to display more)</p>
<p>With the way the VIC is currently setup, the 8 sprite pointers start at $07f8, and the correct index to store in the first one so that it will point at the first frame of data we stored at $2000 is $80. Then, for each successive set of sprite data, we must increase the offset by the number of frames from the previous set, thus arriving at the first frame of the next set, and store that into the next pointer.</p>
<p>That is a bit of a mouthful, hopefully the code will help to make it clear. In asi64, everything between curly braces is 6502 assembler which you can nest anywhere:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 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</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="c1">; start our actual program at $1000</span>
<span class="n">*=</span> <span class="n">$1000</span>
<span class="c1">; enable all sprites</span>
<span class="n">lda</span> <span class="n">@$FF</span>
<span class="n">sta</span> <span class="n">$d015</span>
<span class="c1">; turn on multicolour mode for all sprites</span>
<span class="n">lda</span> <span class="n">@$FF</span>
<span class="n">sta</span> <span class="n">$d01c</span>
<span class="n">lda</span> <span class="n">@$04</span> <span class="c1">; sprite multicolor 1</span>
<span class="n">sta</span> <span class="n">$D025</span>
<span class="n">lda</span> <span class="n">@$06</span> <span class="c1">; sprite multicolor 2</span>
<span class="n">sta</span> <span class="n">$D026</span>
<span class="c1">; set background colour to black</span>
<span class="n">lda</span> <span class="n">@0</span>
<span class="n">sta</span> <span class="n">$d021</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/for.html#(form._((lib._racket/private/base..rkt)._for/fold))" style="color: inherit">for/fold</a></span> <span class="p">(</span><span class="c1">; points at $2000</span>
<span class="p">[</span><span class="n">data-index</span> <span class="n">$80</span><span class="p">]</span>
<span class="c1">; first sprite pointer </span>
<span class="p">[</span><span class="n">sprite-pointer</span> <span class="n">$07f8</span><span class="p">]</span>
<span class="p">[</span><span class="n">code</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._list))" style="color: inherit">list</a></span><span class="p">)])</span>
<span class="p">([</span><span class="n">s</span> <span class="n">sprites</span><span class="p">])</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/let.html#(form._((lib._racket/private/letstx-scheme..rkt)._let))" style="color: inherit">let</a></span> <span class="p">([</span><span class="n">new-code</span>
<span class="p">{</span>
<span class="c1">; set the sprite pointer to the first frame</span>
<span class="c1">; for this animation</span>
<span class="n">lda</span> <span class="n">@data-index</span>
<span class="n">sta</span> <span class="n">sprite-pointer</span>
<span class="p">}])</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/values.html#(def._((quote._~23~25kernel)._values))" style="color: inherit">values</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="p">(</span><span class="n">sprite-data-frame-count</span> <span class="n">s</span><span class="p">)</span> <span class="n">data-index</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="mi">1</span> <span class="n">sprite-pointer</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._cons))" style="color: inherit">cons</a></span> <span class="n">new-code</span> <span class="n">code</span><span class="p">))))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>The for/fold function builds up a list containing chunks of 6502 code, bringing along another 2 accumulators to track the sprite pointer and frame offset.</p>
<p>Racket’s for/fold actually returns all three accumulators as Racket “multiple values”. However, because asi64 only cares about 6502 code, it simply ignores the first two results, but it will then see a list of 6502 code which it will happily assemble.</p>
<p>Next up is to position the sprites on the screen. To do this, you have to set some more VIC registers. $d000 is Sprite 1’s X, $d001 is Sprite 1’s Y, and so on for each sprite.</p>
<p>We want to line the sprites up together at a fixed Y co-ordinate, but of course without overlapping on the X co-ordinates. A sprite is 24 pixels wide, so we’ll factor that in.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6
7
8</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="c1">;position sprites</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/for.html#(form._((lib._racket/private/base..rkt)._for))" style="color: inherit">for</a></span> <span class="p">([</span><span class="n">x</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sequences.html#(def._((lib._racket/private/base..rkt)._in-range))" style="color: inherit">in-range</a></span> <span class="mi">8</span><span class="p">)])</span>
<span class="p">{</span>
<span class="n">lda</span> <span class="n">@</span><span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="n">$20</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._*))" style="color: inherit">*</a></span> <span class="n">x</span> <span class="mi">24</span><span class="p">))</span>
<span class="n">sta</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="n">$d000</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._*))" style="color: inherit">*</a></span> <span class="n">x</span> <span class="mi">2</span><span class="p">))</span> <span class="c1">; x</span>
<span class="n">lda</span> <span class="n">@$D0</span>
<span class="n">sta</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="n">$d000</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="mi">1</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._*))" style="color: inherit">*</a></span> <span class="n">x</span> <span class="mi">2</span><span class="p">)))</span> <span class="c1">; y</span>
<span class="p">})</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>This is very easy since we can use all the bits of racket and the assembler together as one.</p>
<h2 id="animation">Animation</h2>
<p>Each animation has a set number of frames which we have extracted. What we will need to do is the following:</p>
<ul>
<li>Wait for some time so the animations aren’t ridiculously fast</li>
<li>Animate each sprite by changing its sprite pointer to the next frame, or wrapping back to the start</li></ul>
<p>How do we know where each animation currently is? Well, we know which sprite we are dealing with, and we can read its current pointer value. With a bit of maths we can work out where its base pointer is, therefore which frame it is currently in, and what the pointer value will be when it is at the last frame.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 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</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="k"><a href="http://docs.racket-lang.org/reference/Delayed_Evaluation.html#(form._((lib._racket/promise..rkt)._delay))" style="color: inherit">delay</a></span> <span class="n">$5</span><span class="p">)</span>
<span class="n">lda</span> <span class="n">@</span> <span class="k"><a href="http://docs.racket-lang.org/reference/Delayed_Evaluation.html#(form._((lib._racket/promise..rkt)._delay))" style="color: inherit">delay</a></span>
<span class="n">sta</span> <span class="n">$42</span>
<span class="n">:loop</span>
<span class="c1">; wait for the raster to hit the bottom of the screen</span>
<span class="n">lda</span> <span class="n">$d012</span>
<span class="n">cmp</span> <span class="n">@$ff</span>
<span class="n">bne</span> <span class="n">loop-</span>
<span class="c1">; decrease our delay by one</span>
<span class="n">ldx</span> <span class="n">$42</span>
<span class="n">dex</span>
<span class="c1">; if it is zero, branch out</span>
<span class="n">beq</span> <span class="n">change+</span>
<span class="c1">; otherwise store the new delay value and go back to waiting</span>
<span class="n">stx</span> <span class="n">$42</span>
<span class="n">jmp</span> <span class="n">loop-</span>
<span class="n">:change</span>
<span class="c1">; reset delay</span>
<span class="n">ldx</span> <span class="n">@</span> <span class="k"><a href="http://docs.racket-lang.org/reference/Delayed_Evaluation.html#(form._((lib._racket/promise..rkt)._delay))" style="color: inherit">delay</a></span>
<span class="n">stx</span> <span class="n">$42</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/for.html#(form._((lib._racket/private/base..rkt)._for/fold))" style="color: inherit">for/fold</a></span> <span class="p">([</span><span class="n">base-offset</span> <span class="n">$80</span><span class="p">]</span>
<span class="p">[</span><span class="n">index</span> <span class="mi">0</span><span class="p">]</span>
<span class="p">[</span><span class="n">code</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._list))" style="color: inherit">list</a></span><span class="p">)])</span>
<span class="p">([</span> <span class="n">s</span> <span class="n">sprites</span><span class="p">])</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/let.html#(form._((lib._racket/private/letstx-scheme..rkt)._let))" style="color: inherit">let</a></span> <span class="p">([</span><span class="n">new-code</span>
<span class="p">{</span>
<span class="c1">;load sprite pointer value</span>
<span class="n">ldx</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="n">$07f8</span> <span class="n">index</span><span class="p">)</span>
<span class="c1">;is it on the final frame? </span>
<span class="n">cpx</span> <span class="n">@</span><span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="n">base-offset</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._-))" style="color: inherit">-</a></span> <span class="p">(</span><span class="n">sprite-data-frame-count</span> <span class="n">s</span><span class="p">)</span> <span class="mi">1</span><span class="p">))</span>
<span class="n">bne</span> <span class="n">skip+</span>
<span class="c1">;reset to its first frame</span>
<span class="n">ldx</span> <span class="n">@base-offset</span>
<span class="n">stx</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="n">$07f8</span> <span class="n">index</span><span class="p">)</span>
<span class="n">jmp</span> <span class="n">done+</span>
<span class="n">:skip</span>
<span class="c1">; move to next frame</span>
<span class="n">inx</span>
<span class="n">stx</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="n">$07f8</span> <span class="n">index</span><span class="p">)</span>
<span class="n">:done</span>
<span class="p">}])</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/values.html#(def._((quote._~23~25kernel)._values))" style="color: inherit">values</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="n">base-offset</span> <span class="p">(</span><span class="n">sprite-data-frame-count</span> <span class="n">s</span><span class="p">))</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="mi">1</span> <span class="n">index</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._cons))" style="color: inherit">cons</a></span> <span class="n">new-code</span> <span class="n">code</span><span class="p">))))</span>
<span class="n">jmp</span> <span class="n">loop-</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Again here we are using our old friend for/fold to generate the code for us. Notice in this example, the generated code uses local labels of :skip and :done, it is able to do this since asi64 has a (fairly common) feature of being able to have many labels named the same thing. You tell it to jump to the nearest one it finds either in front or behid the current location by suffixing with + or - respectively.</p>
<h3 id="conclusion">Conclusion</h3>
<p>The full porgram has a few more features, but hopefully has exemplified the idea of mixing racket and 6502 together to help generating code. It is now very easy to dump some new files into the directory, regardless of how many frames they have, compile and run the program to see them animated in the emulator (or on the real machine!)</p>
<p>If you want to know more about how the sprites work on the C64, check out <a href="http:///www.codebase64.org">codebase</a> which is chock full of great information.</p>Lexical scoping and redefining function applicationurn:http-www-pinksquirrellabs-com:-blog-2017-08-10-lexical-scoping-and-redefining-function-application2017-08-10T16:17:04Z2017-08-10T16:17:04Zpezi
<p><a href="http://pinksquirrellabs.com/blog/2017/08/04/racket-macros-scurry/">The previous post</a> layed the foundations of creating a language and “compiler” using Racket macros.</p>
<p>This is all very nice, but utimately it is just a bunch of macros. The “language” itself doesn’t have any form of enforced semantics. You can introduce whatever syntax and macros you want, and use them however you like, even if it makes no sense at all.</p>
<p>Whilst this is nice in a way (and can lead to some .. interesting .. “features”) it is often more of a pain than it’s worth. Most of the errors we make in our day to day programming are picked up immediately by the background compiler, or the full compilation. Silly things like “clipboard inheritance” or typos attempting to use bindings that aren’t in scope are high on the list of culprits here.</p>
<p>In this post we will see how Racket can be used to help out by doing some lexical scope “analysis” in a slightly different way from a traditional compiler. We will also see how Racket can redefine its entire notion of function application, which will allow us to introduce some very nifty new syntax into Scurry itself.</p>
<!-- more-->
<h1 id="lexical-scoping">Lexical Scoping</h1>
<p>Scurry supports local bindings, lambdas and closures. This means that a given section of code can only “see” bindings that are in scope for it. The virtual machine itself of course manages this, but I can tell you it’s not much fun having to compile a program, load it in the VM and run it only to discover that you spelt “john” or “x” wrong.</p>
<p>A traditional compiler will lex/parse the code and produce an asbtract syntax tree. It will then perform a semantic analysis pass where it checks to make sure everything “makes sense”. This includes type checking and lexical scoping, amongst possibly other things. I don’t care about type checking for this language, but it would be nice to make sure bindings that are being used are in scope! Unlike a normal compiler though, the “compilation” here is happening within the racket compiler via macro expansion. This puts us in a unique position where we are “there as it happens” rather than “looking at it afterwards”.</p>
<p>A macro itself can also execute Racket code just like it can at runtime.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Defining_Simple_Macros.html#(form._((lib._syntax/parse/define..rkt)._define-syntax-parser))" style="color: inherit">define-syntax-parser</a></span> <span class="n">test</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/Writing.html#(def._((lib._racket/private/misc..rkt)._writeln))" style="color: inherit">writeln</a></span> <span class="s2">"at <a href="http://docs.racket-lang.org/reference/eval.html#(def._((quote._~23~25kernel)._compile))" style="color: inherit">compile</a> time"</span><span class="p">)</span>
<span class="o">#'</span><span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/Writing.html#(def._((lib._racket/private/misc..rkt)._writeln))" style="color: inherit">writeln</a></span> <span class="s2">"at runtime"</span><span class="p">)])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>This means we can do some interesting stuff such as track what is going on during compilation by writing whatever code we want. In this case, we can emulate what the VM does by keeping track of what bindings are in scope. The data structure for this is a stack of sets, where the stack represents layers of scopes and the sets are the names of bindings.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 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</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/begin.html#(form._((quote._~23~25kernel)._begin-for-syntax))" style="color: inherit">begin-for-syntax</a></span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">scoped-bindings-stack</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/boxes.html#(def._((quote._~23~25kernel)._box))" style="color: inherit">box</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._list))" style="color: inherit">list</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._mutable-set))" style="color: inherit">mutable-set</a></span><span class="p">))))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">push-scoped-stack</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/let.html#(form._((lib._racket/private/letstx-scheme..rkt)._let*))" style="color: inherit">let*</a></span> <span class="p">([</span><span class="n">lst</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/boxes.html#(def._((quote._~23~25kernel)._unbox))" style="color: inherit">unbox</a></span> <span class="n">scoped-bindings-stack</span><span class="p">)]</span>
<span class="p">[</span><span class="n">new-lst</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._cons))" style="color: inherit">cons</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._mutable-set))" style="color: inherit">mutable-set</a></span><span class="p">)</span> <span class="n">lst</span><span class="p">)])</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/boxes.html#(def._((quote._~23~25kernel)._set-box!))" style="color: inherit">set-box!</a></span> <span class="n">scoped-bindings-stack</span> <span class="n">new-lst</span><span class="p">)))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">pop-scoped-stack</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/let.html#(form._((lib._racket/private/letstx-scheme..rkt)._let*))" style="color: inherit">let*</a></span> <span class="p">([</span><span class="n">lst</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/boxes.html#(def._((quote._~23~25kernel)._unbox))" style="color: inherit">unbox</a></span> <span class="n">scoped-bindings-stack</span><span class="p">)]</span>
<span class="p">[</span><span class="n">new-lst</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._cdr))" style="color: inherit">cdr</a></span> <span class="n">lst</span><span class="p">)])</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/boxes.html#(def._((quote._~23~25kernel)._set-box!))" style="color: inherit">set-box!</a></span> <span class="n">scoped-bindings-stack</span> <span class="n">new-lst</span><span class="p">)))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">peek-scoped-stack</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/let.html#(form._((lib._racket/private/letstx-scheme..rkt)._let))" style="color: inherit">let</a></span> <span class="p">([</span><span class="n">lst</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/boxes.html#(def._((quote._~23~25kernel)._unbox))" style="color: inherit">unbox</a></span> <span class="n">scoped-bindings-stack</span><span class="p">)])</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._car))" style="color: inherit">car</a></span> <span class="n">lst</span><span class="p">)))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">add-scoped-binding</span> <span class="n">stx-name</span> <span class="n">stx</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/let.html#(form._((lib._racket/private/letstx-scheme..rkt)._let))" style="color: inherit">let</a></span> <span class="p">([</span><span class="n">name</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stxops.html#(def._((quote._~23~25kernel)._syntax-e))" style="color: inherit">syntax-e</a></span> <span class="n">stx-name</span><span class="p">)]</span>
<span class="p">[</span><span class="n">scoped</span> <span class="p">(</span><span class="n">peek-scoped-stack</span><span class="p">)])</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/when_unless.html#(form._((lib._racket/private/letstx-scheme..rkt)._when))" style="color: inherit">when</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set-member~3f))" style="color: inherit">set-member?</a></span> <span class="n">scoped</span> <span class="n">name</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/Writing.html#(def._((lib._racket/private/misc..rkt)._writeln))" style="color: inherit">writeln</a></span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/Writing.html#(def._((quote._~23~25kernel)._format))" style="color: inherit">format</a></span> <span class="s2">"warning: <a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/format..rkt)._~7ea))" style="color: inherit">~a</a> is already in scope at ~a"</span>
<span class="n">name</span> <span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Source_Locations.html#(def._((lib._syntax/srcloc..rkt)._source-location-~3estring))" style="color: inherit">source-location->string</a></span> <span class="n">stx</span><span class="p">))))</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set-add!))" style="color: inherit">set-add!</a></span> <span class="n">scoped</span> <span class="n">name</span><span class="p">)))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">in-scope?</span> <span class="n">name</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">aux</span> <span class="n">lst</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._cond))" style="color: inherit">cond</a></span>
<span class="p">[(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/list..rkt)._empty~3f))" style="color: inherit">empty?</a></span> <span class="n">lst</span><span class="p">)</span> <span class="no">#f</span><span class="p">]</span>
<span class="p">[(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sets.html#(def._((lib._racket/set..rkt)._set-member~3f))" style="color: inherit">set-member?</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._car))" style="color: inherit">car</a></span> <span class="n">lst</span><span class="p">)</span> <span class="n">name</span><span class="p">)</span> <span class="no">#t</span><span class="p">]</span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._else))" style="color: inherit">else</a></span> <span class="p">(</span><span class="n">aux</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._cdr))" style="color: inherit">cdr</a></span> <span class="n">lst</span><span class="p">))]))</span>
<span class="p">(</span><span class="n">aux</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/boxes.html#(def._((quote._~23~25kernel)._unbox))" style="color: inherit">unbox</a></span> <span class="n">scoped-bindings-stack</span><span class="p">))))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>You’ll notice the first thing is <code>begin-for-syntax</code> this elevates the <a href="http://docs.racket-lang.org/guide/phases.html">phase-level</a> by one, which makes this set of bindings accessible from the macros, meaning this stuff will happen at compile time.</p>
<p>You can see I am using mutable sets and (effectively mutable) lists for this implementation. Racket is a functional language and I’m sure there’s nicer ways to do this at compile time, but this is (currently) easy to reason about and it works just fine, so it will do for the time being!</p>
<p>Most of this is not very interesting - it does what you would expect and provides functions for pushing / popping new scopes, adding a binding name to the current scope, and a function that walks up the stack looking for a binding with a particular name.</p>
<p>One part that is interesting is inside <code>add-scoped-binding</code> - you can see it takes a syntax object <code>stx</code> which it can use to present a warning to the user if they have shadowed a binding, along with the location in the source file where it occured.</p>
<p>Let’s introduce a new syntax class like the <code>binding</code> one from the last post, with a key difference.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/begin.html#(form._((quote._~23~25kernel)._begin-for-syntax))" style="color: inherit">begin-for-syntax</a></span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/stxparse-specifying.html#(form._((lib._syntax/parse..rkt)._define-syntax-class))" style="color: inherit">define-syntax-class</a></span> <span class="n">scoped-binding</span>
<span class="kd">#:description</span> <span class="s2">"identifier in scope"</span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/stxparse-specifying.html#(form._((lib._syntax/parse..rkt)._pattern))" style="color: inherit">pattern</a></span> <span class="n">x:id</span>
<span class="kd">#:with</span> <span class="n">name</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/symbols.html#(def._((quote._~23~25kernel)._symbol-~3estring))" style="color: inherit">symbol->string</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stxops.html#(def._((quote._~23~25kernel)._syntax-e))" style="color: inherit">syntax-e</a></span> <span class="o">#'</span><span class="n">x</span><span class="p">))</span>
<span class="kd">#:when</span> <span class="p">(</span><span class="n">in-scope?</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/symbols.html#(def._((quote._~23~25kernel)._symbol-~3estring))" style="color: inherit">symbol->string</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stxops.html#(def._((quote._~23~25kernel)._syntax-e))" style="color: inherit">syntax-e</a></span> <span class="o">#'</span><span class="n">x</span><span class="p">))))))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>This is identical to the other syntax class, except it has a <code>when</code> clause that says the stringified version of it must be <code>in-scope?</code>.</p>
<p>Since all uses of bound identifiers as arguments must at some point or another come through the <code>eval-arg</code> macro, we can make a small tweak from this:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Defining_Simple_Macros.html#(form._((lib._syntax/parse/define..rkt)._define-syntax-parser))" style="color: inherit">define-syntax-parser</a></span> <span class="n">eval-arg</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">id:binding</span><span class="p">)</span>
<span class="o">#''</span><span class="p">((</span><span class="ss">ldvar</span> <span class="ss">id.name</span><span class="p">))</span>
<span class="c1">; rest of macro</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>to this:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Defining_Simple_Macros.html#(form._((lib._syntax/parse/define..rkt)._define-syntax-parser))" style="color: inherit">define-syntax-parser</a></span> <span class="n">eval-arg</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">id:scoped-binding</span><span class="p">)</span>
<span class="o">#''</span><span class="p">((</span><span class="ss">ldvar</span> <span class="ss">id.name</span><span class="p">))</span>
<span class="c1">; rest of macro</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>And that’s it. We will now get compile errors <em>anywhere in the entire language</em> that we try to use an identifier that is not bound. Of course, we are missing a piece, which is modifiying the macros that introduce bindings and scopes to call the relevant functions. Here’s def:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Defining_Simple_Macros.html#(form._((lib._syntax/parse/define..rkt)._define-syntax-parser))" style="color: inherit">define-syntax-parser</a></span> <span class="n">def</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">id:binding</span> <span class="n">expr</span><span class="p">)</span>
<span class="p">(</span><span class="n">add-scoped-binding</span> <span class="o">#'</span><span class="n">id.name</span> <span class="n"><a href="http://docs.racket-lang.org/syntax/stxparse-specifying.html#(form._((lib._syntax/parse..rkt)._this-syntax))" style="color: inherit">this-syntax</a></span><span class="p">)</span>
<span class="o">#'`</span><span class="p">(</span><span class="o">,</span><span class="p">(</span><span class="n">eval-arg</span> <span class="n">expr</span><span class="p">)</span>
<span class="p">(</span><span class="ss">stvar</span> <span class="ss">id.name</span><span class="p">))])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<div class="figure"><img src="http://www.pinksquirrellabs.com/img/scurry/scurry-1.png" alt="" />
<p class="caption"></p></div>
<p>Notice here the background compiler has picked up this error in Emacs! This is because the error occurs at macro expansion time.</p>
<p>Here is lambda:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Defining_Simple_Macros.html#(form._((lib._syntax/parse/define..rkt)._define-syntax-parser))" style="color: inherit">define-syntax-parser</a></span> <span class="n">s-lambda</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="p">(</span><span class="n">arg:binding</span><span class="p">)</span> <span class="n">body</span><span class="p">)</span>
<span class="p">(</span><span class="n">push-scoped-stack</span><span class="p">)</span>
<span class="p">(</span><span class="n">add-scoped-binding</span> <span class="o">#'</span><span class="n">arg.name</span> <span class="n"><a href="http://docs.racket-lang.org/syntax/stxparse-specifying.html#(form._((lib._syntax/parse..rkt)._this-syntax))" style="color: inherit">this-syntax</a></span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._with-syntax))" style="color: inherit">with-syntax</a></span>
<span class="p">([</span><span class="n">label</span> <span class="p">(</span><span class="n">new-label</span><span class="p">)])</span>
<span class="o">#'`</span><span class="p">(</span>
<span class="c1">;tell the assembler to create this later</span>
<span class="p">(</span><span class="ss">pending-function</span>
<span class="ss">label</span>
<span class="p">(</span><span class="ss">stvar</span> <span class="ss">arg.name</span><span class="p">)</span>
<span class="o">,</span><span class="n">body</span>
<span class="o">,</span><span class="p">(</span><span class="n">pop-scoped-stack</span><span class="p">)</span>
<span class="p">(</span><span class="ss">ret</span><span class="p">))</span>
<span class="p">(</span><span class="ss"><a href="http://docs.racket-lang.org/reference/lambda.html#(form._((lib._racket/private/base..rkt)._lambda))" style="color: inherit">lambda</a></span> <span class="ss">label</span><span class="p">)))])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Notice in lambda I am using <code>,(pop-scoped-stack)</code> which should not work since it’s at a different phase level (since it’s in the syntax being returned). I used a little trick here where I simply define a macro with the same name that it CAN see, that returns an empty list (there’s probably a nicer way to do this, I have not much clue what I am doing yet).</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6
7
8
9</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Defining_Simple_Macros.html#(form._((lib._syntax/parse/define..rkt)._define-syntax-parser))" style="color: inherit">define-syntax-parser</a></span> <span class="n">pop-scoped-stack</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="p">)</span>
<span class="p">(</span><span class="n">pop-scoped-stack</span><span class="p">)</span>
<span class="o">#''</span><span class="p">()])</span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Defining_Simple_Macros.html#(form._((lib._syntax/parse/define..rkt)._define-syntax-parser))" style="color: inherit">define-syntax-parser</a></span> <span class="n">push-scoped-stack</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span><span class="p">)</span>
<span class="p">(</span><span class="n">push-scoped-stack</span><span class="p">)</span>
<span class="o">#'`</span><span class="p">()])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Regardless, this is quite cool! The actual compiled bytecode of the lambda itself is re-arranged by the assembler much later and put at the bottom of the binary file. The scoping doesn’t care about this though as it only deals with what happens at <em>expansion time</em>. In this case, <code>,body</code> gets expanded first, then the scope is popped during expansion of <code>,(pop-scoped-stack)</code>, which means in the source definition of the lambda you will only have access to things bound lexically above you :)</p>
<p>Of course this is not limited to lambdas, it means now you can create macros that suggest scope, and have it enforced for you by the compiler. For example, Scurry is part functional part imperative, so it follows one of the most-used tools is <code>foreach</code> which allows you to bind each element of a list to some identifier and then use it in the body. I have now placed the scoping functions at the relavent places and the compiler will stop you attempting to use the bound identifier outside of the <code>foreach</code> scope.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 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</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define-syntax))" style="color: inherit">define-syntax</a></span> <span class="p">(</span><span class="n">foreach</span> <span class="n">stx</span><span class="p">)</span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Parsing_Syntax.html#(form._((lib._syntax/parse..rkt)._syntax-parse))" style="color: inherit">syntax-parse</a></span> <span class="n">stx</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="p">(</span><span class="n">var:binding</span> <span class="n">list-expr</span><span class="p">)</span> <span class="n">exprs</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)</span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/reference/syntax-util.html#(form._((lib._racket/syntax..rkt)._with-syntax*))" style="color: inherit">with-syntax*</a></span>
<span class="p">([</span><span class="n">label</span> <span class="p">(</span><span class="n">new-label</span><span class="p">)]</span>
<span class="p">[</span><span class="n">continue</span> <span class="p">(</span><span class="n">new-label</span><span class="p">)]</span>
<span class="p">[</span><span class="n">idx</span> <span class="p">(</span><span class="n">new-var</span><span class="p">)]</span>
<span class="p">[</span><span class="n">start</span>
<span class="o">#'`</span><span class="p">(</span>
<span class="o">,</span><span class="p">(</span><span class="n">eval-arg</span> <span class="n">list-expr</span><span class="p">)</span>
<span class="c1">;test there are items otherwise skip</span>
<span class="p">(</span><span class="ss">p_len</span><span class="p">)</span>
<span class="p">(</span><span class="ss">ldval</span> <span class="mi">0</span><span class="p">)</span>
<span class="p">(</span><span class="ss">beq</span> <span class="ss">continue</span><span class="p">)</span>
<span class="p">(</span><span class="ss">ldval</span> <span class="mi">0</span><span class="p">)</span>
<span class="p">(</span><span class="ss">stvar</span> <span class="ss">idx</span><span class="p">)</span>
<span class="p">(</span><span class="ss">label</span> <span class="ss">ldvar</span> <span class="ss">idx</span><span class="p">)</span>
<span class="p">(</span><span class="ss">p_index</span><span class="p">)</span>
<span class="p">(</span><span class="ss">stvar</span> <span class="ss">var.name</span><span class="p">))]</span>
<span class="p">[</span><span class="n">end</span>
<span class="o">#'`</span><span class="p">(</span>
<span class="p">(</span><span class="ss">p_len</span><span class="p">)</span>
<span class="p">(</span><span class="ss">ldvar</span> <span class="ss">idx</span><span class="p">)</span>
<span class="p">(</span><span class="ss">inc</span><span class="p">)</span>
<span class="p">(</span><span class="ss">p_stvar</span> <span class="ss">idx</span><span class="p">)</span>
<span class="p">(</span><span class="ss">bne</span> <span class="ss">label</span><span class="p">)</span>
<span class="p">(</span><span class="ss">continue</span><span class="p">)</span>
<span class="p">(</span><span class="ss">pop</span><span class="p">)</span>
<span class="o">,</span><span class="p">(</span><span class="n">pop-scoped-stack</span><span class="p">))])</span>
<span class="p">(</span><span class="n">push-scoped-stack</span><span class="p">)</span>
<span class="p">(</span><span class="n">add-scoped-binding</span> <span class="o">#'</span><span class="n">var.name</span> <span class="n">stx</span><span class="p">)</span>
<span class="o">#'</span><span class="p">(</span><span class="n">start</span> <span class="n">exprs</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span> <span class="n">end</span><span class="p">))]))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Here is an example of using foreach, where we shadow the binding <code>i</code> and get a warning for it, then try to use it again outside of the scope and get an error.</p>
<div class="figure"><img src="http://www.pinksquirrellabs.com/img/scurry/scurry-2.png" alt="" />
<p class="caption"></p></div>
<div class="figure"><img src="http://www.pinksquirrellabs.com/img/scurry/scurry-3.png" alt="" />
<p class="caption"></p></div>
<h1 id="property-accessors">Property Accessors</h1>
<p>The core datatype in Scurry, much like JavaScript or Lua, is a string->object dictionary.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">def-obj</span> <span class="n">player</span> <span class="p">([</span><span class="s2">"name"</span> <span class="s2">"juan"</span><span class="p">]</span>
<span class="p">[</span><span class="s2">"coins"</span> <span class="mi">0</span><span class="p">]))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>In order to use a property you must use the somewhat verbose <code>get-prop</code> syntax</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">def</span> <span class="n">money</span> <span class="p">(</span><span class="n">get-prop</span> <span class="n">player</span> <span class="s2">"coins"</span><span class="p">))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>This is very flexible as you can determine the object and the key with expressions, however, a lot of the time you just want to pass a property to some function call. As you can imagine, this can quickly get annoying. Even worse, if you want to add 10 to the player’s money, you’d have to do this</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">set-prop</span> <span class="n">player</span> <span class="s2">"coins"</span> <span class="p">(</span><span class="n">add</span> <span class="p">(</span><span class="n">get-prop</span> <span class="n">player</span> <span class="s2">"coins"</span><span class="p">)</span> <span class="mi">10</span><span class="p">))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Nasty! Since this is so common, I wrote some macros so you can do the following</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">prop+=</span> <span class="n">player</span> <span class="s2">"coins"</span> <span class="mi">10</span><span class="p">)</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Better, but still not very satisfing.</p>
<p>What I would really like is a sytax like Lua where i can write <code>obj.prop</code> as shorthand to refer to a property. Let’s see if we can write a syntax class to help do exactly that</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6
7
8
9</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/begin.html#(form._((quote._~23~25kernel)._begin-for-syntax))" style="color: inherit">begin-for-syntax</a></span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/stxparse-specifying.html#(form._((lib._syntax/parse..rkt)._define-syntax-class))" style="color: inherit">define-syntax-class</a></span> <span class="n">prop-accessor</span>
<span class="kd">#:description</span> <span class="s2">"property accessor"</span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/stxparse-specifying.html#(form._((lib._syntax/parse..rkt)._pattern))" style="color: inherit">pattern</a></span> <span class="n">x:id</span>
<span class="kd">#:when</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/string..rkt)._string-contains~3f))" style="color: inherit">string-contains?</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/symbols.html#(def._((quote._~23~25kernel)._symbol-~3estring))" style="color: inherit">symbol->string</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stxops.html#(def._((quote._~23~25kernel)._syntax-e))" style="color: inherit">syntax-e</a></span> <span class="o">#'</span><span class="n">x</span><span class="p">))</span> <span class="s2">"."</span><span class="p">)</span>
<span class="kd">#:with</span> <span class="n">ident</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._car))" style="color: inherit">car</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/string..rkt)._string-split))" style="color: inherit">string-split</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/symbols.html#(def._((quote._~23~25kernel)._symbol-~3estring))" style="color: inherit">symbol->string</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stxops.html#(def._((quote._~23~25kernel)._syntax-e))" style="color: inherit">syntax-e</a></span> <span class="o">#'</span><span class="n">x</span><span class="p">))</span> <span class="s2">"."</span><span class="p">))</span>
<span class="kd">#:when</span> <span class="p">(</span><span class="n">in-scope?</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stxops.html#(def._((quote._~23~25kernel)._syntax-e))" style="color: inherit">syntax-e</a></span> <span class="o">#'</span><span class="n">ident</span><span class="p">))</span>
<span class="kd">#:with</span> <span class="n">prop</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._cadr))" style="color: inherit">cadr</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/string..rkt)._string-split))" style="color: inherit">string-split</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/symbols.html#(def._((quote._~23~25kernel)._symbol-~3estring))" style="color: inherit">symbol->string</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stxops.html#(def._((quote._~23~25kernel)._syntax-e))" style="color: inherit">syntax-e</a></span> <span class="o">#'</span><span class="n">x</span><span class="p">))</span> <span class="s2">"."</span><span class="p">))</span>
<span class="p">)))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Here we check if the bidning has a "." in it and then split it into two halves. We also check the left half is <code>in-scope?</code> whilst we are at it, and return the left and right sides as <code>ident</code> and <code>prop</code>.</p>
<p>(apologies for the redundant bits of code here, I’ve not worked out how to sort that out yet!)</p>
<p>Now we can add a new ’lil case to the old faithful <code>eval-arg</code> macro:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">id:prop-accessor</span><span class="p">)</span>
<span class="o">#'</span><span class="p">(</span><span class="n">get-prop</span> <span class="n">id.ident</span> <span class="n">id.prop</span><span class="p">)]</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>And we are done. Now, we can use the shorthand property acessor anywhere in the whole language that accepts an argument! As an extra bonus, it will give you a compile error if you get your identifier wrong.</p>
<div class="figure"><img src="http://www.pinksquirrellabs.com/img/scurry/scurry-4.png" alt="" />
<p class="caption"></p></div>
<p>Fantastic! What about the other problem though? Wouldn’t it be really nice if you could write this, in completely non-lisp style?</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">john.coins</span> <span class="n">+=</span> <span class="mi">10</span><span class="p">)</span>
<span class="p">(</span><span class="n">john.coins</span> <span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._~3d))" style="color: inherit">=</a></span> <span class="mi">58</span><span class="p">)</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Of course, Lisp generally only accepts the prefix style, where the first element in the list must be a macro or function name. This would mean that <code>join.coins</code> would have to be a macro or function - that would be silly though, obviously!</p>
<p>One of the coolest tools in the Racket toolbox is the ability to override the way it applies functions themselves. It gives you the ability to “get in there first” and match on the whole pice of syntax and re-arrange it before it carries on (if it has not already matched the name to a macro, as far as I understand). There is a little logistical work to enable this which I won’t cover here, but essentially you end up re-defining the special form <code>#%app</code></p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define-syntax))" style="color: inherit">define-syntax</a></span> <span class="p">(</span><span class="n">app</span> <span class="n">stx</span><span class="p">)</span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Parsing_Syntax.html#(form._((lib._syntax/parse..rkt)._syntax-parse))" style="color: inherit">syntax-parse</a></span> <span class="n">stx</span>
<span class="kd">#:datum-literals</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._~3d))" style="color: inherit">=</a></span> <span class="n">+=</span> <span class="n">-=</span><span class="p">)</span>
<span class="p">[(</span><span class="n">app</span> <span class="n">f:prop-accessor</span> <span class="n">+=</span> <span class="n">val</span><span class="p">)</span>
<span class="o">#'</span><span class="p">(</span><span class="n">prop+=</span> <span class="n">f.ident</span> <span class="n">f.prop</span> <span class="n">val</span><span class="p">)]</span>
<span class="p">[(</span><span class="n">app</span> <span class="n">f:prop-accessor</span> <span class="n">-=</span> <span class="n">val</span><span class="p">)</span>
<span class="o">#'</span><span class="p">(</span><span class="n">prop-=</span> <span class="n">f.ident</span> <span class="n">f.prop</span> <span class="n">val</span><span class="p">)]</span>
<span class="p">[(</span><span class="n">app</span> <span class="n">f:prop-accessor</span> <span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._~3d))" style="color: inherit">=</a></span> <span class="n">val</span><span class="p">)</span>
<span class="o">#'</span><span class="p">(</span><span class="n">set-prop</span> <span class="n">f.ident</span> <span class="n">f.prop</span> <span class="n">val</span><span class="p">)]</span>
<span class="c1">; process everything else as normal</span>
<span class="p">[(</span><span class="n">app</span> <span class="n">f</span> <span class="o">.</span> <span class="n">a</span><span class="p">)</span> <span class="o">#'</span><span class="p">(</span><span class="n">f</span> <span class="o">.</span> <span class="n">a</span><span class="p">)]))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>In this very cool piece of code, we pattern match on the syntax just like any other macro, except this time we are matching on <em>all applications</em>. You can see here I use the <code>prop-accessor</code> syntax class in the head position, followed by one of the three literals = += and -=. If these match, they are rewritten to their relevant scurry forms, otherwise, we allow the application to carry on as it normally would.</p>
<p>Now, this code works, and we still get the in-scope check :)</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">scurry</span>
<span class="p">(</span><span class="n">def-obj</span> <span class="n">john</span> <span class="p">([</span><span class="s2">"coins"</span> <span class="mi">100</span><span class="p">]))</span>
<span class="p">(</span><span class="n">dbgl</span> <span class="s2">"john has"</span> <span class="n">john.coins</span> <span class="s2">" coins"</span><span class="p">)</span>
<span class="p">(</span><span class="n">john.coins</span> <span class="n">+=</span> <span class="mi">10</span><span class="p">)</span>
<span class="p">(</span><span class="n">dbgl</span> <span class="s2">"john now has"</span> <span class="n">john.coins</span> <span class="s2">" coins"</span><span class="p">))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Imagine the possibilies with this!</p>
<p>In fact, here’s a very cool one. Since Scurry is a mixture of compile time macros and lambda function applications, I had to have a macro to perform the function application:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Defining_Simple_Macros.html#(form._((lib._syntax/parse/define..rkt)._define-syntax-parser))" style="color: inherit">define-syntax-parser</a></span> <span class="n">~</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">f</span> <span class="n">args</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)</span>
<span class="o">#'`</span><span class="p">(</span><span class="o">,</span><span class="p">(</span><span class="n">eval-arg</span> <span class="n">f</span><span class="p">)</span>
<span class="p">((</span><span class="o">,</span><span class="p">(</span><span class="n">eval-arg</span> <span class="n">args</span><span class="p">)</span> <span class="p">(</span><span class="ss"><a href="http://docs.racket-lang.org/reference/procedures.html#(def._((lib._racket/private/base..rkt)._apply))" style="color: inherit">apply</a></span><span class="p">))</span> <span class="ss"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">))])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>This is great, but it gets very annoying having to write <code>(~ f arg)</code> everywhere, and it’s easy to forget. Wouldn’t it be nice if Racket just assumed everyhing that wasn’t a macro must need a scurry function application?</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="c1">; process everything else as a scurry function appication</span>
<span class="p">[(</span><span class="n">app</span> <span class="n">f</span> <span class="o">.</span> <span class="n">a</span><span class="p">)</span> <span class="o">#'</span><span class="p">(</span><span class="n">~</span> <span class="n">f</span> <span class="o">.</span> <span class="n">a</span><span class="p">)]</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Done! Now the entire language no longer needs explicit function application.</p>
<p>That’s it for this time around, I hope this shows you some more of what Racket is capable of.</p>Racket Macros : Scurryurn:http-www-pinksquirrellabs-com:-blog-2017-08-04-racket-macros-scurry2017-08-04T13:12:48Z2017-08-04T13:12:48Zpezi
<p>This post will be about <a href="http://docs.racket-lang.org/guide/macros.html">Racket macros</a>. As a delivery mechanism, I will be using bits of my latest project, which is a virtual machine designed for emulating multiplayer networked board games via <a href="http://zeromq.org/">ZeroMQ</a>. drey-vm executes compiled bytecode files - much like the CLR or JVM - using an instruction set of my design.</p>
<p>The design of the computer is out of the scope of this post (maybe another post if people are interested in it - let me know in the comments!?) suffice to stay it is written in D and is mostly a stack based computer, supporting functional and imperative programming. It has a string/object dictionary as its primary type,like lua and js.</p>
<p>Much like <a href="http://pinksquirrellabs.com/blog/2017/05/30/asi64/">asi64</a>, I wrote an assembler for the virtual machine in Racket. On top of that assembler I can now build a language (scurry). To start with, I am just creating a Racket language that is still a lisp - Racket has the fantasic power of being able to build macros on macros, gradually introducing higher level syntatic forms. In this way, I don’t really need write an actual compiler. Racket gives me the front end of the compiler for free (being lisp), and the macros-over-assembler method is a very fun and flexibile way to build up a language.</p>
<!-- more-->
<h1 id="macros">Macros</h1>
<p>This post is about macros. I am still new to them and have learnt a lot, but am many many leagues from being an expert. Macros can be hard to get your head around and I spent many hours flailing around not knowing how to do stuff I wanted, so hopefully some of things I discovered might help someone else out.</p>
<p>It is recommended you have already read Greg Hendershott’s excellent <a href="http://www.greghendershott.com/fear-of-macros">fear of macros</a> post, which I read many times!.</p>
<p>Let’s look at the basics. The VM has a special object with an id of –1 that represents the game’s global state. In scurry, I would like to write this to retrieve it</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">get-state</span><span class="p">)</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>This should be rewritten to the op-codes that load the game object of id –1 and leave it on the stack. (this will be used in expressions or bound to some identifier later.) Eventually, when this program actually executes and assembles, it is expecting a big list of symbols that represent the program. Thus:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define-syntax))" style="color: inherit">define-syntax</a></span> <span class="p">(</span><span class="n">get-state</span> <span class="n">stx</span><span class="p">)</span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Parsing_Syntax.html#(form._((lib._syntax/parse..rkt)._syntax-parse))" style="color: inherit">syntax-parse</a></span> <span class="n">stx</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span><span class="p">)</span>
<span class="o">#''</span><span class="p">((</span><span class="ss">ldval</span> <span class="mi">-1</span><span class="p">)</span>
<span class="p">(</span><span class="ss">getobj</span><span class="p">))]))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>stx is the syntax object that repesents the Racket expression that has been passed in, including the “get-state” itself. We are then using syntax-parse to pattern match on this syntax object - we expect one value between parens which I have wildcarded out as I know it is “get-state” and don’t care about it. This means if you try and use this macro with an argument, you’ll get a compile error.</p>
<p>Finally we return a syntax object using the shorthand form #’( ). Since what I actually want to return is a list of symbols, we are quoting the response list (otherwise it would try and evaluate (ldval –1) and (getobj) as functions, which don’t exist!).</p>
<h1 id="eval-arg">eval-arg</h1>
<p>Now let’s tackle the first major problem. In practially all other macros from here on out, they are going to accept some inputs. The inputs could be constant strings, numbers, bools, an identifier, or another scurry expression. To illustrate, let’s say we wanted to write this</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">def</span> <span class="n">x</span> <span class="mi">42</span><span class="p">)</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p> x here is the name of a variable or binding. In drey-vm terms, it has to translate the usage of an identifier like this to storing or retrieving a named variable currently in scope on the call stack. The question is, how can we tell the difference between them and generate the correct code? Let’s look at macro that will be used heavily from this point onwards.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define-syntax))" style="color: inherit">define-syntax</a></span> <span class="p">(</span><span class="n">eval-arg</span> <span class="n">stx</span><span class="p">)</span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Parsing_Syntax.html#(form._((lib._syntax/parse..rkt)._syntax-parse))" style="color: inherit">syntax-parse</a></span> <span class="n">stx</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">ident:id</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._with-syntax))" style="color: inherit">with-syntax</a></span> <span class="p">([</span><span class="n">name</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/symbols.html#(def._((quote._~23~25kernel)._symbol-~3estring))" style="color: inherit">symbol->string</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stxops.html#(def._((quote._~23~25kernel)._syntax-e))" style="color: inherit">syntax-e</a></span> <span class="o">#'</span><span class="n">ident</span><span class="p">))])</span>
<span class="c1">; if this is an identifier then it will be a string table lookup</span>
<span class="c1">; to a variable </span>
<span class="o">#''</span><span class="p">((</span><span class="ss">ldvar</span> <span class="ss">name</span><span class="p">)))]</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">expr:str</span><span class="p">)</span>
<span class="o">#''</span><span class="p">((</span><span class="ss">ldvals</span> <span class="ss">expr</span><span class="p">))]</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">expr:integer</span><span class="p">)</span>
<span class="o">#''</span><span class="p">((</span><span class="ss">ldval</span> <span class="ss">expr</span><span class="p">))]</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">expr:boolean</span><span class="p">)</span>
<span class="o">#''</span><span class="p">((</span><span class="ss">ldvalb</span> <span class="ss">expr</span><span class="p">))]</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">expr</span><span class="p">)</span>
<span class="c1">;otherwise let it pass through</span>
<span class="o">#'</span><span class="n">expr</span> <span class="p">]))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Several new and interesting things are happening here. Firstly, we are making use of <a href="https://docs.racket-lang.org/syntax/Library_Syntax_Classes_and_Literal_Sets.html?q=syntax%20class">Racket’s syntax classes</a>. These are the annoataions you see in the pattern match, :id :str :integer and :boolean. These are standard syntax classes supplied by the Racket language to help match on common things.</p>
<p>The first case will only match if the passed argument is an identifier. Then, we introduce a new piece of syntax <em>name</em>, that is produced by unwrapping the syntax object <em>ident</em> and turning it into a string. We can then use it directly in the returned syntax block, ’((ldvar name)). If <em>ident</em> was the identifier <em>x</em>, it would produce the code ’((ldvar “x”)) which is what the assembler expects. Pretty cool huh!</p>
<p>The subsequent 3 matches simply produce the correct op code to load the given int, string or bool constant.</p>
<p>The last match catches all other expressions - in this case we do not want to directy output bytecode - we want to continue evaluating whatever it is. All we have to do here is simply return the bit of syntax as it is and let the Racket compiler continue its expansion of it where neccesary.</p>
<p>The with-syntax part takes some getting your head around. It tends to be used so often that if you need just a single bit of extra syntax like we had in this case, there is a shortcut you can use:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">ident:id</span><span class="p">)</span>
<span class="kd">#:with</span> <span class="n">name</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/symbols.html#(def._((quote._~23~25kernel)._symbol-~3estring))" style="color: inherit">symbol->string</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stxops.html#(def._((quote._~23~25kernel)._syntax-e))" style="color: inherit">syntax-e</a></span> <span class="o">#'</span><span class="n">x</span><span class="p">))</span>
<span class="o">#''</span><span class="p">((</span><span class="ss">ldvar</span> <span class="ss">name</span><span class="p">)))</span><span class="err">]</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>In fact, since we will need to do this kind of thing all the time (turning an identifier into a name) we can even write out very own syntax class to help out!</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/begin.html#(form._((quote._~23~25kernel)._begin-for-syntax))" style="color: inherit">begin-for-syntax</a></span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/stxparse-specifying.html#(form._((lib._syntax/parse..rkt)._define-syntax-class))" style="color: inherit">define-syntax-class</a></span> <span class="n">binding</span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/stxparse-specifying.html#(form._((lib._syntax/parse..rkt)._pattern))" style="color: inherit">pattern</a></span> <span class="n">x:id</span> <span class="kd">#:with</span> <span class="n">name</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/symbols.html#(def._((quote._~23~25kernel)._symbol-~3estring))" style="color: inherit">symbol->string</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stxops.html#(def._((quote._~23~25kernel)._syntax-e))" style="color: inherit">syntax-e</a></span> <span class="o">#'</span><span class="n">x</span><span class="p">)))))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Notice how this uses both the :id syntax class and the #:with shorthand to introduce a new piece of syntax. Now in the original code we can write this to get at it</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">ident:binding</span><span class="p">)</span>
<span class="o">#''</span><span class="p">((</span><span class="ss">ldvar</span> <span class="ss">ident.name</span><span class="p">)))</span><span class="err">]</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Very nice, yes?</p>
<h1 id="level-up">Level up</h1>
<p>Now let’s see how we can use this previous macro in the context of other macros. Let’s re-visit def. We wanted to write</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">def</span> <span class="n">x</span> <span class="mi">42</span><span class="p">)</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>The macro pretty much writes itself</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define-syntax))" style="color: inherit">define-syntax</a></span> <span class="p">(</span><span class="n">def</span> <span class="n">stx</span><span class="p">)</span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Parsing_Syntax.html#(form._((lib._syntax/parse..rkt)._syntax-parse))" style="color: inherit">syntax-parse</a></span> <span class="n">stx</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">id:binding</span> <span class="n">expr</span><span class="p">)</span>
<span class="o">#'`</span><span class="p">(</span> <span class="c1">;expr should calculate some value on the stack, or load a constant</span>
<span class="o">,</span><span class="p">(</span><span class="n">eval-arg</span> <span class="n">expr</span><span class="p">)</span>
<span class="p">(</span><span class="ss">stvar</span> <span class="ss">id.name</span><span class="p">)))))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>So, we tell the macro to expect two bits of syntax, the first must match our handy <em>binding</em> syntax class from before, and some <em>expr</em>. Now, we don’t know what <em>expr</em> is - it could be anything. Thankfully, our equally-handy <em>eval-arg</em> macro will sort it out for us. Notice here we are using a slightly different syntax to return the syntax object, usually we use #’’( ) but here we are using a backtick instead. This is because we are returning a quoted list, but there’s one part of the list we <em>don’t</em> want quoted, because we want racket to expand it - that is of course the <em>eval-arg</em> macro, which you can see is prefixed with , - a shorthand for <em>unquote</em>. If this doesn’t make sense, study and play with it until it does, since it is very important and part of the secret sacue that makes writing these so nice.</p>
<p>As an illustrative example, if we had not used the unquote, it would have simply returned a list of symbols ((eval-arg expr) (stvar “x”)). This is not what we want, eval-arg is not an opcode - what we wanted is for it to expand out to ((ldvals “hello world”)(stvar “x”)) or similar.</p>
<p>Let’s actually see this in action. First let’s write a cool macro that will produce the assembly code for the VM to add two numbers together. It needs to load the numbers onto the stack and call the add instruction.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Defining_Simple_Macros.html#(form._((lib._syntax/parse/define..rkt)._define-syntax-parser))" style="color: inherit">define-syntax-parser</a></span> <span class="n">add</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">left</span> <span class="n">right</span><span class="p">)</span>
<span class="o">#'`</span><span class="p">(</span><span class="o">,</span><span class="p">(</span><span class="n">eval-arg</span> <span class="n">left</span><span class="p">)</span>
<span class="o">,</span><span class="p">(</span><span class="n">eval-arg</span> <span class="n">right</span><span class="p">)</span>
<span class="p">(</span><span class="ss">add</span><span class="p">))])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Easy! Here we are using the shorthand <em>define-syntax-parser</em> so we don’t have to keep writing the redundant <em>define-syntax</em>, <em>syntax-parse</em> stuff. The nested macros make short work of this task and our wonderful add macro will work with any constants <em>or nested expressions</em> just as you would expect it to.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">def</span> <span class="n">x</span> <span class="mi">42</span><span class="p">)</span>
<span class="c1">; this works! </span>
<span class="p">(</span><span class="n">def</span> <span class="n">y</span> <span class="p">(</span><span class="n">add</span> <span class="n">x</span> <span class="mi">58</span><span class="p">))</span>
<span class="c1">; so does this!!</span>
<span class="p">(</span><span class="n">def</span> <span class="n">z</span> <span class="p">(</span><span class="n">add</span> <span class="n">y</span> <span class="p">(</span><span class="n">add</span> <span class="n">z</span> <span class="n">x</span><span class="p">))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>What about if we want our add macro to take more than two numbers, in the typical lisp style? For example, I’d like to write (def z (add y z x)). Enter the ellipsis!</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Defining_Simple_Macros.html#(form._((lib._syntax/parse/define..rkt)._define-syntax-parser))" style="color: inherit">define-syntax-parser</a></span> <span class="n">add</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">left</span> <span class="n">right</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span> <span class="p">)</span>
<span class="o">#'`</span><span class="p">(</span><span class="o">,</span><span class="p">(</span><span class="n">eval-arg</span> <span class="n">left</span><span class="p">)</span>
<span class="p">((</span><span class="o">,</span><span class="p">(</span><span class="n">eval-arg</span> <span class="n">right</span><span class="p">)</span>
<span class="p">(</span><span class="ss">add</span><span class="p">))</span> <span class="ss"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">))])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>The use of the ellipsis here means the argument <em>right</em> can represent any amount of arguments. Then, in the syntax that is returned, we wrap the expression we want to repeat for each instance of <em>right</em> in some more parens and place the … after. The result of this is the following; If you call (add 1 2), after its nested macro expansion, you would get</p>
<p>(ldval 1) (ldval 2) (add)</p>
<p>And if you call (add 1 2 3 4) you will get</p>
<p>(ldval 1) (ldval 2) (add) (ldval 3) (add) (ldval 4) (add)</p>
<p>Very awesome, yes? (n.b. actually, there would be a few more parens in there due to the extra ones we had to put in to get the ellipsis pattern to work, I left them out here for readability - the assembler removes any excess)</p>
<h1 id="further-adventures-in-macro-land">Further adventures in macro land</h1>
<p>Let’s try something else. The language is pretty terrible with no conditionals and logical functions in it. We will try and implement <em>and</em>. The <em>and</em> macro should take any amount of expressions, evaluate them, and if any return <em>false</em> then we short-circuit out and load the constant value 0 on stack. If all return true, we load the constant value 1 on the stack.</p>
<p>This needs some new bits to help it along - the assembler and bytecode can only deal in jumps to explict locations in memory, so we will need a way to label instructions so they can be used as jump targets. The assembler itself already supports this, and the details are out of scope of this post - let’s look at the macro</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Defining_Simple_Macros.html#(form._((lib._syntax/parse/define..rkt)._define-syntax-parser))" style="color: inherit">define-syntax-parser</a></span> <span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._and))" style="color: inherit">and</a></span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">expr</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)</span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/reference/syntax-util.html#(form._((lib._racket/syntax..rkt)._with-syntax*))" style="color: inherit">with-syntax*</a></span>
<span class="p">([</span><span class="n">when-false</span> <span class="p">(</span><span class="n">new-label</span><span class="p">)]</span>
<span class="p">[</span><span class="n">end</span> <span class="p">(</span><span class="n">new-label</span><span class="p">)]</span>
<span class="p">[(</span><span class="n">cases</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)</span>
<span class="o">#'`</span><span class="p">((</span><span class="o">,</span><span class="p">(</span><span class="n">eval-arg</span> <span class="n">expr</span><span class="p">)</span>
<span class="p">(</span><span class="ss">ldvalb</span> <span class="mi">0</span><span class="p">)</span>
<span class="p">(</span><span class="ss">beq</span> <span class="ss">when-false</span><span class="p">))</span><span class="ss"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)])</span>
<span class="o">#'`</span><span class="p">(</span><span class="o">,</span><span class="p">(</span><span class="n">cases</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)</span>
<span class="p">(</span><span class="ss">ldvalb</span> <span class="mi">1</span><span class="p">)</span>
<span class="p">(</span><span class="ss">branch</span> <span class="ss">end</span><span class="p">)</span>
<span class="p">(</span><span class="ss">when-false</span> <span class="ss">ldvalb</span> <span class="mi">0</span><span class="p">)</span>
<span class="p">(</span><span class="ss">end</span><span class="p">)))])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Hmm, what’s going on here! A bunch of new stuff. Firstly, the <em>with-syntax*</em> form alows you to introduce several bits of syntax, where later ones are able to reference the earlier ones.</p>
<p>You can see two labels are introduced <em>when-false</em> and <em>end</em> (the details are not important, its basically just a unique string). The we have some magic in <em>cases …</em>. You can see on the left hand side of the expression we have an ellipsis - this says that we are creating several bits of syntax here that we can refer to later, based on the ellipsis in the parent syntax, in this case our sequence of <em>expr</em> expressions.</p>
<p>So, the implementation of a <em>case</em> is to evaluate the expression, load 0 on the to stack and then call the branch-equal (beq) opcode with the jump target of <em>when-false</em>. This is basically going to check each expression result against 0 (false) and if it is, then jump to the <em>when-false</em> label, short-circuiting the evaluation of the rest of the exressions.</p>
<p>You can see then in the actual syntax that is returned, the first thing that happens is that the <em>cases …</em> syntax is spliced in using the unuqote mechanism. We know that if we reach the code beyond the cases, they must have all returned true - so we load 1 onto the stack and uncondtionally branch to the <em>end</em> label. Next, you can see the <em>when-false</em> label which loads 0 onto the stack and continues. Finally. the <em>end</em> label which signifies where whatever the next code to be assembled is.</p>
<p>(note - the <em>cases …</em> did not have to be introduced in the <em>with-syntax</em>, it could have just been in the body like before - I was showing alternate ways to include ellipsis based syntax)</p>
<h1 id="macros-in-macros-in-macros-in-macros-">Macros in macros in macros in macros …</h1>
<p>Let’s take this to the next level by introducing a truly higher level macro, that is defined almost entirely using other macros. drey-vm has the concept of what I have called <em>flowroutines</em> TM. As their name indicates, they are similar to co-routines, and seamlessly handle getting a response from a particular client. To use them, you create a <em>flow</em> object and add a bunch of “choices” into it - these are basically a string and an index. Upon calling the opcode <em>suspend</em>, the VM will turn the flow object into a json request, send it to the client over ZMQ and suspend execution until it gets a result. When the client responds, the VM can assert the response is a valid one and then load the client’s choice index on to the stack and continue executing. Here is an example on how it looks in a game I am writing.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="p">(</span><span class="n">def-λ</span> <span class="p">(</span><span class="n">enter-temple</span> <span class="n">player</span> <span class="n"><a href="http://docs.racket-lang.org/xml/index.html#(def._((lib._xml/main..rkt)._location))" style="color: inherit">location</a></span><span class="p">)</span>
<span class="c1">;player can donate up to three coins to the temple</span>
<span class="p">(</span><span class="n">extract</span> <span class="p">([(</span><span class="n">clientid</span> <span class="n">coins</span><span class="p">)</span> <span class="n">player</span><span class="p">])</span>
<span class="p">(</span><span class="n">def-λ</span> <span class="p">(</span><span class="n">coins->temple</span> <span class="n">n</span><span class="p">)</span>
<span class="p">(</span><span class="n">prop-=</span> <span class="n">player</span> <span class="s2">"coins"</span> <span class="n">n</span><span class="p">)</span>
<span class="p">(</span><span class="n">prop+=</span> <span class="n">player</span> <span class="s2">"points"</span> <span class="n">n</span><span class="p">)</span>
<span class="p">(</span><span class="n">prop+=</span> <span class="n"><a href="http://docs.racket-lang.org/xml/index.html#(def._((lib._xml/main..rkt)._location))" style="color: inherit">location</a></span> <span class="p">(</span><span class="n">concat</span> <span class="n">clientid</span> <span class="s2">"-coins"</span><span class="p">)</span> <span class="n">n</span><span class="p">))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/when_unless.html#(form._((lib._racket/private/letstx-scheme..rkt)._when))" style="color: inherit">when</a></span> <span class="p">(</span><span class="n">gt</span> <span class="n">coins</span> <span class="mi">0</span><span class="p">)</span>
<span class="p">(</span><span class="n">flow</span> <span class="n">clientid</span> <span class="s2">"donate to the temple"</span>
<span class="p">([</span><span class="no">#t</span> <span class="s2">"1 coin"</span> <span class="p">(</span><span class="n">~</span> <span class="n">coins->temple</span> <span class="mi">1</span><span class="p">)]</span>
<span class="p">[(</span><span class="n">gt</span> <span class="n">coins</span> <span class="mi">1</span><span class="p">)</span> <span class="s2">"2 coins"</span> <span class="p">(</span><span class="n">~</span> <span class="n">coins->temple</span> <span class="mi">2</span><span class="p">)]</span>
<span class="p">[(</span><span class="n">gt</span> <span class="n">coins</span> <span class="mi">2</span><span class="p">)</span> <span class="s2">"3 coins"</span> <span class="p">(</span><span class="n">~</span> <span class="n">coins->temple</span> <span class="mi">3</span><span class="p">)]</span>
<span class="p">[</span><span class="no">#t</span> <span class="s2">"do <a href="http://docs.racket-lang.org/reference/booleans.html#(def._((quote._~23~25kernel)._not))" style="color: inherit">not</a> donate"</span> <span class="o">'</span><span class="p">()])))))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>There’s several other scurry things you have not seen yet, including lambda functions with closures, <em>extract</em> which is a form of pattern matching, and function application ( ~ ). <em>flow</em> is what we are interested in here, though. You can see it accepts a clientid and some title, then it is followed by a list of expressions. Each expression starts with a predicate that determines if this choice shoud be included, then a name for the choice, and finally, an expression that will be evaluated if the user chooses that particular choice.</p>
<p>They way I wrote this (and all the other higher level macros) is to simply write the syntax how I would like to use it (as above), then re-write what it will need to look like expanded, and finally attempt to write a macro to convert from one to the other. So, in this case, I would like the (flow …) expression above to be re-written to the following, rather boring and full of boiler-plate code, that has nothing do with the actual itent of what is happening:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n">def-flow</span> <span class="n">some-generated-name</span> <span class="s2">"enter temple"</span><span class="p">)</span>
<span class="c1">; add cases</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/when_unless.html#(form._((lib._racket/private/letstx-scheme..rkt)._when))" style="color: inherit">when</a></span> <span class="no">#t</span>
<span class="p">(</span><span class="n">add-flow-action</span> <span class="n">some-generated-name</span> <span class="mi">0</span> <span class="s2">"1 coin"</span><span class="p">))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/when_unless.html#(form._((lib._racket/private/letstx-scheme..rkt)._when))" style="color: inherit">when</a></span> <span class="p">(</span><span class="n">gt</span> <span class="n">coins</span> <span class="mi">1</span><span class="p">)</span>
<span class="p">(</span><span class="n">add-flow-action</span> <span class="n">some-generated-name</span> <span class="mi">1</span> <span class="s2">"2 coins"</span><span class="p">))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/when_unless.html#(form._((lib._racket/private/letstx-scheme..rkt)._when))" style="color: inherit">when</a></span> <span class="p">(</span><span class="n">gt</span> <span class="n">coins</span> <span class="mi">2</span><span class="p">)</span>
<span class="p">(</span><span class="n">add-flow-action</span> <span class="n">some-generated-name</span> <span class="mi">2</span> <span class="s2">"3 coins"</span><span class="p">))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/when_unless.html#(form._((lib._racket/private/letstx-scheme..rkt)._when))" style="color: inherit">when</a></span> <span class="no">#t</span>
<span class="p">(</span><span class="n">add-flow-action</span> <span class="n">some-generated-name</span> <span class="mi">3</span> <span class="s2">"do <a href="http://docs.racket-lang.org/reference/booleans.html#(def._((quote._~23~25kernel)._not))" style="color: inherit">not</a> donate"</span><span class="p">))</span>
<span class="c1">; suspend to client</span>
<span class="p">(</span><span class="n">def</span> <span class="n">another-generated-name</span> <span class="p">(</span><span class="n">flow</span> <span class="n">some-generated-name</span> <span class="n">clientid</span><span class="p">))</span>
<span class="c1">; dispatch based on response</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._cond))" style="color: inherit">cond</a></span>
<span class="p">[(</span><span class="n">eq</span> <span class="n">another-generated-name</span> <span class="mi">0</span><span class="p">)</span> <span class="p">(</span><span class="n">~</span> <span class="n">coins->temple</span> <span class="mi">1</span><span class="p">)]</span>
<span class="p">[(</span><span class="n">eq</span> <span class="n">another-generated-name</span> <span class="mi">1</span><span class="p">)</span> <span class="p">(</span><span class="n">~</span> <span class="n">coins->temple</span> <span class="mi">2</span><span class="p">)]</span>
<span class="p">[(</span><span class="n">eq</span> <span class="n">another-generated-name</span> <span class="mi">2</span><span class="p">)</span> <span class="p">(</span><span class="n">~</span> <span class="n">coins->temple</span> <span class="mi">3</span><span class="p">)]</span>
<span class="p">[(</span><span class="n">eq</span> <span class="n">another-generated-name</span> <span class="mi">3</span><span class="p">)</span> <span class="o">'</span><span class="p">()])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>I think we can agree, the proposed syntax is way nicer than having to manually write that lot all the time! However, it sems like a tall order - somehow we have to generate those index numbers, and although we are repeating code for each input case, we need several pieces of generated code in different places - how is it going to work? Amazingly, it is not that diffcult - other than a trick to generate the index numbers.</p>
<p>Let’s start with the flow clauses. They consist of three expressions each, and there may be several of them. Racket allows us to define a <em>splicing syntax class</em> that is exactly the same as the syntax classes we’ve already seen except it works with ellipsis patterns. Here it is:</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/begin.html#(form._((quote._~23~25kernel)._begin-for-syntax))" style="color: inherit">begin-for-syntax</a></span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/stxparse-specifying.html#(form._((lib._syntax/parse..rkt)._define-splicing-syntax-class))" style="color: inherit">define-splicing-syntax-class</a></span> <span class="n">flow-clauses</span>
<span class="p">[</span><span class="n"><a href="http://docs.racket-lang.org/syntax/stxparse-specifying.html#(form._((lib._syntax/parse..rkt)._pattern))" style="color: inherit">pattern</a></span> <span class="p">{</span><span class="n"><a href="http://docs.racket-lang.org/syntax/stxparse-patterns.html#(form._((lib._syntax/parse..rkt)._~7eseq))" style="color: inherit">~seq</a></span> <span class="p">[</span><span class="n">eq-expr</span> <span class="n">case-title-expr</span> <span class="n">true-expr</span><span class="p">]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">}</span>
<span class="kd">#:with</span> <span class="p">[</span><span class="n">n</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">]</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/private/map..rkt)._map))" style="color: inherit">map</a></span> <span class="nb"><a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/format..rkt)._~7ea))" style="color: inherit">~a</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/list..rkt)._range))" style="color: inherit">range</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._length))" style="color: inherit">length</a></span> <span class="p">(</span><span class="n">attribute</span> <span class="n">eq-expr</span><span class="p">))))]))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Here you can see we expect a <em>flow-clause</em> to contain three expressions in brackets, and indicate there may be many of them with the ellipsis at the end. The #:with is some magic I struggled to get to work - however it is very similar to the <em>cases</em> from earlier - it indicates there will be one <em>n</em> for each pattern, and we produce a list of numbers from 0 to the amount of patterns that exist by using the <em>range</em> function and testing the <em>eq-expr</em> attribute’s length from the syntax.</p>
<p>Phew, that was a bit of a hard one. Thankfully, with that bit written and functioning, the rest is actually fairly striaght forward. Notice how it closely resembles the manually written out version above.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Defining_Simple_Macros.html#(form._((lib._syntax/parse/define..rkt)._define-syntax-parser))" style="color: inherit">define-syntax-parser</a></span> <span class="n">flow</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">client</span> <span class="n">title-expr</span> <span class="p">(</span><span class="n">expr:flow-clauses</span><span class="p">))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._with-syntax))" style="color: inherit">with-syntax</a></span>
<span class="p">([</span><span class="n">flow-name</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/symbols.html#(def._((quote._~23~25kernel)._string-~3esymbol))" style="color: inherit">string->symbol</a></span> <span class="p">(</span><span class="n">new-var</span><span class="p">))]</span>
<span class="p">[</span><span class="n">resp-name</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/symbols.html#(def._((quote._~23~25kernel)._string-~3esymbol))" style="color: inherit">string->symbol</a></span> <span class="p">(</span><span class="n">new-var</span><span class="p">))])</span>
<span class="o">#'`</span><span class="p">(</span><span class="o">,</span><span class="p">(</span><span class="n">def-flow</span> <span class="n">flow-name</span> <span class="n">title-expr</span><span class="p">)</span>
<span class="p">((</span><span class="o">,</span><span class="p">(</span><span class="n">s-when</span> <span class="n">expr.eq-expr</span>
<span class="p">(</span><span class="n">add-flow-action</span> <span class="n">flow-name</span> <span class="n">expr.n</span> <span class="n">expr.case-title-expr</span><span class="p">))</span><span class="ss"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">))</span>
<span class="o">,</span><span class="p">(</span><span class="n">def</span> <span class="n">resp-name</span> <span class="p">(</span><span class="n">flow</span> <span class="n">flow-name</span> <span class="n">client</span><span class="p">))</span>
<span class="o">,</span><span class="p">(</span><span class="n">s-cond</span>
<span class="p">[(</span><span class="n">eq</span> <span class="n">resp-name</span> <span class="n">expr.n</span><span class="p">)</span> <span class="n">expr.true-expr</span><span class="p">]</span> <span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._......))" style="color: inherit">...</a></span><span class="p">)</span>
<span class="p">))]</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">req</span> <span class="n">client</span><span class="p">)</span>
<span class="o">#'`</span><span class="p">(</span><span class="o">,</span><span class="p">(</span><span class="n">eval-arg</span> <span class="n">req</span><span class="p">)</span>
<span class="o">,</span><span class="p">(</span><span class="n">eval-arg</span> <span class="n">client</span><span class="p">)</span>
<span class="p">(</span><span class="ss">suspend</span><span class="p">))])</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Notice here how we use the ellipsis <em>twice</em> in this to generate code for the whens and the cond - racket is perfectly happy with this and pretty much does exactly what you expect! Fairly amazing stuff! The case at the bottom is an overloaded <em>flow</em> that does the actual work of loading the flow object, client, and calling <em>suspend</em> with it.</p>
<h1 id="end">End</h1>
<p>I hope this post has given you some idea on the power of these racket macros! I still have a long way to go, no doubt - I am constantly surprised with the new stuff I learn. If you want to see more of these macros for scurry (there’s over 1k lines of them) you can have a look in my <a href="https://github.com/pezipink/scurry/blob/master/asm.rkt">github here</a>. If you are interested in seeing more of these or would like to know more about the virtual machine itself, please let me know in the comments!</p>
<p>Happy macroing !</p>Asi64urn:http-www-pinksquirrellabs-com:-blog-2017-05-30-asi642017-05-30T13:37:10Z2017-05-30T13:37:10Zpezi
<p>In my last few posts, I detailed some of my experience learning <a href="http://6502.org/">6502</a> assembler for the Commodore 64. I started off using <a href="http://dasm-dillon.sourceforge.net/">DASM</a>, which seems to be quite a nice assembler, severely lacking in documentation. Then I discovered the very awesome <a href="http://www.theweb.dk/KickAssembler/Main.html#frontpage">KickAssembler</a>, which includes a full blown scripting language on top of java, lots of other very nice features, and great documentation. This made me realise what a powerful modern assembler could be like - and perhaps I could go one step further with it.</p>
<p>Asi64 extends <a href="http://racket-lang.org/">Racket</a> to become a 6502 assembler. No need for scripting languages or half baked macro systems here - you have literally all of Racket and its amazing macro system on your side. It also has direct support for <a href="http://vice-emu.sourceforge.net/">Vice</a>, a popular Commodore 64 emulator, passing your labels and breakpoints along enabling a fluid programming and debugging cycle. Hats off to the fantasic KickAssembler, I have stolen many ideas from it :)</p>
<div class="figure"><img src="http://www.pinksquirrellabs.com/img/asi/asi0.png" alt="" />
<p class="caption"></p></div>
<!-- more-->
<p>If you want to have a go, <a href="https://github.com/pezipink/Asi64">you get can asi64 from my github here</a> or the racket package manager - see the github repo for a brief rundown of syntax and getting started. Currently, this is targetted at Windows - the assembler itself should work fine on any OS but it might need a small tweak in how it executes the emulator - PRs would be welcome!</p>
<p>By way of introduction to some bits of the assembler (definetly not even touching on its potential) we will write a relatively simple demo effect, a very basic starfield. (note this is not attempting to teach 6502 or Racket!)</p>
<h2 id="starfields">Starfields!</h2>
<p>To make a simple starfield we will use the C64’s character graphics. In this mode, the VIC-II graphics chip will point at an area in memory where a character set of our design is stored. A character is defined as an 8x8 grid of pixels. In memory, this is stored sequentially as 8 bytes, where the bits of each byte represent a pixel, going from the top row of the character downwards.</p>
<p>The VIC chip goes on its merry way rendering graphics. On every 8th scanline (known as a “bad line”) it will read the next row of video memory in and work out which characters it needs to display. This is fairly simple, the video memory is somewhere of our choosing and represents the 40*25 characters laid out sequentially. Each byte in the memory represents a character index from the character set to render. This means you can have 256 characters in a set, for a 2k total of memory.</p>
<h2 id="setup">Setup</h2>
<p>First, let’s get the boring stuff out of the way, which is telling the VIC chip where to look for the video and character memory. In this example, we will use $0c00 for the video memory, $2000 for the character memory, and stick our program at $1000.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6
7
8
9</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="kn">#lang </span><span class="nn">asi64</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">vic-control</span> <span class="n">$d018</span><span class="p">)</span>
<span class="p">(</span><span class="n">C64</span><span class="p">{</span>
<span class="n">*=</span> <span class="n">$1000</span>
<span class="n">lda</span> <span class="n">@%00111000</span>
<span class="c1">; screen at $0c00, characters at $2000</span>
<span class="n">sta</span> <span class="n">vic-control</span>
<span class="n">jmp</span> <span class="p">(</span><span class="n">here</span><span class="p">)</span> <span class="c1">;infinite loop</span>
<span class="p">})</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>$d018 is the vic register which controls where it looks for things. Here we load the value 00111000 into it which <a href="http://codebase64.org/doku.php?id=base:vicii_memory_organizing">sets things up how we want</a>. The combination of lda, sta is so common that we can get asi64 to provide us a little abstraction over it by using the <code>define-op</code> macro.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="kn">#lang </span><span class="nn">asi64</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">vic-control</span> <span class="n">$d018</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">black</span> <span class="mi">0</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">background</span> <span class="n">$d021</span><span class="p">)</span>
<span class="p">(</span><span class="n">define-op</span> <span class="p">(</span><span class="n">mov</span> <span class="n">src</span> <span class="n">dst</span><span class="p">){</span>
<span class="n">lda</span> <span class="n">src</span>
<span class="n">sta</span> <span class="n">dst</span>
<span class="p">})</span>
<span class="p">(</span><span class="n">C64</span><span class="p">{</span>
<span class="n">*=</span> <span class="n">$1000</span>
<span class="p">(</span><span class="n">mov</span> <span class="n">@%00111000</span> <span class="n">vic-control</span><span class="p">)</span>
<span class="p">(</span><span class="n">mov</span> <span class="n">@black</span> <span class="n">background</span><span class="p">)</span>
<span class="n">jmp</span> <span class="p">(</span><span class="n">here</span><span class="p">)</span> <span class="c1">;infinite loop</span>
<span class="p">})</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>From now on I will mostly omit code that’s already been shown since assembly quickly gets large.</p>
<h2 id="character-design">Character Design</h2>
<p>What we will do is have 5 characters in a row and rotate pixels through them on each screen refresh. Therefore, character 0 we will start off with a single pixel in the centre of it. The next 4 characters will simply be blank, waiting to recieve the pixel. Then, the video memory will be tiled with chracters 0 – 5 to give the illusion of a (terrible) star field.</p>
<p>So let’s go ahead and build our characters. We know the memory starts at $2000, therefore that address represents the top row of pixels for the first character.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="n">lda</span> <span class="n">@0</span>
<span class="n">sta</span> <span class="n">$2000</span>
<span class="n">sta</span> <span class="n">$2001</span>
<span class="n">sta</span> <span class="n">$2002</span>
<span class="n">sta</span> <span class="n">$2003</span>
<span class="n">sta</span> <span class="n">$2005</span>
<span class="n">sta</span> <span class="n">$2006</span>
<span class="n">sta</span> <span class="n">$2007</span>
<span class="c1">; a single pixel in the centre!</span>
<span class="n">lda</span> <span class="n">@%00001000</span>
<span class="n">sta</span> <span class="n">$20004</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Well, this is boring. And we still need to do the next 4 characters. As ever in assembly you have to choose between writing loops or unrolling them - space vs speed - in this case we will stick to unrolled code. I think racket can help us out here though.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="n">lda</span> <span class="n">@0</span>
<span class="c1">;splat the first 5 characters </span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/for.html#(form._((lib._racket/private/base..rkt)._for))" style="color: inherit">for</a></span> <span class="p">([</span><span class="n">i</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sequences.html#(def._((lib._racket/private/base..rkt)._in-range))" style="color: inherit">in-range</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._*))" style="color: inherit">*</a></span> <span class="mi">8</span> <span class="mi">5</span><span class="p">))])</span>
<span class="p">{</span><span class="n">sta</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="n">$2000</span> <span class="n">i</span><span class="p">)})</span>
<span class="c1">; load our humble pixel</span>
<span class="p">(</span><span class="n">mov</span> <span class="n">@%00001000</span> <span class="n">$2004</span><span class="p">)</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Much better. Ok, so we might have written over $2004 in the loop needlessly, but whatever, that could easily be rectified. Next up is to tile the screen with the 0–4 sequence. We could unroll some code to do this, or write a loop, but there is another option. We can simply write to the video memory directly as part of the assembly process.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="n">*=</span> <span class="n">$0c00</span> <span class="c1">;asssemble at video memory location</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/for.html#(form._((lib._racket/private/base..rkt)._for))" style="color: inherit">for</a></span> <span class="p">([</span><span class="n">i</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sequences.html#(def._((lib._racket/private/base..rkt)._in-range))" style="color: inherit">in-range</a></span> <span class="mi">0</span> <span class="mi">200</span><span class="p">)])</span>
<span class="p">(</span><span class="n">data</span> <span class="mi">0</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span><span class="p">))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Don’t know about you but I am already bored of keep writing this for .. in-range stuff. Let’s knock up a quick macro to do it for us.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6
7</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define-syntax))" style="color: inherit">define-syntax</a></span> <span class="p">(</span><span class="n">fori</span> <span class="n">stx</span><span class="p">)</span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/syntax/Parsing_Syntax.html#(form._((lib._syntax/parse..rkt)._syntax-parse))" style="color: inherit">syntax-parse</a></span> <span class="n">stx</span>
<span class="p">([</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">e</span> <span class="n">f</span><span class="p">]</span>
<span class="c1">; breaking hygeine here, very sorry</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._with-syntax))" style="color: inherit">with-syntax</a></span> <span class="p">([</span><span class="n">f2</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stxops.html#(def._((quote._~23~25kernel)._syntax-~3edatum))" style="color: inherit">syntax->datum</a></span> <span class="o">#'</span><span class="n">f</span><span class="p">)])</span>
<span class="o">#'</span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/for.html#(form._((lib._racket/private/base..rkt)._for))" style="color: inherit">for</a></span> <span class="p">([</span><span class="n">i</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sequences.html#(def._((lib._racket/private/base..rkt)._in-range))" style="color: inherit">in-range</a></span> <span class="mi">0</span> <span class="n">e</span><span class="p">)])</span>
<span class="n">f2</span><span class="p">)))))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Yes, this is a terrible macro! It breaks hygeine and won’t even work in some cases. I am just putting it here to show that you can!</p>
<p>Now we can write</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="n">lda</span> <span class="n">@0</span>
<span class="c1">;splat the first 5 characters </span>
<span class="p">(</span><span class="n">fori</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._*))" style="color: inherit">*</a></span> <span class="mi">8</span> <span class="mi">5</span><span class="p">)</span> <span class="p">{</span><span class="n">sta</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="n">$2000</span> <span class="n">i</span><span class="p">)})</span>
<span class="c1">; load our humble pixel</span>
<span class="p">(</span><span class="n">mov</span> <span class="n">@%00001000</span> <span class="n">$2004</span><span class="p">)</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>and</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="n">*=</span> <span class="n">$0c00</span> <span class="c1">;asssemble at video memory location</span>
<span class="p">(</span><span class="n">fori</span> <span class="mi">200</span> <span class="p">(</span><span class="n">data</span> <span class="mi">0</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span><span class="p">))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Rawr!</p>
<div class="figure"><img src="http://www.pinksquirrellabs.com/img/asi/asi1.png" alt="" />
<p class="caption"></p></div>
<h2 id="move-it">Move it!</h2>
<p>I’ll admit this looks like a pretty terrible star field. Even when moving it will look bad, but one problem at a time. Let’s get it moving! The basic operation will be to rotate $2004 to the right. This will move the bit along one place, and if it falls off the end of the byte it will end up in the processor’s carry bit. From there, if we rotate right the same row-byte of the next character ($200c) the bit will move from the carry into the most signficant bit of the next character’s byte. we can repeat this process, with a special case for the last character since it needs to wrap around back to the first one if the carry is set.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6
7
8</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="n">:update_starfield</span>
<span class="n">clc</span> <span class="c1">; clear carry bit</span>
<span class="c1">; ror our little guy through memory</span>
<span class="p">(</span><span class="n">fori</span> <span class="mi">5</span> <span class="p">{</span><span class="n">ror</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="n">$2004</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._*))" style="color: inherit">*</a></span> <span class="n">i</span> <span class="mi">8</span><span class="p">))})</span>
<span class="n">bcc</span> <span class="n">end+</span>
<span class="n">ror</span> <span class="n">$2004</span>
<span class="n">:end</span>
<span class="n">rts</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>We will call this subroutine once each video frame. To achieve this we will burn cycles until the raster hits the bottom of the screen-ish (since we don’t want to update whilst the VIC is rendering!), call this procedure, and then wait again. Usually you’d do this with raster interrupts since obviously sitting waiting for the screen means you can’t do anything else, but it will suffice for this example.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="n">lda</span> <span class="n">@$ff</span>
<span class="n">:loop</span> <span class="n">cmp</span> <span class="n">$d012</span> <span class="c1">; wait for line 256</span>
<span class="n">bne</span> <span class="n">loop-</span>
<span class="n">jsr</span> <span class="n">update_starfield+</span>
<span class="c1">; do nothing for a while so </span>
<span class="c1">; this doesn't trigger more than</span>
<span class="c1">; once on the same frame!</span>
<span class="p">(</span><span class="n">fori</span> <span class="mi">100</span> <span class="p">{</span><span class="n">nop</span><span class="p">})</span>
<span class="n">lda</span> <span class="n">@$ff</span>
<span class="n">jmp</span> <span class="n">loop-</span>
</pre></div>
</td></tr></tbody></table>
</div>
<div class="figure"><img src="http://www.pinksquirrellabs.com/img/asi/asi2.gif" alt="" />
<p class="caption"></p></div>
<h2 id="making-it-not-terrible">Making it not terrible</h2>
<p>As amazing as the single pixel going across the screen in a lockstep obviously repeated pattern is, we can probably do better. The obvious problems are:</p>
<ul>
<li>There is only one lonely pixel</li>
<li>The pixels should travel at different speeds to produce a parallax effect</li>
<li>The tiling should be broken up into different perumations on each row</li></ul>
<p>If we had more pixels, it would mean more RORing of the relevant bytes. To make them move faster, we’d have to repeat the whole ROR cycle more than once. Clearly, this quickly escalates into tons of boring and hard to change code. Instead, we will get racket to help us out by writing a function that can generate a starfield update to our specifications. We will pass it a memory location of the character set, the amount of characters to rotate through, a list of tuples that indicate which rows of the character need rotating and at what speed.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define-struct.html#(form._((lib._racket/private/base..rkt)._struct))" style="color: inherit">struct</a></span> <span class="n">starbank</span> <span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/xml/index.html#(def._((lib._xml/main..rkt)._location))" style="color: inherit">location</a></span> <span class="n">len</span> <span class="n">rows</span><span class="p">))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">generate-starfield-updates-1</span> <span class="n">starbank</span><span class="p">)</span>
<span class="c1">;location - charset location where the first starfield char is</span>
<span class="c1">;len - how many chars to ROL through</span>
<span class="c1">;rows - which rows of the character contain stars (no point ROLing them otherwise)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">char-index</span> <span class="n">i</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="p">(</span><span class="n">starbank-location</span> <span class="n">starbank</span><span class="p">)</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._*))" style="color: inherit">*</a></span> <span class="mi">8</span> <span class="n">i</span><span class="p">)))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/for.html#(form._((lib._racket/private/base..rkt)._for))" style="color: inherit">for</a></span> <span class="p">([</span><span class="n">row</span> <span class="p">(</span><span class="n">starbank-rows</span> <span class="n">starbank</span><span class="p">)])</span>
<span class="c1">;extract the row number and speed</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/let.html#(form._((lib._racket/private/letstx-scheme..rkt)._let))" style="color: inherit">let</a></span> <span class="p">([</span><span class="n">row</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._car))" style="color: inherit">car</a></span> <span class="n">row</span><span class="p">)]</span>
<span class="p">[</span><span class="n">speed</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._cadr))" style="color: inherit">cadr</a></span> <span class="n">row</span><span class="p">)])</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/for.html#(form._((lib._racket/private/base..rkt)._for))" style="color: inherit">for</a></span> <span class="p">([</span><span class="n">s</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sequences.html#(def._((lib._racket/private/base..rkt)._in-range))" style="color: inherit">in-range</a></span> <span class="mi">0</span> <span class="n">speed</span><span class="p">)])</span>
<span class="c1">;repeat the ror cycle for speed times</span>
<span class="p">{</span><span class="n">clc</span> <span class="c1">; clear the carry bit!</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/for.html#(form._((lib._racket/private/base..rkt)._for))" style="color: inherit">for</a></span> <span class="p">([</span><span class="n">char</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sequences.html#(def._((lib._racket/private/base..rkt)._in-range))" style="color: inherit">in-range</a></span> <span class="mi">0</span> <span class="p">(</span><span class="n">starbank-len</span> <span class="n">starbank</span><span class="p">))])</span>
<span class="c1">;now we just ror each character in turn</span>
<span class="p">{</span><span class="n">ror</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="p">(</span><span class="n">char-index</span> <span class="n">char</span><span class="p">)</span> <span class="n">row</span><span class="p">)})</span>
<span class="c1">; special wrap-around case</span>
<span class="n">bcc</span> <span class="n">end+</span>
<span class="n">ror</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="p">(</span><span class="n">char-index</span> <span class="mi">0</span><span class="p">)</span> <span class="n">row</span><span class="p">)</span>
<span class="n">:end</span> <span class="n">rts</span> <span class="p">}))))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>This is pretty cool. It basically writes the same code as we did manually last time except now it can do it for multiple rows at different speeds. This makes it really easy to tinker with the values to produce a nice looking starfield.</p>
<p>What if we wanted to scroll the stars left instead of right? The basic principle is the same, we still need to rotate the pixels through memory, except we must rotate left, the wrap around goes from the first to the last character, and the characters must be processed in reverse. Since racket is allowing us to conditionally generate assembly code, we can interleave this as an option into our generator</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define-struct.html#(form._((lib._racket/private/base..rkt)._struct))" style="color: inherit">struct</a></span> <span class="n">starbank</span> <span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/xml/index.html#(def._((lib._xml/main..rkt)._location))" style="color: inherit">location</a></span> <span class="n">len</span> <span class="n">rows</span><span class="p">))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">generate-starfield-updates</span> <span class="n">starbank</span> <span class="n">going-right?</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">char-index</span> <span class="n">i</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="p">(</span><span class="n">starbank-location</span> <span class="n">starbank</span><span class="p">)</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._*))" style="color: inherit">*</a></span> <span class="mi">8</span> <span class="n">i</span><span class="p">)))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/for.html#(form._((lib._racket/private/base..rkt)._for))" style="color: inherit">for</a></span> <span class="p">([</span><span class="n">row</span> <span class="p">(</span><span class="n">starbank-rows</span> <span class="n">starbank</span><span class="p">)])</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/let.html#(form._((lib._racket/private/letstx-scheme..rkt)._let))" style="color: inherit">let</a></span> <span class="p">([</span><span class="n">row</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._car))" style="color: inherit">car</a></span> <span class="n">row</span><span class="p">)]</span>
<span class="p">[</span><span class="n">speed</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._cadr))" style="color: inherit">cadr</a></span> <span class="n">row</span><span class="p">)])</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/for.html#(form._((lib._racket/private/base..rkt)._for))" style="color: inherit">for</a></span> <span class="p">([</span><span class="n">s</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sequences.html#(def._((lib._racket/private/base..rkt)._in-range))" style="color: inherit">in-range</a></span> <span class="mi">0</span> <span class="n">speed</span><span class="p">)])</span>
<span class="p">{</span><span class="n">clc</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/for.html#(form._((lib._racket/private/base..rkt)._for))" style="color: inherit">for</a></span> <span class="p">([</span><span class="n">char</span> <span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((quote._~23~25kernel)._if))" style="color: inherit">if</a></span> <span class="n">going-right?</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sequences.html#(def._((lib._racket/private/base..rkt)._in-range))" style="color: inherit">in-range</a></span> <span class="mi">0</span> <span class="p">(</span><span class="n">starbank-len</span> <span class="n">starbank</span><span class="p">))</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sequences.html#(def._((lib._racket/private/base..rkt)._in-range))" style="color: inherit">in-range</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._-))" style="color: inherit">-</a></span> <span class="p">(</span><span class="n">starbank-len</span> <span class="n">starbank</span><span class="p">)</span> <span class="mi">1</span><span class="p">)</span> <span class="mi">-1</span> <span class="mi">-1</span><span class="p">))])</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((quote._~23~25kernel)._if))" style="color: inherit">if</a></span> <span class="n">going-right?</span>
<span class="p">{</span><span class="n">ror</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="p">(</span><span class="n">char-index</span> <span class="n">char</span><span class="p">)</span> <span class="n">row</span><span class="p">)}</span>
<span class="p">{</span><span class="n">rol</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="p">(</span><span class="n">char-index</span> <span class="n">char</span><span class="p">)</span> <span class="n">row</span><span class="p">)}))</span>
<span class="c1">;finally wrap around if the carry is et</span>
<span class="n">bcc</span> <span class="n">end+</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((quote._~23~25kernel)._if))" style="color: inherit">if</a></span> <span class="n">going-right?</span>
<span class="p">{</span><span class="n">ror</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="p">(</span><span class="n">char-index</span> <span class="mi">0</span><span class="p">)</span> <span class="n">row</span><span class="p">)}</span>
<span class="p">{</span><span class="n">rol</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="p">(</span><span class="n">char-index</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._-))" style="color: inherit">-</a></span> <span class="p">(</span><span class="n">starbank-len</span> <span class="n">starbank</span><span class="p">)</span> <span class="mi">1</span><span class="p">))</span> <span class="n">row</span><span class="p">)})</span>
<span class="n">:end</span><span class="p">}))))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>It’s pretty much the same code, it just produces rols instead of rors and processes the things backwards.</p>
<p>You could extend this to also create the chracter memory for you, and have it return two functions that you can call and label somewhere in the program, one for generating and the other for updating. You can probably see how this could quickly become a build-your-own-tailored-compiler-kit if you wanted it to.</p>
<p>The last part was to re-arrange to video memory so each row has a different permuatation of the 0 1 2 3 4 sequence. There’s a number of ways we could do this of course. Randomness doens’t work very well, so I messed around a bit until I found a good pattern, and hardcoded it at compile-time.</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="n">*=</span> <span class="n">$0c00</span> <span class="c1">;asssemble at video memory location</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/let.html#(form._((lib._racket/private/letstx-scheme..rkt)._let))" style="color: inherit">let</a></span> <span class="p">([</span><span class="n">perm1</span> <span class="o">'</span><span class="p">(</span><span class="mi">0</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span><span class="p">)]</span>
<span class="p">[</span><span class="n">perm2</span> <span class="o">'</span><span class="p">(</span><span class="mi">4</span> <span class="mi">0</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span><span class="p">)]</span>
<span class="p">[</span><span class="n">perm3</span> <span class="o">'</span><span class="p">(</span><span class="mi">3</span> <span class="mi">4</span> <span class="mi">0</span> <span class="mi">1</span> <span class="mi">2</span><span class="p">)]</span>
<span class="p">[</span><span class="n">perm4</span> <span class="o">'</span><span class="p">(</span><span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span> <span class="mi">0</span> <span class="mi">1</span><span class="p">)]</span>
<span class="p">[</span><span class="n">order</span> <span class="o">'</span><span class="p">(</span><span class="mi">1</span> <span class="mi">4</span> <span class="mi">2</span> <span class="mi">1</span> <span class="mi">3</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">4</span>
<span class="mi">1</span> <span class="mi">4</span> <span class="mi">2</span> <span class="mi">1</span> <span class="mi">3</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">4</span>
<span class="mi">1</span> <span class="mi">4</span> <span class="mi">2</span> <span class="mi">1</span> <span class="mi">3</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">4</span>
<span class="mi">1</span><span class="p">)])</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/for.html#(form._((lib._racket/private/base..rkt)._for))" style="color: inherit">for</a></span> <span class="p">([</span><span class="n">next</span> <span class="n">order</span><span class="p">])</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/for.html#(form._((lib._racket/private/base..rkt)._for))" style="color: inherit">for</a></span><span class="p">([</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/list..rkt)._count))" style="color: inherit">count</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/sequences.html#(def._((lib._racket/private/base..rkt)._in-range))" style="color: inherit">in-range</a></span> <span class="mi">8</span><span class="p">)])</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/case.html#(form._((lib._racket/private/more-scheme..rkt)._case))" style="color: inherit">case</a></span> <span class="n">next</span>
<span class="p">[(</span><span class="mi">1</span><span class="p">)</span> <span class="p">(</span><span class="n">data</span> <span class="n">perm1</span><span class="p">)]</span>
<span class="p">[(</span><span class="mi">2</span><span class="p">)</span> <span class="p">(</span><span class="n">data</span> <span class="n">perm2</span><span class="p">)]</span>
<span class="p">[(</span><span class="mi">3</span><span class="p">)</span> <span class="p">(</span><span class="n">data</span> <span class="n">perm3</span><span class="p">)]</span>
<span class="p">[(</span><span class="mi">4</span><span class="p">)</span> <span class="p">(</span><span class="n">data</span> <span class="n">perm4</span><span class="p">)]))))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Omitting the code to stick some more pixels in our character set,our new update code becomes</p>
<div class="brush: racket">
<table class="highlighttable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14</pre></div></td>
<td class="code">
<div class="highlight">
<pre><span></span> <span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">sb1</span> <span class="p">(</span><span class="n">starbank</span> <span class="n">$2000</span> <span class="mi">5</span> <span class="o">'</span><span class="p">((</span><span class="mi">1</span> <span class="mi">1</span><span class="p">)</span> <span class="p">(</span><span class="mi">3</span> <span class="mi">2</span><span class="p">)</span> <span class="p">(</span><span class="mi">5</span> <span class="mi">4</span><span class="p">))))</span>
<span class="n">lda</span> <span class="n">@$ff</span>
<span class="n">:loop</span> <span class="n">cmp</span> <span class="n">$d012</span> <span class="c1">; wait for line 256</span>
<span class="n">bne</span> <span class="n">loop-</span>
<span class="n">jsr</span> <span class="n">update-starfield</span>
<span class="c1">; do nothing for a while so </span>
<span class="c1">; this doesn't trigger more than</span>
<span class="c1">; once on the same frame!</span>
<span class="p">(</span><span class="n">fori</span> <span class="mi">100</span> <span class="p">{</span><span class="n">nop</span><span class="p">})</span>
<span class="n">lda</span> <span class="n">@$ff</span>
<span class="n">jmp</span> <span class="n">loop-</span>
<span class="n">:update-starfield</span>
<span class="p">(</span><span class="n">generate-starfield-updates</span> <span class="n">sb1</span> <span class="no">#t</span><span class="p">)</span>
<span class="n">rts</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>The final result, I think you will agree is much better looking, even if it is still a bit rubbish! (actually, the gif is kinda terrible, it looks a lot better on the emulator and much better still on the real thing!)</p>
<div class="figure"><img src="http://www.pinksquirrellabs.com/img/asi/asi3.gif" alt="" />
<p class="caption"></p></div>
<h2 id="conclusion">Conclusion</h2>
<p>Asi64 brings racket and 6502 together in a (hopefully!) glorious fusion. It is by no means finished, and will likely be rewritten again at least one more time. This is basically my first proper Racket project so I still have much to learn, but it is a lot more fun to program the Commodore 64 now ! (You could also use this to program the NES!). Comments are welcome.</p>
<p>Here is a picture of the lovely starfield running on the real hardware :)</p>
<div class="figure"><img src="http://www.pinksquirrellabs.com/img/asi/asi4.png" alt="" />
<p class="caption"></p></div>
<p>The full code for this example can be found at the github repo <a href="https://github.com/pezipink/asi64/blob/master/samples/starfield.rkt">here</a></p>Programming in Racket #1urn:http-www-pinksquirrellabs-com:-blog-2017-01-14-programming-in-racket-12017-01-14T02:48:06Z2017-01-14T02:48:06Zpezi
<p>Over the last few days I have been learning <a href="http://docs.racket-lang.org/index.html">Racket</a>, a language derived from Scheme.  The main selling point of Racket is its <a href="http://docs.racket-lang.org/reference/Macros.html">extensive macro system</a> that lets you do everything from the simplest macros through to redefining the entire language (yes you can even get rid of the parens!).  It is a programming language programming language. In fact, Racket is more of a customisable programming language infrastructure / engine with a default language on top of it.</p>
<!-- more-->
<p>Now, we won’t get to anything too crazy in this post since, well, the mental stuff I have wrote I’d not be happy to show you yet (there will be a little macro though!), but I have been working on the <a href="http://adventofcode.com/2015">Advent of Code 2015</a> problems with an eye for attempting to discover the various language features and interesting things it has to offer - rather than the primary objective being to solve the Advent of Code puzzles. Here is some of what I have learnt so far.</p>
<p>
<h2>Day 1</h2>
<p>Day 1 of AOC has us help tracking Santa’s position in a lift.  This is seemingly a job for our good old friend fold.</p>
<p><a href="http://www.pinksquirrellabs.com/img/old/2017-01-13%2017_56_45-emacs@DESKTOP-2DMNUOL_1.png"><img title="2017-01-13 17_56_45-emacs@DESKTOP-2DMNUOL" style="margin: 8px 0px 12px; display: inline" alt="2017-01-13 17_56_45-emacs@DESKTOP-2DMNUOL" src="http://www.pinksquirrellabs.com/img/old/2017-01-13%2017_56_45-emacs@DESKTOP-2DMNUOL_thumb_1.png" width="533" height="65" /></a></p>
<p>As you would imagine, Racket has all the usual functional programming higher-order functions, but it also contains a boat-load of “<a href="http://docs.racket-lang.org/reference/for.html">iterators/comprehensions</a>” (such as this<em>for/fold</em>) that allow us perform map, fold and friends in a variety of forms, using a shorthand notation.  These can be used to directly create the various in-built data types, such as sets, vectors, lists and dictionaries.</p>
<p>Nothing too crazy going on here, we fold over each character in each string, and create a single accumulator<em>level</em>which is increased if the current character is a (, otherwise it is decreased.</p>
<p>Part 2 of this puzzle has us perform the same thing, but the requirement is to find out at what index into the sequence that Santa first hits floor –1</p>
<p><a href="http://www.pinksquirrellabs.com/img/old/2017-01-13%2018_03_38-emacs@DESKTOP-2DMNUOL_2.png"><img title="2017-01-13 18_03_38-emacs@DESKTOP-2DMNUOL" style="margin: 8px 0px 12px; display: inline" alt="2017-01-13 18_03_38-emacs@DESKTOP-2DMNUOL" src="http://www.pinksquirrellabs.com/img/old/2017-01-13%2018_03_38-emacs@DESKTOP-2DMNUOL_thumb_2.png" width="486" height="149" /></a></p>
<p>To achieve this, Racket allows us to simply add an additional accumulator to the fold, in this case called<em>index</em>which is increased on each iteration.  An optional break clause is added (nice!) which causes the fold to terminate early, as soon as the level is equal to minus one, leaving the index at the required value.</p>
<p>In this case we must always return 2 accumulator values.  Unlike most languages,<a href="http://docs.racket-lang.org/reference/eval-model.html?q=multiple%20values#%28part._values-model%29">Racket allows you to return more than one value</a> (note this is different from something like F# which uses Tuples, it is still only returning a single value!).  One of the ways to achieve this is using the<em>values</em> function, as demonstrated here.</p>
<h2>Day 2</h2>
<p>For day two, those Elves need some help working out how much wrapping paper they need, and then how much ribbon they need in the second part of the puzzle.  Here we can try out some basic pattern matching, which comes in a<a href="http://docs.racket-lang.org/reference/match.html?q=match#%28form._%28%28lib._racket%2Fmatch..rkt%29._match%29%29">million different forms</a>, all which can be nested in each other. </p>
<p><a href="http://www.pinksquirrellabs.com/img/old/2017-01-13%2018_35_13-emacs@DESKTOP-2DMNUOL_1.png"><img title="2017-01-13 18_35_13-emacs@DESKTOP-2DMNUOL" style="margin: 8px 0px 12px; display: inline" alt="2017-01-13 18_35_13-emacs@DESKTOP-2DMNUOL" src="http://www.pinksquirrellabs.com/img/old/2017-01-13%2018_35_13-emacs@DESKTOP-2DMNUOL_thumb_1.png" width="426" height="320" /></a></p>
<p>The<em><a href="http://docs.racket-lang.org/reference/match.html?q=match#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-let%2A%29%29">match-let*</a></em> construct here is used to introduce local function bindings that can optionally use the vast variety of pattern matching functionality from<em>racket/match</em>.  Each expression on the right hand side is matched with the pattern on the left.  You can see the first binding introduced in the function<em>dimensions</em> matches on the parameter<em>args</em> using the<em>list</em>pattern.  My pattern expects three elements in the list to be present and will bind them to<em>l</em>,<em>w</em>and h respectively.</p>
<p>The subsequent bindings are not using any special pattern matching, in the normal format for<em>let</em>, simply binding to the results of some mathematical functions using the previously bound values.  Note that this is possible because we are using the *’d version of<em>match-let (match-let*)</em>, else you do not have access to values that have been bound during the same expression.</p>
<p>The<em>ribbon</em> function is very similar, however since we need only the minimum two elements of the list to determine the length, the<em>args</em> list is sorted as part of the matching expression input.</p>
<p><a href="http://www.pinksquirrellabs.com/img/old/2017-01-13%2018_46_31-emacs@DESKTOP-2DMNUOL_1.png"><img title="2017-01-13 18_46_31-emacs@DESKTOP-2DMNUOL" style="margin: 8px 0px 12px; display: inline" alt="2017-01-13 18_46_31-emacs@DESKTOP-2DMNUOL" src="http://www.pinksquirrellabs.com/img/old/2017-01-13%2018_46_31-emacs@DESKTOP-2DMNUOL_thumb_1.png" width="542" height="260" /></a></p>
<p>So far, without writing any macros, this is the closest I have managed to get to F#s’s pipeline operator.  The higher-order function<em>day2</em> uses the<em>let*</em> function to introduce a series of bindings that shadow each other, using the data introduced from the previous one.  You will notice the second line uses a lambda function, the lambda symbol is optional and can equally be the much longer<em>lambda</em> keyword.</p>
<p>The second call to map has to explicitly call<em>curry</em> in order to partially apply the inner<em>map</em> function with the function<em>string->number</em>.  Unlike F#, vanilla Racket does not have implicit partial application (for good reasons). </p>
<h2>Day 3</h2>
<p>Santa needs our help to guide him around delivering presents.  At the end, we need to provide the amount of distinct houses we have delivered presents to.</p>
<p><a href="http://www.pinksquirrellabs.com/img/old/2017-01-13%2020_12_11-emacs@DESKTOP-2DMNUOL_1.png"><img title="2017-01-13 20_12_11-emacs@DESKTOP-2DMNUOL" style="margin: 8px 0px 12px; display: inline" alt="2017-01-13 20_12_11-emacs@DESKTOP-2DMNUOL" src="http://www.pinksquirrellabs.com/img/old/2017-01-13%2020_12_11-emacs@DESKTOP-2DMNUOL_thumb_1.png" width="335" height="187" /></a></p>
<p>Racket provides us with a fundamental<em><a href="http://docs.racket-lang.org/reference/structures.html?q=match">struct</a></em>type. It supports structural equality out of the box and also pattern matching support, as you would expect, alongside a ton of other stuff I am not going to talk about here.  The intend of this code should be fairly obvious, and also shows the use of the standard<em>match</em> construct that is used as a normal expression.  Here I have used<em>match-let</em> first to de-structure the point into its<em>x</em> and<em>y</em> values which are then used in the subsequence match to create a new point.</p>
<p>The next part is more interesting.  Since we only need to count each distinct location a present is delivered to, this sounds like a job for a<em>set</em> which Racket provides as a fundamental type from within<em><a href="http://docs.racket-lang.org/reference/sets.html">racket/set</a></em>.  Like F#, attempting to add something to the set that already exists has no effect, and is perfect for what is required here.</p>
<p><a href="http://www.pinksquirrellabs.com/img/old/2017-01-13%2020_26_49-emacs@DESKTOP-2DMNUOL.png"><img title="2017-01-13 20_26_49-emacs@DESKTOP-2DMNUOL" style="margin: 8px 0px 12px; display: inline" alt="2017-01-13 20_26_49-emacs@DESKTOP-2DMNUOL" src="http://www.pinksquirrellabs.com/img/old/2017-01-13%2020_26_49-emacs@DESKTOP-2DMNUOL_thumb.png" width="555" height="192" /></a></p>
<p>A few new things introduced here, including something I omitted from the code above in part 2 of day 1. <em><a href="http://docs.racket-lang.org/reference/let.html?q=let-values#%28form._%28%28quote._~23~25kernel%29._let-values%29%29">let-values</a></em> is similar to<em>let</em>in that it introduces local bindings, with the difference being that it is especially designed to receive<em><a href="http://docs.racket-lang.org/reference/eval-model.html?q=multiple%20values#%28part._values-model%29">multiple values</a></em> that I mentioned earlier.  Since the fold here uses two accumulators, it ultimately returns two values (as opposed to, say, a pair or a list) which are then bound to<em>c</em>and<em>v</em>for use within the following body of the<em>let</em>.  This is a common pattern in Racket, with many functions having –<em>values</em> versions of them.</p>
<p>The rest is fairly straight forward, we fold Santa and his visited locations through the instructions, and at the end return the count of the set.</p>
<p>Part 2 is much more interesting, the arrival of RoboSanta means we need to keep track of two locations and alternate each instruction between Santa and RoboSanta.  An initial obvious solution is to simply add an extra location accumulator, and a flag that flips between iterations to determine how moves next.</p>
<p><a href="http://www.pinksquirrellabs.com/img/old/2017-01-13%2020_34_55-emacs@DESKTOP-2DMNUOL_1.png"><img title="2017-01-13 20_34_55-emacs@DESKTOP-2DMNUOL" style="margin: 8px 0px 12px; display: inline" alt="2017-01-13 20_34_55-emacs@DESKTOP-2DMNUOL" src="http://www.pinksquirrellabs.com/img/old/2017-01-13%2020_34_55-emacs@DESKTOP-2DMNUOL_thumb_1.png" width="571" height="261" /></a></p>
<p>However, I thought this would be a good opportunity to have a look at how Racket deals with<a href="http://docs.racket-lang.org/reference/sequences_streams.html">streams</a>.  I would like to eliminate the flag based logic and instead return successive pairs of the input stream so that Santa and RoboSanta can be updated in lock-step.  It seems the<em>generator</em> is the tool for the job from<em><a href="http://docs.racket-lang.org/reference/Generators.html?q=generator#%28form._%28%28lib._racket%2Fgenerator..rkt%29._generator%29%29">racket/generator</a></em>.</p>
<p><a href="http://www.pinksquirrellabs.com/img/old/2017-01-13%2021_14_25-emacs@DESKTOP-2DMNUOL.png"><img title="2017-01-13 21_14_25-emacs@DESKTOP-2DMNUOL" style="margin: 8px 0px 12px; display: inline" alt="2017-01-13 21_14_25-emacs@DESKTOP-2DMNUOL" src="http://www.pinksquirrellabs.com/img/old/2017-01-13%2021_14_25-emacs@DESKTOP-2DMNUOL_thumb.png" width="273" height="200" /></a></p>
<p>A few new things here. Firstly the special<em>generator</em> form will evaluate the body you give it, suspending after<em><a href="http://docs.racket-lang.org/reference/Generators.html?q=generator#%28def._%28%28lib._racket%2Fgenerator..rkt%29._yield%29%29">yield</a></em> is called.  In fact, this is basically a co-routine, something I will have to look more closely at later.  Other new things introduced here are<em><a href="http://docs.racket-lang.org/reference/match.html?q=define%2Fmatch#%28form._%28%28lib._racket%2Fmatch..rkt%29._define%2Fmatch%29%29">define/match</a></em>, which allows you do define a function that immediately matches on the parameters you give it.  In this case, I use the<em>list-rest</em>pattern to extract the first two elements as<em>a</em>and<em>b</em> with the rest of the list as<em>tail</em>.  The pair of<em>a</em>and<em>b</em>is then yielded via<em>cons</em> and the function is called recursively on the tail.</p>
<p>The last wildcard pattern matches when the list runs out, and returns<em>(void). </em>I am not sure if this is totally necessary, but when consuming this sequence using the function<em><a href="http://docs.racket-lang.org/reference/sequences.html?q=in-producer#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._in-producer%29%29">in-producer</a></em> it required you to give it an expression that determines when it should stop.  Omitting the data access code for brevity, the reformed version of the fold looks like this</p>
<p><a href="http://www.pinksquirrellabs.com/img/old/2017-01-13%2021_22_53-emacs@DESKTOP-2DMNUOL_1.png"><img title="2017-01-13 21_22_53-emacs@DESKTOP-2DMNUOL" style="margin: 8px 0px 12px; display: inline" alt="2017-01-13 21_22_53-emacs@DESKTOP-2DMNUOL" src="http://www.pinksquirrellabs.com/img/old/2017-01-13%2021_22_53-emacs@DESKTOP-2DMNUOL_thumb_1.png" width="522" height="261" /></a></p>
<p>Here<em>match-let*</em> is used again to simulate a pipeline of data, first extracting and then moving Santa and RoboSanta, updating the visited location set and finally returning the accumulated data. It is about the same amount of code as before, but perhaps the generator will come in handy later!</p>
<h2>Day 4</h2>
<p>I am going to skip this since it was very easy and I didn’t learn much about the language other than how to create md5 hashes and bit masking.</p>
<h2>Day 5</h2>
<p>Santa is in a pickle working out which strings have been naughty and nice.  This problem obviously screams “regex!” but, frankly, regex can get in the sea. No one ever had fun writing regex. Instead I am going to do it manually, and as an additional target try to perform only one pass over each string and break processing early if a bad string is detected.</p>
<p><a href="http://www.pinksquirrellabs.com/img/old/2017-01-13%2021_59_44-emacs@DESKTOP-2DMNUOL.png"><img title="2017-01-13 21_59_44-emacs@DESKTOP-2DMNUOL" style="margin: 8px 0px 12px; display: inline" alt="2017-01-13 21_59_44-emacs@DESKTOP-2DMNUOL" src="http://www.pinksquirrellabs.com/img/old/2017-01-13%2021_59_44-emacs@DESKTOP-2DMNUOL_thumb.png" width="388" height="239" /></a></p>
<p><em>define/match</em> is back on the scene to create some functions that match on multiple values (rather than lists).  Nothing new in the first function, however the second shows a new pattern<em>or</em> being used inside the pattern match.  It could equally have been written with one pattern for each letter, but this is a tiny glimpse into the power of Racket’s pattern matching (which of course I know hardly any of yet)</p>
<p>I decided to track if a bad pair has been detected, count the amount of vowels and count the amount of occurrences for letters that appear twice.  My<em>by-pairs</em> generator is no good for this, needing something more like F#’s<em>Seq.windowed</em>, I decided to simply pass along the previous character as another accumulator.</p>
<p><a href="http://www.pinksquirrellabs.com/img/old/2017-01-13%2022_07_29-emacs@DESKTOP-2DMNUOL.png"><img title="2017-01-13 22_07_29-emacs@DESKTOP-2DMNUOL" style="margin: 8px 0px 12px; display: inline" alt="2017-01-13 22_07_29-emacs@DESKTOP-2DMNUOL" src="http://www.pinksquirrellabs.com/img/old/2017-01-13%2022_07_29-emacs@DESKTOP-2DMNUOL_thumb.png" width="455" height="336" /></a></p>
<p>A couple of interesting things here.  If at any point<em>is-bad-pair?</em> returns true, the fold stops on the next iteration due to<em>break bad?</em> clause. (Breaking Bad!) Lastly the perhaps slightly mysterious looking<em><a href="http://docs.racket-lang.org/reference/match.html?q=match-*#%28form._%28%28lib._racket%2Fmatch..rkt%29._match%2A%29%29">match*</a></em> at the bottom uses some new pattern matching forms.  ? allows you to pass a function which will be called on the respective value and only match if it returns true.  In this case I have inlined a lambda that matches if there are at least three vowels.  The last case uses the<em>not</em>pattern to ensure at least one letter appeared twice.</p>
<p>Part two is much more sinister, and took me quite some time to come up with a nicer solution for it that didn’t have to do multiple or n2 iterations on the data.  Mostly because I had read the problem incorrectly, several times. The first part is easy, and will introduce another matching concept.  The string must have at least one occurrence of the same letter, either side of any letter. </p>
<p><a href="http://www.pinksquirrellabs.com/img/old/2017-01-13%2022_15_28-emacs@DESKTOP-2DMNUOL.png"><img title="2017-01-13 22_15_28-emacs@DESKTOP-2DMNUOL" style="margin: 8px 0px 12px; display: inline" alt="2017-01-13 22_15_28-emacs@DESKTOP-2DMNUOL" src="http://www.pinksquirrellabs.com/img/old/2017-01-13%2022_15_28-emacs@DESKTOP-2DMNUOL_thumb.png" width="446" height="73" /></a></p>
<p>In Racket, if you use the same identifier to bind the results of patterns to, like I have done here with<em>a,</em>this means<em>they must be equal</em>. Otherwise it wouldn’t make any sense, would it?  In this case, it is simple to see if the same letter exists on both sides of some other letter. Very nice!</p>
<p>The second part is trickier.  The requirement is that the string must have at least two instances of the same pair of letters, but not where they overlap.  So “jkjk” is ok, “aaaa” is ok, but “aaa” is not. To fulfil this we can examine the next 3 characters in the string.  If they are all the same, we can add a pair of them to our “seen pairs” set, and then continue processing recursively,<em>skipping</em> the second character, which is critical to the algorithm skipping overlapping pairs.  All other cases of pairs are just added to the set.  In all cases, before adding to the set, we can check if the pair already exists, if it does then the condition is satisfied and the process can prematurely end.  The first version looked like this</p>
<p><a href="http://www.pinksquirrellabs.com/img/old/2017-01-13%2022_23_12-emacs@DESKTOP-2DMNUOL.png"><img title="2017-01-13 22_23_12-emacs@DESKTOP-2DMNUOL" style="margin: 8px 0px 12px; display: inline" alt="2017-01-13 22_23_12-emacs@DESKTOP-2DMNUOL" src="http://www.pinksquirrellabs.com/img/old/2017-01-13%2022_23_12-emacs@DESKTOP-2DMNUOL_thumb.png" width="451" height="260" /></a></p>
<p>This should all be familiar by now.  Again, using the rather nifty matching allows us to specify the case where 3 identifiers are the same, solves this with ease.  The thing I don’t like about this is the repetition of the code that checks if a pair s in a set, then recursively calls the routine again, adding to the set if not.  This code is basically identical in each case, other than the pair construction.  You could try and create a local function to help with this, but there is a better way.</p>
<h2>Macros</h2>
<p>The solution is to introduce a new piece of syntax that can write the repetitive stuff for us.  Like everything else in Racket,<a href="http://docs.racket-lang.org/reference/Macros.html?q=match-*">macros</a> come in a million different forms, and are (or can be) lexically scoped.  I am going to use one of the many short-hand ways of writing a small macro,<em><a href="http://docs.racket-lang.org/reference/stx-patterns.html?q=define-syntax-rule#%28form._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._define-syntax-rule%29%29">define-syntax-rule</a></em> and have it scoped inside the<em>au</em>x<em></em>function.</p>
<p><a href="http://www.pinksquirrellabs.com/img/old/2017-01-13%2022_29_16-emacs@DESKTOP-2DMNUOL.png"><img title="2017-01-13 22_29_16-emacs@DESKTOP-2DMNUOL" style="margin: 8px 0px 12px; display: inline" alt="2017-01-13 22_29_16-emacs@DESKTOP-2DMNUOL" src="http://www.pinksquirrellabs.com/img/old/2017-01-13%2022_29_16-emacs@DESKTOP-2DMNUOL_thumb.png" width="461" height="80" /></a></p>
<p>This very simple form defines a macro called<em>step</em>.  It expects two expressions as inputs.  Unlike a normal function, these are compile time constructs, and the input expressions here are<em>the program itself</em> rather than data at run time.  The following body defines a syntax template which the macro expander will use to replace the call site.  Here I have simply wrote the same repetitive code, substituting the two bits of program I have passed in where applicable.  Now the function can be re-written as follows</p>
<p><a href="http://www.pinksquirrellabs.com/img/old/2017-01-13%2022_34_48-emacs@DESKTOP-2DMNUOL.png"><img title="2017-01-13 22_34_48-emacs@DESKTOP-2DMNUOL" style="margin: 8px 0px 12px; display: inline" alt="2017-01-13 22_34_48-emacs@DESKTOP-2DMNUOL" src="http://www.pinksquirrellabs.com/img/old/2017-01-13%2022_34_48-emacs@DESKTOP-2DMNUOL_thumb.png" width="449" height="254" /></a></p>
<p>Beware here that the<em>define-syntax-rule</em> form can be a bit misleading with its ease of use. It is also very limiting and to do the really powerful stuff you will want to revert to monsters such as<em><a href="http://docs.racket-lang.org/syntax/Parsing_Syntax.html?q=syntax-parse#%28form._%28%28lib._syntax%2Fparse..rkt%29._syntax-parse%29%29">syntax/parse</a></em> which provides comprehensive pattern matching capabilities for program structure and composition.</p>
<h2>Conclusion</h2>
<p>I am liking Racket after messing around with it for a few days.  I did some crazy stuff not shown here with macros, and hopefully in following posts I will be able to cover more on building languages using the metaprogramming features Racket provides to do some cool (or completely ridiculous) things.</p></p>