SBTCVM: Working with SBTCVM assembly

Working with SBTCVM assembly.

Guess That Trit - Game

OK. so SBTCVM is a balanced ternary virtual machine with an
oddball

 
assembly language. How hard is it?

(note: if you want to try the tutorial in this post, make sure you have SBTCVM installed. you can get it here. SBTCVM requires python and pygame as well.)

hello world:
textstart
Hello World
textstop

That wasn't hard was it?
Ok. so the other 99.9% of use cases are not that simple.


The assembler does have these nifty address references.
for example: the goto reference pointer (or "pointer" for short):
null|000000000|foobar
(some commands...)
(this data-based goto is pointed to that "pointer")
gotodata|>foobar
this is a basic loop. Basically whatever "(some commands...)" is, is looped. and it doesn't matter where the pointer is in the resulting ROM, as the assembler automatically calculates that for you.

there are also similar, but predefined, IObus references:
IOread1|>random
IOwrite1|>mem1
This example reads from the random integer port, and writes that random integer to scratch memory point 1 (the scratch memory ranges from mem1 to mem729)

Lets look at how the Fibonacci demo works:

textstart
Fibonacci sequence.
Starting with params 1 , 1
textstop
#a bit of startup...
colorfill|---------

setcolorvect|000------
setcolorreg|00000000+
#our starting parameters. the negitive variation just has "-" 
#where there are "+" here.
setreg1|00000000+
setreg2|00000000+
#dump primary CPU register 1. also this is the beginning of the 
#loop.
dumpreg1|000000000|fibloopback
#color display line instruction. also note the use of a goto 
#pointer with a setdata instruction. this can be VERY handy.
colorline|00000000+|fibcollinevx
#since the color data is 6 trits, it needs to be set separately
setcolorreg|00000000+|fibcolreg
#exactly what it says it is. an addition operation.
#it adds primary CPU registers 1 & 2.
add
#store Reg1's state in scratch memory point 1
IOwrite2|>mem1
#set reg 2 to MNI to check for a integer overflow.
setreg2|---------
#if an integer overflow is detected, leave the loop.
gotodataif|>fibdone
#copy register 1 to register 2
copy1to2
#read that stored state of register 1 from scratch memory.
IOread1|>mem1
#set those drawing instructions from earlier.
setdata|>fibcollinevx
setdata|>fibcolreg
#go back to beginning of loop.
gotodata|>fibloopback
#go here to exit loop.
null|000000000|fibdone

Don't worry if you don't get it. lets start easy.

Create a tasm file in VMUSER called example1.tasm and place these lines of tasm code in your newly created tasm source file.

textstart
hello world
textstop

Ok, now remember to save it!

Ok, We have a SBTCVM assembly file, now what to we do with it?

well. we run the SBTCVM assembler on it of course!


For example on linux, from the base directory of your copy of SBTCVM. (the one SBTCVM-asm2.py is in)

examples for on linux. (use the appropriate syntax for your OS, command arguments for SBTCVM utilities are the same regardless of OS.

./SBTCVM-asm2.py example1
or from SBTCVM's command shell (run MK2-CS.py in a terminal):
asm example1 

Or if you like, you can create a tracelog of the assembly process (its placed in the CAP directory) using:
./SBTCVM-asm2.py -t example1
or from SBTCVM's command shell:
asm -t example1 
hey! where is the extension??

well. the assembler is smart enough to find example1.tasm without the extension, and as long as its in ROMS, VMUSER, VMSYSTEM (or the ROMS directory in VMSYSTEM), SBTCVM-asm2.py will find it automatically, and put the resulting TROM in the same directory.

OK, wise guy, how do i run it?

example for on linux. (use the appropriate syntax for your OS, command arguments for SBTCVM utilities are the same regardless of OS.
./MK2-RUN.py example1
or from SBTCVM's command shell:
run example1
like the assembler, its smart enough to find it. 

When you run it.  it should print "Hello World" in SBTCVM's virtual TTY.

VM SYSHALT:
soft stop
don't panic! Its supposed to say that. you see, SBTCVM's assembler adds an extra VM "stop" instruction at the end of the compiled file if it doesn't see one, or a explicit goto.

Ok, that works. Anything else i should know?

Yes actually.  SBTCVM's command shell also has some other commands.
there are a selection of math commands, a list command to help with finding that pesky trom. and the gfx toolkit can also be accessed from it.