Apoo assembly language
Keywords: apoo

Subsections

- - Memory Management
  - Pseudo-instructions
  - System Stack
  - Instruction form
  - Comments
  - Basic Instruction Set
  - Memory- mapped instructions
- Examples
  - Memory- mapped instructions

##
`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 are named R0,R1,R2,R3,R4,R5,R6,R7,...

#### Memory Management

The size of the RAM is predefined (e.g. 1K) and divided into two areas: static memory and system stack. The static memory, begins at address 0 and it is allocated when a `Apoo` program is loaded. Static memory cells can be reserved in in two ways, using the following pseudo-instructions:

#### Pseudo-instructions

|  |  | Meaning
`<Label:>` | `mem` | `n` | reserves n memory addresses
`Label:` | `const` | `n1` |
| `const` | `n2` | contents of memory address `Label` is `n1`, of Label+1 is `n2`
|  | .... | `ni` can be a character `'c'`.
`<Label:>` | `equ` | `n` | Allows a symbolic name for a number
`<Label:>` | `string` | `"seqNWSCharacteres"` | Allocates memory addresses and set them to the correspondent characters ASCII codes. The characters cannot be whitespaces: use `` for `space`, `` for `tab` and `` for `newline`.

`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... If a `equ` value is used as a memory address, that address must be already reserved or be a known memory-mapped instruction. The `string` argument must be quoted and is converted to a sequence of ascii codes ending with `0`.

#### System Stack

The system stack occupies the rest of the RAM (growing for higher addresses). Since `Apoo`version 3.0 it can be used in an advanced way to implement activation records (see section 3.2).

However in can be used in a simpler way 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 `push` and `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 beginning with # will be ignored by the parser; so it can be used to write comments of the program

#### Basic 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
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
jnzero | Ri | Addr | jumps to instruction address Addr, if contents of Ri is different from zero; Addr can be a Label
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
--- | --- | ---
50000 |
`load 50000 Ri`
loads 0 in `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.

Here is an example:

    	loadn	97	R0
    	store	R0	50000
    	store 	R0	50010
    	store	R0	50001
    	store	R0	50010
    	load	50001	R0
    	loadn	5	R1
    	add	R0	R1
    	store	R0	50001
    	store 	R0	50010
    	halt

### Examples

Some `Apoo` programs can be found here

#### Memory- mapped instructions