Skip to content

Latest commit

 

History

History
331 lines (242 loc) · 10.3 KB

README.md

File metadata and controls

331 lines (242 loc) · 10.3 KB

IGUANA MAC INTERPRETER

A simple 16-bit stack-based assembly interpreter for Andrew S. Tanenbaum's MAC assembly language. The interpreter is written in Rust and supports a variety of operations, including arithmetic, memory, control flow, bitwise, and debug operations.

Example Assembly Code

The following example finds the largest of two values:

# Find the biggest between two values

.data
VAL1: .word 10
VAL2: .word 257
BIGGER: .word 0

.text
    LODD VAL1
    SUBD VAL2
    JPOS LABEL1

    LODD VAL2 
    STOD BIGGER
    JUMP PRINT_AND_END

LABEL1:
    LODD VAL1  
    STOD BIGGER   

PRINT_AND_END:
    LODD BIGGER
    PRINTLNAC
    HALT

output:

257

Usage Instructions

Running a File

To run a assembly file, use the following command:

iguana run <file>

Display Interpreter Informations

To display the interpreter information, use the following command:

iguana info

Build Instructions

  1. Ensure that you have Rust and Cargo installed:

    • Follow the installation guide on the official Rust website if needed.

  2. Clone the repository:

    • Use the following command to clone the repository: 
      git clone https://github.com/joeCavZero/iguana-mac-interpreter.git

  3. Build the source code:

    • Run the following command to build the project in release mode: 
      cargo build --release

  4. Locate the generated binary:

    • After the build is complete, the binary will be located at: 
      ./target/release/iguana.exe on Windows 
( or iguana.app on MacOS or iguana on Linux )

Iguana's MAC Operations Guide

Constant Loading

  • LOCO X
    Behavior: Loads the constant value X into the accumulator (ac).
    Pseudo-behavior: ac = X

Memory Operations

  • LODD X
    Behavior: Loads the value from the stack at address X into the accumulator (ac).
    Pseudo-behavior: ac = M[X]

  • STOD X
    Behavior: Stores the value in the accumulator (ac) into the stack at address X.
    Pseudo-behavior: M[X] = ac

  • LODL X
    Behavior: Loads a value from the stack relative to the stack pointer (sp) into the accumulator (ac).
    Pseudo-behavior: ac = M[sp + X]

  • STOL X
    Behavior: Stores the value in the accumulator (ac) into the stack relative to the stack pointer (sp).
    Pseudo-behavior: M[sp + X] = ac

  • PSHI
    Behavior: Pushes the value in the accumulator (ac) onto the stack.
    Pseudo-behavior: sp = sp - 1; M[sp] = M[ac]

  • POPI
    Behavior: Pops a value from the stack into the memory address stored in the accumulator (AC).
    Pseudo-behavior: M[AC] = M[SP]; SP = SP + 1

  • PUSH
    Behavior: Pushes the value in the accumulator (ac) onto the stack.
    Pseudo-behavior: sp = sp - 1; M[sp] = ac

  • POP
    Behavior: Pops a value from the stack into the accumulator (ac).
    Pseudo-behavior: ac = M[sp]; sp = sp + 1

  • SWAP
    Behavior: Swaps the value in the accumulator (ac) with the value at the top of the stack.
    Pseudo-behavior: temp = ac; ac = sp; sp = temp

  • INSP X
    Behavior: Increments the stack pointer (sp) by X.
    Pseudo-behavior: sp = sp - X

  • DESP X
    Behavior: Decrements the stack pointer (sp) by X.
    Pseudo-behavior: sp = sp + X

Arithmetic Operations

  • ADDD X
    Behavior: Adds the value at address X in the stack to the accumulator (ac).
    Pseudo-behavior: ac = ac + M[X]

  • SUBD X
    Behavior: Subtracts the value at address X in the stack from the accumulator (ac).
    Pseudo-behavior: ac = ac - M[X]

  • MULD X
    Behavior: Multiplies the value in the accumulator (ac) by the value at address X in the stack.
    Pseudo-behavior: ac = ac * M[X]

  • DIVD X
    Behavior: Divides the value in the accumulator (ac) by the value at address X in the stack.
    Pseudo-behavior: ac = ac / M[X]

  • ADDL X
    Behavior: Adds a value from the stack relative to the stack pointer (sp) to the accumulator (ac).
    Pseudo-behavior: ac = ac + M[sp + X]

  • SUBL X
    Behavior: Subtracts a value from the stack relative to the stack pointer (sp) from the accumulator (ac).
    Pseudo-behavior: ac = ac - M[sp + X]

  • MULL X
    Behavior: Multiplies a value from the stack relative to the stack pointer (sp) to the accumulator (ac).
    Pseudo-behavior: ac = ac * M[sp + X]

  • DIVL X
    Behavior: Divides a value from the stack relative to the stack pointer (sp) from the accumulator (ac).
    Pseudo-behavior: ac = ac / M[sp + X]

