APARA Assembly Language and Tools¶
APARA programs are written in mcode, the engine's assembly language,
and assembled with this project's own tools in compiler/apara/. (They
can also be written in a subset of C, see The C Compiler,
which writes mcode for these tools.) The
tools are plain Python 3, using only the standard library, so there is
nothing to install.
The assembler checks programs strictly: it stops with an error on anything it cannot encode exactly, rather than producing a wrong program (see Error messages).
A first program¶
// Sum the 8-bit elements of a vector in $r1, store the result.
sum:
||
$vreduce + $r2 ($vi8) $r1 // 1+2+...+8 = 36
;
store:
||
$st ($i64) [$r0 + 16] $r2 // DMEM bytes 16..23
;
|| $halt ;
The program's three bundles run one after another:
$vreducereads$r1as a vector of eight 8-bit signed elements and adds them up, into$r2.$ststores$r2, as a 64-bit integer, at DMEM address$r0 + 16, that is, 16 ($r0is always 0).$haltstops the thread.
$r1 is set before the run: by a registers file given to the
simulator (see File formats), or, in a test, by the
INIT section of its .vprj (see APARA Validation
Suite).
Program structure¶
- Bundles
A program is a sequence of bundles. Each starts with||, holds one to eight instructions, and ends with;. A bundle may be written on one line or span several. - Labels
A bundle may have a label (sum:), which branches and calls can name as their target. - Comments
//starts a comment, to the end of the line. - Instructions
Every instruction is listed in APARA Instruction Set.
What the assembler does¶
Beyond translating each instruction, the assembler turns the bundles as written into bundles the engine can run. It does this in seven steps:
- Parses and checks every instruction: register numbers, types, immediate and increment ranges, and whether each operation is allowed for its type.
- Checks each bundle: at most 8 instructions, at most one branch/call/return, at most 4 loads and stores, at most one divide or square root, and no register written by two instructions.
- Closes each bundle, filling it with
$nulls up to its size: 8 slots if it holds a control transfer, load or store, divide, or square root, otherwise the smallest power of two that fits. - Places the bundles in IMEM, each at an address that is a multiple
of its size, filling any gaps with
$nullbundles. - Arranges the slots of each 8-slot bundle: the control transfer in slot 0, a divide or square root in slot 1, loads and stores in slots 4 to 7, and the other instructions, in source order, in the free slots.
- Resolves labels: a branch or call holds its target relative to its own address (its bundle's address plus its slot).
- Encodes every instruction, setting bit 31 on each bundle's first word.
The tools¶
The tools are run with python3, from the repository root. The
assembler and the disassembler translate between mcode and object files,
which the simulators load. Two more tools build on the assembler. One
writes a program as a C header for the SPARC side of sparc_apara, and
the other is the C compiler.
| Tool | Reads | Writes |
|---|---|---|
apara_as.py, the assembler |
mcode | an object file (.obj) |
apara_dis.py, the disassembler |
an object file | mcode |
apara_obj_to_c.py |
mcode, C, or an object file | a C header |
apcc.py, the C compiler |
C | mcode |
The assembler names its object file after the source, so the first
command below writes prog.obj. The option -o gives it another name.
Two more options write extra files. --aligned writes the program as
placed and arranged, with every bundle's address, which is the program
the engine actually runs. --listing writes each word's address,
encoding and instruction.
python3 compiler/apara/apara_as.py prog.mcode
python3 compiler/apara/apara_as.py prog.mcode --aligned prog.aligned.mcode --listing prog.lst
The disassembler writes mcode to standard output, and names branch and
call targets L_<address>. Its output assembles back to the same object
file.
apara_obj_to_c.py is described in Programming the
System, and
apcc.py in The C Compiler.
python3 compiler/apara/test_mcode.py runs the assembler's and
disassembler's own unit tests. The validation/apara/asm_errors/ suite
tests the assembler's checks. Each of its programs breaks one rule on
purpose, and passes only when the assembler rejects it with the expected
message.
Error messages¶
Any error stops the assembly, with the file, the line, and the reason:
Some messages, and what they mean:
| Message | Cause |
|---|---|
immediate 600 is out of range (-512 to 511) |
Immediates are 10-bit signed. |
a bundle holds at most one divide or square root |
The engine has one divider, shared by divides and square roots. |
floats have only + - * / |
No logic operations or shifts on float types. |
the registers from $r30 run past $r31 |
A $u256 transfer needs 4 consecutive registers. |
a vector cast changes the element width by one step |
($vi8) to ($vi32) needs two casts. |
undefined label x |
A misspelled label. |
File formats¶
The tools and the simulators share these file formats. In every
format, numbers are hexadecimal and ! starts a comment.
| File | Lines | Example |
|---|---|---|
object (.obj) |
<word index>: <instruction word> |
8: 80000000 |
data (data.map) |
<dword index>: <64-bit value> |
10: 0x0102030405060708 |
| registers | <thread> <register> <value> |
0 1f 0x10 |
| results | <thread> pc <pc> [mask] |
0 pc 0x21 |
<thread> reg <register> <value> [mask] |
0 reg 0x5 0x67 |
|
<thread> mem <dword index> <value> [mask] |
0 mem 0x4 0x00aa000000001234 |
|
<thread> error <ERROR> [mask] (this project's addition) |
0 error 0x2000000 |
A data file gives DMEM's initial contents by dword (8-byte word) index,
taken modulo the DMEM size: index 0x10 is DMEM bytes 0x80 to 0x87. A
results file lists the expected final state, and a mask, if given,
selects the bits compared.
Editor support¶
- vim:
compiler/apara/vim/mcode.vim. Copy it to~/.vim/syntax/, and addau BufRead,BufNewFile *.mcode set filetype=mcodeto~/.vimrc. - This documentation highlights
```mcodecode blocks with the Pygments lexer indocs/mcode_pygments_lexer/.