The Quadruple Machine is an abstract computer and its implementation,
used as the target machine of programming on JYU POPL course in fall
2004. The machine is specified on assembly programming level in the
course handout. It doesn't contain data registers. Instead, temporary
data is meant to be stored in memory and stack to be used only for
subroutine control. The machine contains operating system calls for
file IO, processes, threading, and IPC.

The implementation is a rather thin but portable simulator of the
machine.


 ***

The machine is described in the course handout on assembler and
syscall level. The implementation shall correspond to this
description.

    * course handout:
      http://www.mit.jyu.fi/antkaij/opetus/okp/2004/moniste/jy-okp-2004-09-07.pdf

    * Division is not well-defined in word types, if the dividend is
      immediate data. (Immediate data can't be 64 bits.)
    

    * Syscall READ returns input until and including the first \n. If
      eof is reached first or the buffer fills, buffer is returned.
    

    * Syscall WRITE writes the whole buffer. If an error occurs, less
      is written.

 ***

= To users of the Quadruple Machine =

The primary specification of the Quadruple Machine is in the course
handout, which is in Finnish. If the tables of instructions and
syscalls are not comprehensible, please ask for further documentation,
or see the source code `:-)`

The implementation of the Quadruple Machine consists of an assembler
and a simulator for the machine. Neither has user interface in
addition to command-line options. As there isn't a debugger, the
simulator has a trace mode and some unofficial syscalls that can be
used to inspect the state of the machine as it runs.

 (101) Print "Hello, world!" (`HELLO`)

 (102) Print the current register values in hexadecimal and decimal (`STATE`)

 (103) Print the words between SP and FP in hexadecimal (`FRAME`)

 (104) Print an unsigned word integer (`PUTWU`)
        '''Parameters:''' `[SP+0]` contains the integer to be printed

        '''Return data:''' Not any.

The official specification is not fully implemented either, which
means weird things happening can be because the implementation is
lacking. Things missing include modulo of float values, doubleword
type in multiplication and division, official syscalls other than
`READ`, `WRITE`, `EXIT`, `TIME`. The simulator complains when it meets
something it doesn't support yet.

The assembler is very picky about the input format and will complain
often. It doesn't support octal or hex character escapes or
continuation lines in string constants. It separates words by space,
so you can't write `[dest]<-[source]` or `[SP + 0] <- [source]`.

== assembler ==

The assembler reads in a source program file written in the Quadruple
Machine assembly language, and produces an object program file in the
Quadruple Machine executable format. The source file would be produced
by some language compiler, and the object file can be further loaded
and run in the Quadruple Machine simulator.

 Usage: `assembler` [ `-o` objectfile ] sourcefile

 Example: `assembler -o hello hello.s`

 `-o` allows overriding the object filename, which defaults to source
 filename with `.s` ending replaced with `.o`

See files under directory `tests/errors` for examples of syntax errors
and other files under `tests` for examples of correct syntax.


== simulator ==

The simulator loads a binary file in the Quadruple Machine executable
format, and simulates the machine executing the instructions and
performing the system calls. The simulator prints information about
the machine operation, as well as directs to the user any input and
output from the running program.

 Usage: `simulator` [ `-v` ] [ `-t` ] objectfile

 Example: `simulator -t test.o`

 `-v` turns on verbose mode, reporting about simulator internal state

 `-t` turns on trace mode, showing the instructions executed

See files under directory `examples` for short programs to assemble
and try in the simulator.

 ***

== Version control using Darcs ==

Getting a copy of the central repository: {{{
darcs get http://kaijanaho.info/repos/quadmachine
}}}

Pulling changes from the central repository: {{{
darcs pull http://kaijanaho.info/repos/quadmachine
}}}

Commiting patches: {{{
darcs send --sign http://kaijanaho.info/repos/quadmachine
}}}

The URL in these is needed only the first time; darcs then remembers it.

== Coding style ==

Linux-style: 8-character indentations, opening brace on its own line
only for function definitions, more at
http://pantransit.reptiles.org/prog/CodingStyle.html.  Set in emacs
using `C-c . linux RET`.

== Source files ==

 * `examples/' - example programs written in the assembly language

 * `tests/ams/' - assembly code snippets to test addressing modes
 * `tests/ops/' - assembly code snippets to test instructions
 * `tests/errors/' - assembly code snippets with mistakes to test error reporting
 * `tests/types/' - assembly programs to test data types
 * `tests/syscalls/' - assembly programs to test syscalls

 * `Makefile` - instructions for `make` command about how to compile the programs and run tests
 * `assembler.c` - assembler main program
 * `simulator.c` - simulator main program

 * `symboltable.c` - an implementation of symbol table for the assembler
 * `symboltable.h`

 * `segment.c` - an implementation of memory segment for the simulator
 * `segment.h`

 * `compat.h` - conditional definition of macros to achieve compatibility between several compilers
 * `types.h` - `typedef`s for the primitive machine data types `byte_t` and `word_t`
 * `qm-ds.h` - definitions needed for data coding and decoding in the assembler and simulator
 * `syscalls.h` - system call numbers for simulator
 * `util.h` - utility functions `equals` and `startswith`
 * `errors.h` - error handling functions `check_alloc`, `fatal` and `pfatal`