XXIIVV

Uxntal Software

Here's a list of small self-hosted development tools:

Boostrapping

Since the assembler is written in the language it is assembling, you have a few choices:

  1. Download a pre-assembled rom.
  2. Assemble your own with the live REPL.
  3. Bootstrap from a hexdump.

If you are unable to assemble your own copy of drifblim, lost its source file, or simply want to make sure that the assembler is unaltered, you will need the hexadecimal data of drifblim.rom. Here are some portable tools to help with the bootstrapping process:

Step 0: xh.txt

First off, you need a way to create binary files from hex dumps. If you don't have access to xxd, you can paste the following line in a text file, and run a hex dump through it:

FAFAFXFZFwfaalFBFAAFFZFZXVGfoAAFXFZFFXXfoKgaam&/$AAAFXJgaam&/AFAAFXFFZZDYJF$/FXAKF|Bgaam/AAFXFZFXgBFAYXFEF|BGGoGAFAFXFZDYFEF|B/DAAFX_gBAGYgDAAFXFXAXZEEZXGPgBAAFXFFZZ_]GQFAPGA^GAQFAPgaamFPGAAFXFXFFXXW
cat drifblim.rom.txt | uxncli xh.txt > drifblim.rom

Step 1: cat.rom

If for some reason you do not have access to the unix cat program, you can read files and output their content through the console with the cat program, which reads a file and outputs the content via the console.

a001 0780 1037 0080 1216 0680 1f0a 2000
1502 6000 1aa0 000f 13a0 0317 1608 2000
04a0 800f 1700 a000 0081 80fb 1331 00a0
0000 80a8 37a0 0001 80aa 37a0 014b 80ac
b780 a316 2000 0302 226c a000 1817 40ff
ef
uxncli cat.rom drifblim.rom.txt | uxncli xh.txt > drifblim.rom

Step 2: drifboot.rom

At this point, you have recovered your own drifblim.rom from a hex dump. The next step is to make a new drifblim.rom from its source code, using the newly assembled rom.

uxncli drifblim.rom drifblim.tal.txt drifboot.rom

Note that in Uxntal, hexadecimal numbers are valid code and so any rom can be recovered from a hex dump with a working assembler.

Step 3: hx.rom

To close the circle, the assembled rom needs to turned back into a hex dump, we'll print its hex dump using a the following utility:

@on-reset ( -> )
	;on-console #10 DEO2 BRK
@on-console ( -> )
	#0417 DEI NEQ [ JMP BRK ]
	#12 DEI DUP #04 SFT emit emit INC
@spacer ( c -> )
	DUP #0f AND ?{ #0a18 DEO BRK }
	DUP #01 AND ?{ #2018 DEO } BRK
@emit ( c -- )
	#0f AND DUP #09 GTH #27 MUL ADD
	LIT "0 ADD #18 DEO JMP2r
uxncli drifblim.rom hx.tal.txt hx.rom
cat drifboot.rom | uxncli hx.rom > drifboot.rom.txt

Step 4: eq.rom

Finally, we should have two identical hex dumps of the assembler, where one was assembled from the textual source. If for some reason you do not have access to the unix diff command, you can compare the two hexadecimal dumps with the eq program, which takes two filepaths and compare their content.

uxncli drifblim.rom eq.tal.txt eq.rom
uxncli eq.rom drifblim.rom.txt drifboot.rom.txt

Alternatively, if your Varvara implementation does not support the File device, use the Drifloon assembler(tal/rom). To validate your own assembler, see the tests, and disassemble the result with uxndis.

A collection of commonly used routines in Uxntal projects.

The following libraries are in the standard Drifblim style. If you discover faster and smaller helpers, please get in touch with me.

Uxnfor is a formatter for Uxntal.

The formatter expects the standard Uxntal Notation, sometimes called Drifblim-style.

If a routine is printing, drawing, or sometimes ingesting all of its arguments, the routine can be wrapped within angular brackets to indicate that it should end a line to Uxnfor.

@<emit-num> ( num* -- )
	LIT "0 ADD .Console/write DEO JMP2r

Uxnbal is a stack effect validator.

Program validation is done at compile-time by comparing a routine's stack effect, against the resulting balance of all stack changes occurring in the routine's code. Words that do not pass the stack-checker are generating a warning, and so essentially this defines a very basic and permissive type system that nevertheless catches some invalid programs and enables compiler optimizations. For more details, see Uxnbal.

The simplest case is when a piece of code does not have any branches or recursion, and merely pushes literals and calls words. The stack effect routines is always known statically from the declaration.

@add-eight ( a -- a+8 )
	#0008 ADD JMP2r

Working-stack imbalance of +1, in add-eight.

In the case of branching, each branch is evaluated and if an imbalance occurs inside one of the branches, the branch name is indicated:

@branching ( a* -- c )
	LDAk #01 EQU ?&one
	LDAk #02 EQU ?&two
	POP2 #ff JMP2r
	&one ( a* -- c ) POP2 #12 JMP2r
	&two ( a* -- c d ) ADD JMP2r

Working-stack imbalance of -1, in branching/two.

In the case of a recursion, the validator will use the stack effect instead of repeatedly walking through the body of the routine.

@print-string ( str* -- )
	LDAk DUP ?{ POP POP2 JMP2r }
	emit-letter 
	INC2 !print-string

For loops that exits without affecting the stack depth, a > prefixed label is used as a shorthand to reduce the need for extraneous stack effect definitions in cases where it can be inferred:

@many-times ( a -- )
	DUP
	&>l
		INC DUP ?&>l
	POP2 JMP2r

Routines that pull items from the stack beyond their allowed depth will also raise a warning, making the stack effect act a sort of boundary:

@shallow ( a -- )
	POP2 JMP2r

Working-stack depth error of 1, in shallow.

Lastly, a runtime specific solution to validate the stack state at any one point during the execution of a program, is to read the System/wst port and compare it against a given stack pointer byte value.

@on-reset ( -> )
	#abcd DUP2 
	.System/wst DEI #05 EQU ?{
		#01 .System/debug DEO }
	BRK

Uxnlin is an optimizer for Uxntal.

It finds known patterns in programs that can be optimized, or that are unsafe.

Bicycle is an interactive Uxntal playground.

Bicycle is a little Uxntal interpreter designed for teach the language in front of an audience. Bicycle allows you to vizualize source code next to its equivalent bytecode and step through the evaluation.

As Companion

To launch Bicycle as a companion application, you need just pipe the left.rom instance of uxnemu to the one of bicycle.rom. Left can send both a selection of text to be evaluated, or the entire working tal file, by pressing ctrl+p. The result should be instantly displayed in the Bicycle window.

uxnemu left.rom | uxnemu bicycle.rom
Drawing by Rekka Bellum

As an alternative, to experiment with Uxntal you can also use the web-based REPL.

Beetbug is a step debugger.

Inspired from Uxn32's fantastic debugger, Beetbug is a step debugger for Varvara, written in Uxntal. It is the perfect tool to step through a running program. It uses Varvara's Console write port to print debug to the interface, and the System's debug port to put a breakpoint.

Beetbug supports symbol files, and will highlight both the return address on top of the return stack, and the address on top of the working stack, giving you a visual indication of the addresses that are being accessed.

Manual

Launch beetbug with the target rom to debug:

uxnemu beetbug.rom some_project.rom

Beetbug will evaluate the reset vector, starting at 0100, until a BRK is reached, to pause evaluation, you can use the System's debug port as follow:

#010e DEO

Controls

incoming: uxntal devlog