Index
1. COMPILE / INSTALL
2. WHAT IS IT
3. ASSEMBLY (two examples)
  3.1 BRIEF DESCRIPTION
  3.2 SUBROUTINES
  3.3 CONSTANTS
  3.4 PREPROCESSOR
4. LATEST DEVELOPMENTS
  4.1 TEMORARIES / Registers Auto-allocation
  4.2 CALLING CONVENTIONS
  4.2 ELF Object FILES
  4.4 SAMPLE FILES

--------------------------------------------------------------------------------
1. COMPILE / INSTALL

Before trying to compile it, remember to run autoreconf.

It will then be enough to type:
./configure
make

I'm not providing a predefined way to install right now. It's more like a toy,
than a tool.

--------------------------------------------------------------------------------
2. WHAT IS IT

vARCH is a virtual machine / interpreter of bytecode for a virtual architecture
that I invented for learning purposes.
It is not intended for performance or flexibility use cases. It's just a simple
and easy to learn architecture.

For the ease of development I also created a simple assembler.
Explanation on how to write the asm code is aided by some practical examples.

If you want to contribute to vARCH, you should ask for documentation/answers to
me directly, because it is a spare time project and I don't have much time for
documentation.

What I will report here are samples of the Asm language: they need to be
assembled and then either moved to the name "bios.bin" or soft linked to that
name.

--------------------------------------------------------------------------------
3. ASSEMBLY

The first example is a simple program for calculating the first n factorials.
The "main" function is special in the sense that is always put at the beginning
of the generated executable.

----------------
biosFactorial.s
----------------

; calculate the factorial by definition of the first 5 numbers
.function "main"
.init:
    MOV,   $1 ,   %R8
.start:
; the counter is post incremented after the copy
    MOV,   %R8+ , %R1
    MOV,   $1 ,   %R2
.iter:
    MULT,  %R1- , %R2
    MO,    %R1 ,  $1
    IFNJ,  @save
    JMP,   @iter
.save:
    PUSH,  %R2
    MO,    %R8 ,  .maxnum
    IFJ,   @end
    JMP,   @start
.end:
    HALT
.end

.global
  .maxnum:
    .i32_t  $12
.end

--------------------------------
Another simple program that shows how to give shape to subroutines.
It also exploits a missing feature to ease the work of outputting text: it
should launch the signal to the peripheral and than wait for the ready state,
before sending another character to display, but it's just pretending that a
terminal can work synchronously with the cpu.

----------------
biosTestAssembler.s
----------------

#include "std_conversion.s"

.function   "main"
.init:
  MOV,     @string1 ,   %T001
  MOV,     4 ,          %R6
; call the printing subroutine
  JSR,     @print ,     %T001
; call recursive subroutine
  MOV,     4 ,          %T002
  MOV,     %T002 ,      %T012
  MOV,     %T012 ,      %T013
  MOV,     %T013 ,      %T014
  JSR,     @recursive , %T014
; call conversion subroutine
  MOV,     @bufferEnd , %T003
  SUB,     @buffer ,    %T003
  MOV,     15234 ,      %T004
  MOV,     @buffer ,    %T005
  JSR,     @integerToString , %T004 , %T005 , %T003
; Verify result
  MOV,     %R0 ,        %T008
  EQ,      %T008 ,      0
  IFJ,     @error
  MOV,     @buffer ,    %T007
  JSR,     @print ,     %T007
  HALT
.error:
  MOV,     @stringError , %T001
  JSR,     @print ,       %T001
  HALT
.end

.global
  ; string to write
  .string1:
    .string     "test: yeah"
    .i8_t      10           ; '\n'
    .i8_t      0
  .stringError:
    .string     "Error"
    .i8_t      0
.end

.function   "recursive"
  .param  %R1         %T001

  .local
    .decrement: .const
      .i32_t  2
    .numberOfCalls: .static
      .i32_t  0
    .lowerBound:
      .i32_t  0
    .stateRegister:
      .i32_t  0
    .localString:
      .string "local_string"
      .i8_t  0
  .end

  SUB,     .decrement , %T001
  INCR,    .numberOfCalls
  LO,      %T001 ,      .lowerBound
  IFJ,     @exit
  JSR,     @recursive , %T001
.exit:
  MOV,     %SR ,        .stateRegister
  RET
.end

.global
  .uselessGlobal:
    .i32_t        $4
.end

----------------
std_io.s
----------------

; subroutine to call
.function   "print"
  .param    %R1         %T001 ; address of the string to print

  .local
    .printCmd: .const
      .i32_t  131072
    .printCmd1: .const
      .i32_t  131073
    .endChar: .const
      .i16_t   0
  .end

  MOV,    0 ,    %T002
.test:
  EQ,     (%T001) : .i8_t,    .endChar : .i16_t
  IFJ,    @exit
  PUT,    (%T001)+ : .i8_t,   .printCmd1
  INCR,   %T002
  JMP,    @test
.exit:
  RET,    %T002
.end

-----------------------------------
BRIEF DESCRIPTION OF EXAMPLES:

There are 8 data registers R1, R2, .. , R8, and 8 general purpose address
registers A1, A2, .. , A8. Then a specific register for the stack pointer SP,
and USP for the priviledged executor that wants to access unprivileged stack
pointer. (Issuing SP when privileged, an issuing SP when unprivileged gives two
different stack pointers)

