Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
210 lines (162 sloc) 5.98 KB
Textmode Virtual Macaroni, or TMVM, is a simple, poorly-designed,
simulation of a register-based system.
It currently has an addressable memory space of 256 segments containing
256 bytes (00..ff) each, for a total of 65536 bytes (or 64KiB).
It runs at a nominal speed of 1MHz.
It's not presently useful for much of anything, it is also likely to be
unstable and unreliable, so have fun! :D
In all honesty, TMVM could be used as a toy system, or as an instructive
aid (once it's more stable). It's nigh-complete lack of higher-level
features or space means it's effectively a void, an empty sandpit, in
which you can do pretty much anything you want without stepping on
anything's toes.
Note: TMVM is still under development, expect fundamental design and API
TMVM is created by DMB/Textmode, while ignoring the well thought-out
advice of many helpful people who didn't realise that TMVM was meant to
be very dubious in quality and use.
# Requirements
* Lua 5.1 or better.
* A sense of humor.
# Usage
TMVM is divided into two basic parts; the machine (AKA Core), and the
There is also the support lib bitfield.
The ASM is the component that takes programs expressed in FUASSM code. It
is a runnable module.
Machine represents functions for creating and managing individual TMVMs.
loading data into their memory, and controlling their operation. It is
not yet a runnable module, but its likely to become one in the future.
Bitfield contains utility functions for dealing with numbers as bitfields.
It provides bitwise operations, binary indexing and similar features
required by the core but not provided by lua.
## Machine
machine.lua can be required normally.
As a module, machine exposes the following functions:
returns: machine
Creates a new machine with the given name.
If no name is given, a default name will be provided.
returns: signal, description
If given no parms, returns the current signal, and a (short) textual
Otherwise it triggers the given signal.
Tf another signal has yet to be cleared, it will trigger a double
If a double-fault is uncleared, a triple-fault.
Triggering the signal NONE will clear the signal.
(VM):load(opt_start, data_string_or_table)
returns: (nothing)
Attempts to load the given data into the machine's memory.
If start is omitted, it will load at address 0, segment 0.
returns: machine_state
completes num instruction cycles. if num is omitted, it will assume
1 cycle.
(VM):run(bool_show_status_dumps) -- Broken!
returns: (nothing)
Attempts to run the machine at it's base speed.
if passed true, it will call VM:dump() roughly 1/s
returns: (nothing)
Prints state information on the current machine
## ASM
asm.lua can be required normally. Additionally, it is a runnable module and
can be directly run.
As a program, asm.lua takes the name of a FUASM source file, and optionally
the name of an output file. if no output file is given, it outputs to the
same filename with .crap replacing it's original extension: thus
'test.asm' outputs to 'test.crap'. Regardless, it also prints a
lua-formatted table of hex digits representing the assembled binary.
As a module, it exposes the following functions:
returns: preparsed_chunk
loads the given file and returns a normalised chunk, suitable for
further parsing.
returns: preparsed_chunk
processes the given string into a pre-parsed chunk, suitable for
further parsing.
returns: final_bytestring
takes a string or pre-parsed chunk, and returns a fully-assembled
chunk as a string, suitable for saving or loading into a machine.
## Bitfield
Bitfield is a support library, providing emulated bitwise operations for
As a module, it exposes the following functions:
bitfield:new(opt_num, opt_width)
returns: bitfield
Creates and returns a new bitfield. If opt_num is provided, the
initial value of the bitfield will be the binary representation of
that number, otherwise it will be zero.
If opt_width is provided it will be used as the effective bitwidth
of the bitfield, otherwise it will default to 16 bits.
returns: bit
Returns true if the nth bit is set, otherwise returns false. if a bit
outside the range of the bitfield's width is requested, it returns
nil instead (which is also logically false)
(bf)[n] = v
returns: (nothing)
Sets the nth bit of bf to the truth value of v
returns: num
Negates the value of bf. Additionally returns the resulting value.
NOT 1 -> 0
NOT 0 -> 1
returns: num
ANDs the value of bf with b. Additionally returns the resulting
0 AND 0 -> 0
0 AND 1 -> 0
1 AND 0 -> 0
1 AND 1 -> 1
returns: num
ORs the value of bf with b. Additionally returns the resulting value.
0 OR 0 -> 0
0 OR 1 -> 1
1 OR 0 -> 1
1 OR 1 -> 1
returns: num
XORs the value of bf with b. Additionally returns the resulting
0 XOR 0 -> 0
0 XOR 1 -> 1
1 XOR 0 -> 1
1 XOR 1 -> 0
returns: num
NANDs the value of bf with b. Additionally returns the resulting
0 NAND 0 -> 1
0 NAND 1 -> 1
1 NAND 0 -> 1
1 NAND 1 -> 0
returns: num
NORs the value of bf with b. Additionally returns the resulting value.
0 NOR 0 -> 1
0 NOR 1 -> 0
1 NOR 0 -> 0
1 NOR 1 -> 0
returns: num
XNORs the value of bf with b. Additionally returns the resulting
0 XNOR 0 -> 1
0 XNOR 1 -> 0
1 XNOR 0 -> 0
1 XNOR 1 -> 1
(bf):shift(n, sign-ext)
returns: num
Shifts the value of bf by n. Additionally returns the resulting
Positive values shift left, negative values shift right. if sign-ext
is true, then the sign bit will be extended during a right-shift.