g2asm guide

G2asm getting started guide

Overview:

SBTCVM Gen 2 is all about a new start for the codebase, and the assembler is no exception. v3 of SBTCVM assembly brings many changes, and some groundbreaking features over its predecessors.

New integer-type keyword syntaxes:

Every keyword that accepts a ternary integer as a data value (most keywords do, even if they don't use any data arguments in machine code) now has support for these new features:

• Unified namespace system. (explained in its own section)
• Decimal ints via a '10x' prefix. i.e. '10x1', '10x-5'
• trit values of varying length. i.e. you dont need '00000000+'. Just '+' will do.
• n0p notation (a balanced ternary representation, where n is negative and p is positive) Follows same assembler syntax rules as SBTCVM's usual -0+ notation.
• SBTCVM-BTT2 character syntax via :char syntax (NOT 100% the same as the Mark 2 TTYWrite character syntax.)

the basic syntax:
keyword;data;label-variable(optional)

keyword refers to the assembler keyword in use. i.e. add, setreg1, goto, etc.

data refers to the information the keyword needs (if any). usually this is numeric, and sometimes optional altogether. i.e. with 'null'


Namespace variables:
SBTCVM assembly v3 has a unified namespace that is accesible via the >var syntax for data arguments of keywords. i.e. setreg1;>bob

You can create these in two ways:

• null;;sam  -this will set namespace variable 'sam' to the address that keyword begins at in the resulting trom image. note its separated from the data via a second semicolon. This traces back to the origin of the namespace variables: goto address calculating.
• v>sam;10x1 -this is a more direct way of doing it. This is called a prefix keyword. the variable prefix keyword to be exact.  Everything after 'v>' and before the first semicolon is the variable name, and the data specified after the first semicolon is used as it's value.

Header variables:
header variables configure how the assembler should assemble a tasm file, include nsp files, (see below), and various other things. Some can be stated multiple times for different effects. i.e. head-nspin allows repeated use for importing multiple nsp files.

• head-mode=mode
• head-mode=trom (default): export trom (and nsp if enabled)
• head-mode=vars: only export nsp file (if enabled)
• head-rname=filename: override trom name (minus extension)
• head-nspname=filename: override nsp name (minus extension)
• head-nspout=1: enable nsp file output
• head-nspin=nspname import nsp namespace file: nspname (can be used more than once) (expects a nsp filename WITHOUT A PATH. should be in one of the standard trom locations. i.e. VMSYSTEM/ROMS, VMUSER, ROMS, etc. If it is, the assembler should locate and load it automatically.

NSP namespace files:

using the head-nsp* header variables above, you can export & import nsp namespace files. these files provide everything from IO addresses, to generic datasets.

vars from nsps and tas0 files WILL NOT be included in an outputted nsp file, unless you 'copy' them via v>var;>var. You may also use a different var name

stdnsp is a very important nsp file to remember! it contains things like IO address variables (so no you don't need to memorize where the TTY port is, just that 'io.ttywr' points to it. Think of it as a sort of 'standard library'

tas0 modules:

these nifty bits of code can be included in tasm & other tas0 modules with one of these keywords:

include;tas0filename
or
includeas;tas0filename,var_namespace
 

where tas0filename is the base name (i.e. no path, just the filename) of the tas0 you wish to include. should be in one of the standard trom locations. (i.e. roms, vmsystem/roms, vmsystem, vmuser, apps, demos) If it is, the assembler should locate and load it automatically.

You may also specify a directory in one of these places if it contains a file matching the 'auto_*.tas0' pattern, or you append its name like so:
'myappdir+myfile.tas0' . most places in SBTCVM's bundled tools that require file arguments support at least the latter.

In the latter example, 'var_namespace' is a prefix for all contained namespace variables. i.e. if tas0filename contained 'bob', it would be included as var_namespace.bob

writing a tas0 is just the same as an SBTCVM assembly file, only you dont assemble it, the assembler will do that upon it being included in a source file.

building your programs:

For beginners:
the simple way is to just do
g2asm.py [source file name]*
asm [source file name]* (From XAS shell/XAS scripts)


 
If all goes well, you will see messages for passes 0 through 5, without any nasty error messages, otherwise, you'll be dealing with an error message of some kind. usually this will state the line number, and if apropiate, the source filename, that the fault was found in.

xas script (for advanced users):
xas scripts are build automation scripts, originally part of the assembler's runtume, that now exist as part of the XAS Shell. A cross-platform development shell, that also has some interactive features helpful for non-dev users.

See:  XAS system documentation

Note on file paths:
* You may also specify a directory in one of  (i.e. roms, vmsystem/roms, vmsystem, vmuser, apps, demos) if it contains a file matching the 

'auto_*.tasm'

pattern, or you append its name like so:




'myappdir+myfile.tasm' .


most places in SBTCVM's bundled tools that require file arguments support at least the latter scheme.

 

 

 Tools:

Other doodads.

romdump.py

an essential tool for anyone trying to debug a trom. provides both basic and detailed views. (detailed views offer text and decimal printouts along with the usual trit printout) use its -h option for specifics.