#!/usr/bin/env retro

Muri: a Minimalist Assembler for Nga

This is a small assembler used to build the initial image for RETRO. The implementation here uses the runtime variant included in the core RETRO system. See the glossary entries for i, d, r, as{, and }as for details on these.

The full assembler has a postfix notation. Syntax is:

<directive> <data>

Directives are a single character. Muri recognizes:

i for instructions
d for numeric data
s for string data
: for creating a label
r for references to labels

Instructions are packed up to four instructions per location. You can specify them using the first two characters of the instruction name. For a non operation, use '..' instead of 'no'.

0 nop   5 push  10 ret   15 fetch 20 div   25 zret 1 lit   6 pop   11 eq    16 store 21 and   26 halt 2 dup   7 jump  12 neq   17 add   22 or    27 ienum 3 drop  8 call  13 lt    18 sub   23 xor   28 iquery 4 swap  9 ccall 14 gt    19 mul   24 shift 29 iinvoke

E.g., for a sequence of dup, multiply, no-op, drop:

i dumu..dr

An example of a small program:

i liju.... r main : square i dumure.. : main i lilica.. d 12 r square i ha......

As mentioned earlier this requires knowledge of Nga architecture. While you can pack up to four instructions per location, you should not place anything after an instruction that modifies the instruction pointer. These are: ju, ca, cc, re, and zr.


This is documented in example/retro-unu.forth, but basically it provides a combinator that runs a quote for each line in a file, provided that the lines are in fenced blocks starting and ending with ~~~.

The RETRO sources are written in this style, so I include Unu here to simplify the later workflow.

~~~{{   'Fenced var   :toggle-fence @Fenced not !Fenced ;   :fenced? (-f) @Fenced ;   :handle-line (s-)     fenced? [ over call ] [ drop ] choose ; ---reveal---   :unu (sq-)     swap [ dup '~~~ s:eq?            [ drop toggle-fence ]            [ handle-line       ] choose          ] file:for-each-line drop ; }} ~~~


Now for the assembler. I create a couple of data structures: a buffer for the assembled image and a pointer into this.

~~~'Image d:create #8192 allot 'AP var ~~~

I then use these to implement I,, a word which stores a value into the image buffer and increment the pointer.

~~~:I, (n-) &Image @AP + store &AP v:inc ; ~~~

Pass 1

Muri is a two pass assembler. The first pass handles most of the work. It processes instrution bundles, data, strings, and creates labels pointing to specific addresses in the image. References are compiled as dummy values, to be resolved later.

~~~'Pass_1:_ s:put #0 !AP #0 script:get-argument   [ dup s:length n:zero? [ drop #0 ] if 0;     fetch-next &n:inc dip     $i [ i here n:dec fetch I, ] case     $d [ s:to-number I, ] case     $r [ drop #-1 I, ] case     $: [ @AP swap 'muri! s:prepend const ] case     $s [ &I, s:for-each #0 I, ] case     'ERROR s:put nl   ] unu @AP n:put '_cells s:put nl ~~~

Pass 2

The second pass skips over everything except references, which get resolved and filled in. This allows for forward references.

~~~'Pass_2:_ s:put #0 !AP #0 script:get-argument   [ dup s:length n:zero? [ drop #0 ] if 0;     fetch-next &n:inc dip     $i [ drop &AP v:inc ] case     $d [ drop &AP v:inc ] case     $r [ 'muri! s:prepend d:lookup d:xt fetch I, ] case     $: [ drop ] case     $s [ s:length n:inc &AP v:inc-by ] case     'ERROR s:put nl   ] unu @AP n:put '_cells s:put nl ~~~

Save Image

Saving the image is pretty straightforward. For each cell, convert to bytes and write them to the output file.

~~~'FID var   :write-byte (n-)  @FID file:write ; :mask       (n-)  #255 and ;   :write-cell (n-)            dup mask write-byte   #8 shift dup mask write-byte   #8 shift dup mask write-byte   #8 shift     mask write-byte ;   :save-image (s-)   file:W file:open !FID   &Image @AP [ fetch-next write-cell ] times drop   @FID file:close ;   'ngaImage save-image ~~~

Future Directions

Muri is currently a two-pass assembler. It might be interesting to add additonal passes, one for each item type. This could allow for some cleaner code and easier additions of new features in the future. For now this works nicely though, and is simple and reliable.