wipforth/README.md

Wipforth

Wipforth is a simple Forth implementation that runs in the WebAssembly virtual machine. It does I/O via memory-mapped peripherals, which are emulated in JavaScript.

• For the Forth kernel, see wipforth.wat
• For the JavaScript emulator, see emu.js
• For the Forth prelude, which is loaded at start-up, see prelude.f
• For a description of the peripherals, see the Peripherals section below.

Building and Running

To run, first compile the WebAssembly module:

wat2wasm --enable-threads wipforth.wat

Then run the server:

python3 server.py

You should then be able to open http://localhost:8080 in a browser and use the system from there.

NOTE: The server is just a very simple instantiation of Python's built-in http.server.HTTPServer, configured to set the cross-origin headers required for SharedMemoryBuffer use. You could use any HTTP server that sets these headers.

Peripherals

Terminal

Name	Offset	Size / B	Access
TXBUF	0	32	write
RXBUF	32	32	read
TXHEAD	64	1	atomic read
TXTAIL	65	1	atomic write
RXHEAD	66	1	atomic write
RXTAIL	67	1	atomic read

For both sending (TX) and receiving (RX), there are three registers: xBUF, xHEAD and xTAIL:

• xBUF registers are 32-byte FIFO ring buffers used for data
• The xHEAD and xTAIL registers specify the start and end of data in the ring buffer, xHEAD being the offset of the first byte of data, and xTAIL being the offset of the first byte after the data.

In order to be distinguishable from the empty state, the ring buffers must never be completely full -- there must always be at least one unoccupied byte between the tail and the head.

System status

Name	Offset	Size / B	Access
SYSREADY	68	1	atomic write

The SYSREADY register is used to indicate when the system has booted up and is ready for user input.