The Assembler

Usage: subleq-asm.py <file.slq>

If you look at the “hello-world.slq”, you can probably figure most of it out but in case you can’t here goes.

  • <identifier>: define a the label “identifier” at this point in the output
  • .ascii <string> output the string at this point int he output
  • .int <number> output the number as a word sized int at this point in the output
  • .fill <number> output the number of word sized ints at this point in the output
  • .align <number> make sure the output is aligned to number bytes

The commands below take arguments; an argument can be a label name (without the “:”), a number, a number/label prefixed with “.offset” (which will give you the offset within the program of the number/label) or can be a a label surrounded by “[” and “]”; which will dereference the value at the label.

  • subleq <src> <dst> <jmp> subtract src from dst, store in dst and if less than zero jump to jmp; jmp is optional
  • hault stops execution

All the commands below here are meta commands and are implemented on top of subleq. This lot all need a label called “Z” which points to an .int register initialised to zero.

  • jmp <label> cause execution to continue at label
  • sub <src> <dst> subtract src from dst and stores in dst
  • add <src> <dst> adds src to dst and stores in dst
  • mov <src> <dst> moves the value from src to dst

These commands are built on top of the preceding ones and also require a label called “sp” which points to an .int register initialised to zero.

  • push <src> moves the value from src to the value at “sp”

This command is used for native calling, it requires all the registers we’ve talked about before plus one called “bar”. This label must be preloaded with the real memory address of the program – this lets you calculate real memory addresses of sublet values so you can create a call stack.

You will probably also need an int label called “dlsym”. Whilst you don’t actually need this register, if you want to be able to do anything useful you’ll need it.

When using the debugger: sublet-dbg.py, it will set the value of dlsym to the real address of the dlsym function and bar to the real address of the sublet program code.

  • callc converts the value at “sp” into a real address, then pops an item off the stack and calls it as a native function (sp should point to the top value – not below it). Once the call is complete it pushes the return value onto the stack and subtracts the bar value

The Disassembler

Usage: subleq-dbg.py <file-bin>

This is pretty self explanatory; its got help (just type “h”). basically you can set breakpoints (bp 15c), continue (c), step (c) (individual subleq micro instructions) and print values (p).

You’ll also notice that the next instruction to be executed will be highlighted in green, breakpoint addresses will get a blue cross in the middle, and changed values will go red.