There is another kind of registers, Tn, where n is any number, which is the set
of temporaries, which are later assigned and optimized by the register
allocation logics.

As noted before, there are two kinds of execution: privileged and unprivileged.
The bit identifying this is in the status register ( SR ). This was inspired by
Motorola 68k family.

Accessing data and registers is achieved in many ways with different meanings:

Addressing registers and memory is again very similar to the way it's done for
M68k asm, so the arguments of the instructions can be:

- IMMEDIATE: prefixing constants with $ which uses those as numerical constants,
or using @ (at) prefixed labels which accesses the pointer to the label.

- REGISTER: prefixing registers with % (eg. %R1, %A3, %SP ..) which accessed the
content of the registers.

- DIRECT: where the explicit address of a memory location is used, either using
. (dot) prefixed labels which accesses the content of the address in memory
marked by the label, or prefixing constants with > which uses them as addresses
(and addresses the memory address pointed by the constant).

- REGISTER INDIRECT: surrounding registers with round parenthesis ( and ), (e.g.
(A1), (SP) ..) which accesses the address in memory, pointed by the content of
the register.

- REGISTER MEMORY INDIRECT: it accesses memory using the address contained in a
location in memory pointed by an address into a register, and this is achieved
by the double parenthesis operator: ((A1)), ((SP)), etc.

- DISPLACED: applies a displacement to the address contained into a register and
accesses to the result, e.g. -20(SP), 3(A1), etc. Displacement is a 24bit signed
integer.

- INDEXED: uses one register as base address to a given location, and then
another register as index for accessing elements in an array, e.g. (A1)[R1]

- DISPLACED+INDEXED: same as the two together, but displacement in this case is
a 16bit signed integer.

There are then other useful methods for reducing code size and speeding up
execution with a compact code:

- prefixing (or postfixing) registers with + or - which in turn pre(post)
increments or decrements the accessed data:
  + if prefixing with %Reg# it will modify the content of the register
  + if prefixing with (Reg#) it will still modify the register content (and not
     of the pointed data)
  + if doing this on (address), data pointed by the address will be modified

------------------
Some words about SUBROUTINES:

Subroutines have a simple but strict syntax. You have to specify subroutine name
after the  .function  marker, and identify the end of the subroutine using the
.end  marker.
The name of the subroutine needs to be enclosed in double quotes, like a normal
string.

There is no possibility to use free code, outside of subroutines, since the main
subroutine serves as entry point for the binary.

Subroutines, when assembled do export their name as a global label and they can
be accessed through . and @ semantics.
To call a subroutine just issue a

	JSR	@name_of_subroutine [arguments...]
Since JSR stands for "Jump to SubRoutine".

The subroutine calling conventions are managed by the assembler. This gives the
freedom to the programmer to specify the arguments (expressed as temporaries) on
the very same line of the function call.

Functions and subroutines can also be recursive and have local variables which
are allocated on the stack each time that the functions are called.
The stack allocation is automatically managed by the assembler.

------------------
Some words about VARIABLES, CONSTANTS and their attributes:

The  .global  marker opens the area where global/public constants should be
located. This area is terminated with an  .end  marker.
Variables or constants, are there visible from everywhere.

It's possible to specify local/private constants for function calls only after
the marker  .local  which is terminated by the  .end  marker, just like
functions and globals.
To specify access to these memory locations, it is also possible to use the
.static  specifier, which behaves exactly like in C.
To optimize things,  .const  declared memory locations, are allocated like
static variables, to prevent stack allocations at every function call.

Local variables on the stack are supported just with the register
auto-allocation logic, because it requires some code transformation.

Labels make data visible and easily callable from outside.

Finally labels can also receive attributes like  .size  and  .num  .
While  .num  is not fully used now (tells how many times  .size  is repeated),
and will extensively used for arrays,  .size  gives the size of the size, in
bytes, of the data reached through the label.

------------------
Some words about PREPROCESSOR:

As can be seen from the example, it is possible to include code from other files
and compile it as if it was part of the current source.

If any error happens in the included files, it will be reported in which file
and at which line the error took place.

------------------
4. ADDITIONAL FEATURES

4.1 - TEMPORARIES

There is, as noted before, a new kind of registers: T[0-9]* which serve as
temporaries for successive elaboration by the allocation logics.

Avoiding explicit register use, for temporaries, frees the programmer from one
of the most bothering tasks, letting the assembler decide which register
allocation to use.

For maximum performance, the programmer can still use direct register assignment
when needed, while letting the assembler manage all the rest.

4.2 - CALLING CONVENTIONS

The arguments of a function are explicitly defined using the ".param" keyword.
While the returned (if returned) element is always in register R1.

Caller-save registers are R[1-5] and A[1-5], while callee-save registers are
R[6-8] and A[6-8].

4.3 - WRITING ELF OBJECT FILES

Compiling with "-c" flag now outputs an object file which respects the ELF file
format. This object file can then be linked against other object files, to
generate proper executables, using the very same syntax of many other famous
compilers.

4.4 - SAMPLE FILES

Some sample .s files are in the main folder:
 testNewAssembler.s
 std_io.s
 std_conversion.s

The user can have a look to these examples.

------------------

If you feel this description incomplete, let me know.

I hope you will enjoy this playground for learning.