Control Flow Operations

  • JPOS X
    Behavior: Jumps to address X if the accumulator (ac) is positive.
    Pseudo-behavior: if ac >= 0: pc = X

  • JZER X
    Behavior: Jumps to address X if the accumulator (ac) is zero.
    Pseudo-behavior: if ac == 0: pc = X

  • JUMP X
    Behavior: Unconditionally jumps to address X.
    Pseudo-behavior: pc = X

  • JNEG X
    Behavior: Jumps to address X if the accumulator (ac) is negative.
    Pseudo-behavior: if ac < 0: pc = X

  • JNZE X
    Behavior: Jumps to address X if the accumulator (ac) is not zero.
    Pseudo-behavior: if ac != 0: pc = X

  • CALL X
    Behavior: Calls a subroutine at address X, saving the return address on the stack.
    Pseudo-behavior: sp = sp - 1; M[sp] = pc + 1; pc = X

  • RETN
    Behavior: Returns from a subroutine by popping the return address from the stack.
    Pseudo-behavior: pc = M[sp]; sp = sp + 1

Bitwise Operations

  • ANDI X
    Behavior: Performs a bitwise AND between the accumulator (ac) and the constant X.
    Pseudo-behavior: ac = ac & X

  • ORI X
    Behavior: Performs a bitwise OR between the accumulator (ac) and the constant X.
    Pseudo-behavior: ac = ac | X

  • XORI X
    Behavior: Performs a bitwise XOR between the accumulator (ac) and the constant X.
    Pseudo-behavior: ac = ac ^ X

  • NOT
    Behavior: Performs a bitwise NOT on the accumulator (ac).
    Pseudo-behavior: ac = ~ac

  • SHFLI X
    Behavior: Shifts the value in the accumulator (ac) left by X bits.
    Pseudo-behavior: ac = ac << X

  • SHFRI X
    Behavior: Shifts the value in the accumulator (ac) right by X bits.
    Pseudo-behavior: ac = ac >> X

  • ANDD X
    Behavior: Performs a bitwise AND between the accumulator (ac) and the value at address X in the stack.
    Pseudo-behavior: ac = ac & M[X]

  • ORD X
    Behavior: Performs a bitwise OR between the accumulator (ac) and the value at address X in the stack.
    Pseudo-behavior: ac = ac | M[X]

  • XORD X
    Behavior: Performs a bitwise XOR between the accumulator (ac) and the value at address X in the stack.
    Pseudo-behavior: ac = ac ^ M[X]

  • NOTD X
    Behavior: Performs a bitwise NOT on the value at address X in the stack and stores the result in the accumulator (ac).
    Pseudo-behavior: ac = ~M[X]

  • SHFRD X
    Behavior: Shifts the value in the accumulator (ac) right by the value at address X in the stack.
    Pseudo-behavior: ac = ac >> M[X]

  • SHFLD X
    Behavior: Shifts the value in the accumulator (ac) left by the value at address X in the stack.
    Pseudo-behavior: ac = ac << M[X]

Debug Operations

  • PRINTLNAC
    Behavior: Prints the value in the accumulator (ac) with a line break.
    Pseudo-behavior: print( ac + '\n' )

  • PRINTAC
    Behavior: Prints the value in the accumulator (ac).
    Pseudo-behavior: print( ac )

  • PRINTLNSP
    Behavior: Prints the value in the stack pointer (sp) with a line break.
    Pseudo-behavior: print( sp + '\n' )

  • PRINTSP
    Behavior: Prints the value in the stack pointer (sp).
    Pseudo-behavior: print( sp )

  • PRINTLNTOPI X
    Behavior: Prints the value at offset X from the stack pointer (sp) with a line break.
    Pseudo-behavior: print( M[ sp + X ] + '\n' )

  • PRINTLNTOPD X
    Behavior: Prints the value at offset X from the stack pointer (sp) with a line break.
    Pseudo-behavior: print( M[ sp + M[X] ] + '\n' )

  • PRINTTOPI X
    Behavior: Prints the value at offset X from the stack pointer (sp).
    Pseudo-behavior: print( M[ sp + X ] )

  • PRINTTOPD X
    Behavior: Prints the value at offset X from the stack pointer (sp).
    Pseudo-behavior: print( M[ sp + M[X] ] )

  • PRINTLNACCHAR
    Behavior: Prints the value in the accumulator (ac) as a character with a line break.
    Pseudo-behavior: print( char( ac ) + '\n' )

  • PRINTACCHAR
    Behavior: Prints the value in the accumulator (ac) as a character.
    Pseudo-behavior: print( char( ac ) )

  • PRINTLNTOPCHARI X
    Behavior: Prints the value at offset X from the stack pointer (sp) as a character with a line break.
    Pseudo-behavior: print( char( M[ sp + X ] ) + '\n' )

  • PRINTLNTOPCHARD X
    Behavior: Prints the value at offset X from the stack pointer (sp) as a character with a line break.
    Pseudo-behavior: print( char( M[ sp + M[X] ] ) + '\n' )

  • PRINTTOPCHARI X
    Behavior: Prints the value at offset X from the stack pointer (sp) as a character.
    Pseudo-behavior: print( char( M[ sp + X ] ) )

  • PRINTTOPCHARD X
    Behavior: Prints the value at offset X from the stack pointer (sp) as a character.
    Pseudo-behavior: print( char( M[ sp + M[X] ] ) )

Custom Operations

  • HALT
    Behavior: Stops the execution of the entire program.
    Pseudo-behavior: halt

  • SLEEPD X
    Behavior: Pauses execution for the number of milliseconds specified by the value at address X in the stack.
    Pseudo-behavior: sleep_in_milliseconds( M[ X ] )

  • SLEEPI X
    Behavior: Pauses execution for X milliseconds.
    Pseudo-behavior: sleep_in_milliseconds( X )