# uxn emulator

There's a uxn emulator along with varvara device implementation living in
emul/uxn. Loading emul/uxn/vm.fs exposes this API:

Device
  An exported structure to allow direct access to the device memory area. See
  emul/uxn/vm.c for field list.

uxn_init ( -- )
  Initialize stacks and zero-out all device data and DEI/DEO handler pointers to
  "null" handlers (will simply read/write from/to "Device dat").

uxn_ram ( -- a )
  Address, on the host, of the 64K memory area for the uxn VM. You will
  typically want to put your bytecode at uxn_ram + $100.

uxn_dev ( port -- dev )
  Yields the address of the Device structure corresponding to "port", a number
  between 0 and 15.

uxn_exec ( frompc -- )
  Repeatedly execute instructions from memory, starting at PC "frompc". Stop
  when a BRK is encountered. You'll typically want to call this with,
  frompc=$100, but varvara device handlers also call this with frompc=vector.

## Varvara

uxn is a lot more fun when combined with varvara, its companion set of virtual
devices. Dusk splits varvara in two: the "console" part and the "gui" part.

The console part is loaded through emul/uxn/varvara.fs and exposes this:

varvara_init ( -- )
  Initialize the uxn VM devices with DEI/DEO handlers for System, Console and
  File devices.

uxn_cli ( -- )
  Initialize uxn, varvara and then call uxn_exec with frompc=$100.

## Varvara GUI

The GUI part of varvara is loaded through emul/uxn/gui.fs:

gui_init ( -- )
  Puts the screen into graphical mode and initializes the Screen and Controller
  devices. If your console isn't graphical (that is, 100% of console
  implementations in Dusk at the moment), this locks you out of the computer, so
  don't call this interactively without a way to get out of it again.

gui_deinit ( -- )
  Put the screen back to text mode.

uxn_gui ( -- )
  Initializes uxn, varvara and put the screen in graphical mode. Then, call
  uxn_exec with frompc=$100, and then enter the "graphical loop". That is:

  1. Call Screen vector if nonzero
  2. Check for controller input
  3. Update Controller device accordingly and call vector if needed.
  4. Check if Escape key has been pressed then released.
  5. If yes, deinit screen and exit loop. If no, goto 1.

## uxntal

You can assemble ".tal" file with the uxntal assembler at asm/uxntal.fs. When
loaded, exposes this API:

uxntal ( srchdl -- res )
  Read IO handler "srchdl" until EOF and spits the resulting bytecode to
  uxn's VM RAM, starting at offset $100.
  Yields a numberical result code which is 0 on success and nonzero on error.

tal>vm ( path -- res )
  Conveniently wraps "uxntal" for a common case: open a file path "path" (a
  string) and assemble it at uxn_ram + $100.
