Overview

Ngaro is a portable virtual machine / emulator for a dual stack processor and various I/O devices. The instruction set is concise and the basic I/O devices are kept minimal to ensure maximum portability and ease of implementation.

Building

Console (C)

For most systems, the following will suffice:

cd console
make

If your system requires curses, open the console/retro.c and change //FLAGS to:

//FLAGS -O3 -fomit-frame-pointer -DCURSES

You will also need to add a //LIBS line (change as needed for your system):

//LIBS -lcurses

Then build as shown above.

.NET and Mono

If you have Mono, you can build the .NET port as well:

cd dotnet
make

The .NET build will run on Microsoft .NET, but building is only tested with Mono.

Go! Language

cd golang
make

Java

This port is mostly abandoned, but can still be built and works on non-Windows hosts only. It's slow, and --endian argument may be needed to load images.

cd z_pending_removal/java/
make

Instruction Set

The instruction set is small, consisting of 31 primary instructions. (Some implementations have extended instruction sets).

Encoding is kept minimal. One instruction per memory location, with certain instructions taking a value from the following location.

All opcodes in the list below are in decimal.

Opcode	Name	Description
000	nop	Do nothing
001	lit	Push a value to the stack
002	dup	Duplicate TOS
003	drop	Lose TOS
004	swap	Swap TOS and NOS
005	push	Move a value from data stack to the address stack
006	pop	Move a value from address stack to data stack
007	call	Call a subroutine
008	jump	Jump to a new address
009	return	Return from a call
010	gt_jump	Jump if NOS is greather than TOS
011	lt_jump	Jump if NOS is less than TOS
012	ne_jump	Jump if TOS and NOS are not equal
013	eq_jump	Jump if TOS and NOS are equal
014	fetch	Fetch from address at TOS
015	store	Store NOS to address in TOS
016	add	Add TOS to NOS
017	subtract	Subtract TOS from NOS
018	multiply	Multiply TOS and NOS
019	divmod	Divide and get Remainder
020	and	Bitwise AND
021	or	Bitwise OR
022	xor	Bitwise XOR
023	shift_left	Shift bits left
024	shift_right	Shift bits right
025	zero_return	Return and drop TOS if TOS is 0. If TOS is not 0, do nothing.
026	inc	Increment TOS by 1
027	dec	Decrement TOS by 1
028	in	Read a value from an IO port
029	out	Send a value to an IO port
030	wait	Wait for an IO event

I/O Devices

Ngaro provides a minimal set of hardware devices, accessible via a collection of I/O ports. The in, out, and wait instructions are used to access these.

Port	Description
000	Device wait state
001	Keyboard Input
002	Console Output
003	Force Console Update
004	Save Image
005	Capabilities Query
006	Canvas Output
007	Mouse Input

Port 0: Trigger I/O Event

To tell Ngaro that an I/O event is coming, write the appropiate values to one of the ports, write 0 to port 0, then invoke the wait instruction.

lit 0  # value
lit 0  # port
out    # write value to port
wait   # wait for an I/O event

Port 1: Keyboard Input

Reading from the keyboard is easy. Send 1 to port 1 and then trigger an I/O event. After the I/O event returns, read the keypress from port 1. If a non-keyboard event is received, the read result will be 0, otherwise it will be the ASCII value of the pressed key.

lit 1
lit 1  # keyboard port
out
# --- wait for I/O event ---
lit 0
lit 0
out
wait
# --- read keypress ---
lit 1
in

Port 2: Console Output

Writing a character to the console is also easy. Push the ASCII code to the screen, then send 1 to port 2 and trigger an I/O event.

lit 98 # ASCII code for 'b'
lit 1
lit 2  # console output port
out
# --- wait for I/O event ---
lit 0
lit 0
out
wait

Port 3: Force Console Update

The Ngaro VM is allowed to cache updates to the console (and canvas). You can force a screen update using port 3.

Port 3 is normally set to 1. To trigger a screen update, send 0 to it.

lit 0
lit 3  # force screen update
out

Note: You do _not_ need to wait for an I/O event on this port.

Port 4: Save the Image

Port 4 is used to save the image. Send 1 to port 4 and trigger an I/O event.

Note: Not all implementations allow this to be done.

Port 5: Query Capabilities

Port 5 is used to query Ngaro about the provided hardware emulation and some aspects of the processor state.

Send one of the following to port 5, trigger an I/O event, then read port 5 to get the results.

Value	Action
-1	Return amount of memory
-2	Is canvas present? -1 if true, 0 if false
-3	Get canvas width
-4	Get canvas height
-5	Get stack depth
-6	Get address stack depth
-7	Is mouse present? -1 if true, 0 if false

Port 6: Draw on the Canvas

Port 6 is used to draw on the canvas.

Value	Action
001	Set color. Takes color value from the stack.
002	Draw a pixel. Takes x and y from the stack.
003	Draw a hollow rectangle. Takes width, height, x, and y from the stack.
004	Draw a filled rectangle. Takes width, height, x, and y from the stack.
005	Draw a vertical line. Takes height, x, and y from the stack.
006	Draw a horizontal line. Takes width, x, and y from the stack.
007	Draw a hollow circle. Takes width, x, and y from the stack.
008	Draw a filled circle. Takes width, x, and y from the stack.

Note: Not all implementations will support the canvas.

Port 7: Interact with the Mouse

Port 7 is used to interact with the mouse device.

To obtain mouse position, send 1 to port 7 and trigger an I/O event.

lit 1
lit 7
out
# --- wait for I/O event ---
lit 0
lit 0
out
wait

The mouse coordinates will be placed on the stack. The Y coordinate will be TOS, and the X coordinate will be NOS.

To obtain the button press state, send 2 to port 7 and trigger an I/O event.

lit 2
lit 7
out
# --- wait for I/O event ---
lit 0
lit 0
out
wait

The button state will be placed on the stack. 1 if a button is pressed, or 2 if a button is not pressed.

Note: Not all implementations will support the canvas.