This is an embeddable Go implementation of the Ngaro Virtual Machine.
This repository contains the embeddable virtual machine, a rudimentary symbolic assembler for easy bootstrapping of projects written in Ngaro machine language, and the retro command line tool that can be used as a replacement for the Retro reference implementations.
Please visit http://forthworks.com/retro/ to get you started about the Retro language and the Ngaro Virtual Machine.
The main purpose of this implementation is to allow customization and communication between Retro programs and Go programs via custom opcodes and I/O handlers (i.e. scripting Go programs in Retro). The package examples demonstrate various use cases. For more details on I/O handling in the Ngaro VM, please refer to http://retroforth.org/docs/The_Ngaro_Virtual_Machine.html.
Custom opcodes are implemented by intercepting implicit calls to negative memory addresses. This limits the total addressable memory to 2GiB on 32 bits systems, but this also allows the VM to be fully backwards compatible with existing Retro images while still providing enhanced capabilities.
This implementation passes all tests from the retro-language test suite and its performance when running tests/core.rx is slightly better than with the reference implementations:
1.12s for this implementation, no custom opcodes, compiled with Go 1.7.
1.30s for the reference Go implementation, compiled with Go 1.7
2.22s for the reference C implementation, compiled with gcc-5.4 -O3 -fomit-frame-pointer
For all intents and purposes, the VM behaves according to the specification. This is of particular importance to implementors of custom opcodes: the VM always increments the PC after each opcode, thus opcodes altering the PC must adjust it accordingly (i.e. set it to its real target minus one).
Install the retro command line tool:
go get -u github.com/db47h/ngaro/cmd/retro
Test:
go test -i github.com/db47h/ngaro/vm
go test -v github.com/db47h/ngaro/vm/...
Build a retroImage:
cd $GOPATH/github.com/db47h/ngaro/cmd/retro
make retroImage
Test the retro command line tool:
./retro --with vm/testdata/core.rx
Should generate a lot of output. Just check that the last lines look like this:
ok summary
360 tests run: 360 passed, 0 failed.
186 words checked, 0 words unchecked, 37 i/o words ignored.
ok bye
Since v2.0.0, the default Cell type (the base data type in Ngaro VM) is Go's int. This means that depending on the target you compile for, it will be either 32 or 64 bits. The retro command line tool supports loading and saving retro memory images where Cells can be either size. For example, to quickly get started you can do this:
echo "save bye" | \
retro -image vm/testdata/retroImage -ibits 32 -o retroImage
This will load the memory image file vm/testdata/retroImage
which we know to
be encoded using 32 bits cells, and save it in the current directory with
whatever encoding is the default for your platform. You could also force a
specific output Cell size with the -obits
flag.
Loading and saving with encodings different from the target platform is safe: it will work or generate an error, but never create a corrupted memory image file. For example, with a 64 bits retro binary, saving to 32 bits cells will check that written values fit in a 32 bit int. If not, it will generate an error.
If for some reason you need a specific cell size, regardless of the target
platform's native int size, you can force it by compiling with the tags
ngaro32
or ngaro64
:
go install -tags ngaro32 github.com/db47h/ngaro/cmd/retro
will build a version of retro that uses 32 bits cells, regardless of
GOOS
/GOARCH
. Likewise, the ngaro64
tag will force 64 bits cells, even on
32 bits targets (it'll be twice as slow though).
This project uses semantic versioning and tries to adhere to it.
Please do not use releases before v2.0.0 as there are a few known bugs in these.
See the releases page.
For a detailed change log, see the commit log.
This project is licensed under the Apache License, Version 2.0.