--------------------------------------------------------------------------
                       Apoo Assembly Language
---------------------------------------------------------------------------

Apoo has a set of general purpose registers (32 by default), a data
memory area, a program memory area, a system stack and a program
counter register.

All memory cells and registers have 32 bits.

Registers: R0,R1,R2,R3,R4,R5,R6,R7, ...

Memory Data:
-----------
Memory cells are created as needed. We can reserve memory cells
in two ways, using the following pseudo-instructions:

Pseudo-instructions:
-------------------

                       Meaning
-------------------------------------------------
<Label:>        mem     n       reserves n memory addresses
-------------------------------------------------
Label:          const   n2      contents of memory address
                const   n1      Label is n1, of Label+1 is n2


Label is any string beginning with a letter and containing only letters
and digits with the exception of legal register names. If exists, must
begin in the first column of a line

NOTE: Every memory address refered, must have been reserved by 
one of the previous pseudo-instructions.
E.g. the instruction "load 3 R2", will cause an "Out of Memory" error, if
at least "mem 3" or three "const" pseudo-instructions were not given...


System Stack
------------

A special memory area used to implement subroutines. We can only push
a value to the Stack and pop a value from it (the one in the
top of the Stack).
It is used by the instructions jsr and rtn.
It can be manipulated by means of the {\tt push} and {\tt pop} instructions.



Instruction form
----------------

<Label:> Operation <Operand1> <Operand2>

Label is any string of letters or digits; if exists, must begin in the
first column of a line

Comments
--------

A line beginnig with # will be ignored by the parser; so it can be
used to write comments of the program

Instruction Set
---------------

--------------------------------------------------------------------------
Operation  Operand1    Operand2    Meanning
--------------------------------------------------------------------------
load       Mem         Ri          loads contents of memory 
                                   address Mem into register Ri;
                                   Mem can be a label 
--------------------------------------------------------------------------
loadn      Num         Ri          loads number Num into register
                                   Ri; Num can be a label
--------------------------------------------------------------------------
loadi      Ri          Rj          loads contents of memory
                                   which address is the contents
                                   of Ri into Rj (indirect load)
--------------------------------------------------------------------------
store      Ri          Mem         stores contents of Ri at memory
                                   address Mem; Mem can be a label
--------------------------------------------------------------------------
storer     Ri          Rj          stores contents of Ri into Rj
--------------------------------------------------------------------------
storei     Ri          Rj          stores contents of Ri
                                   into at  memory address, which is the
                                   contents of Rj
--------------------------------------------------------------------------
add        Ri          Rj          add contents of register Ri to
                                   contents of register Rj, and
                                   stores into Rj (Rj=Ri+Rj)
--------------------------------------------------------------------------
sub        Ri          Rj          subtracts contents of register
                                   Rj from contents of register Rj
                                   and stores into Rj (Rj=Ri-Rj)
--------------------------------------------------------------------------
mul        Ri          Rj          multiplies  contents of register
                                   Ri and contents of register
                                   Rj, and stores into Rj (Rj=Ri*Rj)
--------------------------------------------------------------------------
div        Ri          Rj          stores into Rj the quotient of integer
                                   division of contents  register
                                   Ri by the contents of register
                                   Rj, and stores into Rj (Rj=Ri/Rj)
--------------------------------------------------------------------------
mod        Ri          Rj          stores into Rj the rest of integer
                                   division of contents of register
                                   Ri by the contents of register
                                   Rj, and stores into Rj (Rj=Ri%Rj)
--------------------------------------------------------------------------
zero       Ri                      the contents of Ri becomes 0 (Ri=0)
--------------------------------------------------------------------------
inc        Ri                      increments by 1 the contents of Ri
--------------------------------------------------------------------------
dec        Ri                      decrements by 1 the contents of Ri
--------------------------------------------------------------------------
jump       Addr                    jumps to instruction address Addr;
           Addr                    can be a Label
--------------------------------------------------------------------------
jzero      Ri          Addr        jumps to instruction address Addr,
                                   if contents of Ri is zero;
                                   Addr can be a Label
----------------------------------------------------------------------------
jnzero      Ri          Addr       jumps to instruction address Addr,
                                   if contents of Ri is different
                                   from zero;
--------------------------------------------------------------------------
jpos       Ri          Addr        jumps to instruction address Addr,
                                   if contents of Ri is positiv;
                                   Addr can be a Label
--------------------------------------------------------------------------
jneg       Ri          Addr        jumps to instruction address Addr,
                                   if contents of Ri is negativ
--------------------------------------------------------------------------
jsr        Addr                    pushes the PC into the stack and 
                                   jumps to instruction address Addr
--------------------------------------------------------------------------
rtn                                pops an address from the stack
                                   into the PC
--------------------------------------------------------------------------
push       Ri                      pushes the contents of Ri into the 
                                   system stack
--------------------------------------------------------------------------
pop        Ri                      pops at element from the system stack
                                   into Ri
--------------------------------------------------------------------------
halt                               stops execution; Every program
                                   must have this instruction in order
                                   to end properly; otherwise an
                                   'Out of Program' error will occur


Memory- mapped instructions
---------------------------

Apoo allows the configuration of a set of memory positions for special
purposes. The memory values and its functionality are given as a
parameter of the Apoo virtual machine. The default values allow the
simulation of input/output:



Memory Position 	Load/Store 	     Meaning
----------------------------------------------------------------------
50000 	           load 50000 Ri      loads 0 Ri

		   store Ri 50000     writes the character which ascii
		                      code is  Ri%256 in the Output
		                      Window (in graphical interface)
		                      or in stdout, in text mode.
------------------------------------------------------------------------
50001		   load 50001 Ri      reads an integer and stores it in Ri
	                             

		   store Ri 50001     writes the contents of Ri as an integer 
-------------------------------------------------------------------------------
50010		   load 50010 Ri      loads 0 in Ri
	
                   store Ri 50010     writes a CR in the Output Window 
                                      (in graphical interface) or in
                                      stdout, in text mode.

-------------------------------------------------------------------
(C) 1998-2006 Rogerio Reis, Nelma Moreira {rvr,nam}@ncc.up.pt
