update roadmap and ISA spec

frontend/backend distinction or use of standard model)

.cargo/config.toml

@@ -0,0 +1,7 @@
+[build]
+rustc-wrapper = "sccache"
+# Enable to cut unused deps.
+# rustflags = ["-D", "unused-crate-dependencies"]
+
+[future-incompat-report]
+frequency = "always"

.gitignore

@@ -1,2 +1,3 @@
 /target
-**/*.env
+**/*.env
+Cargo.lock

.vscode/settings.json

@@ -5,5 +5,7 @@
   "files.eol": "\n",
   "files.insertFinalNewline": true,
   "files.trimFinalNewlines": true,
-  "files.trimTrailingWhitespace": true
+  "files.trimTrailingWhitespace": true,
+  "gitea.owner": "LowLevelDevs",
+  "gitea.repo": "damn_simple_architecture",
 }

Cargo.toml

@@ -1,8 +1,17 @@
+cargo-features = ["codegen-backend"]
+
 [workspace]
-members = ["emulator", "common", "assembler", "dsa_editor"]
+members = ["emulator", "common", "assembler", "dsa_editor", "compiler", "dsx-build"]
 resolver = "3"
 
 [workspace.package]
 version = "0.2.0"
 edition = "2024"
 authors = ["zxq5", "nullndvoid"]
+
+[profile.dev]
+codegen-backend = "cranelift"
+panic = "abort" # Cranelift does not support stack unwinds.
+lto = false
+debug = true
+incremental = false # sccache does not support caching incremental crates.

assembler/brainf.bf

@@ -1,34 +0,0 @@
-++++++++++++++++++++++++++++++++++++++++++++		c1v44 : ASCII code of comma
->++++++++++++++++++++++++++++++++			c2v32 : ASCII code of space
->++++++++++++++++					c3v11 : quantity of numbers to be calculated
->							c4v0  : zeroth Fibonacci number (will not be printed)
->+							c5v1  : first Fibonacci number
-<<							c3    : loop counter
-[							block : loop to print (i)th number and calculate next one
->>							c5    : the number to be printed
-
-							block : divide c5 by 10 (preserve c5)
->							c6v0  : service zero
->++++++++++						c7v10 : divisor
-<<							c5    : back to dividend
-[->+>-[>+>>]>[+[-<+>]>+>>]<<<<<<]			c5v0  : divmod algo; results in 0 n d_n%d n%d n/d
->[<+>-]							c5    : move dividend back to c5 and clear c6
->[-]							c7v0  : clear c7
-
->>							block : c9 can have two digits; divide it by ten again
->++++++++++						c10v10: divisor
-<							c9    : back to dividend
-[->-[>+>>]>[+[-<+>]>+>>]<<<<<]				c9v0  : another divmod algo; results in 0 d_n%d n%d n/d
->[-]							c10v0 : clear c10
->>[++++++++++++++++++++++++++++++++++++++++++++++++.[-]]c12v0 : print nonzero n/d (first digit) and clear c12
-<[++++++++++++++++++++++++++++++++++++++++++++++++.[-]] c11v0 : print nonzero n%d (second digit) and clear c11
-
-<<<++++++++++++++++++++++++++++++++++++++++++++++++.[-]	c8v0  : print any n%d (last digit) and clear c8
-<<<<<<<.>.                                              c1c2  : print comma and space
-							block : actually calculate next Fibonacci in c6
->>[>>+<<-]						c4v0  : move c4 to c6 (don't need to preserve it)
->[>+<<+>-]						c5v0  : move c5 to c6 and c4 (need to preserve it)
->[<+>-]							c6v0  : move c6 with sum to c5
-<<<-							c3    : decrement loop counter
-]
-<<++...							c1    : output three dots

assembler/src/assembler/codegen.rs

@@ -11,14 +11,10 @@ pub fn codegen(nodes: Vec<Node>) -> Result<Vec<Instruction>, AssembleError> {
     let mut instructions = vec![];
 
     for node in nodes {
-        instructions.push(
+        instructions.push(build_instruction(&node)?);
-            build_instruction(&node)
-                .unwrap_or_else(|_| panic!("Failed to build instruction: {node:?}")),
-        );
     }
 
-    println!("------------------------");
+    log("Assembly Successful ✅");
-    log("Compilation Success ✅");
 
     Ok(instructions)
 }

assembler/src/assembler/lexer.rs

@@ -7,12 +7,11 @@ use common::prelude::Register;
 pub fn lexer(mut program: String, module: u64) -> Result<Vec<Token>, AssembleError> {
     let mut tokens = Vec::new();
 
-    program = program.replace(',', "");
     let lines = program.lines();
     let mut literal = String::new();
 
     for line in lines {
-        for token in line.split_whitespace() {
+        for (i, token) in line.split_whitespace().enumerate() {
             if token.starts_with("//") {
                 break;
             }
@@ -23,7 +22,9 @@ pub fn lexer(mut program: String, module: u64) -> Result<Vec<Token>, AssembleErr
 
             if !literal.is_empty() {
                 if !token.starts_with('"') {
-                    literal.push(' ');
+                    if i > 0 {
+                        literal.push(' ');
+                    }
                     literal.push_str(token);
                 }
 
@@ -37,6 +38,11 @@ pub fn lexer(mut program: String, module: u64) -> Result<Vec<Token>, AssembleErr
                 continue;
             }
 
+            let token = token.trim_end_matches(',');
+            if token.is_empty() {
+                continue;
+            }
+
             if let Some(token) = parse_register(token)? {
                 tokens.push(token);
             } else if let Some(token) = parse_opcode(token)? {
@@ -59,6 +65,8 @@ pub fn lexer(mut program: String, module: u64) -> Result<Vec<Token>, AssembleErr
         }
     }
 
+    // println!("{:#?}", tokens);
+
     Ok(tokens)
 }
 pub fn parse_register(token: &str) -> Result<Option<Token>, AssembleError> {

assembler/src/assembler/macros.rs

@@ -1,7 +1,6 @@
 //! Macros used throughout the assembler
 
 use crate::assembler::model::{Node, Opcode, Symbol, Token};
-
 /// Parse DSA assembly code with optional formatting
 ///
 /// # Examples

assembler/src/assembler/mod.rs

@@ -9,13 +9,9 @@ use std::{
     thread,
 };
 
+pub use common::logging::log;
 use common::prelude::Instruction;
 
-// TODO: Use an actual logging or tracing library for pretty (scoped) output.
-fn log(message: &str) {
-    println!("\x1b[32mINFO:\x1b[0m {message}");
-}
-
 // Module declarations
 #[macro_use]
 pub mod macros;
@@ -138,7 +134,11 @@ fn assemble(src: &Path) -> Result<Vec<Instruction>, AssembleError> {
     create_sections(&mut nodes)?;
     resolve_symbols(&mut nodes)?;
 
+    log("Generating assembly output...");
+
     let instructions = codegen(nodes)?;
+
+    log("Compilation Successful");
     Ok(instructions)
 }
 
@@ -187,10 +187,7 @@ fn prepare_dependency(
 
     let deps = Parser::get_dependencies(&nodes, path)?;
 
-    log(&format!(
+    log(&format!("{:20} {:20}", "Expanding Pseudo-ops", filename));
-        "{:20} {:20}",
-        "Expanding PseudoInstructions", filename
-    ));
 
     // add a section instruction
     nodes.insert(
@@ -198,9 +195,9 @@ fn prepare_dependency(
         node!(None, Opcode::Segment, Token::Immediate(file_hash as u32)),
     );
 
-    for n in &nodes {
+    // for n in &nodes {
-        println!("{n}");
+    //     println!("{n}");
-    }
+    // }
 
     program.add_module(nodes);
 

assembler/src/assembler/model.rs

@@ -51,19 +51,26 @@ impl fmt::Display for Node {
             .as_ref()
             .map_or_else(String::new, |symbol| format!("{symbol}:\n"));
 
+        let args = self
+            .args()
+            .into_iter()
+            .map(|arg| arg.to_string())
+            .collect::<Vec<_>>()
+            .join(" ");
+
         write!(
             f,
-            "\x1b[93m{} \t\x1b[94m{} \x1b[37m{:?} \x1b[0m",
+            "\x1b[93m{} \t\x1b[94m{} \x1b[37m{} \x1b[0m",
             symbol,
             self.opcode(),
-            self.args()
+            args,
         )
     }
 }
 
 impl fmt::Display for Symbol {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        write!(f, "{} ( module: {})", self.name, self.module)
+        write!(f, "{} [ID:{}]", self.name, self.module)
     }
 }
 
@@ -174,6 +181,18 @@ pub enum Token {
     Opcode(Opcode),
 }
 
+impl fmt::Display for Token {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Symbol(symbol) => write!(f, "{}", symbol),
+            Self::Register(register) => write!(f, "{}", register),
+            Self::Immediate(immediate) => write!(f, "{}", immediate),
+            Self::StringLit(string_lit) => write!(f, "{}", string_lit),
+            Self::Opcode(opcode) => write!(f, "{}", opcode),
+        }
+    }
+}
+
 #[derive(Debug, PartialEq, Eq, Copy, Clone)]
 pub enum TokenType {
     Symbol,

assembler/src/assembler/parser.rs

@@ -113,11 +113,10 @@ impl Parser {
                 let dest = expect_type!(self.next()?, Register)?;
 
                 let mut offset = Token::Immediate(0);
-                if let Ok(next) = self.peek_next() {
+                if let Ok(next) = self.peek_next()
-                    if expect_type!(next, Immediate).is_ok() {
+                    && expect_type!(next, Immediate).is_ok() {
                         offset = self.next()?;
                     }
-                }
 
                 args = vec![base, dest, offset];
             }
@@ -125,11 +124,10 @@ impl Parser {
                 let base = expect_type!(self.next()?, Register)?;
                 let dest = expect_type!(self.next()?, Register, Symbol)?;
                 let mut offset = Token::Immediate(0);
-                if let Ok(next) = self.peek_next() {
+                if let Ok(next) = self.peek_next()
-                    if expect_type!(next, Immediate).is_ok() {
+                    && expect_type!(next, Immediate).is_ok() {
                         offset = self.next()?;
                     }
-                }
                 args = vec![base, dest, offset];
             }
 

assembler/src/lib.rs

@@ -13,11 +13,38 @@
 )]
 
 pub mod assembler;
-pub mod brainf;
+pub mod image_builder;
 pub mod tooling;
 mod util;
 
 pub mod prelude {
     pub use crate::assembler::CompilerEngine;
+    pub use crate::image_builder;
+    pub use crate::tooling::brainf;
     pub use crate::tooling::project;
 }
+
+use std::{fs, path::Path};
+
+use num_cpus as _;
+use threadpool as _;
+
+use crate::prelude::CompilerEngine;
+
+pub fn assemble_file(input: &str, output: &str) -> Result<(), std::io::Error> {
+    let mut engine = CompilerEngine::new();
+    engine.start_compilation(Path::new(input));
+    let result = engine.wait_for_result().unwrap();
+
+    let buffer: Vec<u8> = result
+        .iter()
+        .flat_map(|instruction| instruction.encode().to_be_bytes())
+        .collect();
+
+    if let Err(e) = fs::write(output, buffer) {
+        eprintln!("Failed to write to output file: {e}");
+        std::process::exit(1);
+    }
+
+    Ok(())
+}

assembler/src/main.rs

@@ -1,4 +1,12 @@
-use assembler::{brainf, prelude::*};
+use common as _;
+use num_cpus as _;
+use threadpool as _;
+
+use assembler::{
+    assemble_file,
+    prelude::*,
+    tooling::{brainf, project},
+};
 use std::{fs, io::Write, path::PathBuf};
 
 fn main() {
@@ -16,7 +24,7 @@ fn main() {
 
         let mut file = match fs::File::create("brainf.dsb") {
             Err(e) => {
-                eprintln!("Failed to create output file: {}", e);
+                eprintln!("Failed to create output file: {e}");
                 std::process::exit(1);
             }
             Ok(file) => file,
@@ -24,7 +32,7 @@ fn main() {
 
         for instruction in result {
             if let Err(e) = file.write(&instruction.encode().to_be_bytes()) {
-                eprintln!("Failed to write to output file: {}", e);
+                eprintln!("Failed to write to output file: {e}");
                 std::process::exit(1);
             }
         }
@@ -39,19 +47,5 @@ fn main() {
 
     let input_path = &args[2];
     let output_path = &args[4];
-    let src = PathBuf::from(input_path);
+    assemble_file(input_path, output_path).unwrap();
-
-    // Initialize the compiler engine
-    let mut compiler = CompilerEngine::new();
-    compiler.start_compilation(&src);
-
-    // Or block until done
-    let result = compiler.wait_for_result().unwrap();
-
-    for instruction in result {
-        if let Err(e) = fs::write(output_path, instruction.encode().to_be_bytes()) {
-            eprintln!("Failed to write to output file: {}", e);
-            std::process::exit(1);
-        }
-    }
 }

assembler/src/tooling/mod.rs

@@ -1 +1,2 @@
+pub mod brainf;
 pub mod project;

common/src/instructions.rs

@@ -3,13 +3,19 @@ use crate::{instructions::encode::Encode, prelude::*};
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub enum Interrupt {
     Software(u8),
+    Breakpoint,
+    HardFault,
 }
 
 pub type Address = u32;
 
 impl Interrupt {
-    const fn as_u8(self) -> u8 {
+    // someone tell clippy to stfu.
+    #[allow(clippy::must_use_candidate)]
+    pub const fn as_u8(self) -> u8 {
         match self {
+            Self::Breakpoint => 0,
+            Self::HardFault => 1,
             Self::Software(code) => code,
         }
     }
@@ -19,10 +25,11 @@ impl Interrupt {
 impl From<u8> for Interrupt {
     #[allow(unreachable_code)]
     fn from(code: u8) -> Self {
-        return Self::Software(code);
+        match code {
-        todo!("Implement this once a hardware interrupt convention is established.");
+            0 => Self::Breakpoint,
-
+            1 => Self::HardFault,
-        // Self::Software(_code)
+            _ => Self::Software(code),
+        }
     }
 }
 
@@ -73,7 +80,8 @@ pub enum Register {
 }
 
 impl Register {
-    #[must_use]
+    // this is here so clippy shuts up about the must_use tag.
+    #[allow(clippy::must_use_candidate)]
     pub fn general() -> Vec<Self> {
         vec![
             Self::Rg0,

common/src/instructions/encode.rs

@@ -54,12 +54,14 @@ impl Encode for Instruction {
             ],
             no_args: [Nop, IntReturn, Halt],
             special: [
-                Self::Interrupt(_) => todo!(),
                 Self::Data(data) => data,
+                Self::Interrupt(interrupt) => {
+                    let opcode = u32::from(self.opcode());
+                    (opcode << 26) | u32::from(interrupt.as_u8())
+                },
                 Self::Segment(segment) => {
                     let opcode = u32::from(self.opcode());
-                    let segment = segment as u8;
+                    (opcode << 26) | u32::from(segment as u8)
-                    (opcode << 26) | u32::from(segment)
                 }
             ]
         )

common/src/lib.rs

@@ -13,6 +13,7 @@
 )]
 
 pub mod instructions;
+pub mod logging;
 
 pub mod prelude {
     //! A collection of types you should definitely import when working with this crate.

common/src/logging.rs

@@ -0,0 +1,4 @@
+// TODO: Use an actual logging or tracing library for pretty (scoped) output.
+pub fn log(message: &str) {
+    println!("\x1b[32mINFO:\x1b[0m {message}");
+}

compiler/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "compiler"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+
+[dependencies]
+chrono = "0.4.43"
+common = { path = "../common" }

compiler/bacon.toml

@@ -0,0 +1,129 @@
+# This is a configuration file for the bacon tool
+#
+# Complete help on configuration: https://dystroy.org/bacon/config/
+#
+# You may check the current default at
+#   https://github.com/Canop/bacon/blob/main/defaults/default-bacon.toml
+
+default_job = "check"
+
+[jobs.check]
+command = ["cargo", "check", "--color", "always"]
+need_stdout = false
+
+[jobs.check-all]
+command = ["cargo", "check", "--all-targets", "--color", "always"]
+need_stdout = false
+
+# Run clippy on the default target
+[jobs.clippy]
+command = [
+    "cargo", "clippy",
+    "--color", "always",
+]
+need_stdout = false
+
+# Run clippy on all targets
+# To disable some lints, you may change the job this way:
+#    [jobs.clippy-all]
+#    command = [
+#        "cargo", "clippy",
+#        "--all-targets",
+#        "--color", "always",
+#    	 "--",
+#    	 "-A", "clippy::bool_to_int_with_if",
+#    	 "-A", "clippy::collapsible_if",
+#    	 "-A", "clippy::derive_partial_eq_without_eq",
+#    ]
+# need_stdout = false
+[jobs.clippy-all]
+command = [
+    "cargo", "clippy",
+    "--all-targets",
+    "--color", "always",
+]
+need_stdout = false
+
+# This job lets you run
+# - all tests: bacon test
+# - a specific test: bacon test -- config::test_default_files
+# - the tests of a package: bacon test -- -- -p config
+[jobs.test]
+command = [
+    "cargo", "test", "--color", "always",
+    "--", "--color", "always", # see https://github.com/Canop/bacon/issues/124
+]
+need_stdout = true
+
+[jobs.nextest]
+command = [
+    "cargo", "nextest", "run",
+    "--color", "always",
+    "--hide-progress-bar", "--failure-output", "final"
+]
+need_stdout = true
+analyzer = "nextest"
+
+[jobs.doc]
+command = ["cargo", "doc", "--color", "always", "--no-deps"]
+need_stdout = false
+
+# If the doc compiles, then it opens in your browser and bacon switches
+# to the previous job
+[jobs.doc-open]
+command = ["cargo", "doc", "--color", "always", "--no-deps", "--open"]
+need_stdout = false
+on_success = "back" # so that we don't open the browser at each change
+
+# You can run your application and have the result displayed in bacon,
+# if it makes sense for this crate.
+# Don't forget the `--color always` part or the errors won't be
+# properly parsed.
+[jobs.run]
+command = [
+    "cargo", "run",
+    "--color", "always",
+    "--",
+    "../resources/dsa/example.dsc",
+    "../resources/dsa/example.dsa"
+    # put launch parameters for your program behind a `--` separator
+]
+need_stdout = true
+allow_warnings = true
+background = true
+
+# Run your long-running application (eg server) and have the result displayed in bacon.
+# For programs that never stop (eg a server), `background` is set to false
+# to have the cargo run output immediately displayed instead of waiting for
+# program's end.
+# 'on_change_strategy' is set to `kill_then_restart` to have your program restart
+# on every change (an alternative would be to use the 'F5' key manually in bacon).
+# If you often use this job, it makes sense to override the 'r' key by adding
+# a binding `r = job:run-long` at the end of this file .
+[jobs.run-long]
+command = [
+    "cargo", "run",
+    "--color", "always",
+    # put launch parameters for your program behind a `--` separator
+]
+need_stdout = true
+allow_warnings = true
+background = false
+on_change_strategy = "kill_then_restart"
+
+# This parameterized job runs the example of your choice, as soon
+# as the code compiles.
+# Call it as
+#    bacon ex -- my-example
+[jobs.ex]
+command = ["cargo", "run", "--color", "always", "--example"]
+need_stdout = true
+allow_warnings = true
+
+# You may define here keybindings that would be specific to
+# a project, for example a shortcut to launch a specific job.
+# Shortcuts to internal functions (scrolling, toggling, etc.)
+# should go in your personal global prefs.toml file instead.
+[keybindings]
+# alt-m = "job:my-job"
+c = "job:clippy-all" # comment this to have 'c' run clippy on only the default target

compiler/src/backend/dsa/codegen.rs

@@ -0,0 +1,738 @@
+use std::collections::HashMap;
+use std::sync::atomic::AtomicU32;
+use std::time::SystemTime;
+
+use chrono::{DateTime, Local};
+
+use super::registers::RegisterAllocator;
+use crate::{block, comment, dsa};
+
+use crate::model::{
+    BinaryOperator, CompilerError, ConstExpr, Declaration, Dependency, Expression,
+    Program, Statement, UnaryOperator, Variable,
+};
+
+pub struct CodeGenerator {
+    ast: Program,
+    imports: HashMap<String, String>,
+    globals: Vec<String>,
+    functions: Vec<String>,
+    symbols: Vec<String>,
+    allocator: RegisterAllocator,
+}
+
+fn import(name: &str, path: &str) -> String {
+    format!("include {name}: \"{}\"", path)
+}
+
+impl CodeGenerator {
+    const RET: &'static str = "\tjmp _ret";
+
+    pub fn new(ast: Program) -> Self {
+        CodeGenerator {
+            ast,
+            imports: HashMap::new(),
+            globals: Vec::new(),
+            functions: Vec::new(),
+            symbols: Vec::new(),
+            allocator: RegisterAllocator::new(),
+        }
+    }
+
+    pub fn include(&mut self, name: &str, path: &str) {
+        self.imports.insert(name.to_string(), path.to_string());
+    }
+
+    fn is_global(&self, name: &str) -> bool {
+        // Check if this variable is in the globals list
+        self.globals
+            .iter()
+            .any(|g| g.contains(&format!("dw {}:", name)))
+    }
+
+    pub fn generate(&mut self) -> Result<String, CompilerError> {
+        // always include the print library for debugging!
+        self.include("print", "./lib/io/print.dsa");
+
+        for block in self.ast.clone().declarations {
+            match block {
+                Declaration::Variable {
+                    var: Variable { name, .. },
+                    ..
+                } => self.symbols.push(name),
+                Declaration::Function { name, .. } => self.symbols.push(name),
+                Declaration::Dependency(Dependency { name, .. }) => {
+                    self.symbols.push(name)
+                }
+            }
+        }
+
+        for block in self.ast.clone().declarations {
+            self.generate_block(block.clone())?;
+        }
+
+        self.generate_layout()
+    }
+
+    fn generate_layout(&mut self) -> Result<String, CompilerError> {
+        let datetime: DateTime<Local> = SystemTime::now().into();
+        Ok(dsa![
+            "",
+            comment!("GENERATED BY DSC COMPILER"),
+            comment!(format!(
+                "Generated at {}",
+                datetime.format("%Y-%m-%d %H:%M:%S")
+            )),
+            "",
+            // imports
+            comment!("Imports"),
+            self.imports
+                .iter()
+                .map(|(k, v)| import(k, v))
+                .collect::<Vec<String>>()
+                .join("\n"),
+            "",
+            // reserved memory
+            comment!("Globals & Reserved Memory"),
+            self.globals.join("\n"),
+            "",
+            // entry point
+            comment!("Entry Point"),
+            "dw stack: 0x10000",
+            "db message: \"Process Exited with code:\"",
+            block! [ "_init"
+                dsa![ldw stack, bpr],
+                dsa![mov bpr, spr],
+                dsa![push zero],
+                dsa![call main],
+                dsa![call print::print_newline],
+                dsa![lwi message, rg0],
+                dsa![push rg0],
+                dsa![call print::print],
+                dsa![pop zero],
+                dsa![call print::print_hex_word],
+                dsa![pop zero],
+                dsa![hlt]
+            ],
+            "",
+            comment!("Return"),
+            block! [ "_ret"
+                dsa![mov bpr, spr],
+                dsa![pop bpr],
+                dsa![return]
+            ],
+            comment!("Compiled Code Starts..."),
+            // block! [ "main"
+            //     dsa![push bpr],
+            //     dsa![mov spr, bpr],
+            //     dsa![lwi 67, rg1],
+            //     dsa![stw rg1, spr, 8],
+            //     dsa![mov bpr, spr],
+            //     dsa![pop bpr],
+            //     dsa![return]
+            // ],
+            self.functions.join("\n"),
+        ])
+    }
+
+    fn generate_global(&mut self, name: &str, init: Option<ConstExpr>) {
+        self.globals.push(format!(
+            "dw {}: {}",
+            name,
+            init.unwrap_or(ConstExpr::Number(0))
+        ))
+    }
+
+    fn generate_block(&mut self, block: Declaration) -> Result<(), CompilerError> {
+        match block {
+            Declaration::Variable { var, init, .. } => {
+                self.generate_global(&var.name, init)
+            }
+            Declaration::Function {
+                name, params, body, ..
+            } => {
+                let func = self.generate_function(&name, &params, &body).join("\n");
+
+                self.functions.push(format!("{func}\n"));
+            }
+            Declaration::Dependency(Dependency { name, path }) => {
+                self.imports.insert(name, path);
+            }
+        };
+
+        Ok(())
+    }
+
+    // Example: Generate code for a function
+    fn generate_function(
+        &mut self,
+        name: &str,
+        params: &[Variable],
+        body: &[Statement],
+    ) -> Vec<String> {
+        let mut code = Vec::new();
+
+        // Reset allocator for new function
+        self.allocator.reset();
+
+        // Function prologue
+        code.push(format!("{}:", name));
+        code.push("\tpush bpr".to_string());
+        code.push("\tmov spr, bpr".to_string());
+        code.push(String::new());
+
+        // Allocate parameters to registers or stack locations
+        for (i, param) in params.iter().enumerate() {
+            let offset = 8 + (i as i32 * 4); // Parameters start at bpr+8
+            // Track that this parameter is at a stack location
+            let (reg, load_code) = self.allocator.alloc_var(&param.name).unwrap();
+            code.extend(load_code);
+            code.push(format!("\tldw bpr, {}, {}", reg, offset));
+        }
+
+        // Generate code for function body
+        for stmt in body {
+            let stmt_code = self.generate_statement(stmt).unwrap();
+            code.extend(stmt_code);
+        }
+
+        // automatically return at function end
+        if let Some(x) = code.last()
+            && x == Self::RET
+        {
+        } else {
+            code.push(Self::RET.to_string());
+        }
+
+        code
+    }
+
+    // Example: Generate code for a statement
+    fn generate_statement(
+        &mut self,
+        stmt: &Statement,
+    ) -> Result<Vec<String>, CompilerError> {
+        let mut code = Vec::new();
+
+        match stmt {
+            Statement::Declaration { var, value } => {
+                if let Some(expr) = value {
+                    // Evaluate expression
+                    let (result_reg, expr_code) = self.generate_expression(expr, true)?;
+                    code.extend(expr_code);
+
+                    // Store result in variable
+                    let store_code = self.allocator.store_var(&var.name, &result_reg);
+                    code.extend(store_code);
+
+                    // Free temporary register
+                    self.allocator.free_temp(&result_reg);
+                } else {
+                    // Just declaring variable without initialization
+                    self.allocator.alloc_var(&var.name)?;
+                }
+            }
+
+            Statement::Break => unimplemented!(),
+            Statement::Continue => unimplemented!(),
+
+            Statement::PtrWrite { ptr, value } => {
+                let (result_reg, expr_code) = self.generate_expression(value, true)?;
+                code.extend(expr_code);
+
+                let (ptr_reg, ptr_code) = self.generate_expression(ptr, true)?;
+                code.extend(ptr_code);
+
+                code.push(format!("\tstw {}, {}", result_reg, ptr_reg));
+
+                self.allocator.free_temp(&result_reg);
+                self.allocator.free_temp(&ptr_reg);
+            }
+
+            Statement::Assign { varname, value } => {
+                // Evaluate expression
+                let (result_reg, expr_code) = self.generate_expression(value, true)?;
+                code.extend(expr_code);
+
+                // Check if this is a global variable
+                if self.is_global(varname) {
+                    // Store to global label
+                    code.push(format!("\tstw {}, {}", result_reg, varname));
+                } else {
+                    // Store result in local variable
+                    let store_code = self.allocator.store_var(varname, &result_reg);
+                    code.extend(store_code);
+                }
+
+                // Free temporary register
+                self.allocator.free_temp(&result_reg);
+            }
+
+            Statement::Return(expr) => {
+                if let Some(e) = expr {
+                    let (result_reg, expr_code) = self.generate_expression(e, true)?;
+                    code.extend(expr_code);
+                    code.push(format!("\tstw {}, bpr, 8", result_reg));
+                    code.push(format!("\tjmp _ret"));
+                    self.allocator.free_temp(&result_reg);
+                }
+            }
+
+            Statement::If {
+                condition,
+                then_stmt,
+                else_stmt,
+            } => {
+                // Generate condition
+                let (cond_reg, cond_code) = self.generate_expression(condition, true)?;
+                code.extend(cond_code);
+
+                // Compare with zero
+                code.push(format!("\tcmp {}, zero", cond_reg));
+                self.allocator.free_temp(&cond_reg);
+
+                // Generate unique labels
+                let then_label = format!("_then_{}", self.get_unique_label());
+                let else_label = format!("_else_{}", self.get_unique_label());
+                let end_label = format!("_end_{}", self.get_unique_label());
+
+                // Jump to else if condition is false (equal to zero)
+                code.push(format!("\tjeq {}", else_label));
+
+                // Then block
+                code.push(format!("{}:", then_label));
+                for s in then_stmt {
+                    code.extend(self.generate_statement(s)?);
+                }
+
+                if then_stmt.len() == 0 {
+                    code.push("\tnop".to_string());
+                }
+
+                code.push(format!("\tjmp {}", end_label));
+
+                // Else block
+                code.push(format!("{}:", else_label));
+                for s in else_stmt {
+                    code.extend(self.generate_statement(s)?);
+                }
+
+                if else_stmt.len() == 0 {
+                    code.push("\tnop".to_string());
+                }
+
+                code.push(format!("{}:", end_label));
+            }
+
+            Statement::While { condition, body } => {
+                let loop_start = format!("_while_start_{}", self.get_unique_label());
+                let loop_end = format!("_while_end_{}", self.get_unique_label());
+
+                code.push(format!("{}:", loop_start));
+
+                // Generate condition
+                let (cond_reg, cond_code) = self.generate_expression(condition, true)?;
+                code.extend(cond_code);
+
+                code.push(format!("\tcmp {}, zero", cond_reg));
+                self.allocator.free_temp(&cond_reg);
+
+                code.push(format!("\tjeq {}", loop_end));
+
+                // Loop body
+                for s in body {
+                    code.extend(self.generate_statement(s)?);
+                }
+
+                code.push(format!("\tjmp {}", loop_start));
+                code.push(format!("{}:", loop_end));
+            }
+
+            Statement::Loop(body) => {
+                let loop_start = format!("_loop_start_{}", self.get_unique_label());
+
+                code.push(format!("{}:", loop_start));
+
+                for s in body {
+                    code.extend(self.generate_statement(s)?);
+                }
+
+                code.push(format!("\tjmp {}", loop_start));
+            }
+
+            Statement::Expression { expr } => {
+                let (result_reg, expr_code) = self.generate_expression(expr, false)?;
+                code.extend(expr_code);
+                self.allocator.free_temp(&result_reg);
+            }
+
+            Statement::Block(statements) => {
+                for s in statements {
+                    code.extend(self.generate_statement(s)?);
+                }
+            }
+        }
+
+        Ok(code)
+    }
+
+    // Example: Generate code for an expression
+    // Returns (register containing result, assembly code)
+    fn generate_expression(
+        &mut self,
+        expr: &Expression,
+        use_result: bool,
+    ) -> Result<(String, Vec<String>), CompilerError> {
+        let mut code = Vec::new();
+
+        // optimisation to prevent generating dead code!
+        if expr.is_pure() && !use_result {
+            return Ok((String::new(), code));
+        }
+
+        match expr {
+            Expression::StringLiteral(value) => {
+                let (reg, alloc_code) = self.allocator.alloc_temp()?;
+                code.extend(alloc_code);
+
+                // write string into memory
+                let uuid = self.get_unique_label();
+                code.push(format!("\tdb str_{uuid}: \"{value}\""));
+
+                // Load pointer to string
+                code.push(format!("\tlwi str_{uuid}, {reg}"));
+
+                Ok((reg, code))
+            }
+
+            Expression::CharLiteral(value) => {
+                let (reg, alloc_code) = self.allocator.alloc_temp()?;
+                code.extend(alloc_code);
+
+                // Load immediate value
+                code.push(format!("\tlli {}, {} // '{value}'", *value as u8, reg));
+
+                Ok((reg, code))
+            }
+
+            Expression::Number(value) => {
+                let (reg, alloc_code) = self.allocator.alloc_temp()?;
+                code.extend(alloc_code);
+
+                // Load immediate value
+                code.push(format!("\tlli {}, {}", value & 0xFFFF, reg));
+                if *value > 0xFFFF || *value < 0 {
+                    code.push(format!("\tlui {}, {}", (value >> 16) & 0xFFFF, reg));
+                }
+
+                Ok((reg, code))
+            }
+
+            Expression::Variable { name, .. } => {
+                if self.is_global(&name.name) {
+                    // Allocate a temporary register for the global
+                    let (reg, alloc_code) = self.allocator.alloc_temp()?;
+                    code.extend(alloc_code);
+
+                    // Load from global label
+                    code.push(format!("\tldw {}, {}", name.name, reg));
+
+                    Ok((reg, code))
+                } else {
+                    // Local variable - use existing allocator logic
+                    let (reg, load_code) = self.allocator.load_var(&name.name)?;
+                    code.extend(load_code);
+                    Ok((reg, code))
+                }
+            }
+
+            Expression::Binary { op, left, right } => {
+                // Evaluate left operand
+                let (left_reg, left_code) = self.generate_expression(left, true)?;
+                code.extend(left_code);
+
+                // Evaluate right operand
+                let (right_reg, right_code) = self.generate_expression(right, true)?;
+                code.extend(right_code);
+
+                // Allocate result register
+                let (result_reg, result_alloc) = self.allocator.alloc_temp()?;
+                code.extend(result_alloc);
+
+                // Generate operation
+                match op {
+                    BinaryOperator::Add => {
+                        code.push(format!(
+                            "\tadd {}, {}, {}",
+                            left_reg, right_reg, result_reg
+                        ));
+                    }
+                    BinaryOperator::Sub => {
+                        code.push(format!(
+                            "\tsub {}, {}, {}",
+                            left_reg, right_reg, result_reg
+                        ));
+                    }
+                    BinaryOperator::Mul => {
+                        self.include("maths", "./lib/maths/core.dsa");
+                        // Call multiply function
+                        code.push(format!("\tpush {}", right_reg));
+                        code.push(format!("\tpush {}", left_reg));
+                        code.push("\tcall maths::multiply".to_string());
+                        code.push(format!("\tpop {}", result_reg));
+                        code.push("\tpop zero".to_string());
+                    }
+                    // Comparison operators - return 1 (true) or 0 (false)
+                    BinaryOperator::Eq => {
+                        code.push(format!("\tcmp {}, {}", left_reg, right_reg));
+                        code.push(format!("\tlli 0, {}", result_reg));
+                        let end_label = format!("_cmp_end_{}", self.get_unique_label());
+                        code.push(format!("\tjne {}", end_label)); // If not equal, skip setting to 1
+                        code.push(format!("\tlli 1, {}", result_reg));
+                        code.push(format!("{}:", end_label));
+                    }
+                    BinaryOperator::Ne => {
+                        code.push(format!("\tcmp {}, {}", left_reg, right_reg));
+                        code.push(format!("\tlli 0, {}", result_reg));
+                        let end_label = format!("_cmp_end_{}", self.get_unique_label());
+                        code.push(format!("\tjeq {}", end_label)); // If equal, skip setting to 1
+                        code.push(format!("\tlli 1, {}", result_reg));
+                        code.push(format!("{}:", end_label));
+                    }
+                    BinaryOperator::Lt => {
+                        code.push(format!("\tcmp {}, {}", left_reg, right_reg));
+                        code.push(format!("\tlli 0, {}", result_reg));
+                        let end_label = format!("_cmp_end_{}", self.get_unique_label());
+                        code.push(format!("\tjge {}", end_label)); // If greater or equal, skip setting to 1
+                        code.push(format!("\tlli 1, {}", result_reg));
+                        code.push(format!("{}:", end_label));
+                    }
+                    BinaryOperator::Le => {
+                        code.push(format!("\tcmp {}, {}", left_reg, right_reg));
+                        code.push(format!("\tlli 0, {}", result_reg));
+                        let end_label = format!("_cmp_end_{}", self.get_unique_label());
+                        code.push(format!("\tjgt {}", end_label)); // If greater than, skip setting to 1
+                        code.push(format!("\tlli 1, {}", result_reg));
+                        code.push(format!("{}:", end_label));
+                    }
+                    BinaryOperator::Gt => {
+                        code.push(format!("\tcmp {}, {}", left_reg, right_reg));
+                        code.push(format!("\tlli 0, {}", result_reg));
+                        let end_label = format!("_cmp_end_{}", self.get_unique_label());
+                        code.push(format!("\tjle {}", end_label)); // If less or equal, skip setting to 1
+                        code.push(format!("\tlli 1, {}", result_reg));
+                        code.push(format!("{}:", end_label));
+                    }
+                    BinaryOperator::Ge => {
+                        code.push(format!("\tcmp {}, {}", left_reg, right_reg));
+                        code.push(format!("\tlli 0, {}", result_reg));
+                        let end_label = format!("_cmp_end_{}", self.get_unique_label());
+                        code.push(format!("\tjlt {}", end_label)); // If less than, skip setting to 1
+                        code.push(format!("\tlli 1, {}", result_reg));
+                        code.push(format!("{}:", end_label));
+                    }
+                    _ => unimplemented!(),
+                }
+
+                // Free operand registers (allocator will protect variables)
+                self.allocator.free_temp(&left_reg);
+                self.allocator.free_temp(&right_reg);
+
+                Ok((result_reg, code))
+            }
+
+            Expression::Call { name, args } => {
+                // first evaluate all the args we're going to need
+                let mut arg_regs = Vec::new();
+                for arg in args.iter().rev() {
+                    let (arg_reg, arg_code) = self.generate_expression(arg, true)?;
+                    code.extend(arg_code);
+                    arg_regs.push(arg_reg);
+                }
+
+                // Save caller-saved registers and track which ones we saved
+                // old method, inefficient.
+                // let saved_regs = self.allocator.get_caller_saved_registers();
+                // for reg in &saved_regs {
+                //     code.push(format!("\tpush {}", reg));
+                // }
+
+                // Save caller-saved registers and track which ones we saved
+                let saved_regs = self.allocator.get_caller_saved_registers();
+                for reg in &saved_regs {
+                    // spill variables to stack
+                    code.extend(self.allocator.spill_register(reg).unwrap());
+                }
+
+                // Evaluate and push arguments in reverse order
+                for (i, arg_reg) in arg_regs.iter().enumerate() {
+                    code.push(format!(
+                        "\tpush {} // push arg {}",
+                        arg_reg,
+                        args.len() - 1 - i
+                    ));
+                }
+
+                // if GLOBAL_METHODS.contains_key(name.name.as_str()) {
+                //     code.push(format!("\tcall {}",
+                // GLOBAL_METHODS[name.name.as_str()])); } else
+                if self.symbols.contains(&name.name) {
+                    // Call local function
+                    code.push(format!("\tcall {}", name));
+                } else if let Some(ns) = name.namespace.clone()
+                    && self.imports.contains_key(&ns)
+                {
+                    code.push(format!("\tcall {}", name));
+                } else {
+                    return Err(CompilerError::Undefined(name.clone()));
+                }
+
+                let result_reg: String;
+
+                if use_result {
+                    let (temp_result_reg, result_alloc) = self.allocator.alloc_temp()?;
+                    result_reg = temp_result_reg;
+
+                    code.extend(result_alloc);
+                    code.push(format!("\tpop {}", result_reg));
+
+                    // Clean up arguments
+                    if args.len() > 1 {
+                        for _ in 0..(args.len() - 1) {
+                            code.push("\tpop zero".to_string());
+                        }
+                    }
+                } else {
+                    result_reg = "zero".to_string();
+
+                    // Clean up arguments
+                    if args.len() > 0 {
+                        for _ in 0..(args.len()) {
+                            code.push("\tpop zero".to_string());
+                        }
+                    }
+                }
+
+                // Restore caller-saved registers in reverse order (LIFO)
+                // for reg in saved_regs.iter().rev() {
+                //     code.push(format!("\tpop {}", reg));
+                // }
+
+                // Free argument registers
+                for reg in arg_regs {
+                    self.allocator.free_temp(&reg);
+                }
+
+                Ok((result_reg, code))
+            }
+
+            Expression::Unary { op, operand } => {
+                let (operand_reg, operand_code) =
+                    self.generate_expression(operand, true)?;
+                code.extend(operand_code);
+
+                let (result_reg, result_alloc) = self.allocator.alloc_temp()?;
+                code.extend(result_alloc);
+
+                match op {
+                    UnaryOperator::Minus => {
+                        // Negate: result = 0 - operand
+                        code.push(format!("\tsub zero, {}, {}", operand_reg, result_reg));
+                    }
+                    UnaryOperator::Plus => {
+                        // Just move
+                        code.push(format!("\tmov {}, {}", operand_reg, result_reg));
+                    }
+                    UnaryOperator::Dereference => {
+                        code.push(format!("\tldw {}, {}", operand_reg, result_reg));
+                    }
+                    UnaryOperator::Reference => {
+                        code.extend(self.allocator.spill_register(&operand_reg)?);
+                        code.push(format!(
+                            "\tsubi bpr {} {}",
+                            -(4 + self.allocator.get_stack_offset()),
+                            result_reg
+                        ))
+                    }
+                }
+
+                self.allocator.free_temp(&operand_reg);
+                Ok((result_reg, code))
+            }
+
+            Expression::Empty => Ok(("zero".to_string(), code)),
+        }
+    }
+
+    // Helper for generating unique labels
+    fn get_unique_label(&mut self) -> String {
+        // You'd implement a counter here
+        static COUNTER: AtomicU32 = AtomicU32::new(0);
+
+        let val = COUNTER.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+        (val + 1).to_string()
+    }
+}
+
+/// Build a single string from any number of arguments.
+/// Each argument must implement `Display` or be convertible to a string.
+#[macro_export]
+macro_rules! dsa {
+    ($($arg:expr),* $(,)?) => {{
+        // Start with an empty String – we’ll grow it as we go.
+        use std::fmt::Write;
+        let mut s = ::std::string::String::new();
+        $(
+            // `write!` is cheaper than `format!` for each element
+            // because it re‑uses the same buffer.
+
+            write!(s, "{}\n", $arg).expect("write to String failed");
+        )*
+        s
+    }};
+}
+
+// ────────────────────────  dsa!  ────────────────────────
+// A tiny helper that just turns its token‑stream into a string.
+// The trailing comma is kept – it’s part of the syntax you want.
+#[macro_export]
+macro_rules! cmd {
+    ($($tokens:tt)*) => {{
+        // We’ll just stringify the tokens and return a String.
+        format!("{}", concat!(stringify!($tokens), "\n"))
+    }};
+}
+
+// ────────────────────────  block!  ────────────────────────
+// Usage:
+//
+//   let asm = block![ "name"
+//       dsa![mov rg0, rg1],
+//       dsa![add rg1, rg1]
+//   ];
+//
+// `asm` is a `&'static str` containing:
+//
+//   name:
+//       mov rg0, rg1
+//       add rg1, rg1
+//
+#[macro_export]
+macro_rules! block {
+    // The first token must be a string literal – that’s the label.
+    ($label:literal $(dsa![$($ins:tt)*]),* ) => {{
+        // Build a single string at compile time.
+        const CODE: &str = concat!(
+            $label, ":\n",
+            // Each `dsa!` call yields a string like `"mov rg0, rg1"`.
+            // We add a newline after each one to get the desired layout.
+            $(concat!("\t", stringify!($($ins)*), "\n")),*
+        );
+        CODE
+    }};
+}
+
+#[macro_export]
+macro_rules! comment {
+    ($text:expr) => {{ format!("// {}", $text) }};
+}

compiler/src/backend/dsa/mod.rs

@@ -0,0 +1,9 @@
+use crate::model::{CompilerError, Program};
+
+mod codegen;
+mod registers;
+
+pub fn generate_code(ast: &Program) -> Result<String, CompilerError> {
+    let mut codegen = codegen::CodeGenerator::new(ast.clone());
+    codegen.generate()
+}

compiler/src/backend/dsa/registers.rs

@@ -0,0 +1,348 @@
+use std::collections::HashMap;
+
+use crate::model::CompilerError;
+
+/// Register allocator for DSA assembly generation
+/// Manages general-purpose registers (rg0-rgf) and handles stack spilling
+pub struct RegisterAllocator {
+    /// Available general-purpose registers
+    available_registers: Vec<String>,
+
+    /// Maps variable names to their current location (register or stack offset)
+    variable_locations: HashMap<String, Location>,
+
+    /// Maps registers to the variables they currently hold
+    register_contents: HashMap<String, String>,
+
+    /// Current stack offset for local variables (relative to bpr)
+    /// Starts at -4 (going downward from base pointer)
+    stack_offset: i32,
+
+    /// Track which registers are currently in use
+    in_use: HashMap<String, bool>,
+}
+
+#[derive(Debug, Clone)]
+pub enum Location {
+    Register(String),
+    Stack(i32), // offset from bpr
+}
+
+impl RegisterAllocator {
+    pub fn new() -> Self {
+        // Initialize with available GP registers (rg0-rgf = 16 registers)
+        let registers = vec![
+            "rg0", "rg1", "rg2", "rg3", "rg4", "rg5", "rg6", "rg7", "rg8", "rg9", "rga",
+            "rgb", "rgc", "rgd", "rge", "rgf",
+        ]
+        .into_iter()
+        .map(String::from)
+        .collect();
+
+        RegisterAllocator {
+            available_registers: registers,
+            variable_locations: HashMap::new(),
+            register_contents: HashMap::new(),
+            stack_offset: -4, // Start at -4 (first local below saved bpr)
+            in_use: HashMap::new(),
+        }
+    }
+
+    /// Allocate a temporary register for expression evaluation
+    /// Returns the register name and optionally assembly code to save it
+    pub fn alloc_temp(&mut self) -> Result<(String, Vec<String>), CompilerError> {
+        let mut code = Vec::new();
+
+        // Try to find an unused register
+        for reg in &self.available_registers {
+            if !self.in_use.get(reg).unwrap_or(&false) {
+                self.in_use.insert(reg.clone(), true);
+                return Ok((reg.clone(), code));
+            }
+        }
+
+        // All registers in use - need to spill one
+        // Choose the first register with a variable we can spill
+        // Find a register to spill
+        let reg_to_spill = self
+            .available_registers
+            .iter()
+            .find(|reg| self.register_contents.contains_key(*reg))
+            .cloned();
+
+        if let Some(reg) = reg_to_spill {
+            // Spill this variable to stack
+            let spill_code = self.spill_register(&reg)?;
+            code.extend(spill_code);
+
+            self.in_use.insert(reg.clone(), true);
+            return Ok((reg, code));
+        }
+
+        Err(CompilerError::Generic(
+            "All registers are used up yet there are no variables to spill to the stack"
+                .to_string(),
+        ))
+    }
+
+    /// Free a temporary register after use
+    /// NOTE: This will NOT free registers that contain variables!
+    /// Variables persist throughout their scope and must not be freed
+    pub fn free_temp(&mut self, reg: &str) {
+        // Check if this register contains a variable
+        if self.register_contents.contains_key(reg) {
+            // This register holds a variable - don't free it!
+            // Variables are only freed when they go out of scope via free_var()
+            return;
+        }
+
+        // This is a true temporary - safe to free
+        self.in_use.insert(reg.to_string(), false);
+    }
+
+    /// Allocate a register for a named variable
+    /// Returns the register and any necessary assembly code
+    pub fn alloc_var(
+        &mut self,
+        var_name: &str,
+    ) -> Result<(String, Vec<String>), CompilerError> {
+        if let Some(location) = self.variable_locations.get(var_name).cloned() {
+            match location {
+                Location::Register(reg) => {
+                    return Ok((reg.clone(), Vec::new()));
+                }
+                Location::Stack(offset) => {
+                    // Variable was pushed, need to calculate actual position
+                    let (reg, mut code) = self.alloc_temp()?;
+
+                    // Load from bpr + offset (offset is negative)
+                    code.push(format!("\tsubi bpr {} {}", -(offset + 4), reg));
+                    code.push(format!(
+                        "\tldw {}, {} // bpr{}: {}",
+                        reg,
+                        reg,
+                        offset - 4,
+                        var_name
+                    ));
+
+                    // Update location to register
+                    self.variable_locations
+                        .insert(var_name.to_string(), Location::Register(reg.clone()));
+                    self.register_contents
+                        .insert(reg.clone(), var_name.to_string());
+
+                    return Ok((reg, code));
+                }
+            }
+        }
+
+        // Variable doesn't have a location yet, allocate a new register
+        let (reg, code) = self.alloc_temp()?;
+        self.variable_locations
+            .insert(var_name.to_string(), Location::Register(reg.clone()));
+        self.register_contents
+            .insert(reg.clone(), var_name.to_string());
+
+        Ok((reg, code))
+    }
+
+    /// Get the current location of a variable
+    pub fn _get_var_location(&self, var_name: &str) -> Option<&Location> {
+        self.variable_locations.get(var_name)
+    }
+
+    /// Load a variable into a register (allocating if necessary)
+    /// Returns the register and assembly code to load it
+    pub fn load_var(
+        &mut self,
+        var_name: &str,
+    ) -> Result<(String, Vec<String>), CompilerError> {
+        self.alloc_var(var_name)
+    }
+
+    /// Store a value from a register into a variable
+    /// Updates tracking and returns any necessary assembly code
+    pub fn store_var(&mut self, var_name: &str, source_reg: &str) -> Vec<String> {
+        let mut code = Vec::new();
+
+        // Check if variable already has a location
+        if let Some(location) = self.variable_locations.get(var_name) {
+            match location {
+                Location::Register(dest_reg) => {
+                    if dest_reg != source_reg {
+                        code.push(format!(
+                            "\tmov {}, {} // var {}",
+                            source_reg, dest_reg, var_name
+                        ));
+                    }
+                }
+                Location::Stack(offset) => {
+                    code.push(format!(
+                        "\tstw {}, bpr, {} // var {}",
+                        source_reg, offset, var_name
+                    ));
+                }
+            }
+        } else {
+            // Variable doesn't exist yet, we can just use the same reg.
+
+            // self.variable_locations.insert(
+            //     var_name.to_string(),
+            //     Location::Register(source_reg.to_string()),
+            // );
+            // self.register_contents
+            //     .insert(source_reg.to_string(), var_name.to_string());
+            // self.in_use.insert(source_reg.to_string(), true);
+
+            let source_reg = source_reg.to_string();
+
+            // if we can avoid a move, absolutely do that.
+            if self.available_registers.contains(&source_reg) {
+                self.variable_locations
+                    .insert(var_name.to_string(), Location::Register(source_reg.clone()));
+                self.register_contents
+                    .insert(source_reg.clone(), var_name.to_string());
+                self.in_use.insert(source_reg, true);
+            } else if let Some(free_reg) = self.find_free_register() {
+                code.push(format!("\tmov {}, {}", source_reg, free_reg));
+                self.variable_locations
+                    .insert(var_name.to_string(), Location::Register(free_reg.clone()));
+                self.register_contents
+                    .insert(free_reg.clone(), var_name.to_string());
+                self.in_use.insert(free_reg, true);
+            } else {
+                // No free registers - allocate on stack
+                // code.push(format!("\tstw {}, bpr, {}", source_reg, self.stack_offset));
+                // self.variable_locations
+                //     .insert(var_name.to_string(), Location::Stack(self.stack_offset));
+                // self.stack_offset -= 4; // Move to next stack slot
+                //
+                todo!(
+                    "we should spill other registers and keep this variable on the stack as it's more recent!"
+                );
+            }
+        }
+
+        code
+    }
+
+    /// Spill a register to the stack
+    /// Returns assembly code to perform the spill
+    pub fn spill_register(&mut self, reg: &str) -> Result<Vec<String>, CompilerError> {
+        let mut code = Vec::new();
+
+        if let Some(var_name) = self.register_contents.get(reg).cloned() {
+            // PUSH register to stack (spr decrements automatically)
+            code.push(format!(
+                "\tpush {} // bpr{}: {}",
+                reg, self.stack_offset, var_name
+            ));
+
+            // Track that we pushed one word
+            self.stack_offset -= 4;
+
+            // Update variable location - it's now at current spr
+            // Note: We track offset from bpr for consistency
+            self.variable_locations
+                .insert(var_name.clone(), Location::Stack(self.stack_offset));
+
+            // Remove from register tracking
+            self.register_contents.remove(reg);
+        }
+
+        Ok(code)
+    }
+
+    /// Find a free register (not currently in use)
+    fn find_free_register(&self) -> Option<String> {
+        for reg in &self.available_registers {
+            if !self.in_use.get(reg).unwrap_or(&false) {
+                return Some(reg.clone());
+            }
+        }
+        None
+    }
+
+    /// Spill all registers to stack (useful before function calls)
+    pub fn _spill_all(&mut self) -> Vec<String> {
+        let mut code = Vec::new();
+
+        let regs_to_spill: Vec<String> = self.register_contents.keys().cloned().collect();
+
+        for reg in regs_to_spill {
+            if let Ok(spill_code) = self.spill_register(&reg) {
+                code.extend(spill_code);
+            }
+        }
+
+        code
+    }
+
+    /// Get the total stack offset
+    pub fn get_stack_offset(&self) -> i32 {
+        self.stack_offset
+    }
+
+    /// Get the total stack space needed for local variables
+    pub fn _get_stack_size(&self) -> i32 {
+        -self.stack_offset // Convert negative offset to positive size
+    }
+
+    /// Reset allocator for a new function
+    pub fn reset(&mut self) {
+        self.variable_locations.clear();
+        self.register_contents.clear();
+        self.stack_offset = -4;
+        self.in_use.clear();
+    }
+
+    /// Mark a variable as dead (no longer needed)
+    /// Frees its register if it's in one
+    pub fn _free_var(&mut self, var_name: &str) {
+        if let Some(Location::Register(reg)) = self.variable_locations.get(var_name) {
+            let reg = reg.clone();
+            self.register_contents.remove(&reg);
+            self.in_use.insert(reg, false);
+        }
+        self.variable_locations.remove(var_name);
+    }
+
+    /// Get list of registers that contain variables and are in use
+    /// These need to be saved before function calls
+    pub fn get_caller_saved_registers(&self) -> Vec<String> {
+        self.register_contents
+            .iter()
+            .filter(|(reg, _)| *self.in_use.get(*reg).unwrap_or(&false))
+            .map(|(reg, _)| reg.clone())
+            .collect()
+    }
+
+    /// Save caller-saved registers before a function call
+    /// Returns assembly code to save them
+    pub fn _save_caller_saved(&mut self) -> Vec<String> {
+        let mut code = Vec::new();
+
+        // For simplicity, save all currently used registers
+        // In a more sophisticated compiler, you'd only save registers that are live
+        for (reg, _) in self.register_contents.clone() {
+            if *self.in_use.get(&reg).unwrap_or(&false) {
+                code.push(format!("\tpush {}", reg));
+            }
+        }
+
+        code
+    }
+
+    /// Restore caller-saved registers after a function call
+    /// Returns assembly code to restore them
+    pub fn _restore_caller_saved(&mut self, saved_regs: &[String]) -> Vec<String> {
+        let mut code = Vec::new();
+
+        // Restore in reverse order (LIFO)
+        for reg in saved_regs.iter().rev() {
+            code.push(format!("\tpop {}", reg));
+        }
+
+        code
+    }
+}

compiler/src/backend/mod.rs

@@ -0,0 +1,13 @@
+use crate::model::{CompilerError, Program};
+
+mod dsa;
+
+pub fn compiler_backend(ext: &str, ast: &Program) -> Result<String, CompilerError> {
+    match ext {
+        "dsa" => Ok(dsa::generate_code(ast)?),
+        _ => Err(CompilerError::Generic(format!(
+            "File type {} not supported",
+            ext
+        ))),
+    }
+}

compiler/src/frontend/c/lexer.rs

@@ -0,0 +1,336 @@
+// ============================================================================
+// Token Types
+// ============================================================================
+
+#[derive(Debug, Clone, PartialEq)]
+pub enum TokenType {
+    // Keywords
+    Int,
+    If,
+    Else,
+    While,
+    Return,
+    Include,
+
+    // Identifiers and literals
+    Identifier(String),
+    Number(i32),
+    String(String),
+    Char(char),
+
+    // Operators
+    Plus,
+    Minus,
+    Star,
+    Slash,
+    Assign,
+    Eq,
+    Ne,
+    Lt,
+    Gt,
+    Le,
+    Ge,
+
+    // Delimiters
+    LParen,
+    RParen,
+    LBrace,
+    RBrace,
+    Semicolon,
+    Comma,
+    Colon,
+    Namespace,
+
+    Eof,
+}
+
+#[allow(unused)]
+pub enum Type {
+    Int32,
+    Int16,
+    Int8,
+    Uint32,
+    Uint16,
+    Uint8,
+    Char,
+}
+
+#[derive(Debug, Clone)]
+pub struct Token {
+    pub token_type: TokenType,
+    pub line: usize,
+    pub col: usize,
+}
+
+impl Token {
+    pub fn new(token_type: TokenType, line: usize, col: usize) -> Self {
+        Self {
+            token_type,
+            line,
+            col,
+        }
+    }
+}
+
+// ============================================================================
+// Lexer
+// ============================================================================
+
+pub struct Lexer {
+    source: Vec<char>,
+    pos: usize,
+    line: usize,
+    col: usize,
+}
+
+impl Lexer {
+    pub fn new(source: &str) -> Self {
+        Self {
+            source: source.chars().collect(),
+            pos: 0,
+            line: 1,
+            col: 1,
+        }
+    }
+
+    fn error(&self, msg: &str) -> String {
+        format!(
+            "Lexer error at line {}, col {}: {}",
+            self.line, self.col, msg
+        )
+    }
+
+    fn peek(&self, offset: usize) -> Option<char> {
+        self.source.get(self.pos + offset).copied()
+    }
+
+    fn advance(&mut self) -> Option<char> {
+        if self.pos >= self.source.len() {
+            return None;
+        }
+        let ch = self.source[self.pos];
+        self.pos += 1;
+        if ch == '\n' {
+            self.line += 1;
+            self.col = 1;
+        } else {
+            self.col += 1;
+        }
+        Some(ch)
+    }
+
+    fn skip_whitespace(&mut self) {
+        while let Some(ch) = self.peek(0) {
+            if ch.is_whitespace() {
+                self.advance();
+            } else {
+                break;
+            }
+        }
+    }
+
+    fn skip_comment(&mut self) {
+        if self.peek(0) == Some('/') && self.peek(1) == Some('/') {
+            while let Some(ch) = self.peek(0) {
+                if ch == '\n' {
+                    break;
+                }
+                self.advance();
+            }
+        }
+    }
+
+    fn read_number(&mut self) -> i32 {
+        let mut num_str = String::new();
+        while let Some(ch) = self.peek(0) {
+            if ch.is_ascii_digit() {
+                num_str.push(ch);
+                self.advance();
+            } else {
+                break;
+            }
+        }
+        num_str.parse().unwrap_or(0)
+    }
+
+    fn read_identifier(&mut self) -> String {
+        let mut ident = String::new();
+        while let Some(ch) = self.peek(0) {
+            if ch.is_alphanumeric() || ch == '_' {
+                ident.push(ch);
+                self.advance();
+            } else {
+                break;
+            }
+        }
+        ident
+    }
+
+    fn read_string(&mut self) -> Result<String, String> {
+        let mut string = String::new();
+        self.advance(); // Consume the opening quote
+
+        while let Some(ch) = self.peek(0) {
+            if ch == '"' {
+                self.advance(); // Consume the closing quote
+                return Ok(string);
+            } else if ch == '\\' {
+                self.advance(); // Consume the backslash
+                if let Some(escaped_char) = self.peek(0) {
+                    string.push(escaped_char);
+                    self.advance();
+                }
+            } else {
+                string.push(ch);
+                self.advance();
+            }
+        }
+
+        Err(String::from("Unexpected EOF"))
+    }
+
+    fn read_char(&mut self) -> Result<char, String> {
+        self.advance(); // Consume the opening quote
+
+        if let Some(ch) = self.peek(0) {
+            self.advance();
+            if self.peek(0) == Some('\'') {
+                self.advance();
+                return Ok(ch);
+            } else {
+                Err(String::from("expected closing quote"))
+            }
+        } else {
+            Err(String::from("expected character"))
+        }
+    }
+
+    pub fn tokenize(&mut self) -> Result<Vec<Token>, String> {
+        let mut tokens = Vec::new();
+
+        loop {
+            self.skip_whitespace();
+            self.skip_comment();
+
+            if self.pos >= self.source.len() {
+                break;
+            }
+
+            let line = self.line;
+            let col = self.col;
+            let ch = self.peek(0).unwrap();
+
+            let token_type = if ch.is_ascii_digit() {
+                let num = self.read_number();
+                TokenType::Number(num)
+            } else if ch == '"' {
+                let string = self.read_string()?;
+                TokenType::String(string)
+            } else if ch == '\'' {
+                let char = self.read_char()?;
+                TokenType::Char(char)
+            } else if ch.is_alphabetic() || ch == '_' {
+                let ident = self.read_identifier();
+                match ident.as_str() {
+                    "int" => TokenType::Int,
+                    "if" => TokenType::If,
+                    "else" => TokenType::Else,
+                    "while" => TokenType::While,
+                    "return" => TokenType::Return,
+                    "include" => TokenType::Include,
+                    _ => TokenType::Identifier(ident),
+                }
+            } else {
+                match ch {
+                    ':' if self.peek(1) == Some(':') => {
+                        self.advance();
+                        self.advance();
+                        TokenType::Namespace
+                    }
+                    ':' => {
+                        self.advance();
+                        TokenType::Colon
+                    }
+                    '=' if self.peek(1) == Some('=') => {
+                        self.advance();
+                        self.advance();
+                        TokenType::Eq
+                    }
+                    '!' if self.peek(1) == Some('=') => {
+                        self.advance();
+                        self.advance();
+                        TokenType::Ne
+                    }
+                    '<' if self.peek(1) == Some('=') => {
+                        self.advance();
+                        self.advance();
+                        TokenType::Le
+                    }
+                    '>' if self.peek(1) == Some('=') => {
+                        self.advance();
+                        self.advance();
+                        TokenType::Ge
+                    }
+                    '+' => {
+                        self.advance();
+                        TokenType::Plus
+                    }
+                    '-' => {
+                        self.advance();
+                        TokenType::Minus
+                    }
+                    '*' => {
+                        self.advance();
+                        TokenType::Star
+                    }
+                    '/' => {
+                        self.advance();
+                        TokenType::Slash
+                    }
+                    '=' => {
+                        self.advance();
+                        TokenType::Assign
+                    }
+                    '<' => {
+                        self.advance();
+                        TokenType::Lt
+                    }
+                    '>' => {
+                        self.advance();
+                        TokenType::Gt
+                    }
+                    '(' => {
+                        self.advance();
+                        TokenType::LParen
+                    }
+                    ')' => {
+                        self.advance();
+                        TokenType::RParen
+                    }
+                    '{' => {
+                        self.advance();
+                        TokenType::LBrace
+                    }
+                    '}' => {
+                        self.advance();
+                        TokenType::RBrace
+                    }
+                    ';' => {
+                        self.advance();
+                        TokenType::Semicolon
+                    }
+                    ',' => {
+                        self.advance();
+                        TokenType::Comma
+                    }
+                    _ => return Err(self.error(&format!("Unexpected character: {}", ch))),
+                }
+            };
+
+            tokens.push(Token::new(token_type, line, col));
+        }
+
+        tokens.push(Token::new(TokenType::Eof, self.line, self.col));
+        Ok(tokens)
+    }
+}

compiler/src/frontend/c/mod.rs

@@ -0,0 +1,25 @@
+use common::logging::log;
+
+use crate::model::{CompilerError, Program};
+use parser::Parser;
+
+pub mod lexer;
+pub mod parser;
+
+pub fn generate_ast(input: &str) -> Result<Program, CompilerError> {
+    log("Tokenising Input...");
+
+    let mut lexer = lexer::Lexer::new(&input);
+    let tokens = lexer.tokenize().map_err(|e| CompilerError::Generic(e))?;
+    // println!("{tokens:?}");
+
+    log(&format!("Parsing {} Tokens...", tokens.len()));
+
+    let mut parser = Parser::new(tokens);
+    let ast = match parser.parse() {
+        Ok(ast) => ast,
+        Err(e) => return Err(CompilerError::Generic(e)),
+    };
+
+    Ok(ast)
+}

compiler/src/frontend/c/parser.rs

@@ -0,0 +1,471 @@
+// ============================================================================
+// AST Node Types
+// ============================================================================
+
+use crate::model::{
+    BinaryOperator, Block, ConstExpr, Declaration, Dependency, Expression, Name, Program,
+    Statement, TypeId, UnaryOperator, Variable,
+};
+
+use super::lexer::{Token, TokenType};
+
+// ============================================================================
+// Parser
+// ============================================================================
+
+pub struct Parser {
+    tokens: Vec<Token>,
+    pos: usize,
+}
+
+impl Parser {
+    pub fn new(tokens: Vec<Token>) -> Self {
+        Self { tokens, pos: 0 }
+    }
+
+    fn error(&self, msg: &str) -> String {
+        let token = self.current();
+        format!(
+            "Parser error at line {}, col {}: {}",
+            token.line, token.col, msg
+        )
+    }
+
+    fn current(&self) -> &Token {
+        self.tokens
+            .get(self.pos)
+            .unwrap_or_else(|| self.tokens.last().unwrap())
+    }
+
+    fn peek(&self, offset: usize) -> &Token {
+        self.tokens
+            .get(self.pos + offset)
+            .unwrap_or_else(|| self.tokens.last().unwrap())
+    }
+
+    fn advance(&mut self) -> &Token {
+        if self.pos < self.tokens.len() - 1 {
+            self.pos += 1;
+        }
+        self.current()
+    }
+
+    fn expect(&mut self, expected: TokenType) -> Result<Token, String> {
+        let token = self.current().clone();
+        if std::mem::discriminant(&token.token_type) != std::mem::discriminant(&expected)
+        {
+            return Err(self.error(&format!(
+                "Expected {:?}, got {:?}",
+                expected, token.token_type
+            )));
+        }
+        self.advance();
+        Ok(token)
+    }
+
+    pub fn parse(&mut self) -> Result<Program, String> {
+        let mut declarations = Vec::new();
+
+        while !matches!(self.current().token_type, TokenType::Eof) {
+            declarations.push(self.parse_declaration()?);
+        }
+
+        Ok(Program { declarations })
+    }
+
+    fn parse_declaration(&mut self) -> Result<Declaration, String> {
+        // check for an import
+        if let TokenType::Include = self.current().token_type {
+            self.advance();
+
+            let name =
+                if let TokenType::Identifier(id) = self.current().clone().token_type {
+                    Some(id)
+                } else {
+                    None
+                }
+                .ok_or(String::from("Expected identifier"))?;
+
+            self.advance();
+            self.expect(TokenType::Colon)?;
+
+            let path = if let TokenType::String(id) = self.current().clone().token_type {
+                Some(id)
+            } else {
+                None
+            }
+            .ok_or(String::from("Expected string literal"))?;
+
+            self.advance();
+            return Ok(Declaration::Dependency(Dependency { name, path }));
+        }
+
+        self.expect(TokenType::Int)?;
+
+        let name = match &self.current().token_type {
+            TokenType::Identifier(s) => s.clone(),
+            _ => return Err(self.error("Expected identifier")),
+        };
+        self.advance();
+
+        match &self.current().token_type {
+            TokenType::LParen => {
+                // Function declaration
+                self.advance();
+                let mut params = Vec::<Variable>::new();
+
+                if !matches!(self.current().token_type, TokenType::RParen) {
+                    self.expect(TokenType::Int)?;
+
+                    match &self.current().token_type {
+                        TokenType::Identifier(s) => {
+                            params.push(Variable {
+                                name: s.clone(),
+                                type_id: TypeId::U32,
+                            });
+                            self.advance();
+                        }
+                        _ => return Err(self.error("Expected parameter name")),
+                    }
+
+                    while matches!(self.current().token_type, TokenType::Comma) {
+                        self.advance();
+                        self.expect(TokenType::Int)?;
+
+                        match &self.current().token_type {
+                            TokenType::Identifier(s) => {
+                                params.push(Variable {
+                                    name: s.clone(),
+                                    type_id: TypeId::U32,
+                                });
+                                self.advance();
+                            }
+                            _ => return Err(self.error("Expected parameter name")),
+                        }
+                    }
+                }
+
+                self.expect(TokenType::RParen)?;
+                let body = self.parse_block()?;
+
+                Ok(Declaration::Function {
+                    name,
+                    params,
+                    body,
+                    return_type: TypeId::U32,
+                })
+            }
+            _ => {
+                // Variable declaration
+                let init = if matches!(self.current().token_type, TokenType::Assign) {
+                    self.advance();
+
+                    if let TokenType::Number(n) = self.current().token_type {
+                        self.advance();
+                        Some(ConstExpr::Number(n))
+                    } else {
+                        return Err(self
+                            .error("Expected constant in global variable declaration"));
+                    }
+                } else {
+                    None
+                };
+
+                self.expect(TokenType::Semicolon)?;
+                Ok(Declaration::Variable {
+                    var: Variable {
+                        name,
+                        type_id: TypeId::U32,
+                    },
+                    init,
+                    is_const: false,
+                })
+            }
+        }
+    }
+
+    fn parse_block(&mut self) -> Result<Block, String> {
+        self.expect(TokenType::LBrace)?;
+        let mut statements = Vec::new();
+
+        while !matches!(self.current().token_type, TokenType::RBrace) {
+            statements.push(self.parse_statement()?);
+        }
+
+        self.expect(TokenType::RBrace)?;
+        Ok(statements)
+    }
+
+    fn parse_statement(&mut self) -> Result<Statement, String> {
+        match &self.current().token_type {
+            TokenType::LBrace => Ok(Statement::Block(self.parse_block()?)),
+            TokenType::If => self.parse_if_stmt(),
+            TokenType::While => self.parse_while_stmt(),
+            TokenType::Return => self.parse_return_stmt(),
+            TokenType::Identifier(name) => {
+                let name = name.clone();
+
+                // peek ahead for open paren (func call expr)
+                if matches!(self.peek(1).token_type, TokenType::LParen) {
+                    let expr = self.parse_expression()?; // a function call expr
+                    self.expect(TokenType::Semicolon)?;
+                    return Ok(Statement::Expression { expr });
+                }
+
+                self.advance(); // advance past identifier
+
+                // assignment expression
+                if matches!(self.current().token_type, TokenType::Assign) {
+                    self.advance();
+                    let expr = self.parse_expression()?;
+
+                    self.expect(TokenType::Semicolon)?;
+                    Ok(Statement::Assign {
+                        varname: name,
+                        value: expr,
+                    })
+                }
+                // var expression
+                else {
+                    self.expect(TokenType::Semicolon)?;
+                    Ok(Statement::Expression {
+                        expr: Expression::Variable {
+                            name: Name {
+                                name,
+                                namespace: None,
+                            },
+                            expr_type: None,
+                        },
+                    })
+                }
+            }
+            TokenType::Int => {
+                // Local variable declaration
+                self.advance();
+                let name = match &self.current().token_type {
+                    TokenType::Identifier(s) => s.clone(),
+                    _ => return Err(self.error("Expected variable name")),
+                };
+                self.advance();
+
+                let init = if matches!(self.current().token_type, TokenType::Assign) {
+                    self.advance();
+                    Some(self.parse_expression()?)
+                } else {
+                    None
+                };
+
+                self.expect(TokenType::Semicolon)?;
+
+                // Convert to assignment expression statement
+                let expr = if let Some(init_expr) = init {
+                    Statement::Assign {
+                        varname: name,
+                        value: init_expr,
+                    }
+                } else {
+                    Statement::Assign {
+                        varname: name,
+                        value: Expression::Empty,
+                    }
+                };
+
+                Ok(expr)
+            }
+            _ => {
+                let expr = if matches!(self.current().token_type, TokenType::Semicolon) {
+                    Expression::Empty
+                } else {
+                    self.parse_expression()?
+                };
+
+                self.expect(TokenType::Semicolon)?;
+                Ok(Statement::Expression { expr })
+            }
+        }
+    }
+
+    fn parse_if_stmt(&mut self) -> Result<Statement, String> {
+        self.expect(TokenType::If)?;
+        self.expect(TokenType::LParen)?;
+        let condition = self.parse_expression()?;
+        self.expect(TokenType::RParen)?;
+        let then_stmt = self.parse_block()?;
+
+        let else_stmt = if matches!(self.current().token_type, TokenType::Else) {
+            self.advance();
+            self.parse_block()?
+        } else {
+            Vec::new()
+        };
+
+        Ok(Statement::If {
+            condition,
+            then_stmt,
+            else_stmt,
+        })
+    }
+
+    fn parse_while_stmt(&mut self) -> Result<Statement, String> {
+        self.expect(TokenType::While)?;
+        self.expect(TokenType::LParen)?;
+        let condition = self.parse_expression()?;
+        self.expect(TokenType::RParen)?;
+        let body = self.parse_block()?;
+
+        Ok(Statement::While { condition, body })
+    }
+
+    fn parse_return_stmt(&mut self) -> Result<Statement, String> {
+        self.expect(TokenType::Return)?;
+
+        let expr = if matches!(self.current().token_type, TokenType::Semicolon) {
+            None
+        } else {
+            Some(self.parse_expression()?)
+        };
+
+        self.expect(TokenType::Semicolon)?;
+        Ok(Statement::Return(expr))
+    }
+
+    fn parse_expression(&mut self) -> Result<Expression, String> {
+        self.parse_comparison()
+    }
+
+    fn parse_comparison(&mut self) -> Result<Expression, String> {
+        let mut expr = self.parse_additive()?;
+
+        while let Some(op) = match &self.current().token_type {
+            TokenType::Eq => Some(BinaryOperator::Eq),
+            TokenType::Ne => Some(BinaryOperator::Ne),
+            TokenType::Lt => Some(BinaryOperator::Lt),
+            TokenType::Gt => Some(BinaryOperator::Gt),
+            TokenType::Le => Some(BinaryOperator::Le),
+            TokenType::Ge => Some(BinaryOperator::Ge),
+            _ => None,
+        } {
+            self.advance();
+            let right = Box::new(self.parse_additive()?);
+            expr = Expression::Binary {
+                op,
+                left: Box::new(expr),
+                right,
+            };
+        }
+
+        Ok(expr)
+    }
+
+    fn parse_additive(&mut self) -> Result<Expression, String> {
+        let mut expr = self.parse_multiplicative()?;
+
+        while let Some(op) = match &self.current().token_type {
+            TokenType::Plus => Some(BinaryOperator::Add),
+            TokenType::Minus => Some(BinaryOperator::Sub),
+            _ => None,
+        } {
+            self.advance();
+            let right = Box::new(self.parse_multiplicative()?);
+            expr = Expression::Binary {
+                op,
+                left: Box::new(expr),
+                right,
+            };
+        }
+
+        Ok(expr)
+    }
+
+    fn parse_multiplicative(&mut self) -> Result<Expression, String> {
+        let mut expr = self.parse_unary()?;
+
+        while let Some(op) = match &self.current().token_type {
+            TokenType::Star => Some(BinaryOperator::Mul),
+            TokenType::Slash => Some(BinaryOperator::Div),
+            _ => None,
+        } {
+            self.advance();
+            let right = Box::new(self.parse_unary()?);
+            expr = Expression::Binary {
+                op,
+                left: Box::new(expr),
+                right,
+            };
+        }
+
+        Ok(expr)
+    }
+
+    fn parse_unary(&mut self) -> Result<Expression, String> {
+        let op = match &self.current().token_type {
+            TokenType::Plus => Some(UnaryOperator::Plus),
+            TokenType::Minus => Some(UnaryOperator::Minus),
+            _ => None,
+        };
+
+        if let Some(op) = op {
+            self.advance();
+            let operand = Box::new(self.parse_unary()?);
+            return Ok(Expression::Unary { op, operand });
+        }
+
+        self.parse_primary()
+    }
+
+    fn parse_primary(&mut self) -> Result<Expression, String> {
+        match &self.current().token_type.clone() {
+            TokenType::Number(n) => {
+                let value = *n;
+                self.advance();
+                Ok(Expression::Number(value as isize))
+            }
+            TokenType::Identifier(name) => {
+                let name = name.clone();
+                self.advance();
+
+                if matches!(self.current().token_type, TokenType::LParen) {
+                    // Function call
+                    self.advance();
+                    let mut args = Vec::new();
+
+                    if !matches!(self.current().token_type, TokenType::RParen) {
+                        args.push(self.parse_expression()?);
+
+                        while matches!(self.current().token_type, TokenType::Comma) {
+                            self.advance();
+                            args.push(self.parse_expression()?);
+                        }
+                    }
+
+                    self.expect(TokenType::RParen)?;
+                    Ok(Expression::Call {
+                        name: Name {
+                            name,
+                            namespace: None,
+                        },
+                        args,
+                    })
+                } else {
+                    Ok(Expression::Variable {
+                        name: Name {
+                            name,
+                            namespace: None,
+                        },
+                        expr_type: None,
+                    })
+                }
+            }
+            TokenType::LParen => {
+                self.advance();
+                let expr = self.parse_expression()?;
+                self.expect(TokenType::RParen)?;
+                Ok(expr)
+            }
+            _ => Err(self.error(&format!(
+                "Unexpected token: {:?}",
+                self.current().token_type
+            ))),
+        }
+    }
+}

compiler/src/frontend/dsc/lexer.rs

@@ -0,0 +1,627 @@
+use std::iter::Peekable;
+use std::str::Chars;
+
+#[derive(Debug, PartialEq, Clone)]
+pub enum Token {
+    // Keywords
+    Fn,
+    Let,
+    If,
+    Else,
+    Loop,
+    While,
+    Break,
+    Return,
+    Continue,
+    Include,
+    Static,
+    Const,
+
+    // Identifiers and literals
+    Identifier(Name),
+    String(String),
+    Integer(u64),
+    Char(char),
+
+    // Symbols
+    LeftParen,  // (
+    RightParen, // )
+    LeftBrace,  // {
+    RightBrace, // }
+    Semicolon,  // ;
+    Colon,      // :
+    Comma,      // ,
+
+    // Operators
+    Plus,         // +
+    Minus,        // -
+    Star,         // *
+    Amphersand,   // &
+    Slash,        // /
+    Assign,       // =
+    EqualEqual,   // ==
+    Bang,         // !
+    BangEqual,    // !=
+    Less,         // <
+    LessEqual,    // <=
+    Greater,      // >
+    GreaterEqual, // >=
+    RightArrow,   // ->
+
+    // Special
+    Eof,
+}
+
+use std::fmt;
+
+use crate::model::Name;
+
+impl fmt::Display for Name {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        if let Some(ref ns) = self.namespace {
+            write!(f, "{}::{}", ns, self.name)
+        } else {
+            write!(f, "{}", self.name)
+        }
+    }
+}
+
+impl Token {
+    pub fn tt(&self) -> &str {
+        match self {
+            Token::Const => "Const",
+            Token::Static => "Static",
+            Token::Include => "Include",
+            Token::Fn => "Fn",
+            Token::If => "If",
+            Token::Let => "Let",
+            Token::Else => "Else",
+            Token::Loop => "Loop",
+            Token::While => "While",
+            Token::Break => "Break",
+            Token::Return => "Return",
+            Token::Continue => "Continue",
+            Token::Identifier(_) => "Identifier",
+            Token::String(_) => "String",
+            Token::Integer(_) => "UnsignedInt",
+            Token::Char(_) => "Char",
+            Token::LeftParen => "LeftParen",
+            Token::RightParen => "RightParen",
+            Token::LeftBrace => "LeftBrace",
+            Token::RightBrace => "RightBrace",
+            Token::Semicolon => "Semicolon",
+            Token::Colon => "Colon",
+            Token::Comma => "Comma",
+            Token::RightArrow => "RightArrow",
+            Token::Plus => "Plus",
+            Token::Minus => "Minus",
+            Token::Star => "Star",
+            Token::Amphersand => "Amphersand",
+            Token::Slash => "Slash",
+            Token::Assign => "Assign",
+            Token::EqualEqual => "EqualEqual",
+            Token::Bang => "Bang",
+            Token::BangEqual => "BangEqual",
+            Token::Less => "Less",
+            Token::LessEqual => "LessEqual",
+            Token::Greater => "Greater",
+            Token::GreaterEqual => "GreaterEqual",
+            Token::Eof => "Eof",
+        }
+    }
+}
+
+#[derive(Debug)]
+pub struct Lexer<'a> {
+    chars: Peekable<Chars<'a>>,
+    current: Option<char>,
+    line: usize,
+}
+
+impl<'a> Lexer<'a> {
+    pub fn new(input: &'a str) -> Self {
+        let mut chars = input.chars().peekable();
+        let current = chars.next();
+
+        Lexer {
+            chars,
+            current,
+            line: 1,
+        }
+    }
+
+    fn advance(&mut self) -> Option<char> {
+        self.current = self.chars.next();
+        self.current
+    }
+
+    fn peek(&mut self) -> Option<&char> {
+        self.chars.peek()
+    }
+
+    fn skip_whitespace(&mut self) {
+        while let Some(c) = self.current {
+            if !c.is_whitespace() {
+                break;
+            }
+            if c == '\n' {
+                self.line += 1;
+            }
+            self.advance();
+        }
+    }
+
+    fn skip_line_comment(&mut self) {
+        // Skip the two slashes
+        self.advance(); // first /
+        self.advance(); // second /
+
+        // Skip until newline or EOF
+        while let Some(c) = self.current {
+            if c == '\n' {
+                self.line += 1;
+                self.advance();
+                break;
+            }
+            self.advance();
+        }
+    }
+
+    fn skip_block_comment(&mut self) -> Result<(), String> {
+        // Skip the /*
+        self.advance(); // /
+        self.advance(); // *
+
+        let start_line = self.line;
+
+        // Look for */
+        while let Some(c) = self.current {
+            if c == '\n' {
+                self.line += 1;
+            }
+
+            if c == '*' {
+                if let Some(&next) = self.peek() {
+                    if next == '/' {
+                        self.advance(); // *
+                        self.advance(); // /
+                        return Ok(());
+                    }
+                }
+            }
+
+            self.advance();
+        }
+
+        Err(format!(
+            "Unterminated block comment starting at line {}",
+            start_line
+        ))
+    }
+
+    fn skip_whitespace_and_comments(&mut self) {
+        loop {
+            self.skip_whitespace();
+
+            // Check for comments
+            if let Some('/') = self.current {
+                if let Some(&next) = self.peek() {
+                    match next {
+                        '/' => {
+                            self.skip_line_comment();
+                            continue;
+                        }
+                        '*' => {
+                            if let Err(e) = self.skip_block_comment() {
+                                eprintln!("Lexer error: {}", e);
+                            }
+                            continue;
+                        }
+                        _ => break,
+                    }
+                }
+            }
+
+            break;
+        }
+    }
+
+    fn read_identifier(&mut self) -> String {
+        let mut ident = String::new();
+
+        // Include the current character if it's valid
+        if let Some(c) = self.current {
+            if c.is_alphabetic() || c == '_' {
+                ident.push(c);
+            }
+        }
+
+        // Read remaining characters
+        while let Some(&c) = self.peek() {
+            if c.is_alphanumeric() || c == '_' {
+                self.advance();
+                ident.push(c);
+            } else {
+                break;
+            }
+        }
+
+        ident
+    }
+
+    fn keyword_or_identifier(&mut self) -> Token {
+        let first_ident = self.read_identifier();
+
+        // Check if it's a keyword first (keywords can't have namespaces)
+        let keyword = match first_ident.as_str() {
+            "fn" => Some(Token::Fn),
+            "if" => Some(Token::If),
+            "else" => Some(Token::Else),
+            "while" => Some(Token::While),
+            "loop" => Some(Token::Loop),
+            "break" => Some(Token::Break),
+            "return" => Some(Token::Return),
+            "continue" => Some(Token::Continue),
+            "include" => Some(Token::Include),
+            "let" => Some(Token::Let),
+            "const" => Some(Token::Const),
+            "static" => Some(Token::Static),
+            _ => None,
+        };
+
+        if let Some(kw) = keyword {
+            return kw;
+        }
+
+        // Not a keyword - check for namespace separator (::)
+        // We need to peek TWO characters ahead without consuming anything
+        if let Some(&':') = self.peek() {
+            // We see one colon, but we need to check if there's another one after it
+            // We can't peek two ahead directly, so we need a different approach
+
+            // Save the current position by using a temporary peekable iterator
+            // Actually, we can't do that easily. Instead, let's just check:
+            // If we see ':', temporarily advance and check the next char
+
+            // Create a temporary check
+            let mut temp_chars = self.chars.clone();
+            let _ = temp_chars.next(); // This is the ':' we already saw
+            let second_peek = temp_chars.peek();
+
+            if let Some(&':') = second_peek {
+                // It's :: - consume both colons
+                self.advance(); // consume first :
+                self.advance(); // consume second :
+
+                // Read the second identifier (the actual name)
+                let second_ident = self.read_identifier();
+
+                // Return namespaced identifier
+                return Token::Identifier(Name {
+                    namespace: Some(first_ident),
+                    name: second_ident,
+                });
+            }
+            // else: It's a single colon (type annotation) - DON'T consume it
+            // Just fall through and return the identifier
+        }
+
+        // No namespace separator - just a regular identifier
+        Token::Identifier(Name {
+            namespace: None,
+            name: first_ident,
+        })
+    }
+
+    fn read_number(&mut self) -> Result<u64, String> {
+        let current = self.current.unwrap();
+
+        // Check for hex (0x) or binary (0b) prefix
+        if current == '0' {
+            if let Some(&next_char) = self.peek() {
+                match next_char {
+                    'x' | 'X' => {
+                        self.advance(); // consume '0'
+                        self.advance(); // consume 'x'
+                        return self.read_hex_number();
+                    }
+                    'b' | 'B' => {
+                        self.advance(); // consume '0'
+                        self.advance(); // consume 'b'
+                        return self.read_binary_number();
+                    }
+                    _ => {}
+                }
+            }
+        }
+
+        // Read decimal number
+        self.read_decimal_number()
+    }
+
+    fn read_decimal_number(&mut self) -> Result<u64, String> {
+        let mut num_str = String::new();
+
+        if let Some(c) = self.current {
+            num_str.push(c);
+        }
+
+        while let Some(&c) = self.peek() {
+            if c.is_ascii_digit() {
+                self.advance();
+                num_str.push(c);
+            } else {
+                break;
+            }
+        }
+
+        num_str
+            .parse::<u64>()
+            .map_err(|_| format!("Invalid decimal number: {}", num_str))
+    }
+
+    fn read_hex_number(&mut self) -> Result<u64, String> {
+        let mut num_str = String::new();
+
+        // Read current character if it's a hex digit
+        if let Some(c) = self.current {
+            if c.is_ascii_hexdigit() {
+                num_str.push(c);
+            }
+        }
+
+        while let Some(&c) = self.peek() {
+            if c.is_ascii_hexdigit() {
+                self.advance();
+                num_str.push(c);
+            } else {
+                break;
+            }
+        }
+
+        if num_str.is_empty() {
+            return Err("Invalid hexadecimal number: no digits after 0x".to_string());
+        }
+
+        u64::from_str_radix(&num_str, 16)
+            .map_err(|_| format!("Invalid hexadecimal number: {}", num_str))
+    }
+
+    fn read_binary_number(&mut self) -> Result<u64, String> {
+        let mut num_str = String::new();
+
+        // Read current character if it's a binary digit
+        if let Some(c) = self.current {
+            if c == '0' || c == '1' {
+                num_str.push(c);
+            }
+        }
+
+        while let Some(&c) = self.peek() {
+            if c == '0' || c == '1' {
+                self.advance();
+                num_str.push(c);
+            } else {
+                break;
+            }
+        }
+
+        if num_str.is_empty() {
+            return Err("Invalid binary number: no digits after 0b".to_string());
+        }
+
+        u64::from_str_radix(&num_str, 2)
+            .map_err(|_| format!("Invalid binary number: {}", num_str))
+    }
+
+    fn read_string(&mut self) -> Result<String, String> {
+        self.advance(); // Skip the opening quote
+        let mut s = String::new();
+
+        while let Some(c) = self.current {
+            if c == '"' {
+                return Ok(s);
+            }
+
+            // Handle escape sequences
+            if c == '\\' {
+                self.advance();
+                if let Some(escaped) = self.current {
+                    let escaped_char = match escaped {
+                        'n' => '\n',
+                        't' => '\t',
+                        'r' => '\r',
+                        '\\' => '\\',
+                        '"' => '"',
+                        _ => escaped, // For now, just use the character as-is
+                    };
+                    s.push(escaped_char);
+                } else {
+                    return Err("Unexpected end of string after escape".to_string());
+                }
+            } else {
+                s.push(c);
+            }
+
+            self.advance();
+        }
+
+        Err("Unterminated string literal".to_string())
+    }
+
+    fn match_next(&mut self, expected: char) -> bool {
+        match self.peek() {
+            Some(&c) if c == expected => {
+                self.advance();
+                true
+            }
+            _ => false,
+        }
+    }
+
+    fn scan_single_char_token(&mut self, c: char) -> Option<Token> {
+        match c {
+            '(' => Some(Token::LeftParen),
+            ')' => Some(Token::RightParen),
+            '{' => Some(Token::LeftBrace),
+            '}' => Some(Token::RightBrace),
+            ';' => Some(Token::Semicolon),
+            ',' => Some(Token::Comma),
+            '&' => Some(Token::Amphersand),
+            '+' => Some(Token::Plus),
+            '*' => Some(Token::Star),
+            _ => None,
+        }
+    }
+
+    fn scan_operator(&mut self, c: char) -> Option<Token> {
+        match c {
+            '-' => Some(if self.match_next('>') {
+                Token::RightArrow
+            } else {
+                Token::Minus
+            }),
+            '!' => Some(if self.match_next('=') {
+                Token::BangEqual
+            } else {
+                Token::Bang
+            }),
+            '=' => Some(if self.match_next('=') {
+                Token::EqualEqual
+            } else {
+                Token::Assign
+            }),
+            '<' => Some(if self.match_next('=') {
+                Token::LessEqual
+            } else {
+                Token::Less
+            }),
+            '>' => Some(if self.match_next('=') {
+                Token::GreaterEqual
+            } else {
+                Token::Greater
+            }),
+            ':' => {
+                // Single colon (for type annotations)
+                // Note: :: is handled in keyword_or_identifier for namespaces
+                Some(Token::Colon)
+            }
+            '/' => {
+                // Check if it's a comment or division
+                if let Some(&next) = self.peek() {
+                    if next == '/' || next == '*' {
+                        // It's a comment, don't consume it here
+                        // Let skip_whitespace_and_comments handle it
+                        None
+                    } else {
+                        Some(Token::Slash)
+                    }
+                } else {
+                    Some(Token::Slash)
+                }
+            }
+            _ => None,
+        }
+    }
+
+    pub fn next_token(&mut self) -> Token {
+        self.skip_whitespace_and_comments();
+
+        let Some(c) = self.current else {
+            return Token::Eof;
+        };
+
+        // Try single-character tokens first
+        if let Some(token) = self.scan_single_char_token(c) {
+            self.advance();
+            return token;
+        }
+
+        // Try operators (may be multi-character)
+        if let Some(token) = self.scan_operator(c) {
+            self.advance();
+            return token;
+        }
+
+        // Char literals
+        if c == '\'' {
+            let mut value = ' ';
+            self.advance();
+            if let Some(ch) = self.current {
+                value = ch;
+                self.advance();
+            }
+            if self.current == Some('\'') {
+                self.advance();
+                return Token::Char(value);
+            }
+            eprintln!("Lexer error on line {}: Invalid char literal", self.line);
+        }
+
+        // String literals
+        if c == '"' {
+            let token = match self.read_string() {
+                Ok(s) => Token::String(s),
+                Err(e) => {
+                    eprintln!("Lexer error on line {}: {}", self.line, e);
+                    // Skip to next quote or end
+                    while let Some(ch) = self.current {
+                        if ch == '"' || ch == '\n' {
+                            break;
+                        }
+                        self.advance();
+                    }
+                    Token::String(String::new())
+                }
+            };
+            self.advance();
+            return token;
+        }
+
+        // Identifiers and keywords (including namespaced identifiers)
+        if c.is_alphabetic() || c == '_' {
+            let token = self.keyword_or_identifier();
+            self.advance();
+            return token;
+        }
+
+        // Numbers (decimal, hex, binary)
+        if c.is_ascii_digit() {
+            let token = match self.read_number() {
+                Ok(num) => Token::Integer(num),
+                Err(e) => {
+                    eprintln!("Lexer error on line {}: {}", self.line, e);
+                    // Skip invalid number
+                    while let Some(&ch) = self.peek() {
+                        if !ch.is_alphanumeric() {
+                            break;
+                        }
+                        self.advance();
+                    }
+                    Token::Integer(0)
+                }
+            };
+            self.advance();
+            return token;
+        }
+
+        // Unknown character - skip it
+        eprintln!(
+            "Lexer warning on line {}: Skipping unknown character '{}'",
+            self.line, c
+        );
+        self.advance();
+        self.next_token()
+    }
+}
+
+impl<'a> Iterator for Lexer<'a> {
+    type Item = Token;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        match self.next_token() {
+            Token::Eof => None,
+            token => Some(token),
+        }
+    }
+}

compiler/src/frontend/dsc/mod.rs

@@ -0,0 +1,38 @@
+use common::logging::log;
+
+use crate::model::{CompilerError, Program};
+use parser::{ParseResult, Parser};
+use semantic_analyser::Analyser;
+
+pub mod lexer;
+pub mod parser;
+pub mod semantic_analyser;
+
+pub fn generate_ast(input: &str) -> Result<Program, CompilerError> {
+    log("Tokenising Input...");
+
+    let lexer = lexer::Lexer::new(&input);
+    let tokens = lexer.collect::<Vec<_>>();
+    // println!("{tokens:?}");
+
+    log(&format!("Parsing {} Tokens...", tokens.len()));
+
+    let mut parser = Parser::new(tokens);
+    let ast = match parser.parse() {
+        ParseResult::Accept(ast) => ast,
+        ParseResult::Reject(e) => return Err(e),
+        ParseResult::Deny => {
+            return Err(CompilerError::Generic("Parser used ::Deny".to_string()));
+        }
+    };
+    // println!("{ast:#?}");
+
+    log("Analyzing AST...");
+    log("Checking Type Information...");
+
+    let analyser = Analyser::new();
+    analyser.analyse(ast.clone()).unwrap();
+
+    log("Type Checking Complete...");
+    Ok(ast)
+}

compiler/src/frontend/dsc/parser.rs

@@ -0,0 +1,604 @@
+use super::lexer::Token;
+use crate::model::{
+    BinaryOperator, Block, CompilerError, ConstExpr, Declaration, Dependency, Expression,
+    Program, Statement, TypeId, UnaryOperator, Variable,
+};
+use crate::{expect_tt, expect_value};
+use std::ops::{ControlFlow, FromResidual, Try};
+
+#[derive(Debug, Clone)]
+pub enum ParseResult<T, E> {
+    Accept(T),
+    Deny,
+    Reject(E),
+}
+
+pub struct Parser {
+    tokens: Vec<Token>,
+    idx: usize,
+}
+
+impl Parser {
+    pub fn new(tokens: Vec<Token>) -> Self {
+        Self { tokens, idx: 0 }
+    }
+
+    pub fn parse(&mut self) -> ParseResult<Program, CompilerError> {
+        let mut declarations = Vec::new();
+
+        while let ParseResult::Accept(_) = self.peek_next() {
+            declarations.push(self.parse_declaration()?);
+        }
+
+        ParseResult::Accept(Program { declarations })
+    }
+
+    fn parse_declaration(&mut self) -> ParseResult<Declaration, CompilerError> {
+        if expect_tt!(self.peek_next()?, Fn).accepted() {
+            return self.parse_func();
+        }
+
+        if expect_tt!(self.peek_next()?, Include).accepted() {
+            // expect include keyword
+            let _ = self.next();
+
+            // expect namespace identifier
+            let name = expect_value!(self.next()?, Identifier)?;
+
+            // expect colon
+            let _ = expect_tt!(self.next()?, Colon)?;
+
+            // expect string literal (module path)
+            let path = expect_value!(self.next()?, String)?;
+
+            // expect semicolon
+            let _ = expect_tt!(self.next()?, Semicolon)?;
+
+            return ParseResult::Accept(Declaration::Dependency(Dependency {
+                name: name.name,
+                path,
+            }));
+        }
+
+        if expect_tt!(self.peek_next()?, Const, Static).accepted() {
+            let is_const = match self.next()? {
+                Token::Const => true,
+                Token::Static => false,
+                _ => {
+                    return ParseResult::Reject(CompilerError::Generic(String::from(
+                        "This can't happen!",
+                    )));
+                }
+            };
+
+            let var = self.parse_var_decl()?;
+
+            let _ = expect_tt!(self.next()?, Assign)?;
+
+            let value = self.next()?;
+            let init = match value {
+                Token::String(x) => Some(ConstExpr::String(x)),
+                Token::Integer(x) => Some(ConstExpr::Number(x as i32)),
+                _ => {
+                    return ParseResult::Reject(CompilerError::UnexpectedToken(
+                        value.tt().to_string(),
+                    ));
+                }
+            };
+
+            let _ = expect_tt!(self.next()?, Semicolon)?;
+
+            return ParseResult::Accept(Declaration::Variable {
+                var,
+                init,
+                is_const,
+            });
+        }
+
+        ParseResult::Reject(CompilerError::UnexpectedEndOfInput)
+    }
+
+    fn parse_func(&mut self) -> ParseResult<Declaration, CompilerError> {
+        // expect function keyword
+        let _ = expect_tt!(self.next()?, Fn);
+        // expect function name
+        let name = expect_value!(self.next()?, Identifier)?;
+
+        // expect left paren
+        let _ = expect_tt!(self.next()?, LeftParen)?;
+
+        let mut params = Vec::new();
+        while expect_tt!(self.peek_next()?, Identifier).accepted() {
+            let arg = self.parse_var_decl()?;
+            params.push(arg);
+
+            if expect_tt!(self.peek_next()?, Comma).accepted() {
+                self.next()?;
+            } else {
+                break;
+            }
+        }
+
+        // expect right paren
+        let _ = expect_tt!(self.next()?, RightParen)?;
+
+        // see if we can parse the return type!
+        let mut return_type = TypeId::Void;
+        if expect_tt!(self.peek_next()?, RightArrow).accepted() {
+            let _ = self.next();
+            return_type = self.parse_type()?;
+        }
+
+        // expect vald block
+        if expect_tt!(self.peek_next()?, LeftBrace).accepted() {
+            ParseResult::Accept(Declaration::Function {
+                name: name.name,
+                params,
+                return_type,
+                body: self.parse_block()?,
+            })
+        } else {
+            ParseResult::Reject(CompilerError::UnexpectedToken(
+                self.peek_next()?.tt().to_string(),
+            ))
+        }
+    }
+
+    fn parse_block(&mut self) -> ParseResult<Block, CompilerError> {
+        // expect left brace
+        let _ = expect_tt!(self.next()?, LeftBrace)?;
+
+        let mut block = Vec::new();
+        while !expect_tt!(self.peek_next()?, RightBrace).accepted() {
+            block.push(self.parse_statement()?);
+        }
+
+        // expect right brace
+        let _ = expect_tt!(self.next()?, RightBrace)?;
+
+        ParseResult::Accept(block)
+    }
+
+    fn parse_statement(&mut self) -> ParseResult<Statement, CompilerError> {
+        // handle if statements
+        if expect_tt!(self.peek_next()?, If).accepted() {
+            self.next()?;
+
+            let condition = self.parse_expression()?;
+
+            let then_stmt = self.parse_block()?;
+
+            if !expect_tt!(self.peek_next()?, Else).accepted() {
+                return ParseResult::Accept(Statement::If {
+                    condition,
+                    then_stmt,
+                    else_stmt: vec![],
+                });
+            }
+
+            let _ = expect_tt!(self.next()?, Else)?;
+
+            let else_stmt = self.parse_block()?;
+
+            return ParseResult::Accept(Statement::If {
+                condition,
+                then_stmt,
+                else_stmt,
+            });
+        }
+
+        // handle while loops
+        if expect_tt!(self.peek_next()?, While).accepted() {
+            self.next()?;
+
+            // expect valid expression
+            let expr = self.parse_expression()?;
+
+            // expect valid block after
+            let block = self.parse_block()?;
+
+            // return result
+            return ParseResult::Accept(Statement::While {
+                condition: expr,
+                body: block,
+            });
+        }
+
+        // handle indefinite loops
+        if expect_tt!(self.peek_next()?, Loop).accepted() {
+            self.next()?;
+
+            // parse the inner block
+            return ParseResult::Accept(Statement::Loop(self.parse_block()?));
+        }
+
+        if expect_tt!(self.peek_next()?, Return).accepted() {
+            self.next()?;
+
+            // handle case where nothing is returned
+            if expect_tt!(self.peek_next()?, Semicolon).accepted() {
+                return ParseResult::Accept(Statement::Return(None));
+            }
+
+            let expr = self.parse_expression()?;
+            expect_tt!(self.next()?, Semicolon)?;
+
+            return ParseResult::Accept(Statement::Return(Some(expr)));
+        }
+
+        if expect_tt!(self.peek_next()?, Break).accepted() {
+            self.next()?;
+
+            // expect semicolon
+            expect_tt!(self.next()?, Semicolon)?;
+
+            // return result
+            return ParseResult::Accept(Statement::Break);
+        }
+
+        if expect_tt!(self.peek_next()?, Continue).accepted() {
+            self.next()?;
+
+            // expect semicolon
+            expect_tt!(self.next()?, Semicolon)?;
+
+            // return result
+            return ParseResult::Accept(Statement::Continue);
+        }
+
+        // handle writes to pointers!
+        if expect_tt!(self.peek_next()?, Star).accepted() {
+            self.next()?;
+
+            let left = if expect_tt!(self.peek_next()?, Identifier).accepted() {
+                let identifier = expect_value!(self.next()?, Identifier)?;
+
+                Expression::Variable {
+                    name: identifier,
+                    expr_type: None,
+                }
+            } else if expect_tt!(self.peek_next()?, LeftParen).accepted() {
+                self.next()?;
+
+                let expr = self.parse_expression()?;
+
+                let _ = expect_tt!(self.next()?, RightParen).accepted();
+
+                expr
+            } else {
+                return ParseResult::Reject(CompilerError::UnexpectedToken(
+                    self.peek_next()?.tt().to_string(),
+                ));
+            };
+
+            let _ = expect_tt!(self.next()?, Assign)?;
+
+            let right = self.parse_expression()?;
+
+            // expect semicolon
+            expect_tt!(self.next()?, Semicolon)?;
+
+            // return result
+            return ParseResult::Accept(Statement::PtrWrite {
+                ptr: left,
+                value: right,
+            });
+        }
+
+        // handle let statements (declarations)
+        if expect_tt!(self.peek_next()?, Let).accepted() {
+            self.next();
+
+            // expect variable name and type.
+            let name = self.parse_var_decl()?;
+
+            // handle uninitialised variable case
+            if expect_tt!(self.peek_next()?, Semicolon).accepted() {
+                self.next();
+                return ParseResult::Accept(Statement::Declaration {
+                    var: name,
+                    value: None,
+                });
+            }
+
+            // handle initialised case
+            // expect equals
+            let _ = expect_tt!(self.next()?, Assign)?;
+
+            // expect a valid expression
+            let expr = self.parse_expression()?;
+
+            let _ = expect_tt!(self.next()?, Semicolon);
+
+            // return statement
+            return ParseResult::Accept(Statement::Declaration {
+                var: name,
+                value: Some(expr),
+            });
+        }
+
+        // handle assignment without "let"
+        let name = expect_value!(self.peek_next()?, Identifier);
+        if name.accepted() {
+            let varname = name?;
+            if expect_tt!(self.peek(1)?, LeftParen).accepted() {
+                let expr = self.parse_expression()?; // a function call expr
+                let _ = expect_tt!(self.next()?, Semicolon)?;
+                return ParseResult::Accept(Statement::Expression { expr });
+            }
+
+            self.next()?;
+            let _ = expect_tt!(self.next()?, Assign)?;
+
+            let value = self.parse_expression()?;
+
+            let _ = expect_tt!(self.next()?, Semicolon);
+
+            return ParseResult::Accept(Statement::Assign {
+                varname: varname.name,
+                value,
+            });
+        }
+
+        ParseResult::Reject(CompilerError::UnexpectedToken(
+            self.peek_next()?.tt().to_string(),
+        ))
+    }
+
+    fn parse_expression(&mut self) -> ParseResult<Expression, CompilerError> {
+        self.parse_comparison()
+    }
+
+    fn parse_comparison(&mut self) -> ParseResult<Expression, CompilerError> {
+        let mut expr = self.parse_additive()?;
+
+        while let Some(op) = match self.peek_next()? {
+            Token::EqualEqual => Some(BinaryOperator::Ne),
+            Token::BangEqual => Some(BinaryOperator::Ne),
+            Token::Less => Some(BinaryOperator::Lt),
+            Token::Greater => Some(BinaryOperator::Gt),
+            Token::LessEqual => Some(BinaryOperator::Le),
+            Token::GreaterEqual => Some(BinaryOperator::Ge),
+            _ => None,
+        } {
+            self.next()?;
+            let right = Box::new(self.parse_additive()?);
+            expr = Expression::Binary {
+                op,
+                left: Box::new(expr),
+                right,
+            }
+        }
+
+        ParseResult::Accept(expr)
+    }
+
+    fn parse_additive(&mut self) -> ParseResult<Expression, CompilerError> {
+        let left = self.parse_multiplicative()?;
+
+        let op = match self.peek_next()? {
+            Token::Plus => BinaryOperator::Add,
+            Token::Minus => BinaryOperator::Sub,
+            _ => return ParseResult::Accept(left),
+        };
+
+        self.next()?;
+        ParseResult::Accept(Expression::Binary {
+            op,
+            left: Box::new(left),
+            right: Box::new(self.parse_additive()?),
+        })
+    }
+
+    fn parse_multiplicative(&mut self) -> ParseResult<Expression, CompilerError> {
+        let left = self.parse_unary()?;
+
+        let op = match self.peek_next()? {
+            Token::Star => BinaryOperator::Mul,
+            Token::Slash => BinaryOperator::Div,
+            _ => return ParseResult::Accept(left),
+        };
+
+        self.next()?;
+        ParseResult::Accept(Expression::Binary {
+            op,
+            left: Box::new(left),
+            right: Box::new(self.parse_multiplicative()?),
+        })
+    }
+
+    fn parse_unary(&mut self) -> ParseResult<Expression, CompilerError> {
+        let op = match self.peek_next()? {
+            Token::Plus => UnaryOperator::Plus,
+            Token::Minus => UnaryOperator::Minus,
+            Token::Star => UnaryOperator::Dereference,
+            Token::Amphersand => UnaryOperator::Reference,
+            _ => return ParseResult::Accept(self.parse_primary()?),
+        };
+
+        self.next()?;
+        let operand = Box::new(self.parse_unary()?);
+        ParseResult::Accept(Expression::Unary { op, operand })
+    }
+
+    fn parse_primary(&mut self) -> ParseResult<Expression, CompilerError> {
+        match self.peek_next()? {
+            Token::Integer(value) => {
+                self.next()?;
+                ParseResult::Accept(Expression::Number(value as isize))
+            }
+            Token::String(value) => {
+                self.next()?;
+                ParseResult::Accept(Expression::StringLiteral(value))
+            }
+            Token::Identifier(_) => {
+                let name = expect_value!(self.next()?, Identifier)?;
+
+                if matches!(self.peek_next()?, Token::LeftParen) {
+                    // Function call
+                    self.next()?;
+                    let mut args = Vec::new();
+
+                    if !matches!(self.peek_next()?, Token::RightParen) {
+                        args.push(self.parse_expression()?);
+
+                        while matches!(self.peek_next()?, Token::Comma) {
+                            self.next()?;
+                            args.push(self.parse_expression()?);
+                        }
+                    }
+
+                    let _ = expect_tt!(self.next()?, RightParen)?;
+
+                    ParseResult::Accept(Expression::Call { name, args })
+                } else {
+                    ParseResult::Accept(Expression::Variable {
+                        name,
+                        expr_type: None,
+                    })
+                }
+            }
+            Token::LeftParen => {
+                self.next()?;
+                let expr = self.parse_expression()?;
+                let _ = expect_tt!(self.next()?, RightParen)?;
+                ParseResult::Accept(expr)
+            }
+            _ => ParseResult::Reject(CompilerError::UnexpectedToken(
+                self.peek_next()?.tt().to_string(),
+            )),
+        }
+    }
+
+    fn parse_var_decl(&mut self) -> ParseResult<Variable, CompilerError> {
+        let name = expect_value!(self.next()?, Identifier)?;
+
+        let _ = expect_tt!(self.next()?, Colon)?;
+
+        let type_id = self.parse_type()?;
+
+        ParseResult::Accept(Variable {
+            name: name.name,
+            type_id,
+        })
+    }
+
+    fn parse_type(&mut self) -> ParseResult<TypeId, CompilerError> {
+        // get the type name incl namespace
+        let typename = expect_value!(self.next()?, Identifier)?;
+
+        match typename.name.as_str() {
+            "u32" => ParseResult::Accept(TypeId::U32),
+            "u16" => ParseResult::Accept(TypeId::U16),
+            "u8" => ParseResult::Accept(TypeId::U8),
+            "i32" => ParseResult::Accept(TypeId::I32),
+            "i16" => ParseResult::Accept(TypeId::I16),
+            "i8" => ParseResult::Accept(TypeId::I8),
+            "void" => ParseResult::Accept(TypeId::Void),
+            "char" => ParseResult::Accept(TypeId::Char),
+            "str" => ParseResult::Accept(TypeId::Ptr(Box::new(TypeId::Char))),
+            _ => todo!("Implement parsing for other types!!"),
+        }
+    }
+
+    fn next(&mut self) -> ParseResult<Token, CompilerError> {
+        if self.idx >= self.tokens.len() {
+            ParseResult::Reject(CompilerError::UnexpectedEndOfInput)
+        } else {
+            let token = self.tokens[self.idx].clone();
+            self.idx += 1;
+            ParseResult::Accept(token)
+        }
+    }
+
+    fn peek_next(&self) -> ParseResult<Token, CompilerError> {
+        if self.idx >= self.tokens.len() {
+            ParseResult::Reject(CompilerError::UnexpectedEndOfInput)
+        } else {
+            ParseResult::Accept(self.tokens[self.idx].clone())
+        }
+    }
+
+    fn peek(&self, offset: usize) -> ParseResult<Token, CompilerError> {
+        if self.idx + offset >= self.tokens.len() {
+            ParseResult::Reject(CompilerError::UnexpectedEndOfInput)
+        } else {
+            ParseResult::Accept(self.tokens[self.idx + offset].clone())
+        }
+    }
+}
+
+impl<T, E> ParseResult<T, E> {
+    pub fn accepted(&self) -> bool {
+        matches!(self, ParseResult::Accept(_))
+    }
+}
+
+pub enum ParseResultResidual<T> {
+    Deny,
+    Reject(T),
+}
+
+impl<T, E> Try for ParseResult<T, E> {
+    type Output = T;
+    type Residual = ParseResultResidual<E>;
+
+    fn from_output(output: T) -> Self {
+        ParseResult::Accept(output)
+    }
+
+    fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
+        match self {
+            ParseResult::Accept(v) => ControlFlow::Continue(v),
+            ParseResult::Deny => ControlFlow::Break(ParseResultResidual::Deny),
+            ParseResult::Reject(e) => ControlFlow::Break(ParseResultResidual::Reject(e)),
+        }
+    }
+}
+
+impl<T, E> FromResidual for ParseResult<T, E> {
+    fn from_residual(residual: ParseResultResidual<E>) -> Self {
+        match residual {
+            ParseResultResidual::Deny => ParseResult::Deny,
+            ParseResultResidual::Reject(e) => ParseResult::Reject(e),
+        }
+    }
+}
+
+#[macro_export]
+macro_rules! expect_tt {
+    ($token:expr, $($variant:ident),+) => {{
+        let token = $token.clone();
+        let tt = token.tt().to_string();
+
+        let mut vs = String::new();
+        $(
+            let s = stringify!($variant);
+            vs.push_str(s);
+            vs.push_str("|");
+        )+
+
+        match tt.as_str() {
+            $(
+                stringify!($variant) => ParseResult::Accept(token),
+            )+
+            _ => {
+                // let expected = format!("[{}]", vec![$(stringify!($variant)),+].join(" | "));
+                ParseResult::Reject(CompilerError::UnexpectedToken(tt))
+            }
+        }
+    }};
+}
+
+#[macro_export]
+macro_rules! expect_value {
+    ($expr:expr, $variant:ident) => {{
+        let tok = $expr;
+        match tok.clone() {
+            Token::$variant(value) => ParseResult::Accept(value),
+            _ => {
+                ParseResult::Reject(CompilerError::UnexpectedToken(tok.tt().to_string()))
+            }
+        }
+    }};
+}

compiler/src/frontend/dsc/semantic_analyser.rs

@@ -0,0 +1,13 @@
+use crate::model::{CompilerError, Program};
+
+pub struct Analyser;
+
+impl Analyser {
+    pub fn new() -> Self {
+        Self
+    }
+
+    pub fn analyse(&self, _ast: Program) -> Result<(), CompilerError> {
+        Ok(())
+    }
+}

compiler/src/frontend/mod.rs

@@ -0,0 +1,15 @@
+use crate::model::{CompilerError, Program};
+
+mod c;
+mod dsc;
+
+pub fn compiler_frontend(ext: &str, data: &str) -> Result<Program, CompilerError> {
+    match ext {
+        "dsc" => Ok(dsc::generate_ast(&data)?),
+        "c" => Ok(c::generate_ast(&data)?),
+        _ => Err(CompilerError::Generic(format!(
+            "File type {} not supported",
+            ext
+        ))),
+    }
+}

compiler/src/lib.rs

@@ -0,0 +1,70 @@
+#![feature(try_trait_v2)]
+
+use std::path::Path;
+
+use common::logging::log;
+
+use crate::specialised::build_specialised;
+
+mod backend;
+mod frontend;
+mod model;
+mod specialised;
+
+pub fn compile_file(
+    input_path: &Path,
+    output_path: &Path,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let input = std::fs::read_to_string(input_path).expect("Failed to read input file");
+
+    let input_ext = input_path
+        .extension()
+        .and_then(|s| s.to_str())
+        .unwrap_or("");
+
+    // check if we're using a specialised compiler
+    if let Some(output) = build_specialised(input_ext, &input) {
+        let result = match output {
+            Ok(output) => output,
+            Err(err) => return Err(format!("Compilation failed: {err:?}").into()),
+        };
+
+        std::fs::write(output_path, &result).expect("Failed to write output");
+
+        log(&format!(
+            "Compilation Successful ✅ \n\tSource: {}\n\tOutput: {}\n",
+            input_path.display(),
+            output_path.display(),
+        ));
+
+        return Ok(());
+    }
+
+    // Parse the input using the frontend, providing the file extension and data.
+    let ast = match frontend::compiler_frontend(input_ext, &input) {
+        Ok(ast) => ast,
+        Err(err) => return Err(format!("Compilation failed: {err:?}").into()),
+    };
+
+    let output_ext = output_path
+        .extension()
+        .and_then(|s| s.to_str())
+        .unwrap_or("");
+
+    // Generate the output using the backend with the parsed result.
+    let result = match backend::compiler_backend(output_ext, &ast) {
+        Ok(result) => result,
+        Err(err) => return Err(format!("Compilation failed: {err:?}").into()),
+    };
+
+    // println!("{result}");
+    std::fs::write(output_path, &result).expect("Failed to write output");
+
+    log(&format!(
+        "Compilation Successful ✅ \n\tSource: {}\n\tOutput: {}\n",
+        input_path.display(),
+        output_path.display(),
+    ));
+
+    Ok(())
+}

compiler/src/main.rs

@@ -0,0 +1,21 @@
+use std::path::Path;
+
+use compiler;
+
+fn main() {
+    // read from input file: syntax "c_compiler <src.c> [output.dsa]"
+    let args: Vec<String> = std::env::args().collect();
+    if args.len() < 2 {
+        eprintln!("Usage: c_compiler <src.dsc> [output.dsa]");
+        return;
+    }
+
+    let input_file = &args[1];
+    let output_file = if args.len() > 2 {
+        &args[2]
+    } else {
+        "output.dsa"
+    };
+
+    compiler::compile_file(Path::new(input_file), Path::new(output_file)).unwrap();
+}

compiler/src/model.rs

@@ -0,0 +1,213 @@
+use core::fmt;
+
+#[allow(unused)]
+#[derive(Debug, Clone)]
+pub enum CompilerError {
+    UnexpectedToken(String),
+    UnexpectedEndOfInput,
+    UnexpectedCharacter(char),
+    Undefined(Name),
+    InvalidSyntax(String),
+    Generic(String),
+}
+
+#[derive(Debug, PartialEq, Clone)]
+pub struct Name {
+    pub name: String,
+    pub namespace: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+pub struct Program {
+    pub declarations: Vec<Declaration>,
+}
+
+#[allow(unused)]
+#[derive(Debug, Clone)]
+pub enum Declaration {
+    Function {
+        name: String,
+        return_type: TypeId,
+        params: Vec<Variable>,
+        body: Block,
+    },
+    Variable {
+        var: Variable,
+        init: Option<ConstExpr>,
+        is_const: bool,
+    },
+    Dependency(Dependency),
+}
+
+#[derive(Debug, Clone)]
+pub struct Dependency {
+    pub name: String,
+    pub path: String,
+}
+
+#[allow(unused)]
+#[derive(Debug, Clone)]
+pub enum TypeId {
+    U8,
+    U16,
+    U32,
+    I8,
+    I16,
+    I32,
+    Char,
+    Void,
+    Ptr(Box<TypeId>),
+    Ref(Box<TypeId>),
+    Array(Box<TypeId>, usize),
+    Struct { name: Name, fields: Vec<Variable> },
+}
+
+pub type Block = Vec<Statement>;
+
+#[allow(unused)]
+#[derive(Debug, Clone)]
+pub struct Variable {
+    pub name: String,
+    pub type_id: TypeId,
+}
+
+#[allow(unused)]
+#[derive(Debug, Clone)]
+pub enum Statement {
+    Block(Block),
+    Declaration {
+        var: Variable,
+        value: Option<Expression>,
+    },
+    Assign {
+        varname: String,
+        value: Expression,
+    },
+    PtrWrite {
+        ptr: Expression,
+        value: Expression,
+    },
+    Expression {
+        expr: Expression,
+    },
+    If {
+        condition: Expression,
+        then_stmt: Block,
+        else_stmt: Block,
+    },
+    While {
+        condition: Expression,
+        body: Vec<Statement>,
+    },
+    Loop(Block),
+    Break,
+    Continue,
+    Return(Option<Expression>),
+}
+
+#[derive(Debug, Clone)]
+pub enum ConstExpr {
+    Number(i32),
+    String(String),
+}
+
+impl fmt::Display for ConstExpr {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match self {
+            ConstExpr::Number(n) => write!(f, "{}", n),
+            ConstExpr::String(s) => write!(f, "\"{}\"", s),
+        }
+    }
+}
+
+#[allow(unused)]
+#[derive(Debug, Clone)]
+pub enum Expression {
+    Empty,
+    Binary {
+        op: BinaryOperator,
+        left: Box<Expression>,
+        right: Box<Expression>,
+    },
+    Unary {
+        op: UnaryOperator,
+        operand: Box<Expression>,
+    },
+    Variable {
+        name: Name,
+        expr_type: Option<TypeId>,
+    },
+    Call {
+        name: Name,
+        args: Vec<Expression>,
+    },
+    Number(isize),
+    StringLiteral(String),
+    CharLiteral(char),
+}
+
+impl Expression {
+    pub fn is_pure(&self) -> bool {
+        match self {
+            Expression::Number(_) => true,
+            Expression::StringLiteral(_) => true,
+            Expression::CharLiteral(_) => true,
+            Expression::Call { .. } => false,
+            Expression::Binary { left, right, .. } => left.is_pure() && right.is_pure(),
+            Expression::Unary { operand, .. } => operand.is_pure(),
+            Expression::Empty => true,
+            Expression::Variable { .. } => true,
+        }
+    }
+}
+
+#[allow(unused)]
+#[derive(Debug, Clone, PartialEq)]
+pub enum BinaryOperator {
+    Add,
+    Sub,
+    Mul,
+    Div,
+    Eq,
+    Ne,
+    Lt,
+    Gt,
+    Le,
+    Ge,
+}
+
+impl fmt::Display for BinaryOperator {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match self {
+            BinaryOperator::Add => write!(f, "+"),
+            BinaryOperator::Sub => write!(f, "-"),
+            BinaryOperator::Mul => write!(f, "*"),
+            BinaryOperator::Div => write!(f, "/"),
+            BinaryOperator::Eq => write!(f, "=="),
+            BinaryOperator::Ne => write!(f, "!="),
+            BinaryOperator::Lt => write!(f, "<"),
+            BinaryOperator::Gt => write!(f, ">"),
+            BinaryOperator::Le => write!(f, "<="),
+            BinaryOperator::Ge => write!(f, ">="),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub enum UnaryOperator {
+    Plus,
+    Minus,
+    Reference,
+    Dereference,
+}
+
+impl fmt::Display for UnaryOperator {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match self {
+            UnaryOperator::Plus => write!(f, "+"),
+            UnaryOperator::Minus => write!(f, "-"),
+            UnaryOperator::Dereference => write!(f, "*"),
+            UnaryOperator::Reference => write!(f, "&"),
+        }
+    }
+}

compiler/src/specialised/brainf.rs

@@ -0,0 +1,135 @@
+#[must_use]
+pub fn build(src: &str) -> String {
+    parse(src).join("\n")
+}
+
+#[must_use]
+#[expect(clippy::too_many_lines)]
+pub fn parse(src: &str) -> Vec<String> {
+    let stack = "0x10000";
+    let acc = "acc";
+    let rga = "rga";
+
+    let bpr = "bpr";
+    let spr = "spr";
+    let mut instrs = Vec::<String>::new();
+
+    // Define symbols
+    let print_start = "print";
+
+    let tokens = lex(src);
+
+    let mut idstack = Vec::<u32>::new();
+
+    // set up a stack
+    instrs.push(format!("\tlwi {}, {}", stack, bpr));
+    instrs.push(format!("\tmov {}, {}", bpr, spr));
+    // set up the data pointer
+    instrs.push(format!("{}: \t lwi 0x30000, {}", "main", rga));
+
+    for (id, tok) in tokens.iter().enumerate() {
+        match tok {
+            BfToken::Inc => {
+                instrs.push(format!("\tinc {}", acc));
+            }
+            BfToken::Dec => {
+                instrs.push(format!("\tdec {}", acc));
+            }
+            BfToken::IncPtr => {
+                instrs.push(format!("\tstw {}, {}, 0", acc, rga));
+                instrs.push(format!("\taddi {}, 4, {}", rga, rga));
+                instrs.push(format!("\tlwd {}, {}, 0", rga, acc));
+            }
+            BfToken::DecPtr => {
+                instrs.push(format!("\tstw {}, {}, 0", acc, rga));
+                instrs.push(format!("\tsubi {}, 4, {}", rga, rga));
+                instrs.push(format!("\tlwd {}, {}, 0", rga, acc));
+            }
+            BfToken::Out => {
+                instrs.push(format!("\tpush {}", acc));
+                instrs.push(format!("\tcall {}", print_start));
+                instrs.push(format!("\tpop zero"));
+            }
+            BfToken::In => {
+                instrs.push(format!("\tlwd 0x40000, {}, 0", acc));
+            }
+            BfToken::Forward => {
+                let loop_start = format!("loop_start_{}", id);
+                let loop_end = format!("loop_end_{}", id);
+                idstack.push(id as u32);
+                instrs.push(format!("\tcmp {}, zero", acc));
+                instrs.push(format!("\tjeq {}, zero", loop_end));
+                instrs.push(format!("{}: \tnop", loop_start));
+            }
+            BfToken::Back => {
+                if let Some(start_id) = idstack.pop() {
+                    let loop_start = format!("loop_start_{}", start_id);
+                    let loop_end = format!("loop_end_{}", start_id);
+                    instrs.push(format!("\tcmp {}, zero", acc));
+                    instrs.push(format!("\tjne {}, zero", loop_start));
+                    instrs.push(format!("{}: \tnop", loop_end));
+                } else {
+                    eprintln!("Warning: Unmatched ']' at position {}", id);
+                }
+            }
+        }
+    }
+
+    instrs.push("\thlt".to_string());
+
+    insert_lib(&mut instrs);
+
+    instrs
+}
+
+fn insert_lib(instrs: &mut Vec<String>) {
+    let bpr = "bpr";
+    let spr = "spr";
+    let rg0 = "rg0";
+    let rg1 = "rg1";
+
+    let print_start = "print";
+    let current = "current";
+    instrs.push(format!("\tdw {}, 0x20000", current));
+    instrs.push(format!("{}: \tpush {}", print_start, bpr));
+    instrs.push(format!("\tmov {}, {}", spr, bpr));
+    instrs.push(format!("\tlwd {}, {}, 8", bpr, rg0));
+    instrs.push(format!("\tlwd {}, {}, 0", current, rg1));
+    instrs.push(format!("\tstb {}, {}, 0", rg0, rg1));
+    instrs.push(format!("\taddi {}, 1, {}", rg1, rg1));
+    instrs.push(format!("\tstw {}, {}, 0", rg1, current));
+    instrs.push(format!("\tmov {}, {}", bpr, spr));
+    instrs.push(format!("\tpop {}", bpr));
+    instrs.push("\treturn".to_string());
+}
+
+enum BfToken {
+    Inc,
+    Dec,
+    IncPtr,
+    DecPtr,
+    Out,
+    In,
+    Forward,
+    Back,
+}
+
+fn lex(src: &str) -> Vec<BfToken> {
+    src.chars()
+        .filter_map(|c| match c {
+            '+' => Some(BfToken::Inc),
+            '-' => Some(BfToken::Dec),
+            '>' => Some(BfToken::IncPtr),
+            '<' => Some(BfToken::DecPtr),
+            '.' => Some(BfToken::Out),
+            ',' => Some(BfToken::In),
+            '[' => Some(BfToken::Forward),
+            ']' => Some(BfToken::Back),
+            _ => None,
+        })
+        .collect()
+}
+
+fn _create_symbol(id: u32) -> String {
+    format!("label_{}", id)
+}

compiler/src/specialised/mod.rs

@@ -0,0 +1,13 @@
+use crate::model::CompilerError;
+
+pub mod brainf;
+
+pub fn build_specialised(ext: &str, data: &str) -> Option<Result<String, CompilerError>> {
+    match ext {
+        "bf" => {
+            let res = brainf::build(data);
+            Some(Ok(res))
+        }
+        _ => None,
+    }
+}

docs/DSA_ISA_Specification.md

@@ -0,0 +1,429 @@
+# DSA Instruction Set Architecture Specification
+
+## Overview
+
+The Damn Simple Architecture (DSA) is a 32-bit RISC-style architecture designed for simplicity and educational purposes. This document provides the complete instruction set architecture specification, including all hardware instructions, registers, and encoding formats.
+
+## Data Types and Sizes
+
+| Type | Size | Alignment |
+|------|------|-----------|
+| Byte | 8 bits | 1-byte aligned |
+| Halfword | 16 bits | 2-byte aligned |
+| Word | 32 bits | 4-byte aligned |
+
+**Note on Endianness:**
+- Instructions and numeric data in memory: Little-endian
+- Data defined via `db/dh/dw` directives: Big-endian (assembler-specific)
+
+## Registers
+
+DSA provides 32 programmer-accessible registers plus several internal system registers.
+
+### Programmer-Accessible Registers
+
+| Hex | Register | Type | Description |
+|-----|----------|------|-------------|
+| 0x00-0x0F | **rg0-rgf** | General Purpose | 16 general-purpose registers for variables and temporary values |
+| 0x10 | **acc** | Special | Accumulator for calculations and temporary storage<br/>⚠️ Used as scratch by pseudo-instructions - volatile |
+| 0x11 | **spr** | Special | Stack pointer - points to top of stack |
+| 0x12 | **bpr** | Special | Base pointer - used for stack frame management |
+| 0x13 | **ret** | Special | Return address register - used for function returns |
+| 0x14 | **idr** | Privileged | Interrupt descriptor table address<br/>Read/write triggers protection fault in user mode |
+| 0x15 | **mmr** | Privileged | Hardware memory map table address<br/>Read/write triggers protection fault in user mode |
+| 0x16 | **zero** | Read-only | Constant zero value<br/>Reads always return 0, writes are discarded |
+| 0x17 | **noreg** | Placeholder | Indicates unused register field<br/>Read/write triggers illegal instruction fault<br/>Can also be referenced as **null** |
+| 0x18-0x1F | - | Reserved | Reserved for future use |
+
+**System Registers (indices 0x18-0x1C):**
+These exist in the encoding space but are internal to the CPU implementation:
+
+| Hex | Register | Description |
+|-----|----------|-------------|
+| 0x18 | **mar** | Memory Address Register (CPU internal) |
+| 0x19 | **mdr** | Memory Data Register (CPU internal) |
+| 0x1A | **sts** | Status Register (CPU internal) |
+| 0x1B | **cir** | Current Instruction Register (CPU internal) |
+| 0x1C | **pcx** | Program Counter (read-only, special access) |
+
+**Note on PCX (Program Counter):**
+- PCX can be read in certain contexts (e.g., stored during CALL)
+- Writing to PCX triggers a protection fault
+- PCX is automatically updated by jump and branch instructions
+
+### Status Register (STS) Layout
+
+The status register is a 32-bit register with the following flag bits:
+
+| Bit | Name | Description | Boot Value |
+|-----|------|-------------|------------|
+| 0 | **Equal** | Set if last comparison result was equal | 0 |
+| 1 | **GreaterThan** | Set if last comparison result was greater than | 0 |
+| 2 | **GreaterThanOrEqual** | Set if last comparison was greater than or equal | 0 |
+| 3 | **LessThan** | Set if last comparison result was less than | 0 |
+| 4 | **LessThanOrEqual** | Set if last comparison was less than or equal | 0 |
+| 5 | **Zero** | Set if last arithmetic/logic operation result was zero | 0 |
+| 6-31 | - | Reserved | 0 |
+
+## Instruction Encoding Formats
+
+DSA uses three instruction encoding formats:
+
+### R-Type (Register) Instructions
+
+Used for operations with register operands only, including shifts.
+
+```
+ 31-26  |  25-21  |  20-16  |  15-11  |  10-6  |  5-0
+--------+---------+---------+---------+--------+-------
+ Opcode | SrcReg1 | SrcReg2 | DestReg | ShiftAmt | Unused
+```
+
+- **Opcode** (6 bits): Instruction operation code
+- **SrcReg1** (5 bits): First source register
+- **SrcReg2** (5 bits): Second source register  
+- **DestReg** (5 bits): Destination register
+- **ShiftAmt** (5 bits): Shift amount (for shift instructions only, must be 0 otherwise)
+- **Unused** (6 bits): Must be 0
+
+**Important Rules:**
+- ShiftAmt must be 0 for non-shift instructions (else illegal instruction fault)
+- Unused register fields must be set to `noreg` (0x17) if not used
+- Using registers in unexpected positions may cause illegal instruction fault
+
+### I-Type (Immediate) Instructions
+
+Used for operations with a 16-bit immediate value.
+
+```
+ 31-26  |  25-21  |  20-16  |    15-0
+--------+---------+---------+-------------
+ Opcode | SrcReg  | DestReg | 16-bit Immediate
+```
+
+- **Opcode** (6 bits): Instruction operation code
+- **SrcReg** (5 bits): Source register (base for memory ops)
+- **DestReg** (5 bits): Destination register (or offset register for jumps)
+- **Immediate** (16 bits): Signed 16-bit immediate value or offset
+
+**Usage:**
+- Arithmetic: Immediate is a signed value
+- Memory access: Immediate is a signed byte offset from base address
+- Branches: Immediate is a signed offset added to base register
+- Literal loads: Immediate is unsigned 16-bit value
+
+### J-Type (Jump) Instructions
+
+Used for absolute jumps with large address ranges.
+
+```
+ 31-26  |         25-0
+--------+----------------------
+ Opcode |   26-bit Address
+```
+
+- **Opcode** (6 bits): Jump instruction code
+- **Address** (26 bits): Partial address for jump
+
+**Address Calculation:**
+1. Left-shift the 26-bit address by 2 (word alignment)
+2. OR with upper 4 bits of current PCX
+3. Result is final 32-bit jump address
+
+**Jump Range:** 256MB region around current PC (±128MB)
+
+**Note:** J-type instructions are defined but currently unused. Use I-type JMP with register addressing for all jumps.
+
+## Hardware Instructions
+
+### Data Movement
+
+| Hex | Mnemonic | Type | Operands | Description |
+|-----|----------|------|----------|-------------|
+| 0x00 | **NOP** | R | - | No operation - does nothing |
+| 0x01 | **MOV** | R | SrcReg, DestReg | Copy value from SrcReg to DestReg |
+| 0x02 | **MOVS** | R | SrcReg, DestReg | Copy with sign extension to fill 32 bits |
+
+**MOV/MOVS Details:**
+- MOV performs direct copy (all 32 bits)
+- MOVS sign-extends the value (useful after byte/halfword loads)
+- Both instructions set the Zero flag if result is zero
+
+### Memory Access - Load Instructions
+
+All loads require proper alignment or trigger an alignment fault.
+
+| Hex | Mnemonic | Type | Operands | Description |
+|-----|----------|------|----------|-------------|
+| 0x03 | **LDB** | I | BaseReg, DestReg, Offset | Load byte (8-bit), zero-extend to 32 bits |
+| 0x04 | **LDBS** | I | BaseReg, DestReg, Offset | Load byte (8-bit), sign-extend to 32 bits |
+| 0x05 | **LDH** | I | BaseReg, DestReg, Offset | Load halfword (16-bit), zero-extend to 32 bits |
+| 0x06 | **LDHS** | I | BaseReg, DestReg, Offset | Load halfword (16-bit), sign-extend to 32 bits |
+| 0x07 | **LDW** | I | BaseReg, DestReg, Offset | Load word (32-bit) |
+
+**Load Operation:**
+- Effective address = BaseReg + SignExtend(Offset)
+- Offset is a signed 16-bit value
+- Alignment requirements:
+  - LDB/LDBS: No alignment required (byte-aligned)
+  - LDH/LDHS: Must be 2-byte aligned
+  - LDW: Must be 4-byte aligned
+
+**Encoding Note:** 
+In machine code, the order is: BaseReg (SrcReg field), DestReg field, Offset (Immediate field)
+
+### Memory Access - Store Instructions
+
+All stores require proper alignment or trigger an alignment fault.
+
+| Hex | Mnemonic | Type | Operands | Description |
+|-----|----------|------|----------|-------------|
+| 0x08 | **STB** | I | SrcReg, BaseReg, Offset | Store byte (8-bit) to memory |
+| 0x09 | **STH** | I | SrcReg, BaseReg, Offset | Store halfword (16-bit) to memory |
+| 0x0A | **STW** | I | SrcReg, BaseReg, Offset | Store word (32-bit) to memory |
+
+**Store Operation:**
+- Effective address = BaseReg + SignExtend(Offset)
+- Offset is a signed 16-bit value
+- Only the relevant bits are stored (8, 16, or 32)
+- Alignment requirements:
+  - STB: No alignment required (byte-aligned)
+  - STH: Must be 2-byte aligned
+  - STW: Must be 4-byte aligned
+
+**Encoding Note:**
+In machine code: SrcReg (SrcReg field), BaseReg (DestReg field), Offset (Immediate field)
+
+### Immediate Load Instructions
+
+| Hex | Mnemonic | Type | Operands | Description |
+|-----|----------|------|----------|-------------|
+| 0x0B | **LLI** | I | Value, DestReg | Load 16-bit value into lower 16 bits<br/>⚠️ **CLEARS upper 16 bits!** |
+| 0x0C | **LUI** | I | Value, DestReg | Load 16-bit value into upper 16 bits<br/>Lower 16 bits unchanged |
+
+**Usage for 32-bit Values:**
+```
+LLI 0x1234, rg0    ; rg0 = 0x00001234
+LUI 0xABCD, rg0    ; rg0 = 0xABCD1234
+```
+
+**⚠️ CRITICAL:** Always execute LLI before LUI, as LLI clears the upper 16 bits!
+
+**Note on LUI:** The assembler may shift the immediate value right by 16 bits when encoding, so specify the upper 16 bits directly (e.g., `LUI 0xABCD, rg0` not `LUI 0xABCD0000, rg0`).
+
+**Encoding Note:**
+In machine code: Value (Immediate field), DestReg (SrcReg field for LLI, SrcReg field for LUI)
+
+### Jump and Branch Instructions
+
+| Hex | Mnemonic | Type | Operands | Description |
+|-----|----------|------|----------|-------------|
+| 0x0D | **JMP** | I | Offset, BaseReg | Unconditional jump to (BaseReg + Offset) |
+| 0x0E | **JEQ** | I | Offset, BaseReg | Jump if Equal flag set |
+| 0x0F | **JNE** | I | Offset, BaseReg | Jump if Equal flag NOT set |
+| 0x10 | **JGT** | I | Offset, BaseReg | Jump if GreaterThan flag set |
+| 0x11 | **JGE** | I | Offset, BaseReg | Jump if GreaterThan OR Equal flag set |
+| 0x12 | **JLT** | I | Offset, BaseReg | Jump if LessThan flag set |
+| 0x13 | **JLE** | I | Offset, BaseReg | Jump if LessThan OR Equal flag set |
+
+**Jump Calculation:**
+- Target address = BaseReg + SignExtend(Offset)
+- If BaseReg = zero, this becomes absolute addressing with Offset
+- If BaseReg = ret, this becomes return-style addressing
+- Conditional jumps check flags in STS register
+
+**Common Patterns:**
+```
+JMP label, zero     ; Absolute jump to label address
+JMP 0, ret          ; Jump to address in ret register
+JMP 4, ret          ; Jump to (ret + 4)
+```
+
+**Encoding Note:**
+In machine code: Offset (Immediate field), BaseReg (SrcReg field) (DestReg unused, set to noreg)
+
+### Comparison
+
+| Hex | Mnemonic | Type | Operands | Description |
+|-----|----------|------|----------|-------------|
+| 0x14 | **CMP** | R | Reg1, Reg2 | Compare Reg1 with Reg2, set flags in STS |
+
+**Flag Setting:**
+- Equal: Set if Reg1 == Reg2
+- GreaterThan: Set if Reg1 > Reg2 (signed)
+- GreaterThanOrEqual: Set if Reg1 >= Reg2 (signed)
+- LessThan: Set if Reg1 < Reg2 (signed)
+- LessThanOrEqual: Set if Reg1 <= Reg2 (signed)
+- Zero: Set if (Reg1 - Reg2) == 0 (same as Equal)
+
+**Encoding Note:**
+DestReg and ShiftAmt fields unused (set to noreg and 0)
+
+### Arithmetic Instructions
+
+| Hex | Mnemonic | Type | Operands | Description |
+|-----|----------|------|----------|-------------|
+| 0x15 | **INC** | R | Reg | Increment register by 1 |
+| 0x16 | **DEC** | R | Reg | Decrement register by 1 |
+| 0x19 | **ADD** | R | Src1, Src2, Dest | Dest = Src1 + Src2 |
+| 0x1A | **SUB** | R | Src1, Src2, Dest | Dest = Src1 - Src2 |
+| 0x25 | **IADD** | I | Src, Literal, Dest | Dest = Src + SignExtend(Literal) |
+| 0x26 | **ISUB** | I | Src, Literal, Dest | Dest = Src - SignExtend(Literal) |
+
+**Flag Effects:**
+- Zero flag set if result is zero
+- Other flags undefined after arithmetic (use CMP for comparisons)
+
+**Encoding Notes:**
+- INC/DEC: Reg in SrcReg1 field, DestReg set to noreg
+- IADD/ISUB: Immediate is signed 16-bit value, all three operands required
+
+### Bitwise Logical Operations
+
+| Hex | Mnemonic | Type | Operands | Description |
+|-----|----------|------|----------|-------------|
+| 0x1B | **AND** | R | Src1, Src2, Dest | Dest = Src1 & Src2 (bitwise AND) |
+| 0x1C | **OR** | R | Src1, Src2, Dest | Dest = Src1 \| Src2 (bitwise OR) |
+| 0x1D | **NOT** | R | Src, Dest | Dest = ~Src (bitwise NOT) |
+| 0x1E | **XOR** | R | Src1, Src2, Dest | Dest = Src1 ^ Src2 (bitwise XOR) |
+| 0x1F | **NAND** | R | Src1, Src2, Dest | Dest = ~(Src1 & Src2) (bitwise NAND) |
+| 0x20 | **NOR** | R | Src1, Src2, Dest | Dest = ~(Src1 \| Src2) (bitwise NOR) |
+| 0x21 | **XNOR** | R | Src1, Src2, Dest | Dest = ~(Src1 ^ Src2) (bitwise XNOR) |
+
+**Flag Effects:**
+- Zero flag set if result is zero
+- Other flags undefined
+
+**Encoding Note:**
+NOT uses only Src (SrcReg1) and Dest (DestReg); SrcReg2 unused (set to noreg)
+
+### Shift Operations
+
+| Hex | Mnemonic | Type | Operands | Description |
+|-----|----------|------|----------|-------------|
+| 0x17 | **SHL** | R | Reg, ShiftAmount | Shift Reg left by ShiftAmount bits<br/>Zero-fill from right |
+| 0x18 | **SHR** | R | Reg, ShiftAmount | Shift Reg right by ShiftAmount bits<br/>Zero-fill from left (logical shift) |
+
+**Shift Amount:**
+- **Literal shifts**: ShiftAmount is a 5-bit literal (0-31) in assembly
+  - Stored in ShiftAmt field of instruction
+  - SrcReg2 set to noreg
+- **Register shifts**: ShiftAmount is a register containing shift value
+  - Register specified in SrcReg2 field
+  - ShiftAmt field must be 0
+  - Only low 5 bits of register value used
+
+**Note:** Current assembler implementation may only support literal shifts. Check assembler documentation.
+
+**Flag Effects:**
+- Zero flag set if result is zero
+
+**Encoding Notes:**
+- Reg in both SrcReg1 and DestReg fields (shifted in place)
+- For literal shifts: ShiftAmt field contains shift count, SrcReg2 = noreg
+- For register shifts: SrcReg2 contains register, ShiftAmt must be 0
+
+### System and Control Instructions
+
+| Hex | Mnemonic | Type | Operands | Description |
+|-----|----------|------|----------|-------------|
+| 0x22 | **INT** | I | InterruptCode | Trigger interrupt with 8-bit code<br/>Saves return address to ret register<br/>Sets bpr to kernel stack |
+| 0x23 | **IRT** | R | - | Return from interrupt<br/>Restores execution context |
+| 0x24 | **HLT** | R | - | Halt processor execution<br/>Stops fetch-decode-execute cycle |
+
+**INT Behavior:**
+1. Save current PCX to ret register
+2. Switch bpr to kernel stack address
+3. Look up interrupt handler address in interrupt descriptor table (idr)
+4. Jump to handler at interrupt vector
+
+**IRT Behavior:**
+1. Restore previous execution context
+2. Return to address in ret register
+3. Restore user stack pointer
+
+**Encoding Notes:**
+- INT: InterruptCode in low 8 bits of Immediate field
+- IRT/HLT: All register fields set to noreg, ShiftAmt to 0
+
+### Meta Instructions (Assembler/Linker)
+
+These instructions are used by the assembler and linker but may not represent real CPU operations.
+
+| Hex | Mnemonic | Description |
+|-----|----------|-------------|
+| 0x27 | **SEGMENT** | Segment marker (implementation-specific) |
+| 0x3E | **DATA** | Raw data embedding |
+
+**Note:** The SEGMENT instruction opcode may vary between implementations (0x27 in assembler, 0x3F in some contexts). Consult your specific toolchain documentation.
+
+## Instruction Summary Table
+
+| Opcode | Mnemonic | Type | Category |
+|--------|----------|------|----------|
+| 0x00 | NOP | R | Control |
+| 0x01 | MOV | R | Data Movement |
+| 0x02 | MOVS | R | Data Movement |
+| 0x03 | LDB | I | Memory Load |
+| 0x04 | LDBS | I | Memory Load |
+| 0x05 | LDH | I | Memory Load |
+| 0x06 | LDHS | I | Memory Load |
+| 0x07 | LDW | I | Memory Load |
+| 0x08 | STB | I | Memory Store |
+| 0x09 | STH | I | Memory Store |
+| 0x0A | STW | I | Memory Store |
+| 0x0B | LLI | I | Immediate Load |
+| 0x0C | LUI | I | Immediate Load |
+| 0x0D | JMP | I | Jump |
+| 0x0E | JEQ | I | Branch |
+| 0x0F | JNE | I | Branch |
+| 0x10 | JGT | I | Branch |
+| 0x11 | JGE | I | Branch |
+| 0x12 | JLT | I | Branch |
+| 0x13 | JLE | I | Branch |
+| 0x14 | CMP | R | Comparison |
+| 0x15 | INC | R | Arithmetic |
+| 0x16 | DEC | R | Arithmetic |
+| 0x17 | SHL | R | Shift |
+| 0x18 | SHR | R | Shift |
+| 0x19 | ADD | R | Arithmetic |
+| 0x1A | SUB | R | Arithmetic |
+| 0x1B | AND | R | Logical |
+| 0x1C | OR | R | Logical |
+| 0x1D | NOT | R | Logical |
+| 0x1E | XOR | R | Logical |
+| 0x1F | NAND | R | Logical |
+| 0x20 | NOR | R | Logical |
+| 0x21 | XNOR | R | Logical |
+| 0x22 | INT | I | System |
+| 0x23 | IRT | R | System |
+| 0x24 | HLT | R | System |
+| 0x25 | IADD | I | Arithmetic |
+| 0x26 | ISUB | I | Arithmetic |
+| 0x27 | SEGMENT | - | Meta |
+| 0x3E | DATA | - | Meta |
+
+## Exception Conditions
+
+The following conditions trigger exceptions:
+
+| Exception | Trigger Condition |
+|-----------|------------------|
+| **Illegal Instruction** | - Invalid opcode<br/>- noreg used as source/destination<br/>- ShiftAmt non-zero for non-shift instruction<br/>- Register field violations |
+| **Protection Fault** | - Write to pcx register<br/>- Read/write idr or mmr in user mode<br/>- Read from noreg<br/>- Write to zero register (discarded, no fault) |
+| **Alignment Fault** | - LDH/LDHS/STH with odd address<br/>- LDW/STW with address not divisible by 4 |
+| **Memory Access Violation** | - Access to unmapped or protected memory<br/>- Stack overflow/underflow |
+
+## Calling Convention
+
+See the DSA Assembly Language Reference for the complete calling convention and ABI specification.
+
+## Notes on Design
+
+1. **Word Size:** All addresses and general computation is 32-bit
+2. **Endianness:** Little-endian for instructions and runtime data; assembler data directives may use big-endian
+3. **Stack Growth:** Stack grows **downward** (toward lower addresses) - PUSH decrements SPR
+4. **Alignment:** Natural alignment required for halfword and word accesses
+5. **Sign Extension:** All immediate values are sign-extended unless noted
+6. **Zero Register:** Provides constant zero, writes are legal but discarded
+7. **Reserved Encodings:** Opcodes 0x27-0x3D and 0x3F reserved or implementation-specific

docs/DSA_Project_Roadmap.md

@@ -0,0 +1,875 @@
+# DSA Project Roadmap & Task Breakdown
+
+> **Damn Simple Architecture** — Full ecosystem development plan including emulator, assembler, compiler, debugger, and tooling infrastructure.
+
+---
+
+## Table of Contents
+
+1. [Phase 1: Foundation & Core Infrastructure](#phase-1-foundation--core-infrastructure)
+   - [1.1 Binary Format & Linking System](#11-binary-format--linking-system)
+   - [1.2 Assembler Rewrite](#12-assembler-rewrite)
+   - [1.3 Documentation Updates](#13-documentation-updates)
+2. [Phase 2: Compiler Development](#phase-2-compiler-development)
+   - [2.1 Language Design & Implementation](#21-language-design--implementation)
+   - [2.2 Standard Library](#22-standard-library)
+3. [Phase 3: Build System & Package Management](#phase-3-build-system--package-management)
+   - [3.1 Build System](#31-build-system)
+   - [3.2 Package Management System](#32-package-management-system)
+4. [Phase 4: Debugger & Development Tools](#phase-4-debugger--development-tools)
+   - [4.1 Debug Symbol System](#41-debug-symbol-system)
+   - [4.2 Debugger Implementation](#42-debugger-implementation)
+   - [4.3 Enhanced Editor Integration](#43-enhanced-editor-integration)
+5. [Phase 5: Integration & Polish](#phase-5-integration--polish)
+6. [Phase 6: Future Enhancements (NTH)](#phase-6-future-enhancements-nth)
+7. [Summary Timeline](#summary-timeline)
+8. [Critical Path](#critical-path)
+9. [Recommended Work Order](#recommended-work-order)
+
+---
+
+## Phase 1: Foundation & Core Infrastructure
+
+**Estimated Duration: 3–4 weeks**
+
+---
+
+### 1.1 Binary Format & Linking System
+
+> **Priority: CRITICAL** — Everything depends on this.  
+> **Total Estimate: 1.5 weeks**
+
+---
+
+#### 1.1.1 Design New Binary Format Specification
+
+**Estimate: 2 days**  
+**Dependencies:** None  
+**Deliverable:** `docs/binary-format-spec.md`
+
+- [ ] Research existing object file formats (ELF, COFF, Mach-O) for inspiration
+- [ ] Design `.dsb` object file format specification
+  - [ ] Symbol table structure
+  - [ ] Relocation table format
+  - [ ] Section definitions (code, data, rodata, bss)
+  - [ ] Debug information structure
+  - [ ] Metadata headers
+- [ ] Design `.dse` executable format specification
+  - [ ] Entry point definition
+  - [ ] Memory layout requirements
+  - [ ] Linking metadata
+- [ ] Document format specifications in markdown
+- [ ] Create format version strategy for future compatibility
+
+---
+
+#### 1.1.2 Implement DSB Object File Writer
+
+**Estimate: 3 days**  
+**Dependencies:** 1.1.1  
+**Deliverable:** `dsa-binary-format` crate v0.1.0
+
+- [ ] Create new crate: `dsa-binary-format`
+- [ ] Implement object file structures
+  - [ ] Header structure
+  - [ ] Symbol table builder
+  - [ ] Section manager
+  - [ ] Relocation entry creator
+- [ ] Write serialization logic
+- [ ] Add validation and error handling
+- [ ] Write unit tests for each structure
+- [ ] Integration tests for complete object files
+
+---
+
+#### 1.1.3 Build Linker Program
+
+**Estimate: 4 days**  
+**Dependencies:** 1.1.2  
+**Deliverable:** `dsa-link` executable
+
+- [ ] Create new crate: `dsa-linker`
+- [ ] Implement symbol resolution
+  - [ ] Global symbol table
+  - [ ] Symbol conflict detection
+  - [ ] Weak symbol handling
+- [ ] Implement relocation processing
+  - [ ] Address calculation
+  - [ ] Patch generation
+  - [ ] Cross-section references
+- [ ] Build executable generator
+  - [ ] Combine sections
+  - [ ] Generate final memory layout
+  - [ ] Write `.dse` output
+- [ ] Add linker script support (basic)
+- [ ] Comprehensive error messages
+- [ ] Test suite with complex linking scenarios
+
+---
+
+### 1.2 Assembler Rewrite
+
+> **Priority: HIGH** — Required for all compiled code.  
+> **Total Estimate: 1.5 weeks**
+
+---
+
+#### 1.2.1 Assembler Architecture Design
+
+**Estimate: 1 day**  
+**Dependencies:** 1.1.1  
+**Deliverable:** `docs/assembler-architecture.md`
+
+- [ ] Design multi-pass architecture
+  - [ ] Pass 1: Symbol collection
+  - [ ] Pass 2: Macro expansion
+  - [ ] Pass 3: Code generation
+  - [ ] Pass 4: Relocation generation
+- [ ] Plan error handling strategy
+- [ ] Design threading model for parallel file processing
+- [ ] Define module/import resolution system
+- [ ] Plan integration points with DSC compiler
+
+---
+
+#### 1.2.2 Implement Core Assembler
+
+**Estimate: 5 days**  
+**Dependencies:** 1.1.2, 1.2.1  
+**Deliverable:** `dsa-asm` executable v2.0.0
+
+- [ ] Create new crate: `dsa-assembler-ng` (next-gen)
+- [ ] Implement lexer with better error recovery
+- [ ] Build parser with detailed error messages
+  - [ ] Instruction parsing
+  - [ ] Directive handling
+  - [ ] Macro system
+  - [ ] Include resolution
+- [ ] Symbol table management
+- [ ] Code generator outputting to DSB format
+- [ ] Multi-threading for file parsing
+- [ ] Comprehensive test suite
+- [ ] Error message testing
+
+---
+
+#### 1.2.3 Import System & DSC Integration
+
+**Estimate: 2 days**  
+**Dependencies:** 1.2.2, 2.1.2  
+**Deliverable:** Working import system
+
+- [ ] Design import protocol between DSC and assembler
+- [ ] Implement symbol table merging
+- [ ] Handle pre-compiled object imports
+- [ ] Test DSC → Assembly → Object pipeline
+- [ ] Document integration process
+
+---
+
+### 1.3 Documentation Updates
+
+> **Priority: MEDIUM** — Can be done alongside development.  
+> **Total Estimate: 3 days (distributed)**
+
+---
+
+#### 1.3.1 Update Assembly Documentation
+
+**Estimate: 1 day**  
+**Dependencies:** 1.2.2  
+**Deliverable:** Updated `docs/dsa-assembly-reference.md`
+
+- [ ] Review all instruction documentation
+- [ ] Document new pseudo-instructions
+- [ ] Update calling convention docs
+- [ ] Add examples for new features
+- [ ] Document assembler directives
+- [ ] Macro system documentation
+
+---
+
+#### 1.3.2 Architecture Documentation
+
+**Estimate: 1 day**  
+**Dependencies:** None (can start anytime)  
+**Deliverable:** `docs/dsa-architecture.md`
+
+- [ ] Document ISA specification
+- [ ] Memory model documentation
+- [ ] Interrupt handling
+- [ ] Hardware peripheral specs
+- [ ] Timing/performance characteristics
+
+---
+
+#### 1.3.3 Build Tools Documentation
+
+**Estimate: 1 day**  
+**Dependencies:** 1.2.2, 1.1.3, 3.1.2  
+**Deliverable:** `docs/build-tools-guide.md`
+
+- [ ] Assembler usage guide
+- [ ] Linker usage guide
+- [ ] Build system guide
+- [ ] Tutorial: Building a simple program
+- [ ] Tutorial: Multi-file projects
+
+---
+
+## Phase 2: Compiler Development
+
+**Estimated Duration: 3–4 weeks**
+
+---
+
+### 2.1 Language Design & Implementation
+
+> **Priority: HIGH** — Core functionality.  
+> **Total Estimate: 2.5 weeks**
+
+---
+
+#### 2.1.1 Language Syntax Design
+
+**Estimate: 2 days**  
+**Dependencies:** None  
+**Deliverable:** `docs/language-spec.md`
+
+- [x] Define syntax goals (simplicity, systems programming)
+- [ ] Design type system
+  - [x] Primitive types
+  - [x] Pointers/references
+  - [ ] Structs
+  - [ ] Arrays
+  - [x] Function types
+- [x] Control flow syntax
+- [x] Function declaration syntax
+- [x] Module/import system
+- [x] Operator precedence
+- [ ] Write EBNF grammar
+- [x] Create example programs
+
+---
+
+#### 2.1.2 Lexer & Parser Implementation
+
+**Estimate: 4 days**  
+**Dependencies:** 2.1.1  
+**Deliverable:** Parser in `dsc-compiler` crate
+
+- [x] Adapt existing C lexer to new syntax
+- [ ] Implement new parser for designed syntax
+  - [ ] Array syntax
+  - [ ] Struct syntax
+  - [x] Pointer syntax
+  - [x] Namespaced call syntax
+- [x] AST node definitions
+- [ ] Error recovery mechanisms
+- [ ] Comprehensive parser tests
+- [ ] Syntax error message quality testing
+- [x] Implement C frontend by moving lexer/parser from `c_compiler` to the new `compiler` project structure
+- [ ] Evaluate possible memory management strategies (e.g., keep all variables on the stack vs spill only when calling functions)
+
+---
+
+#### 2.1.3 Code Generation Improvements
+
+**Estimate: 5 days**  
+**Dependencies:** 2.1.2, 1.2.2  
+**Deliverable:** Working code generator
+
+- [x] Review and fix existing codegen issues
+- [ ] Implement missing language features
+  - [ ] Structs
+  - [ ] Arrays
+  - [x] Pointers/memory operations
+  - [ ] For loops
+  - [ ] Switch statements
+  - [ ] Break/continue
+- [ ] Optimize register allocation further
+- [x] Implement proper function calling conventions
+- [ ] Add constant folding optimization
+- [x] Dead code elimination
+- [ ] Test each feature thoroughly
+
+---
+
+#### 2.1.4 Type Checking & Semantic Analysis
+
+**Estimate: 3 days**  
+**Dependencies:** 2.1.2  
+**Deliverable:** Type checker integrated in compiler
+
+- [ ] Implement type checker
+- [ ] Symbol table for scoping
+- [ ] Type inference where applicable
+- [ ] Const checking
+- [ ] Definite assignment analysis
+- [ ] Comprehensive semantic error messages
+- [ ] Test suite for type errors
+
+---
+
+### 2.2 Standard Library
+
+> **Priority: MEDIUM** — Needed for useful programs.  
+> **Total Estimate: 1 week**
+
+---
+
+#### 2.2.1 Core Runtime Library (in Assembly)
+
+**Estimate: 3 days**  
+**Dependencies:** 1.2.2  
+**Deliverable:** `lib/runtime/` directory
+
+- [ ] Memory allocation (malloc/free)
+- [ ] String operations
+- [ ] Math functions
+  - [x] Multiply
+  - [ ] Divide (fix as very slow and broken)
+- [ ] I/O functions (improved print, read)
+  - [x] Print number
+  - [x] Print hex value
+  - [x] Print word
+  - [x] Print byte
+  - [x] Print from string ptr
+  - [x] Print whitespace and newline
+  - [x] Reset display
+  - [x] Reset cursor
+- [ ] System call interface
+- [ ] Tests for each function
+
+---
+
+#### 2.2.2 Standard Library (in DSC)
+
+**Estimate: 2 days**  
+**Dependencies:** 2.1.3, 2.2.1  
+**Deliverable:** `lib/std/` directory
+
+- [ ] String module
+- [ ] Collections (array utilities, maybe simple list)
+- [ ] File I/O module
+- [ ] Math utilities
+- [ ] Tests and examples
+
+---
+
+## Phase 3: Build System & Package Management
+
+**Estimated Duration: 2–3 weeks**
+
+---
+
+### 3.1 Build System
+
+> **Priority: HIGH** — Required for complex projects.  
+> **Total Estimate: 1.5 weeks**
+
+---
+
+#### 3.1.1 Build System Design
+
+**Estimate: 1 day**  
+**Dependencies:** None  
+**Deliverable:** `docs/build-system-design.md`
+
+- [x] Define project structure conventions
+- [ ] Design build manifest format (`dsa-project.toml` or similar)
+- [ ] Dependency resolution strategy
+- [ ] Build cache design
+- [ ] Incremental build strategy
+- [ ] Multi-target support
+
+---
+
+#### 3.1.2 Build Tool Implementation
+
+**Estimate: 5 days**  
+**Dependencies:** 3.1.1, 1.2.2, 1.1.3, 2.1.3  
+**Deliverable:** `dsa-build` executable
+
+- [x] Create crate: `dsa-build`
+- [ ] Manifest parser
+- [ ] Dependency graph builder
+- [ ] Task orchestrator
+  - [x] Compilation tasks
+  - [x] Assembly tasks
+  - [ ] Linking tasks
+- [ ] Build cache implementation
+- [ ] Parallel build support
+- [ ] Clean, rebuild commands
+- [ ] Watch mode for development
+- [ ] Comprehensive tests
+
+---
+
+#### 3.1.3 Project Management Commands
+
+**Estimate: 2 days**  
+**Dependencies:** 3.1.2  
+**Deliverable:** Enhanced `dsa-build` with project management
+
+- [x] `dsa new <project>` — Create new project
+- [x] `dsa init` — Initialize in existing directory
+- [ ] `dsa add <dependency>` — Add dependency
+- [ ] Binary vs library project types
+- [x] Template system for project scaffolding
+- [ ] Documentation for each command
+
+---
+
+### 3.2 Package Management System
+
+> **Priority: MEDIUM** — Enables code sharing.  
+> **Total Estimate: 1.5 weeks**
+
+---
+
+#### 3.2.1 Package Registry Design
+
+**Estimate: 2 days**  
+**Dependencies:** 3.1.1  
+**Deliverable:** `docs/package-registry-design.md`
+
+- [ ] Decide: Git monorepo vs custom hosting
+- [ ] Design package naming conventions
+- [ ] Version resolution strategy (semver)
+- [ ] Package manifest format
+- [ ] Security considerations
+- [ ] Package storage format (source/binary/both)
+- [ ] API design for registry server
+
+---
+
+#### 3.2.2 Local Package Manager Tool
+
+**Estimate: 4 days**  
+**Dependencies:** 3.2.1, 3.1.2  
+**Deliverable:** `dsa-pkg` tool integrated with `dsa-build`
+
+- [ ] Create crate: `dsa-pkg`
+- [ ] Package index synchronization
+- [ ] Dependency resolver
+- [ ] Package download/cache system
+- [ ] Integration with build system
+- [ ] Commands:
+  - [ ] `dsa install <package>`
+  - [ ] `dsa publish`
+  - [ ] `dsa search <query>`
+  - [ ] `dsa update`
+- [ ] Lock file generation
+- [ ] Test with mock registry
+
+---
+
+#### 3.2.3 Package Registry Implementation
+
+**Estimate: 3 days**  
+**Dependencies:** 3.2.1  
+**Deliverable:** Package registry (URL or repo)
+
+- [ ] If **Git monorepo** approach:
+  - [ ] Set up repository structure
+  - [ ] CI/CD for validation
+  - [ ] Submission process
+  - [ ] Package browser website
+- [ ] If **custom hosting**:
+  - [ ] Simple web server (Rust + Axum/Actix)
+  - [ ] Package upload API
+  - [ ] Package search API
+  - [ ] Basic web UI
+  - [ ] Database for metadata
+- [ ] Documentation for publishing
+
+---
+
+## Phase 4: Debugger & Development Tools
+
+**Estimated Duration: 3–4 weeks**
+
+---
+
+### 4.1 Debug Symbol System
+
+> **Priority: HIGH** — Foundation for debugging.  
+> **Total Estimate: 1 week**
+
+---
+
+#### 4.1.1 Debug Symbol Format Design
+
+**Estimate: 1 day**  
+**Dependencies:** 1.1.1  
+**Deliverable:** `docs/debug-symbol-format.md`
+
+- [ ] Design symbol table format
+  - [ ] Function addresses → names
+  - [ ] Line number → address mapping
+  - [ ] Variable location information
+  - [ ] Type information
+- [ ] Define symbol table file format
+- [ ] Plan for embedding in DSE/DSB files
+
+---
+
+#### 4.1.2 Symbol Generation in Tools
+
+**Estimate: 3 days**  
+**Dependencies:** 4.1.1, 1.2.2, 2.1.3  
+**Deliverable:** Debug symbols in build output
+
+- [ ] Modify assembler to emit debug symbols
+- [ ] Modify compiler to emit debug symbols
+  - [ ] Source file/line tracking
+  - [ ] Variable scope tracking
+- [ ] Linker merges debug symbols
+- [ ] Test symbol generation pipeline
+
+---
+
+#### 4.1.3 Symbol Table Loader in Emulator
+
+### Pre-Debugger Editor Integration Tasks
+
+- **Integrate compiler into editor**  
+  - Add a build command that invokes the full compiler pipeline (lexer → parser → codegen).  
+  - Show compilation output and errors in the console panel.  
+
+- **DSC language support**  
+  - Enable syntax highlighting and auto‑completion for DSC files within the editor.  
+  - Provide a dedicated “Build DSC” command that uses the integrated compiler.  
+
+- **Editor diagnostics**  
+  - Wire compiler error messages to the editor’s gutter so users can click to jump to source lines.  
+
+
+**Estimate: 2 days**  
+**Dependencies:** 4.1.2  
+**Deliverable:** Symbol loading in emulator crate
+
+- [ ] Implement symbol table parser
+- [ ] Build address → symbol lookup (HashMap)
+- [ ] Build symbol → address lookup
+- [ ] Memory efficient storage
+- [ ] Tests for symbol resolution
+
+---
+
+### 4.2 Debugger Implementation
+
+> **Priority: HIGH** — Major productivity boost.  
+> **Total Estimate: 2 weeks**
+
+---
+
+#### 4.2.1 Core Debugger Features
+
+**Estimate: 5 days**  
+**Dependencies:** 4.1.3  
+**Deliverable:** Debugger backend
+
+- [ ] Execution control
+  - [ ] Step instruction
+  - [ ] Step over function calls
+  - [ ] Continue to breakpoint
+  - [ ] Run to cursor
+- [ ] Breakpoint system
+  - [ ] Address breakpoints
+  - [ ] Conditional breakpoints
+  - [ ] Watchpoints (memory access)
+- [ ] Register inspection
+- [ ] Memory inspection
+- [ ] Stack trace generation
+- [ ] Test debugger commands
+
+---
+
+#### 4.2.2 Disassembler with Symbol Resolution
+
+**Estimate: 3 days**  
+**Dependencies:** 4.1.3  
+**Deliverable:** Enhanced disassembler
+
+- [ ] Instruction decoder
+- [ ] Format with labels instead of addresses
+- [ ] Show function names at call sites
+- [ ] Inline comments with variable names
+- [ ] Color coding for instruction types
+- [ ] Tests for disassembly output
+
+---
+
+#### 4.2.3 Pseudo-Instruction Decompiler
+
+> ⚠️ **COMPLEX TASK** — Separate pass to decompile assembly into readable pseudo-instructions.
+
+**Estimate: 4 days**  
+**Dependencies:** 4.2.2  
+**Deliverable:** Pseudo-instruction view mode
+
+- [ ] Pattern recognition for common sequences
+  - [ ] Function prologue/epilogue
+  - [ ] Multiplication using shifts/adds
+  - [ ] Division
+  - [ ] Conditional moves
+- [ ] Control flow reconstruction
+  - [ ] If/else detection
+  - [ ] Loop detection
+  - [ ] Switch statement detection
+- [ ] Expression reconstruction
+- [ ] Format as higher-level pseudo-code
+- [ ] Extensive pattern testing
+
+---
+
+#### 4.2.4 Execution History Tracking
+
+**Estimate: 2 days**  
+**Dependencies:** 4.2.1  
+**Deliverable:** Execution trace feature
+
+- [ ] Circular buffer for instruction history
+- [ ] Register state snapshots over time
+- [ ] Configurable history depth
+- [ ] Efficient memory usage
+- [ ] Playback/reverse debugging (basic)
+- [ ] Export trace to file
+
+---
+
+### 4.3 Enhanced Editor Integration
+
+> **Priority: MEDIUM** — UX improvement.  
+> **Total Estimate: 1 week**
+
+---
+
+#### 4.3.1 Tiling Window System
+
+**Estimate: 2 days**  
+**Dependencies:** None (UI work)  
+**Deliverable:** Panel system in emulator
+
+- [ ] Research Rust tiling libraries (`egui_tiles`, or custom)
+- [ ] Design panel layout system
+  - [ ] Code editor panel
+  - [ ] Disassembly panel
+  - [ ] Register panel
+  - [ ] Memory panel
+  - [ ] Console panel
+- [ ] Implement drag-and-drop panel management
+- [ ] Save/load layouts
+
+---
+
+#### 4.3.2 Assembly Editor Improvements
+
+**Estimate: 2 days**  
+**Dependencies:** 4.3.1  
+**Deliverable:** Enhanced assembly editor
+
+- [ ] Syntax highlighting for DSA assembly
+- [ ] Auto-completion for instructions
+- [ ] Label/symbol auto-completion
+- [ ] Error highlighting
+- [ ] Inline documentation tooltips
+- [ ] Jump-to-definition for labels
+
+---
+
+#### 4.3.3 High-Level Language Editor
+
+**Estimate: 2 days**  
+**Dependencies:** 4.3.1, 2.1.4  
+**Deliverable:** DSC language editor
+
+- [ ] Syntax highlighting for DSC language
+- [ ] Basic auto-completion
+- [ ] Bracket matching
+- [ ] Error highlighting from compiler
+- [ ] Go-to-definition (using debug symbols)
+- [ ] Inline type hints
+
+---
+
+#### 4.3.4 Integrate Build Tools and Compiler into Editor
+
+Estimate: 1 day
+Dependencies: 4.3.1, 3.1.2, 2.1.2
+Deliverable: Integrated build experience with compiler support
+
+- [ ] Build button/command in UI that invokes the full compiler pipeline
+- [ ] Show build output and compilation errors in console panel
+- [ ] Error navigation (click to jump to source)
+- [ ] Hot reload on successful build
+- [ ] Build status indicator
+- [ ] Hook DSC language support into editor for syntax highlighting and auto‑completion
+- [ ] Provide dedicated DSC build command that uses the new compiler integration
+
+---
+
+## Phase 5: Integration & Polish
+
+**Estimated Duration: 1–2 weeks**
+
+---
+
+### 5.1 Tool Integration
+
+> **Priority: HIGH** — Everything works together.  
+> **Total Estimate: 1 week**
+
+---
+
+#### 5.1.1 Unified Toolchain
+
+**Estimate: 3 days**  
+**Dependencies:** All previous phases  
+**Deliverable:** `dsa` unified command-line tool
+
+- [ ] Create meta-crate: `dsa-tools`
+- [ ] Unified CLI with subcommands
+  - [ ] `dsa build`
+  - [ ] `dsa run`
+  - [ ] `dsa debug`
+  - [ ] `dsa test`
+  - [ ] `dsa pkg`
+- [ ] Shared configuration system
+- [ ] Tool interop testing
+- [ ] Documentation for workflow
+
+---
+
+#### 5.1.2 Emulator Integration
+
+**Estimate: 2 days**  
+**Dependencies:** 5.1.1, 4.3.4  
+**Deliverable:** Fully integrated development environment
+
+- [ ] Add build tools as emulator dependencies
+- [ ] In-editor build triggered from emulator
+- [ ] Debugger uses build output directly
+- [ ] Source-level debugging with line mapping
+- [ ] Test full edit → build → debug cycle
+
+---
+
+#### 5.1.3 Documentation & Tutorials
+
+**Estimate: 2 days**  
+**Dependencies:** 5.1.2  
+**Deliverable:** Complete documentation suite
+
+- [ ] Getting started guide
+- [ ] Full tutorial: Building a simple game
+- [ ] Debugger usage guide
+- [ ] Best practices document
+- [ ] Troubleshooting guide
+
+---
+
+## Phase 6: Future Enhancements (NTH)
+
+> **Priority: LOW** — Nice to have, long-term goal.  
+> **Estimated Duration: 4+ weeks**
+
+---
+
+### 6.1 Command-Line Emulator
+
+> ⚠️ **COMPLEX LONG-TERM GOAL** — Requires significant design and UX consideration.
+
+---
+
+#### 6.1.1 Design Phase
+
+**Estimate: 1 week**  
+**Dependencies:** None  
+**Deliverable:** `docs/cli-emulator-design.md`
+
+- [ ] UX research for terminal-based debuggers
+- [ ] Design TUI layout (using `ratatui` or similar)
+- [ ] Command syntax design
+- [ ] Scripting support design
+- [ ] Accessibility considerations
+
+---
+
+#### 6.1.2 Implementation
+
+**Estimate: 3+ weeks**  
+**Dependencies:** 6.1.1, Phase 4 complete  
+**Deliverable:** `dsa-emu-cli` executable
+
+- [ ] TUI framework setup
+- [ ] Core emulator integration
+- [ ] Command parser
+- [ ] Panel rendering (code, registers, memory, etc.)
+- [ ] Keyboard shortcuts
+- [ ] Mouse support
+- [ ] Configuration system
+- [ ] Extensive usability testing
+
+---
+
+## Summary Timeline
+
+| Phase                         | Duration  | Key Dependencies    |
+| ----------------------------- | --------- | ------------------- |
+| Phase 1: Foundation           | 3–4 weeks | None                |
+| Phase 2: Compiler             | 3–4 weeks | Phase 1 complete    |
+| Phase 3: Build System         | 2–3 weeks | Phases 1–2 complete |
+| Phase 4: Debugger             | 3–4 weeks | Phases 1–3 complete |
+| Phase 5: Integration          | 1–2 weeks | Phases 1–4 complete |
+| Phase 6: CLI Emulator _(NTH)_ | 4+ weeks  | Phase 4 complete    |
+
+**Total Estimated Time: 12–17 weeks (3–4 months) for Phases 1–5**
+
+---
+
+## Critical Path
+
+The following tasks are on the critical path and will block other work if delayed:
+
+```
+1.1.1 Binary format design
+  └── 1.1.2 Object file writer
+        └── 1.1.3 Linker
+              └── 1.2.2 Assembler rewrite
+                    └── 2.1.3 Compiler codegen
+                          └── 3.1.2 Build system
+                                └── 4.1.2 Debug symbols
+                                      └── 4.2.1 Debugger
+```
+
+---
+
+## Recommended Work Order
+
+| Weeks | Focus                                 | Tasks                                             |
+| ----- | ------------------------------------- | ------------------------------------------------- |
+| 1–2   | Binary Format & Linker                | 1.1.1 → 1.1.2 → 1.1.3                             |
+| 3–4   | Assembler Rewrite                     | 1.2.1 → 1.2.2                                     |
+| 5–6   | Compiler Syntax & Parser              | 2.1.1 → 2.1.2 _(start 1.3 docs in parallel)_      |
+| 7–9   | Compiler Codegen & Types              | 2.1.3 → 2.1.4 _(start 2.2.1 runtime in parallel)_ |
+| 10–11 | Build System                          | 3.1.1 → 3.1.2 → 3.1.3                             |
+| 12–13 | Package Management _(if desired now)_ | 3.2.1 → 3.2.2 → 3.2.3                             |
+| 14–15 | Debug Symbols                         | 4.1.1 → 4.1.2 → 4.1.3                             |
+| 16–18 | Core Debugger                         | 4.2.1 → 4.2.2 → 4.2.4                             |
+| 19–20 | Editor Enhancements                   | 4.3.1 → 4.3.2 → 4.3.3 → 4.3.4                     |
+| 21–22 | Integration & Polish                  | 5.1.1 → 5.1.2 → 5.1.3                             |
+
+---
+
+## Notes
+
+- Time estimates assume ~6–8 productive hours per day.
+- Add **20–30% buffer** for unexpected issues.
+- Testing time is included in each estimate.
+- Documentation is distributed throughout rather than batched at the end.
+- Package management (3.2) can be deferred if time-constrained.
+- Pseudo-instruction decompiler (4.2.3) can be a stretch goal.
+- CLI emulator (Phase 6) is explicitly a "nice to have" and should not block other work.

docs/IMPLEMENTATION_DISCREPANCIES.md

@@ -0,0 +1,638 @@
+# DSA Implementation vs Documentation Discrepancies
+
+## Critical Discrepancies
+
+### 1. **Stack Growth Direction** ❌ CRITICAL
+
+**Documentation states:** Stack grows upward (toward higher addresses)
+
+**Implementation shows (expand.rs:44-51):**
+```rust
+fn expand_push(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    // ...
+    nodes.extend(vec![
+        node!(label, Opcode::SubI, spr, 4, spr),  // spr = spr - 4
+        node!(None, Opcode::Stw, reg, spr, 0),
+    ]);
+```
+
+**Implementation shows (expand.rs:130-137):**
+```rust
+fn expand_pop(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    // ...
+    nodes.extend(vec![
+        node!(label, Opcode::Ldw, spr, reg, 0),
+        node!(None, Opcode::AddI, spr, 4, spr),  // spr = spr + 4
+    ]);
+```
+
+**Reality:** Stack grows **DOWNWARD** (toward lower addresses)
+- PUSH: Decrements SPR by 4, then stores
+- POP: Loads, then increments SPR by 4
+
+**Impact:** All documentation examples and calling convention diagrams are backwards!
+
+---
+
+### 2. **CALL Pseudo-instruction Expansion** ❌ CRITICAL
+
+**Documentation states (DSA_Assembly_Reference.md):**
+```asm
+; call print::print expands to:
+lwi print::print, ret       ; Load function address into ret
+jmp 0, ret                  ; Jump to function (saves return in pcx)
+```
+
+**Implementation shows (expand.rs:109-123):**
+```rust
+fn expand_call(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    nodes.extend(vec![
+        node!(label, Opcode::SubI, spr, 4, spr),    // Decrement stack pointer
+        node!(None, Opcode::Stw, pcx, spr, 0),       // Store PCX (return addr) on stack
+        node!(None, Opcode::Jmp, addr, zero),        // Jump to function
+    ]);
+```
+
+**Reality:** CALL expansion is:
+1. Decrement SPR by 4
+2. Store PCX (return address) to stack
+3. Jump to function address
+
+**Impact:** Return address is stored on the STACK, not in RET register!
+
+---
+
+### 3. **RETURN Pseudo-instruction Expansion** ❌ CRITICAL
+
+**Documentation states:**
+```asm
+; return expands to:
+jmp 0, ret                  ; Jump to address in ret register
+```
+
+**Implementation shows (expand.rs:125-135):**
+```rust
+fn expand_return(current: &Node, nodes: &mut Vec<Node>) {
+    nodes.extend(vec![
+        node!(label, Opcode::Ldw, spr, ret, 0),     // Load return addr from stack
+        node!(None, Opcode::AddI, spr, 4, spr),     // Increment stack pointer
+        node!(None, Opcode::Jmp, 4, ret),           // Jump to (ret + 4)
+    ]);
+}
+```
+
+**Reality:** RETURN expansion is:
+1. Load return address from stack into RET register
+2. Increment SPR by 4
+3. Jump to (RET + 4)
+
+**Why +4?** The stored PCX points to the instruction AFTER the call's jump, so we need to add 4 to skip past the stored PCX instruction itself... or this might be a bug in the implementation.
+
+**Impact:** Return mechanism is completely different from documentation!
+
+---
+
+### 4. **Calling Convention - Stack Frame Layout** ❌ CRITICAL
+
+**Documentation states:**
+```
+Higher Addresses
+├─────────────┤
+│   Arg N     │  ← spr + (8 + 4*(N-1))
+│   ...       │
+│   Arg 2     │  ← spr + 16
+│   Arg 1     │  ← spr + 12
+│   Arg 0     │  ← spr + 8
+├─────────────┤
+│   Ret Addr  │  ← spr + 4
+├─────────────┤
+│   Old BPR   │  ← spr + 0
+├─────────────┤  ← bpr, spr
+│   Locals    │
+Lower Addresses
+```
+
+**Reality based on implementation:**
+Since stack grows DOWN:
+```
+Lower Addresses
+├─────────────┤  ← Current SPR/BPR
+│   Old BPR   │  ← spr + 0 (immediately above SPR)
+├─────────────┤
+│   Ret Addr  │  ← spr + 4 (pushed by CALL)
+├─────────────┤
+│   Arg 0     │  ← spr + 8
+│   Arg 1     │  ← spr + 12
+│   Arg 2     │  ← spr + 16
+│   ...       │
+│   Arg N     │  ← spr + (8 + 4*(N-1))
+├─────────────┤
+Higher Addresses
+```
+
+**The diagram needs to be flipped!** The offsets are correct, but the direction is wrong.
+
+---
+
+### 5. **Label-Based Load/Store Scratch Register** ⚠️ IMPORTANT
+
+**Documentation states:** Uses `rgf` as scratch register
+
+**Implementation confirms (expand.rs:138-153):**
+```rust
+fn expand_ldx(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    // For ldb label, reg:
+    nodes.extend(vec![
+        node!(current.label(), Opcode::Lli, name, reg),
+        node!(None, Opcode::Lui, name, reg),
+        node!(None, opcode, reg, reg, offset),
+    ]);
+```
+
+**Wait! This is WRONG in the implementation!**
+
+The load expansion uses the DESTINATION register as scratch:
+```asm
+ldb buffer, rg2  expands to:
+    lli buffer, rg2    ; Uses rg2 as destination
+    lui buffer, rg2    ; Uses rg2 as destination
+    ldb rg2, rg2, 0    ; Uses rg2 as base
+```
+
+**Documentation says it should use rgf:**
+```asm
+ldb buffer, rg2 expands to:
+    lli buffer, rgf    ; Uses rgf as scratch
+    lui buffer, rgf    ; Uses rgf as scratch
+    ldb rgf, rg2, 0    ; Load from rgf into rg2
+```
+
+**For stores (expand.rs:155-176):**
+```rust
+fn expand_stx(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    // For stb reg, label:
+    let temp = Token::Register(Register::Acc);  // Uses ACC, not RGF!
+    
+    nodes.extend(vec![
+        node!(current.label(), Opcode::Lli, dest, temp),
+        node!(None, Opcode::Lui, dest, temp),
+        node!(None, opcode, base, temp, offset),
+    ]);
+```
+
+**Reality:**
+- Load pseudo-instructions use the DESTINATION register as scratch
+- Store pseudo-instructions use the ACC register as scratch, NOT rgf
+
+**Impact:** Documentation is incorrect about which registers are used!
+
+---
+
+### 6. **LWI Pseudo-instruction** ✅ CORRECT
+
+**Documentation and implementation agree:**
+```rust
+fn expand_lwi(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    nodes.extend(vec![
+        node!(current.label(), Opcode::Lli, val, reg),
+        node!(None, Opcode::Lui, val, reg),
+    ]);
+```
+
+This matches the documented expansion.
+
+---
+
+### 7. **PUSHA/POPA Pseudo-instructions** 📝 UNDOCUMENTED
+
+**These exist in implementation but are NOT in documentation!**
+
+**expand.rs:53-76:**
+```rust
+fn expand_pusha(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    let count = expect_token!(arg0, Immediate)?;
+    let spr = Token::Register(Register::Spr);
+    let registers: Vec<Register> = Register::general();
+
+    nodes.push(node!(label, Opcode::SubI, spr, Token::Immediate(count * 4), spr));
+    
+    nodes.extend((0..count).rev().map(|i| {
+        node!(None, Opcode::Stw,
+            Token::Register(registers[i as usize]),
+            spr,
+            Token::Immediate(i * 4)
+        )
+    }));
+```
+
+**expand.rs:78-101:**
+```rust
+fn expand_popa(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    let count = expect_token!(arg0, Immediate)?;
+    
+    nodes.extend((0..count).rev().map(|i| {
+        node!(
+            { if i == 0 { label.clone() } else { None } },
+            Opcode::Ldw,
+            spr,
+            Token::Register(registers[i as usize]),
+            Token::Immediate(i * 4)
+        )
+    }));
+    
+    nodes.push(node!(None, Opcode::AddI, spr, Token::Immediate(count * 4), spr));
+```
+
+**What they do:**
+- `pusha N` - Push first N general-purpose registers (rg0-rgN) to stack
+- `popa N` - Pop first N general-purpose registers from stack
+
+**Missing from documentation entirely!**
+
+---
+
+### 8. **Register Index Encoding** ⚠️ IMPORTANT
+
+**Documentation states:** System registers like MAR, MDR, STS, CIR, PCX are "internal" and not accessible
+
+**Implementation shows (instructions.rs:148-153):**
+```rust
+0x18 => Self::Mar,
+0x19 => Self::Mdr,
+0x1A => Self::Sts,
+0x1B => Self::Cir,
+0x1C => Self::Pcx,
+```
+
+**Reality:** These registers ARE encoded in the instruction format at indices 0x18-0x1C!
+
+**However, instructions.rs:186 shows:**
+```rust
+"null" => Ok(Self::NoReg),  // Can parse "null" as NoReg
+```
+
+**Documentation never mentions "null" as an alternative name for noreg!**
+
+---
+
+### 9. **LUI Immediate Value Handling** ⚠️ IMPORTANT
+
+**Documentation states:**
+```
+lui immediate, dest_reg     ; Load immediate into upper 16 bits
+```
+
+**Implementation shows (codegen.rs:248-254):**
+```rust
+fn build_load_immediate_instruction(...) -> Result<Instruction, AssembleError> {
+    // ...
+    match opcode {
+        Opcode::Lli => {
+            let instruction_args = args!(I, immediate: value as u16, r1: dest);
+            Ok(Instruction::LoadLowerImmediate(instruction_args))
+        }
+        Opcode::Lui => {
+            let upper_value = value >> 16;  // Shifts right by 16!
+            let instruction_args = args!(I, immediate: upper_value as u16, r1: dest);
+            Ok(Instruction::LoadUpperImmediate(instruction_args))
+        }
+```
+
+**Reality:** When assembling `lui immediate, reg`, the assembler:
+1. Takes the immediate value
+2. Shifts it RIGHT by 16 bits
+3. Stores the result in the instruction
+
+**This means:**
+```asm
+lli 0x1234, rg0    ; Stores 0x1234 in lower 16 bits
+lui 0xABCD0000, rg0  ; Right-shifts to 0xABCD, stores in upper 16 bits
+```
+
+**Or more likely, the assembler expects:**
+```asm
+lli 0x1234, rg0    ; Stores 0x1234 in lower 16 bits
+lui 0xABCD, rg0    ; Stores 0xABCD in upper 16 bits (no shift needed)
+```
+
+**Documentation needs clarification on what immediate value format LUI expects!**
+
+---
+
+### 10. **Data Definition Encoding** ⚠️ IMPORTANT
+
+**Implementation (expand.rs:217-267):**
+```rust
+fn process_dx_data(args: Vec<Token>, size: usize) -> Result<Vec<u32>, AssembleError> {
+    for token in args {
+        match token {
+            Token::StringLit(mut s) => {
+                s.push('\0');  // Automatically adds null terminator!
+                for ch in s.chars() {
+                    let mut char_buf = [0u8; 4];
+                    let char_bytes = ch.encode_utf8(&mut char_buf);
+                    buffer.extend_from_slice(char_bytes.as_bytes());
+                }
+            }
+            Token::Immediate(value) => {
+                buffer.extend_from_slice(&value.to_be_bytes());  // BIG ENDIAN!
+            }
+```
+
+**Key findings:**
+1. String literals automatically get null terminator appended
+2. Numeric values are stored in **BIG ENDIAN** format (to_be_bytes)
+3. Documentation says "little-endian byte order" globally
+
+**Contradiction:** Data definition uses BIG ENDIAN, but doc says LITTLE ENDIAN!
+
+---
+
+### 11. **Segment Instruction** 📝 UNDOCUMENTED
+
+**Implementation has a SEGMENT instruction (0x27/0x3F):**
+```rust
+Segment(u32) = 0x3F,
+```
+
+**This is completely undocumented!**
+
+From model.rs:
+```rust
+Self::Segment => write!(f, "[SEGMENT]"),
+```
+
+From codegen.rs:
+```rust
+Opcode::Segment => build_segment_instruction(&args),
+```
+
+**Purpose unclear, needs documentation!**
+
+---
+
+### 12. **Data Instruction** 📝 UNDOCUMENTED
+
+**Implementation has a DATA instruction (0x3E):**
+```rust
+Data(u32) = 0x3E,
+```
+
+**This appears to be a meta-instruction for embedding raw data, but it's undocumented in the assembly reference!**
+
+---
+
+### 13. **INC/DEC Instruction Encoding** ⚠️ MINOR
+
+**Implementation (codegen.rs:293-299):**
+```rust
+fn build_inc_dec_instruction(opcode: Opcode, args: &[Token]) -> Result<Instruction, AssembleError> {
+    let reg = expect_token!(reg_token, Register)?;
+    match opcode {
+        Opcode::Inc => Ok(Instruction::Increment(args!(R, sr1: reg))),
+        Opcode::Dec => Ok(Instruction::Decrement(args!(R, sr1: reg))),
+```
+
+**Reality:** INC/DEC only set SR1 field, not DR field.
+
+**But args.rs shows:**
+```rust
+impl RTypeArgs {
+    pub fn new(...) -> Self {
+        let sr1 = sr1.unwrap_or_default();  // Defaults to NoReg
+        let dr = dr.unwrap_or_default();     // Defaults to NoReg
+```
+
+**So the DR field gets set to NoReg, which is correct per documentation.**
+
+**However, the Display impl (instructions.rs:449) shows:**
+```rust
+Self::Increment(a) | Self::Decrement(a) => write!(f, " {}", a.sr1),
+```
+
+**This is correct - only shows SR1 in disassembly.**
+
+---
+
+### 14. **Shift Instruction Operand Order** ⚠️ MINOR
+
+**Implementation (codegen.rs:301-312):**
+```rust
+fn build_shift_instruction(opcode: Opcode, args: &[Token]) -> Result<Instruction, AssembleError> {
+    let reg = expect_token!(reg_token, Register)?;
+    let amount = expect_token!(amount_token, Immediate)? as u8;
+    
+    match opcode {
+        Opcode::Shl => Ok(Instruction::ShiftLeft(args!(R, sr1: reg, shamt: amount))),
+```
+
+**This only handles LITERAL shift amounts, not REGISTER shift amounts!**
+
+**Documentation states both are supported:**
+```asm
+shl rg0, 2      ; Literal shift
+shl rg0, rg1    ; Register shift
+```
+
+**The current codegen only handles the literal case!**
+
+**This is a BUG in the implementation - register shifts aren't properly assembled!**
+
+---
+
+### 15. **Jump Instruction Operand Order** ⚠️ CONFUSION
+
+**Documentation shows assembly syntax:**
+```asm
+jmp addr [, offset_reg]
+```
+
+**But implementation (codegen.rs:256-270):**
+```rust
+fn build_jump_instruction(opcode: Opcode, args: &[Token]) -> Result<Instruction, AssembleError> {
+    let address = expect_token!(address_token, Immediate)?;
+    let offset = expect_token!(offset_token, Register)?;
+    let instruction_args = args!(I, immediate: address as u16, r1: offset);
+```
+
+**This expects:**
+1. First arg: immediate (address)
+2. Second arg: register (offset)
+
+**So assembly syntax should be:**
+```asm
+jmp immediate, offset_register
+```
+
+**Example:**
+```asm
+jmp 0x1000, zero   ; Jump to 0x1000
+jmp 4, ret         ; Jump to (ret + 4)
+```
+
+**Documentation syntax is correct, but parameter names are confusing!**
+
+The "address" is actually an OFFSET, and the register is the BASE!
+
+**Better naming:**
+```asm
+jmp offset, base_register
+; Target = base_register + offset
+```
+
+---
+
+### 16. **NOT Instruction Operand Count** ✅ MINOR ISSUE
+
+**Documentation shows:**
+```asm
+not src, dest       ; Two operands
+```
+
+**Implementation (instructions.rs:428-429):**
+```rust
+Self::Compare(args) | Self::Not(args) => {
+    write!(f, " {}, {}", args.sr1, args.sr2)
+}
+```
+
+**This displays BOTH sr1 and sr2 for NOT!**
+
+**But codegen.rs:354-362:**
+```rust
+fn build_not_instruction(args: &[Token]) -> Result<Instruction, AssembleError> {
+    let reg = expect_token!(reg_token, Register)?;
+    let dest = expect_token!(dest_token, Register)?;
+    Ok(Instruction::Not(args!(R, sr1: reg, dr: dest)))
+```
+
+**Sets sr1 and dr, NOT sr1 and sr2!**
+
+**The Display impl is WRONG - should show sr1 and dr:**
+```rust
+Self::Not(args) => write!(f, " {}, {}", args.sr1, args.dr)
+```
+
+**This is a display bug in the implementation!**
+
+---
+
+### 17. **Register File Indexing** ✅ CORRECT
+
+**Documentation and implementation both agree:**
+- 0x00-0x0F: rg0-rgf (general purpose)
+- 0x10: acc
+- 0x11: spr
+- 0x12: bpr
+- 0x13: ret
+- 0x14: idr
+- 0x15: mmr
+- 0x16: zero
+- 0x17: noreg
+
+**This matches perfectly.**
+
+---
+
+### 18. **Immediate Arithmetic Destination** ⚠️ MINOR
+
+**Implementation (codegen.rs:314-330):**
+```rust
+fn build_arithmetic_immediate_instruction(...) -> Result<Instruction, AssembleError> {
+    let reg = expect_token!(reg_token, Register)?;
+    let immediate = expect_token!(immediate_token, Immediate)? as u16;
+    let dest = expect_token!(dest_token, Register)?;
+    let instruction_args = args!(I, immediate: immediate, r1: reg, r2: dest);
+```
+
+**This REQUIRES three arguments:**
+1. Source register
+2. Immediate value
+3. Destination register
+
+**But documentation says destination is optional:**
+```
+iadd src_reg, imm [, dest_reg]   ; dest optional
+```
+
+**Reality:** The assembler REQUIRES the destination register!
+
+**If you want in-place operation:**
+```asm
+iadd rg0, 10, rg0    ; Required to specify rg0 twice
+```
+
+**Not:**
+```asm
+iadd rg0, 10         ; This won't work!
+```
+
+**Documentation is misleading - destination is NOT optional!**
+
+---
+
+### 19. **Memory Instruction Offsets** ✅ CORRECT
+
+**Implementation correctly handles signed 16-bit offsets:**
+```rust
+let offset = expect_token!(offset_token, Immediate)? as u16;
+```
+
+**These are stored as u16 but interpreted as signed i16 at runtime.**
+
+**Documentation is correct about this.**
+
+---
+
+### 20. **Instruction Opcode Values** ✅ VERIFIED
+
+Comparing model.rs opcodes with instructions.rs:
+
+| Instruction | model.rs | instructions.rs | Match |
+|-------------|----------|-----------------|-------|
+| Nop | 0x00 | 0x0 | ✅ |
+| Mov | 0x01 | 0x1 | ✅ |
+| MovSigned | 0x02 | 0x2 | ✅ |
+| LoadByte | 0x03 | 0x3 | ✅ |
+| ... | ... | ... | ✅ |
+| AddImmediate | 0x25 | 0x25 | ✅ |
+| SubImmediate | 0x26 | 0x26 | ✅ |
+| Segment | 0x27 | 0x3F | ❌ MISMATCH! |
+
+**CRITICAL:** Segment instruction has opcode **0x27** in model.rs but **0x3F** in instructions.rs!
+
+---
+
+## Summary of Critical Issues
+
+### Must Fix in Documentation:
+
+1. ✅ **Stack grows DOWNWARD** - flip all diagrams
+2. ✅ **CALL expansion** - uses stack, not ret register directly
+3. ✅ **RETURN expansion** - loads from stack, jumps to ret+4
+4. ✅ **Stack frame layout** - flip diagram vertically
+5. ✅ **Load pseudo scratch register** - uses DEST reg, not rgf
+6. ✅ **Store pseudo scratch register** - uses ACC, not rgf
+7. ✅ **Add PUSHA/POPA documentation**
+8. ✅ **Add SEGMENT instruction documentation**
+9. ✅ **Add DATA instruction documentation**
+10. ✅ **Clarify LUI immediate value handling**
+11. ✅ **Fix endianness** - data definition uses BIG endian
+12. ✅ **IADD/ISUB destination NOT optional**
+13. ✅ **Add "null" as alias for noreg**
+14. ✅ **Fix Segment opcode** - 0x27 or 0x3F?
+
+### Potential Implementation Bugs:
+
+1. ⚠️ **Shift instruction** - doesn't handle register shifts
+2. ⚠️ **NOT display** - shows sr2 instead of dr
+3. ⚠️ **RETURN +4 offset** - why is this needed?
+4. ⚠️ **Segment opcode mismatch** - 0x27 vs 0x3F
+
+### Minor Documentation Improvements:
+
+1. Add explicit examples of stack growth direction
+2. Show complete memory layout diagrams
+3. Document which registers are volatile/preserved
+4. Add troubleshooting section for common mistakes
+5. Clarify jump instruction parameter semantics

docs/inconsistencies.md

@@ -0,0 +1,149 @@
+# DSA Documentation Inconsistencies Analysis
+
+## 1. Register Descriptions
+
+### Issue: System Registers vs Assembly-Accessible Registers
+- `registers.md` lists MAR, STS, CIR, MDR as "System" registers
+- These are NOT mentioned in `dsa_assembly_reference.md` or `instruction_set.md`
+- **Resolution**: System registers are internal CPU registers not directly accessible in assembly. They should be documented separately from programmer-accessible registers.
+
+### Issue: Register Naming Inconsistencies
+- `registers.md` uses `RG0-RGF` (uppercase)
+- `dsa_assembly_reference.md` uses `rg0-rgf` (lowercase)
+- **Resolution**: Assembly syntax should be lowercase (standard convention)
+
+### Issue: NOREG Register
+- `registers.md`: "Loads/using as dest register must cause an illegal instruction trap"
+- `dsa_assembly_reference.md`: "on-read/write: illegal instruction fault"
+- **Resolution**: Consistent terminology needed - use "illegal instruction fault"
+
+## 2. Instruction Operand Order Inconsistencies
+
+### Issue: Load Instructions
+- `instruction_set.md`: `LDB BaseReg, Offset, DestReg`
+- `dsa_assembly_reference.md`: `LDB base_reg, dest_reg [, offset]`
+- **Resolution**: Assembly reference shows standard syntax (base, dest, offset optional), instruction set shows encoding order
+
+### Issue: Store Instructions
+- `instruction_set.md`: `STB SrcReg, BaseReg, Offset`
+- `dsa_assembly_reference.md`: `STB src_reg, base_reg [, offset]`
+- **Resolution**: Consistent - offset is optional
+
+### Issue: Immediate Load Instructions
+- `instruction_set.md`: `LLI DstReg, Value` (destination first)
+- `dsa_assembly_reference.md`: `LLI imm, dest_reg` (immediate first)
+- **Resolution**: Assembly reference shows gas-style syntax (source, dest), instruction set shows encoding order
+
+### Issue: Jump Instructions
+- `instruction_set.md`: `JMP DestReg, Offset | Address`
+- `dsa_assembly_reference.md`: `JMP addr [, offset_reg]` or `JMP imm, offset_reg`
+- **Resolution**: Different perspectives - instruction set shows encoding, assembly shows usage
+
+## 3. Instruction Behavior Differences
+
+### Issue: IADD/ISUB Operands
+- `instruction_set.md`: `IADD Src1, Literal, Dest` (3 operands)
+- `dsa_assembly_reference.md`: `IADD src_reg, imm [, dest_reg]` (dest optional)
+- **Resolution**: Assembly allows dest to default to src_reg
+
+### Issue: SHL/SHR Operands
+- `instruction_set.md`: `SHL Reg, Literal | ValReg`
+- `dsa_assembly_reference.md`: `SHL reg, shift_amount`
+- **Resolution**: Both literal and register shifts supported
+
+## 4. Pseudo-Instruction Inconsistencies
+
+### Issue: PUSH/POP Expansion
+- `pseudoinstructions.md`: 
+  - PUSH = `INC SPR` then `STW register, SPR`
+  - POP = `LDW SPR, register` then `DEC SPR`
+- Standard stack conventions suggest PUSH should decrement (grow down)
+- **Resolution**: Clarify stack growth direction
+
+### Issue: LDB/LDH/LDW Pseudo vs Hardware
+- `pseudoinstructions.md` lists LDB, LDH, LDW as pseudo-instructions with label addressing
+- `instruction_set.md` lists them as hardware instructions
+- **Resolution**: Both exist - hardware instructions use registers, pseudo-instructions add label support
+
+### Issue: LWI Naming
+- `dsa_assembly_reference.md`: LWI = Load Word Immediate (load address)
+- Could be confused with "Load Word Immediate" (load literal value)
+- **Resolution**: LWI specifically means "Load Word address Into register"
+
+## 5. Calling Convention Details
+
+### Issue: Argument Offsets
+- Calling convention says "first 3 args at offsets 8, 12, 16"
+- This assumes 32-bit words (4 bytes each)
+- Offset 8 is position of first argument (after return address at offset 4, and old BPR at offset 0)
+- **Resolution**: Clarify that SPR+0 = old BPR, SPR+4 = return address, SPR+8 = first arg
+
+### Issue: Return Value Location
+- Says "Store return value (if any) to `spr+8`"
+- This overwrites the first argument
+- **Resolution**: This is intentional - return value replaces first argument position after cleanup
+
+## 6. Missing Information
+
+### From instruction_set.md not in assembly reference:
+- Instruction encoding details (R-type, I-type, J-type)
+- Hex opcodes for each instruction
+- Alignment requirements for memory operations
+- Sign extension behavior details
+
+### From assembly reference not in instruction_set:
+- Complete pseudo-instruction expansions showing what they compile to
+- Library examples (multiply, print)
+- Detailed calling convention walkthrough
+- Module system (INCLUDE directive)
+
+### From registers.md not elsewhere:
+- STS (Status Register) bit layout
+- Boot values for status flags
+- System registers (MAR, STS, CIR, MDR)
+
+## 7. Terminology Inconsistencies
+
+- "halfword" vs "half-word" vs "16-bit value"
+- "word" assumed to be 32-bit (should be explicit)
+- "register" vs "reg" in syntax
+- "immediate" vs "literal" vs "constant"
+
+## 8. Critical Missing Details
+
+### CALL and RETURN Pseudo-instructions
+- Assembly reference shows them but doesn't show their expansion
+- Need to document what they expand to
+
+### Label Addressing Mode
+- Shows expansions for loads/stores with labels
+- Uses RGF as scratch register - should this be documented as reserved for this purpose?
+
+### Stack Direction
+- Not explicitly stated whether stack grows up or down
+- PUSH uses INC SPR (suggests growing up) - unusual!
+
+## Recommendations
+
+1. **Separate Documentation into Logical Layers**:
+   - ISA Specification (hardware-level, for CPU implementers)
+   - Assembly Language Reference (for programmers)
+   - ABI/Calling Convention (for compiler/linker writers)
+
+2. **Standardize Terminology**:
+   - Use consistent casing (lowercase for assembly mnemonics)
+   - Define terms clearly (word = 32-bit, halfword = 16-bit, byte = 8-bit)
+   - Distinguish "literal" (immediate value in code) from "address" (memory location)
+
+3. **Document Stack Convention Clearly**:
+   - Explicitly state stack grows upward (unusual but valid)
+   - Show memory layout diagrams
+
+4. **Show Complete Pseudo-instruction Expansions**:
+   - CALL, RETURN need full expansion documentation
+   - Document which register(s) are used as temporaries
+
+5. **Clarify Register Usage Conventions**:
+   - ACC: used by pseudo-instructions, volatile
+   - RGF: used by label addressing, volatile
+   - RG0-RGE: general purpose, callee may use per calling convention

dsa_editor/src/syntax/dsc.rs

@@ -0,0 +1,25 @@
+use super::Syntax;
+use std::collections::BTreeSet;
+
+impl Syntax {
+    pub fn dsc() -> Self {
+        Syntax {
+            language: "Damn Simple Code",
+            case_sensitive: false,
+            comment: "//",
+            comment_multiline: ["/*", "*/"],
+            hyperlinks: BTreeSet::from(["http"]),
+            keywords: BTreeSet::from([
+                "include", "fn", "let", "const", "static", "if", "else", "while", "for",
+                "break", "continue", "loop", "return",
+            ]),
+            types: BTreeSet::from([
+                "u32", "u16", "u8", "i32", "i16", "i8", "str", "char", "bool", "void",
+            ]),
+            special: BTreeSet::from([
+                ",", ";", ".", ":", "=", "+", "-", "*", "/", "%", "&", "|", "^", "~",
+                "!", "?", "<", ">", "<<", ">>", "==", "!=", "<=", ">=", "&&", "||",
+            ]),
+        }
+    }
+}

dsa_editor/src/syntax/mod.rs

@@ -1,5 +1,6 @@
 #![allow(dead_code)]
 pub mod dsa;
+pub mod dsc;
 
 use std::collections::BTreeSet;
 use std::hash::{Hash, Hasher};

dsx-build/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "dsx-build"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+
+[dependencies]
+compiler = { path = "../compiler" }
+assembler = { path = "../assembler" }
+chrono = "0.4.43"

dsx-build/src/main.rs

@@ -0,0 +1,200 @@
+use std::process::{Command, Stdio};
+use std::{
+    env, fs,
+    path::{Path, PathBuf},
+};
+
+use crate::templates::{Dsa, Dsc, Template};
+
+mod templates;
+
+/// Run a command and exit on failure.
+fn run(cmd: &mut Command) {
+    let status = cmd.status().expect("failed to execute command");
+    if !status.success() {
+        std::process::exit(1);
+    }
+}
+
+fn main() {
+    // Very small CLI – only three sub‑commands.
+    let args: Vec<String> = env::args().collect();
+    if args.len() < 2 {
+        eprintln!("Usage: dsx-build <new|build|package> [options]");
+        std::process::exit(1);
+    }
+    match args[1].as_str() {
+        "new" => cmd_new(&args[2..]),
+        "build" => cmd_build(),
+        "package" => todo!("Package manager stub – not implemented yet."),
+        _ => {
+            eprintln!("Unknown command: {}", args[1]);
+            std::process::exit(1);
+        }
+    }
+}
+
+// ----------  new project ----------------------------------------------------
+fn cmd_new(args: &[String]) {
+    let mut lang = "dsa";
+    for i in 0..args.len() {
+        if args[i] == "--lang" && i + 1 < args.len() {
+            lang = &args[i + 1];
+        }
+    }
+
+    let lib = args.contains(&"--lib".to_string());
+
+    // Determine project root: a subdirectory named after the supplied --name argument.
+    let mut name_opt = None;
+    for i in 0..args.len() {
+        if args[i] == "--name" && i + 1 < args.len() {
+            name_opt = Some(&args[i + 1]);
+            break;
+        }
+    }
+
+    let project_name = match name_opt {
+        Some(name) => name.to_string(),
+        None => {
+            eprintln!("Error: --name argument required");
+            std::process::exit(1);
+        }
+    };
+
+    let cwd = env::current_dir().unwrap();
+    let src_path = cwd.join(&project_name).join("src");
+    fs::create_dir_all(&src_path).expect("Failed to create project directory");
+
+    match lang {
+        "dsa" => {
+            // Minimal DSA binary template.
+            let path = src_path.join(format!("main.dsa"));
+
+            let template = Dsa::create(&project_name, lib);
+
+            fs::write(path, template).expect("Unable to write DSA file");
+        }
+        "dsc" => {
+            let path = src_path.join(format!("main.dsc"));
+
+            let template = Dsc::create(&project_name, lib);
+
+            fs::write(path, template).expect("Unable to write DSC file");
+        }
+        _ => {
+            eprintln!("Unsupported language: {}", lang);
+            std::process::exit(1);
+        }
+    }
+
+    fs::create_dir_all(src_path.join("lib")).expect("Failed to create lib directory");
+    fs::write(
+        src_path.join("lib/print.dsa"),
+        templates::create_print_lib(),
+    )
+    .expect("Failed to create print.dsa");
+    fs::write(
+        src_path.join("lib/maths.dsa"),
+        templates::create_maths_lib(),
+    )
+    .expect("Failed to create maths.dsa");
+
+    println!(
+        "Created new {} project in {}.",
+        lang,
+        src_path.parent().unwrap().display()
+    );
+}
+
+// ----------  build ----------------------------------------------------------
+fn cmd_build() {
+    let cwd = env::current_dir().unwrap();
+
+    // Detect .dsc or .dsa files in current directory.
+    let mut has_dsc = false;
+    let mut has_dsa = false;
+    for entry in fs::read_dir(&cwd.join("src")).expect("unable to read dir") {
+        if let Ok(entry) = entry {
+            let path = entry.path();
+            if path.extension().and_then(|s| s.to_str()) == Some("dsc") {
+                has_dsc = true;
+            } else if path.extension().and_then(|s| s.to_str()) == Some("dsa") {
+                has_dsa = true;
+            }
+        }
+    }
+
+    if !has_dsc && !has_dsa {
+        eprintln!("No .dsc or .dsa source found in src directory.");
+        std::process::exit(1);
+    }
+
+    // Assemble main.dsa to a dsb binary.
+    println!("Assembling Project to a DSB binary...");
+    let build_dir = cwd.join("build");
+    fs::create_dir_all(&build_dir).expect("Failed to create build directory");
+
+    // Copy everything from `cwd/src` to the build directory.
+    fn copy_recursively(src: &Path, dst: &Path) {
+        if src.is_file() {
+            fs::create_dir_all(dst.parent().unwrap())
+                .expect("Failed to create parent directory");
+            fs::copy(src, dst).expect("Failed to copy file");
+        } else if src.is_dir() {
+            for entry in fs::read_dir(src).expect("Unable to read source dir") {
+                let entry = entry.expect("Failed to read entry");
+                let child_src = entry.path();
+                let child_dst = dst.join(entry.file_name());
+                copy_recursively(&child_src, &child_dst);
+            }
+        }
+    }
+
+    let src_dir = cwd.join("src");
+    if src_dir.exists() {
+        copy_recursively(&src_dir, &build_dir);
+    }
+
+    // Change current working directory to the build directory.
+    env::set_current_dir(&build_dir).expect("Failed to change to build directory");
+
+    if has_dsc {
+        println!("Compiling DSC to DSA...");
+        fn compile_recursive(path: &Path) {
+            if path.is_dir() {
+                for entry in fs::read_dir(path).expect("unable to read dir") {
+                    let entry = entry.expect("failed to read entry");
+                    compile_recursive(&entry.path());
+                }
+            } else if path.extension().and_then(|s| s.to_str()) == Some("dsc") {
+                let input_path = path;
+                let output_path = path.with_extension("dsa");
+                compiler::compile_file(&input_path, &output_path).unwrap_or_else(|e| {
+                    eprintln!("Failed to compile {:?}: {}", input_path, e);
+                    std::process::exit(1);
+                });
+            }
+        }
+        compile_recursive(&build_dir);
+    }
+
+    // Replace .dsc with .dsa only in include statements, recursively for each file.
+    let mut sed_cmd = Command::new("bash");
+    sed_cmd.args(&[
+        "-c",
+        &format!(
+            "find \"{}\" -type f -name '*.dsa' -exec sed -i '/^include/ s/\\.dsc/.dsa/g' {{}} +",
+            build_dir.display()
+        ),
+    ]);
+    run(&mut sed_cmd);
+
+    fs::create_dir_all(&cwd.join("artifacts")).expect("Failed to create build directory");
+    assembler::assemble_file("./main.dsa", "../artifacts/out.dsb").unwrap_or_else(|e| {
+        eprintln!("Failed to assemble {:?}: {}", "./main.dsa", e);
+        std::process::exit(1);
+    });
+
+    println!("Build finished. Binary at {}/main.dsb", build_dir.display());
+}

dsx-build/src/templates.rs

@@ -0,0 +1,589 @@
+pub trait Template {
+    fn lib(project: &str) -> String;
+    fn bin(project: &str) -> String;
+
+    fn create(project: &str, lib: bool) -> String {
+        if lib {
+            Self::lib(project)
+        } else {
+            Self::bin(project)
+        }
+    }
+}
+
+pub struct Dsa;
+pub struct Dsc;
+
+impl Template for Dsa {
+    fn lib(project: &str) -> String {
+        format!(
+            r#"//
+lib.dsa
+// usage:
+//
+// include {project} "<relative path>"
+//
+// usage for {project}_main:
+// push (arg1)
+// push (arg0)
+// call {project}::{project}_main
+// pop (arg0)
+// pop (arg1)
+
+// Example data declarations
+// dw example_data: 0x0000
+
+// Main function template
+{project}_main:
+    // the correct way to start a function as defined by the calling convention
+    push bpr
+    mov spr, bpr
+
+    // explanation of how to access args
+    ldw bpr, rg0, 8  // arg 0
+    ldw bpr, rg0, 12 // arg 1
+
+    // your code goes here
+    // Example: load example_data into rg1
+    // ldw example_data, rg1
+
+    // the correct way to end a function as defined by the calling convention
+    mov bpr, spr
+    pop bpr
+    return
+"#,
+        )
+    }
+
+    fn bin(project: &str) -> String {
+        format!(
+            r#"
+// GENERATED BY DSX-BUILD
+// Generated at: {timestamp}
+// Project name: {project}
+
+// Imports
+include print: "./lib/print.dsa"
+
+// Globals & Reserved Memory
+dw stack: 0x10000
+db message: "Process Exited with code:"
+
+// Entry Point
+_init:
+    ldw stack, bpr
+    mov bpr, spr
+    push zero
+    call main
+    call print::print_newline
+    lwi message, rg0
+    push rg0
+    call print::print
+    pop zero
+    call print::print_hex_word
+    pop zero
+    hlt
+
+main:
+    push bpr
+    mov spr, bpr
+
+    // Your code goes here
+
+    // Return zero
+    stw zero, bpr, 8
+
+    mov bpr, spr
+    pop bpr
+    return"#,
+            timestamp = chrono::Utc::now().format("%Y-%m-%d %H:%M:%S").to_string()
+        )
+    }
+}
+
+impl Template for Dsc {
+    fn lib(project: &str) -> String {
+        format!(
+            r#"
+// GENERATED BY DSX-BUILD
+// Generated at: {timestamp}
+// Project name: {project}
+
+// Imports
+include print: "./lib/print.dsa";
+
+// Main Function
+fn {project}_main() -> u32 {{
+    return 0;
+}}"#,
+            timestamp = chrono::Utc::now().format("%Y-%m-%d %H:%M:%S").to_string()
+        )
+    }
+
+    fn bin(project: &str) -> String {
+        format!(
+            r#"
+// GENERATED BY DSX-BUILD
+// Generated at: {timestamp}
+// Project name: {project}
+
+// Imports
+include print: "./lib/print.dsa";
+
+// Main Function
+fn main() -> u32 {{
+    return 0;
+}}"#,
+            timestamp = chrono::Utc::now().format("%Y-%m-%d %H:%M:%S").to_string()
+        )
+    }
+}
+
+pub fn create_print_lib() -> String {
+    format!(
+        r#"
+// lib:
+// print.dsa
+
+// usage:
+//
+// include print "<relative path>""
+//
+// usage for print:
+//      push (register containing address of string)
+//      push pcx
+//      jmp print::print
+//
+// usage for reset:
+//      push pcx
+//      jmp print::reset
+//
+// usage for clear:
+//      push pcx
+//      jmp print::clear
+//
+// usage for print_byte:
+//      push (register containing byte)
+//      push pcx
+//      jmp print::print_byte
+//
+// usage for print_word:
+//      push (register containing word)
+//      push pcx
+//      jmp print::print_word
+//
+// usage for print_num:
+//      push (register containing number to print in decimal)
+//      push pcx
+//      jmp print::print_num
+//
+
+include maths "./maths.dsa"
+
+dw display: 0x20000
+dw current: 0x20000
+
+// ------------------------------------------
+// prints the string at addr(arg[0]) to the screen. (no trailing whitespace unless explicitly provided)
+print:
+    push bpr
+    mov spr, bpr
+
+    ldw bpr, rg0, 8
+    ldw current, rg1
+
+_print_loop:
+    ldb rg0, acc
+    cmp acc, zero
+    jeq _end
+    stb acc, rg1
+
+    addi rg0, 1
+    addi rg1, 1
+
+    jmp _print_loop
+
+// ------------------------------------------
+println:
+    push bpr
+    mov spr, bpr
+
+    ldw bpr, rg0, 8
+    ldw current, rg1
+
+_println_loop:
+    ldb rg0, acc
+    cmp acc, zero
+    jeq _println_end
+    stb acc, rg1
+
+    addi rg0, 1
+    addi rg1, 1
+
+    jmp _println_loop
+
+_println_end:
+    call print_newline
+    jmp _end
+
+// ------------------------------------------
+// prints the value of arg[0] to the screen.
+print_word:
+    // initialise
+    push bpr
+    mov spr, bpr
+
+    // load byte into acc
+    ldw bpr, rg0, 8
+    ldw current, rg1
+
+    addi rg1, 3
+
+    stb rg0, rg1
+    subi rg1, 1
+    shr rg0, 8
+    stb rg0, rg1
+    subi rg1, 1
+    shr rg0, 8
+    stb rg0, rg1
+    subi rg1, 1
+    shr rg0, 8
+    stb rg0, rg1
+
+    addi rg1, 4
+    jmp _end
+
+// ------------------------------------------
+// prints the last byte of arg[0] to the screen.
+print_byte:
+    push bpr
+    mov spr, bpr
+
+    ldw bpr, rg0, 8
+    ldw current, rg1
+
+    stb rg0, rg1
+    addi rg1, 1
+    jmp _end
+
+// ------------------------------------------
+// prints the value of arg[0] to the screen in hex.
+print_hex_word:
+    push bpr
+    mov spr, bpr
+
+    ldw current, rg1
+
+    ldb bpr, rg0, 8
+    push rg0
+    call _print_hex_byte
+    addi spr, 4
+
+    ldb bpr, rg0, 9
+    push rg0
+    call _print_hex_byte
+    addi spr, 4
+
+    ldb bpr, rg0, 10
+    push rg0
+    call _print_hex_byte
+    addi spr, 4
+
+    ldb bpr, rg0, 11
+    push rg0
+    call _print_hex_byte
+    addi spr, 4
+
+    jmp _end
+
+// ------------------------------------------
+// prints the last byte of arg[0] to the screen in hex.
+print_hex_byte:
+    push bpr
+    mov spr, bpr
+
+    ldw bpr, rg0, 8
+    ldw current, rg1
+
+    call _print_hex_byte
+    jmp _end
+
+// function body
+_print_hex_byte:
+    // mask to get lower nibble
+    lli 0xF, rg2
+    // save rg0 state
+    push rg0
+
+    shr rg0, 4
+    and rg0, rg2, rg0
+    call _print_hex_nibble
+    pop rg0
+
+    and rg0, rg2, rg0
+    call _print_hex_nibble
+    return
+
+// print a hex digit
+_print_hex_nibble:
+    lli 10, rg3
+    cmp rg0, rg3
+    jlt _print_hex_nibble_number
+    addi rg0, 0x37, rg0
+    stb rg0, rg1
+    addi rg1, 1
+    return
+
+// helper function.
+_print_hex_nibble_number:
+    addi rg0, 0x30, rg0
+    stb rg0, rg1
+    addi rg1, 1
+    return
+
+// ------------------------------------------
+// print whitespace
+print_whitespace:
+    push bpr
+    mov spr, bpr
+
+    ldw current, rg1
+    lli 0x20, rg0
+    stb rg0, rg1
+    addi rg1, 1
+    jmp _end
+
+// ------------------------------------------
+// print newline
+print_newline:
+    push bpr
+    mov spr, bpr
+
+    // load variables into registers
+    ldw display, rg0
+    ldw current, rg1
+
+    // get the offset from the display base
+    sub rg1, rg0, rg0
+
+    lwi 80, rg2
+    pusha 3
+    push rg0
+    push rg2
+    call maths::divmod
+    pop zero  // result
+    pop rg3 // remainder
+    popa 3
+
+    sub rg1, rg3, rg2
+    addi rg2, 80, rg1
+
+    // _end saves the display state
+    jmp _end
+
+// ------------------------------------------
+// prints arg[0] as a decimal number to the screen.
+print_num:
+    push bpr
+    mov spr, bpr
+
+    ldw bpr, rg0, 8      // load number to print
+    lli 0, rg5           // rg5 = digit counter
+
+    // check if number is zero
+    cmp rg0, zero
+    jne _print_num_extract_digits
+
+    // special case: print '0' for zero
+    lli 0x30, rg6
+    push rg6             // push digit to stack buffer
+    lli 1, rg5           // we have 1 digit
+    jmp _print_num_output
+
+_print_num_extract_digits:
+    // divide by 10 repeatedly to get digits
+    cmp rg0, zero
+    jeq _print_num_output
+
+    // call divmod(rg0, 10)
+    push rg0             // dividend
+    lli 10, rg1
+    push rg1             // divisor (10)
+    call maths::divmod
+    pop rg0              // quotient (continue dividing this)
+    pop rg1              // remainder (the digit)
+
+    // convert digit to ASCII and push to stack buffer
+    addi rg1, 0x30, rg6  // convert to ASCII
+    push rg6             // push digit to stack
+    inc rg5              // increment digit counter
+
+    jmp _print_num_extract_digits
+
+_print_num_output:
+    // now print digits (pop them off in reverse order)
+    ldw current, rg1     // get display pointer
+
+_print_num_output_loop:
+    // check if we've printed all digits
+    cmp rg5, zero
+    jeq _print_num_done
+
+    // pop digit and print it
+    pop rg6
+    stb rg6, rg1
+    addi rg1, 1
+    dec rg5
+
+    jmp _print_num_output_loop
+
+_print_num_done:
+    jmp _end
+
+// ------------------------------------------
+// resets the cursor position on the screen to 0x20000. (0,0)
+reset:
+    push bpr
+    mov spr, bpr
+    ldw display, rg1
+    jmp _end
+
+// ------------------------------------------
+// clears the screen
+clear:
+    push bpr
+    mov spr, bpr
+    // display size = 2000 bytes / 500 words
+    lli 500 rg0
+    ldw display, rg1
+
+_clear_loop:
+    dec rg0
+    stw zero, rg1
+    addi rg1, 4
+    cmp rg0, zero
+    jgt _clear_loop
+    jmp _end
+
+// ------------------------------------------
+// return
+_end:
+    stw rg1, current
+
+    mov bpr, spr
+    pop bpr
+    return
+"#
+    )
+}
+
+pub fn create_maths_lib() -> String {
+    format!(
+        r#"
+// multiply.dsa
+// usage:
+//
+// include multiply "<relative path>"
+//
+// usage for multiply:
+// push (arg1)
+// push (arg0)
+// call multiply::multiply
+// pop (arg0)
+// pop (arg1)
+
+multiply:
+    push bpr
+    mov spr, bpr
+
+    ldw bpr, rg0, 8  // load op 2
+    ldw bpr, rg1, 12 // load op 1
+    lwi 0, rg2       // initialise rg2 to zero
+
+_multiply_loop:
+    add rg2, rg0, rg2
+    dec rg1
+
+    cmp rg1, zero
+    jgt _multiply_loop
+
+_multiply_end:
+    stw rg2, bpr, 8
+
+    mov bpr, spr
+    pop bpr
+    return
+
+divmod:
+    push bpr
+    mov spr, bpr
+
+    ldw bpr, rg1, 8  // load op 2
+    ldw bpr, rg0, 12 // load op 1
+
+    lli 0, rg3
+
+_divmod_loop:
+    cmp rg0, rg1
+    jlt _divmod_end
+
+    sub rg0, rg1, rg0
+    inc rg3
+
+    jmp _divmod_loop
+
+_divmod_end:
+    // store div in first arg
+    // store mod in second arg
+    stw rg3, bpr, 8
+    stw rg0, bpr, 12
+
+    mov bpr, spr
+    pop bpr
+    return
+
+// multiply.dsa - improved version
+// Multiplies two 32-bit numbers using shift-and-add
+//
+// Usage:
+// push operand2  (multiplier)
+// push operand1  (multiplicand)
+// call multiply::multiply
+// pop result
+// pop zero       (discard second argument)
+
+new_multiply:
+    push bpr
+    mov spr, bpr
+
+    ldw bpr, rg0, 8     // rg0 = multiplicand
+    ldw bpr, rg1, 12    // rg1 = multiplier
+
+    lli 0, rg2          // rg2 = result (accumulator)
+    lli 32, rg3         // rg3 = bit counter
+
+mult_loop:
+    // Check if lowest bit of multiplier is 1
+    lli 1, acc
+    and rg1, acc, acc   // acc = rg1 & 1
+    cmp acc, zero
+    jeq skip_add        // if (rg1 & 1) == 0, skip addition
+
+    // Add multiplicand to result
+    add rg2, rg0, rg2
+
+skip_add:
+    shl rg0, 1          // shift multiplicand left
+    shr rg1, 1          // shift multiplier right
+
+    dec rg3
+    cmp rg3, zero
+    jgt mult_loop
+
+    stw rg2, bpr, 8     // store result
+    mov bpr, spr
+    pop bpr
+    return
+"#
+    )
+}

emulator/Cargo.toml

@@ -16,8 +16,8 @@ required-features = ["config"]
 [dependencies]
 common = { path = "../common" }
 assembler = { path = "../assembler" }
+compiler = { path = "../compiler" }
 dsa_editor = { path = "../dsa_editor" }
-eframe = { version = "0.31.1" }
 egui = "0.31.1"
 dirs = "6.0.0"
 discord-presence = { version = "1.6.0", optional = true }
@@ -30,7 +30,7 @@ default = ["config"]
 discord-rpc = ["dep:discord-presence"]
 config = ["dep:toml", "dep:serde"]
 
-# Add support for Android for the fun of it.
+# Add support for Android for the fun of it. Currently crashes lol.
 [target.'cfg(target_os = "android")'.dependencies]
 winit = { version = "0.30.11", features = ["android-native-activity"] }
 # jni = "0.21.1"
@@ -38,3 +38,6 @@ winit = { version = "0.30.11", features = ["android-native-activity"] }
 [target.'cfg(target_os = "android")'.dependencies.eframe]
 version = "0.31.1"
 features = ["android-native-activity"]
+
+[target.'cfg(not(target_os = "android"))'.dependencies.eframe]
+version = "0.31.1"

emulator/src/emulator/system/emulator.rs

@@ -1,15 +1,12 @@
 use std::sync::Arc;
-use std::{
+use std::sync::mpsc::{self, Receiver, Sender};
-    sync::mpsc::{self, Receiver, Sender},
-    thread,
-    time::Duration,
-};
 
 #[allow(unused_imports)]
 use crate::emulator::misc::rpc::{Activity, RpcClient};
 
+use crate::emulator::system::model::StateUpdate;
 use crate::emulator::system::{
-    model::{Command, PersistentState, Running, State},
+    model::{Command, Running},
     processor::Processor,
 };
 
@@ -19,28 +16,33 @@ use common::prelude::*;
 #[allow(unused_variables)]
 pub fn run_emulator(
     cmd_rx: &Receiver<Command>,
-    state_tx: &Sender<State>,
+    state_tx: &Sender<StateUpdate>,
     mut processor: Processor,
     rpc_client: Option<&Arc<RpcClient>>,
 ) {
     println!("INFO: Starting emulator.");
 
     let mut running = Running::Paused;
-    let mut addr = 0u32;
+    let mut step = 0;
+    let mut addr;
     let mut history = Vec::<(u32, Instruction)>::new();
     let size = 256;
 
-    let memory_view = processor.memory.read_range(addr, size);
+    state_tx
-    let initial_state = state(&mut processor, running, 0, memory_view, &mut history);
+        .send(StateUpdate::Running(Running::Paused))
-    let _ = state_tx.send(initial_state);
+        .expect("Failed to send initial state!");
 
     let mut instruction_count = 0;
+    let mut update = false;
 
     loop {
-        let cmd = if running == Running::Running {
+        let cmd = if running == Running::Running || step > 0 {
             match cmd_rx.try_recv() {
                 Ok(cmd) => Some(cmd),
-                Err(mpsc::TryRecvError::Empty) => None,
+                Err(mpsc::TryRecvError::Empty) => {
+                    update = false;
+                    None
+                }
                 Err(mpsc::TryRecvError::Disconnected) => break,
             }
         } else {
@@ -91,118 +93,153 @@ pub fn run_emulator(
 
                     processor.reset();
                 }
-                Command::Step => {
+                Command::Step(x) => {
-                    running = Running::Paused;
+                    step = x;
-
-                    // Execute one cycle.
-                    match processor.cycle() {
-                        Ok((addr, instruction)) => {
-                            history.push((addr, instruction));
-                        }
-                        Err(why) => {
-                            let pcx = processor.get(Register::Pcx);
-                            eprintln!(
-                                "Could not decode instruction at {pcx:x}. Reason: {why}"
-                            );
-                            continue;
-                        }
-                    }
-
-                    instruction_count += 1;
-                }
-                Command::Read(new, _size) => {
-                    addr = new;
                 }
                 Command::Write(offset, data) => {
-                    processor.memory.write_range(offset, data);
+                    update = true;
+
+                    processor
+                        .memory
+                        .write_range(offset, data)
+                        .unwrap_or_else(|_| {
+                            report_err(
+                                state_tx,
+                                "Failed to write memory range!",
+                                &mut processor,
+                            );
+                        });
                 }
                 Command::Interrupt(_interrupt) => {
+                    update = true;
+
                     todo!("implement interrupts")
                 }
+                Command::MemRequest(new, size) if update => {
+                    addr = new;
+                    let _ = state_tx.send(StateUpdate::MemoryView(
+                        processor.memory.read_range(addr, size).unwrap_or_else(|_| {
+                            report_err(
+                                state_tx,
+                                "Failed to read memory range!",
+                                &mut processor,
+                            );
+                            Vec::new()
+                        }),
+                    ));
+                }
+                Command::DisplayRequest if update => {
+                    let _ = state_tx.send(StateUpdate::DisplayView(
+                        processor.display().unwrap_or_else(|_| {
+                            report_err(
+                                state_tx,
+                                "Failed to read display!",
+                                &mut processor,
+                            );
+                            Vec::new()
+                        }),
+                    ));
+                }
+                Command::StackRequest if update => {
+                    let _ = state_tx.send(StateUpdate::StackView(
+                        processor.get_stack(32).unwrap_or_else(|_| {
+                            report_err(state_tx, "Failed to read stack!", &mut processor);
+                            Vec::new()
+                        }),
+                    ));
+                }
+                Command::RegisterRequest if update => {
+                    let _ = state_tx.send(StateUpdate::Registers(processor.registers));
+                }
+                Command::RunningRequest if update => {
+                    let _ = state_tx.send(StateUpdate::Running(running));
+                }
+                Command::HistoryRequest if update => {
+                    let hsc = history.clone();
+                    history.clear();
+                    let _ = state_tx.send(StateUpdate::InstructionHistory(hsc));
+                }
+                Command::InstructionCountRequest if update => {
+                    let _ = state_tx.send(StateUpdate::Instructions(instruction_count));
+                }
+                Command::WriteBlock(addr, block) => {
+                    processor
+                        .memory
+                        .write_range(addr, block.to_vec())
+                        .unwrap_or_else(|_| {
+                            report_err(
+                                state_tx,
+                                "Failed to write memory block!",
+                                &mut processor,
+                            );
+                        });
+                }
+
+                _ => {}
             }
+        }
 
-            let memory_view = processor.memory.read_range(addr, size);
+        if step > 0 {
-            let state = state(
+            step -= 1;
-                &mut processor,
+            update = true;
-                running,
+            running = Running::Paused;
-                instruction_count,
-                memory_view,
-                &mut history,
-            );
 
-            println!("state");
+            // Execute one cycle.
-
+            match processor.cycle() {
-            let _ = state_tx.send(state);
+                Ok((addr, instruction)) => {
+                    history.push((addr, instruction));
+                }
+                Err(why) => {
+                    let pcx = processor
+                        .get(Register::Pcx)
+                        .expect("SPR should never be invalid");
+                    report_err(
+                        state_tx,
+                        &format!(
+                            "Could not decode instruction at {pcx:x}. Reason: {why}"
+                        ),
+                        &mut processor,
+                    );
+                }
+            }
+            instruction_count += 1;
+            continue;
         }
 
         if running == Running::Running {
-            let mut update = false;
+            update = true;
 
             // Execute one cycle.
             let instruction = match processor.cycle() {
                 Ok(instruction) => instruction,
                 Err(why) => {
-                    let pcx = processor.get(Register::Pcx);
+                    let pcx = processor
-                    eprintln!("Could not decode instruction at {pcx:x}. Reason: {why}");
+                        .get(Register::Pcx)
-                    continue;
+                        .expect("PCX should never be invalid");
+                    report_err(
+                        state_tx,
+                        &format!(
+                            "Could not decode instruction at {pcx:x}. Reason: {why}"
+                        ),
+                        &mut processor,
+                    );
+                    (pcx, Instruction::Nop)
                 }
             };
 
             history.push(instruction);
-
-            // let instruction = match Instruction::decode(cpu_lock.get(Register::Cir))
-            // {};
-
             if matches!(instruction.1, Instruction::Halt) {
                 running = Running::Halted;
-                update = true;
             }
 
             instruction_count += 1;
-
-            // Send state updates every 100 instructions
-            if instruction_count % 100 == 0 {
-                update = true;
-            }
-
-            if update {
-                let memory_view = processor.memory.read_range(addr, size);
-                let state = state(
-                    &mut processor,
-                    running,
-                    instruction_count,
-                    memory_view,
-                    &mut history,
-                );
-                println!("running state");
-                // println!("state!!! {:?}", state.history);
-                let _ = state_tx.send(state);
-            }
-        } else {
-            thread::sleep(Duration::from_millis(1));
         }
     }
 }
 
-fn state(
+fn report_err(state_tx: &Sender<StateUpdate>, why: &str, processor: &mut Processor) {
-    cpu_lock: &mut Processor,
+    processor
-    running: Running,
+        .begin_interrupt(Interrupt::HardFault)
-    instruction_count: usize,
+        .expect("What kind of goofy ahh shenanigans did you do with your fault handler? At this point, the emulator can just crash. this is on you.");
-    memory_view: Vec<u8>,
+    let _ = state_tx.send(StateUpdate::Error(why.to_string()));
-    history: &mut Vec<(u32, Instruction)>,
-) -> State {
-    let hsclone = history.clone();
-    history.clear();
-
-    State {
-        // TODO: Replace with actual register access from your CPU.
-        reg_file: cpu_lock.registers,
-        running,
-        instructions: instruction_count,
-        stack_view: cpu_lock.get_stack(32),
-        memory_view,
-        display_view: cpu_lock.display(),
-        error: None,
-        persistent: PersistentState { history: hsclone },
-    }
 }

emulator/src/emulator/system/memory.rs

@@ -1,13 +1,43 @@
 use std::collections::HashMap;
 
+use crate::emulator::system::model::ProcessorError;
+
 pub trait MemoryUnit: Send + Sync {
     fn reset(&mut self);
-    fn read_byte(&mut self, addr: u32) -> u8;
+    fn read_byte(&mut self, addr: u32) -> Result<u8, ProcessorError>;
-    fn write_byte(&mut self, addr: u32, value: u8);
+    fn write_byte(&mut self, addr: u32, value: u8) -> Result<(), ProcessorError>;
-    fn read_word(&mut self, addr: u32) -> u32;
+    fn read_word(&mut self, addr: u32) -> Result<u32, ProcessorError>;
-    fn write_word(&mut self, addr: u32, value: u32);
+    fn write_word(&mut self, addr: u32, value: u32) -> Result<(), ProcessorError>;
-    fn read_range(&mut self, addr: u32, size: u32) -> Vec<u8>;
+
-    fn write_range(&mut self, addr: u32, value: Vec<u8>);
+    fn read_range(&mut self, addr: u32, size: u32) -> Result<Vec<u8>, ProcessorError> {
+        let mut data = Vec::with_capacity(size as usize);
+        for i in 0..size {
+            data.push(self.read_byte(addr + i)?);
+        }
+        Ok(data)
+    }
+
+    fn write_range(&mut self, addr: u32, value: Vec<u8>) -> Result<(), ProcessorError> {
+        for (i, byte) in value.into_iter().enumerate() {
+            self.write_byte(addr + i as u32, byte)?;
+        }
+        Ok(())
+    }
+
+    fn read_block(&mut self, addr: u32) -> Result<[u8; 256], ProcessorError> {
+        let mut data = [0; 256];
+        for (i, byte) in data.iter_mut().enumerate() {
+            *byte = self.read_byte(addr + i as u32)?;
+        }
+        Ok(data)
+    }
+
+    fn write_block(&mut self, addr: u32, data: [u8; 256]) -> Result<(), ProcessorError> {
+        for (i, byte) in data.iter().enumerate() {
+            self.write_byte(addr + i as u32, *byte)?;
+        }
+        Ok(())
+    }
 }
 
 pub struct MainStore {
@@ -64,59 +94,77 @@ impl MemoryUnit for MainStore {
         self.data.clear();
     }
 
-    fn read_byte(&mut self, addr: u32) -> u8 {
+    fn read_byte(&mut self, addr: u32) -> Result<u8, ProcessorError> {
         let (block_addr, offset) = Self::segment_addr(addr);
         let block = self.block(block_addr);
-        block.data[offset as usize]
+        Ok(block.data[offset as usize])
     }
 
-    fn read_word(&mut self, addr: u32) -> u32 {
+    fn read_word(&mut self, addr: u32) -> Result<u32, ProcessorError> {
+        if addr % 4 != 0 {
+            return Err(ProcessorError::BadMemoryAccess(addr));
+        }
+
         let (block_addr, offset) = Self::segment_addr(addr);
-
-        println!("reading word from {block_addr:x?} + {offset}");
-
         let block = self.mut_block(block_addr);
         let mut bytes = [0; 4];
         bytes[0] = block.data[offset as usize];
         bytes[1] = block.data[(offset + 1) as usize];
         bytes[2] = block.data[(offset + 2) as usize];
         bytes[3] = block.data[(offset + 3) as usize];
-        u32::from_be_bytes(bytes)
+        Ok(u32::from_be_bytes(bytes))
     }
 
-    fn read_range(&mut self, addr: u32, size: u32) -> Vec<u8> {
+    fn read_range(&mut self, addr: u32, size: u32) -> Result<Vec<u8>, ProcessorError> {
         let mut data = Vec::with_capacity(size as usize);
         for i in 0..size {
-            data.push(self.read_byte(addr + i));
+            data.push(self.read_byte(addr + i)?);
         }
 
-        // println!("reading {data:?} from {addr:x?}");
+        Ok(data)
-
-        data
     }
 
-    fn write_byte(&mut self, addr: u32, value: u8) {
+    fn write_byte(&mut self, addr: u32, value: u8) -> Result<(), ProcessorError> {
         let (block_addr, offset) = Self::segment_addr(addr);
         let block = self.mut_block(block_addr);
         block.data[offset as usize] = value;
+        Ok(())
     }
 
-    fn write_word(&mut self, addr: u32, value: u32) {
+    fn write_word(&mut self, addr: u32, value: u32) -> Result<(), ProcessorError> {
+        if addr % 4 != 0 {
+            return Err(ProcessorError::BadMemoryAccess(addr));
+        }
+
         let (block_addr, offset) = Self::segment_addr(addr);
         let block = self.mut_block(block_addr);
         block.data[offset as usize] = (value >> 24) as u8;
         block.data[(offset + 1) as usize] = (value >> 16) as u8;
         block.data[(offset + 2) as usize] = (value >> 8) as u8;
         block.data[(offset + 3) as usize] = value as u8;
+        Ok(())
     }
 
-    fn write_range(&mut self, addr: u32, value: Vec<u8>) {
+    fn write_range(&mut self, addr: u32, value: Vec<u8>) -> Result<(), ProcessorError> {
-        // println!("writing {value:?} to {addr:x?}");
-
         for (i, byte) in value.into_iter().enumerate() {
             let (block_addr, offset) = Self::segment_addr(addr + i as u32);
             let block = self.mut_block(block_addr);
             block.data[offset as usize] = byte;
         }
+
+        Ok(())
+    }
+
+    fn read_block(&mut self, addr: u32) -> Result<[u8; 256], ProcessorError> {
+        let (block_addr, _) = Self::segment_addr(addr);
+        let block = self.block(block_addr);
+        Ok(block.data)
+    }
+
+    fn write_block(&mut self, addr: u32, data: [u8; 256]) -> Result<(), ProcessorError> {
+        let (block_addr, _) = Self::segment_addr(addr);
+        let block = self.mut_block(block_addr);
+        block.data = data;
+        Ok(())
     }
 }

emulator/src/emulator/system/model.rs

@@ -1,3 +1,5 @@
+use std::sync::mpsc::{self, Receiver, Sender};
+
 use common::prelude::*;
 
 #[derive(PartialEq, Eq, Debug, Clone, Copy)]
@@ -16,15 +18,143 @@ pub trait IODevice: Send + Sync {
 
 #[derive(PartialEq, Eq, Debug, Clone)]
 pub enum Command {
+    // set emulator state.
     Start,
     Stop,
-    Step,
+    Step(usize),
     Reset(usize),
     Interrupt(Interrupt),
-
-    // Performs direct read/write operations on the emulator's memory.
-    Read(Address, u32),
     Write(Address, Vec<u8>),
+    WriteBlock(Address, Box<[u8; 256]>),
+
+    // request emulator state.
+    MemRequest(Address, u32),
+    DisplayRequest,
+    StackRequest,
+    RegisterRequest,
+    RunningRequest,
+    HistoryRequest,
+    InstructionCountRequest,
+}
+
+#[derive(Debug)]
+pub enum ProcessorError {
+    InvalidInstruction(u32),
+    InvalidRegister(u8),
+    BadMemoryAccess(u32),
+}
+
+impl std::error::Error for ProcessorError {}
+
+impl std::fmt::Display for ProcessorError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::InvalidInstruction(instruction) => {
+                write!(f, "Invalid instruction: {instruction}")
+            }
+            Self::InvalidRegister(register) => {
+                write!(f, "Invalid register: {register}")
+            }
+            Self::BadMemoryAccess(address) => {
+                write!(f, "Bad memory access: {address}")
+            }
+        }
+    }
+}
+
+pub struct State {
+    pub state_receiver: Receiver<StateUpdate>,
+    pub cmd_sender: Sender<Command>,
+
+    // Processor state
+    pub reg_file: RegFile,
+    pub running: Running,
+    pub instructions: usize,
+
+    // Memory access views
+    pub stack_view: Vec<u8>,
+    pub memory_view: Vec<u8>,
+    pub display_view: Vec<u8>,
+
+    pub error_log: Vec<String>,
+
+    pub instruction_history: Vec<(u32, Instruction)>,
+}
+
+impl State {
+    #[must_use]
+    pub fn new(sender: Sender<Command>, receiver: Receiver<StateUpdate>) -> Self {
+        Self {
+            state_receiver: receiver,
+            cmd_sender: sender,
+            reg_file: RegFile::default(),
+            running: Running::Paused,
+            instructions: 0,
+            stack_view: vec![],
+            memory_view: vec![],
+            display_view: vec![],
+            error_log: vec![],
+            instruction_history: vec![],
+        }
+    }
+
+    pub fn send(&mut self, cmd: Command) {
+        if let Err(e) = self.cmd_sender.send(cmd) {
+            self.error_log.push(e.to_string());
+        }
+    }
+
+    pub fn update(&mut self) -> Result<(), mpsc::TryRecvError> {
+        while let Ok(update) = self.state_receiver.try_recv() {
+            match update {
+                StateUpdate::Registers(reg_file) => self.reg_file = reg_file,
+                StateUpdate::Running(running) => self.running = running,
+                StateUpdate::Instructions(instructions) => {
+                    self.instructions = instructions;
+                }
+                StateUpdate::StackView(stack_view) => self.stack_view = stack_view,
+                StateUpdate::MemoryView(memory_view) => self.memory_view = memory_view,
+                StateUpdate::DisplayView(display_view) => {
+                    self.display_view = display_view;
+                }
+                StateUpdate::Error(err_state) => self.error_log.push(err_state),
+                StateUpdate::InstructionHistory(history) => {
+                    self.instruction_history.extend(history);
+                }
+            }
+
+            if self.error_log.len() > 256 {
+                self.error_log.drain(0..self.error_log.len() - 256);
+            }
+
+            if self.instruction_history.len() > 1024 {
+                self.instruction_history
+                    .drain(0..self.instruction_history.len() - 1024);
+            }
+        }
+
+        if let Err(e) = self.state_receiver.try_recv() {
+            match e {
+                mpsc::TryRecvError::Empty => {}
+                mpsc::TryRecvError::Disconnected => {
+                    return Err(e);
+                }
+            }
+        }
+
+        Ok(())
+    }
+}
+
+pub enum StateUpdate {
+    Registers(RegFile),
+    Running(Running),
+    Instructions(usize),
+    StackView(Vec<u8>),
+    MemoryView(Vec<u8>),
+    DisplayView(Vec<u8>),
+    Error(String),
+    InstructionHistory(Vec<(u32, Instruction)>),
 }
 
 #[derive(Default, Debug, Clone, Copy, PartialEq, Eq)]
@@ -127,8 +257,8 @@ impl RegFile {
         self.pcx = 0;
     }
 
-    pub fn reg(&mut self, reg: Register) -> &mut u32 {
+    pub const fn reg(&mut self, reg: Register) -> Result<&mut u32, ProcessorError> {
-        match reg {
+        Ok(match reg {
             Register::Rg0 => &mut self.rg0,
             Register::Rg1 => &mut self.rg1,
             Register::Rg2 => &mut self.rg2,
@@ -156,13 +286,13 @@ impl RegFile {
             Register::Sts => &mut self.sts,
             Register::Cir => &mut self.cir,
             Register::Pcx => &mut self.pcx,
-            _ => panic!("Invalid register."),
+            _ => return Err(ProcessorError::InvalidRegister(Register::NoReg as u8)),
-        }
+        })
     }
 
     #[must_use]
-    pub fn get(&self, reg: Register) -> u32 {
+    pub const fn get(&self, reg: Register) -> Result<u32, ProcessorError> {
-        match reg {
+        Ok(match reg {
             Register::Rg0 => self.rg0,
             Register::Rg1 => self.rg1,
             Register::Rg2 => self.rg2,
@@ -191,51 +321,7 @@ impl RegFile {
             Register::Cir => self.cir,
             Register::Pcx => self.pcx,
             Register::Zero => 0,
-            _ => panic!("Invalid register."),
+            _ => return Err(ProcessorError::InvalidRegister(Register::NoReg as u8)),
-        }
+        })
-    }
-}
-
-pub struct State {
-    pub reg_file: RegFile,
-    pub running: Running,
-    pub instructions: usize,
-
-    // Memory access views
-    pub stack_view: Vec<u8>,
-    pub memory_view: Vec<u8>,
-    pub display_view: Vec<u8>,
-    pub error: Option<String>,
-
-    pub persistent: PersistentState,
-}
-
-impl Default for State {
-    fn default() -> Self {
-        Self {
-            reg_file: RegFile::default(),
-            running: Running::Paused,
-            instructions: 0,
-            stack_view: vec![],
-            memory_view: vec![],
-            display_view: vec![],
-            persistent: PersistentState::default(),
-            error: None,
-        }
-    }
-}
-
-#[derive(Clone, Debug, Default)]
-pub struct PersistentState {
-    pub history: Vec<(u32, Instruction)>,
-}
-
-impl PersistentState {
-    pub fn update(&mut self, new_state: &Self) {
-        self.history.extend(new_state.history.clone());
-        if self.history.len() > 1024 {
-            let len = self.history.len() - 1024;
-            self.history.drain(..len);
-        }
     }
 }

emulator/src/emulator/system/processor/mod.rs

@@ -5,12 +5,10 @@ use std::{
 
 use crate::emulator::system::{
     memory::MemoryUnit,
-    model::{IODevice, RegFile},
+    model::{IODevice, ProcessorError, RegFile},
 };
 
-use common::instructions::{
+use common::instructions::{Instruction, Interrupt, Register};
-    Instruction, Interrupt, Register, errors::InstructionDecodeError,
-};
 
 pub struct Processor {
     pub memory: Box<dyn MemoryUnit>,
@@ -18,14 +16,13 @@ pub struct Processor {
     pub halted: bool,
     pub io_devices: Vec<Arc<dyn IODevice>>,
 
-    pub dustbin: u32,
+    pub void: u32,
 }
 
 fn log(message: &str) {
     println!("\x1b[32mINFO:\x1b[0m {message}");
 }
 
-#[allow(clippy::needless_pass_by_ref_mut)]
 impl Processor {
     #[must_use]
     pub fn new(memory: Box<dyn MemoryUnit>, io_devices: Vec<Arc<dyn IODevice>>) -> Self {
@@ -34,7 +31,7 @@ impl Processor {
             registers: RegFile::default(),
             halted: false,
             io_devices,
-            dustbin: 0,
+            void: 0,
         }
     }
 
@@ -48,48 +45,45 @@ impl Processor {
         self.memory.reset();
     }
 
-    pub fn cycle(&mut self) -> Result<(u32, Instruction), InstructionDecodeError> {
+    pub fn cycle(&mut self) -> Result<(u32, Instruction), ProcessorError> {
         self.halted = false;
 
         // Get value from PCX.
-        let addr = self.fetch();
+        let addr = self.fetch()?;
         // Increment PCX.
         self.advance();
 
         // Set MAR to the previous value of PCX.
-        *self.reg(Register::Mar) = addr;
+        *self.reg(Register::Mar)? = addr;
-        let val = self.memory.read_word(addr);
+        let val = self.memory.read_word(addr)?;
 
         // Set CIR to the value of RAM[MAR].
-        *self.reg(Register::Mar) = val;
+        *self.reg(Register::Mar)? = val;
 
         // Decode and execute the instruction.
-        let instruction = Instruction::decode(val)?;
+        let instruction = Instruction::decode(val)
-
+            .map_err(|_| ProcessorError::InvalidInstruction(val))?;
-        log(&instruction.to_string());
-
-        instruction.execute(self);
 
+        instruction.execute(self)?;
         Ok((addr, instruction))
     }
 
-    fn fetch(&self) -> u32 {
+    const fn fetch(&self) -> Result<u32, ProcessorError> {
         self.get(Register::Pcx)
     }
 
-    #[must_use]
+    pub const fn get(&self, reg: Register) -> Result<u32, ProcessorError> {
-    pub fn get(&self, reg: Register) -> u32 {
         self.registers.get(reg)
     }
 
-    pub fn reg(&mut self, reg: Register) -> &mut u32 {
+    pub const fn reg(&mut self, reg: Register) -> Result<&mut u32, ProcessorError> {
         match reg {
-            Register::Zero => &mut self.dustbin,
+            Register::Zero => Ok(&mut self.void),
             _ => self.registers.reg(reg),
         }
     }
 
-    pub fn display(&mut self) -> Vec<u8> {
+    pub fn display(&mut self) -> Result<Vec<u8>, ProcessorError> {
         self.memory.read_range(0x20000, 2000)
     }
 
@@ -99,53 +93,74 @@ impl Processor {
         self.set_flag(Flag::LessThan, a < b);
     }
 
-    // stack operations
-
-    pub fn push(&mut self, value: u32) {
-        let stack_ptr = self.get(Register::Spr);
-        *self.reg(Register::Spr) += 4;
-        self.memory.write_word(stack_ptr, value);
-    }
-
-    pub fn pop(&mut self) -> u32 {
-        *self.reg(Register::Spr) -= 4;
-        self.memory.read_word(self.get(Register::Spr))
-    }
-
     // functions to set new state
-
     fn set_flag(&mut self, flag: Flag, value: bool) {
         if value {
-            *self.reg(Register::Sts) |= flag as u32;
+            *self
+                .reg(Register::Sts)
+                .expect("STS should never be invalid") |= flag as u32;
         } else {
-            *self.reg(Register::Sts) &= !(flag as u32);
+            *self
+                .reg(Register::Sts)
+                .expect("STS should never be invalid") &= !(flag as u32);
         }
     }
 
-    fn get_flag(&self, flag: Flag) -> bool {
+    fn get_flag(&self, flag: Flag) -> Result<bool, ProcessorError> {
-        self.get(Register::Sts) & (flag as u32) != 0
+        Ok(self.get(Register::Sts)? & (flag as u32) != 0)
     }
 
-    fn advance(&mut self) {
+    fn advance(&mut self) -> Result<(), ProcessorError> {
         // increment PCX
-        *self.reg(Register::Pcx) += 4;
+        *self.reg(Register::Pcx)? += 4;
+        Ok(())
     }
 
-    fn jump(&mut self, reg: Register, offset: u16) {
+    fn jump(&mut self, reg: Register, offset: u16) -> Result<(), ProcessorError> {
-        *self.reg(Register::Pcx) = self.get(reg) + u32::from(offset);
+        *self.reg(Register::Pcx)? = self.get(reg)? + u32::from(offset);
+        Ok(())
     }
 
-    fn begin_interrupt(&mut self, _int: Interrupt) {
+    pub fn begin_interrupt(
-        // first we get the address of the interrupt descriptor table.
+        &mut self,
-        todo!();
+        interrupt: Interrupt,
+    ) -> Result<(), ProcessorError> {
+        let idt = self.get(Register::Idr)?;
+
+        let addr = self
+            .memory
+            .read_word(idt + u32::from(interrupt.as_u8()) * 4)?;
+        println!("INFO: Interrupt {interrupt:?} addr: {addr}");
+
+        self.push(self.get(Register::Pcx)?)?;
+        *self.reg(Register::Pcx)? = addr;
+        Ok(())
     }
 
-    fn end_interrupt(&mut self) {
+    fn push(&mut self, val: u32) -> Result<(), ProcessorError> {
-        todo!();
+        *self.reg(Register::Spr)? -= 4;
+        let reg = *self.reg(Register::Spr)?;
+        self.memory.write_word(reg, val)
     }
 
-    pub fn get_stack(&mut self, n: u32) -> Vec<u8> {
+    fn pop(&mut self) -> Result<u32, ProcessorError> {
-        let addr = self.get(Register::Spr);
+        let reg = *self.reg(Register::Spr)?;
+        let val = self.memory.read_word(reg)?;
+        *self.reg(Register::Spr)? += 4;
+        Ok(val)
+    }
+
+    // TODO: remove this once implemented
+    #[allow(clippy::needless_pass_by_ref_mut)]
+    fn end_interrupt(&mut self) -> Result<(), ProcessorError> {
+        let ret = self.pop()?;
+        *self.reg(Register::Ret)? = ret;
+        *self.reg(Register::Pcx)? = ret;
+        Ok(())
+    }
+
+    pub fn get_stack(&mut self, n: u32) -> Result<Vec<u8>, ProcessorError> {
+        let addr = self.get(Register::Spr)?;
         let size = n * 4;
         // returns the stack
         self.memory.read_range(
@@ -170,38 +185,40 @@ enum Flag {
 }
 
 trait Executable {
-    fn execute(self, cpu: &mut Processor);
+    fn execute(self, cpu: &mut Processor) -> Result<(), ProcessorError>;
 }
 
 impl Executable for Instruction {
     #[allow(clippy::too_many_lines)]
-    fn execute(self, cpu: &mut Processor) {
+    fn execute(self, cpu: &mut Processor) -> Result<(), ProcessorError> {
         match self {
             // No operation - a blank line.
             // Copies from SrcReg to a.drReg.
             Self::Mov(a) => {
-                *cpu.reg(a.dr) = cpu.get(a.sr1);
+                *cpu.reg(a.dr)? = cpu.get(a.sr1)?;
             }
 
             // Copies from SrcReg to a.drReg, sign extending the value to take up a full
             // word.
             Self::MovSigned(a) => {
-                *cpu.reg(a.dr) = sign_extend(cpu.get(a.sr1));
+                *cpu.reg(a.dr)? = sign_extend(cpu.get(a.sr1)?);
             }
 
             // Loads a byte from memory address (base + offset) into a.drReg. The
             // effective address must be byte-aligned.
             Self::LoadByte(a) => {
-                *cpu.reg(a.r2) = u32::from(
+                *cpu.reg(a.r2)? = u32::from(
-                    cpu.memory.read_byte(cpu.get(a.r1) + u32::from(a.immediate)),
+                    cpu.memory
+                        .read_byte(cpu.get(a.r1)? + u32::from(a.immediate))?,
                 );
             }
 
             // Loads a sign-extended byte from memory address (base + offset) into
             // a.drReg. The effective address must be byte-aligned.
             Self::LoadByteSigned(a) => {
-                *cpu.reg(a.r2) = sign_extend(u32::from(
+                *cpu.reg(a.r2)? = sign_extend(u32::from(
-                    cpu.memory.read_byte(cpu.get(a.r1) + u32::from(a.immediate)),
+                    cpu.memory
+                        .read_byte(cpu.get(a.r1)? + u32::from(a.immediate))?,
                 ));
             }
 
@@ -210,181 +227,184 @@ impl Executable for Instruction {
             Self::LoadHalfword(a) => {
                 // we read an entire word, then right shift so we only get the first half
                 // of the word
-                *cpu.reg(a.r2) =
+                *cpu.reg(a.r2)? = cpu
-                    cpu.memory.read_word(cpu.get(a.r1) + u32::from(a.immediate)) >> 16;
+                    .memory
+                    .read_word(cpu.get(a.r1)? + u32::from(a.immediate))?
+                    >> 16;
             }
 
             // Loads a sign-extended half-word from memory address (base + offset) into
             // a.drReg. The effective address must be 2-byte-aligned.
             Self::LoadHalfwordSigned(a) => {
-                *cpu.reg(a.r2) = sign_extend(
+                *cpu.reg(a.r2)? = sign_extend(
-                    cpu.memory.read_word(cpu.get(a.r1) + u32::from(a.immediate)) >> 16,
+                    cpu.memory
+                        .read_word(cpu.get(a.r1)? + u32::from(a.immediate))?
+                        >> 16,
                 );
             }
 
             // Loads a word from memory address (base + offset) into a.drReg. The
             // effective address must be 4-byte-aligned.
             Self::LoadWord(a) => {
-                *cpu.reg(a.r2) =
+                *cpu.reg(a.r2)? = cpu
-                    cpu.memory.read_word(cpu.get(a.r1) + u32::from(a.immediate));
+                    .memory
+                    .read_word(cpu.get(a.r1)? + u32::from(a.immediate))?;
             }
 
             // Stores a byte from SrcReg in memory address (base + offset) The effective
             // address must be byte-aligned.
             Self::StoreByte(a) => {
                 cpu.memory.write_byte(
-                    cpu.get(a.r2) + u32::from(a.immediate),
+                    cpu.get(a.r2)? + u32::from(a.immediate),
-                    cpu.get(a.r1) as u8,
+                    cpu.get(a.r1)? as u8,
-                );
+                )?;
             }
 
             // Stores a half-word from SrcReg in memory address (base + offset) The
             // effective address must be 2-byte-aligned.
             Self::StoreHalfword(a) => {
                 // split the value into bytes and then write two bytes
-                let bytes = (cpu.get(a.r1) as u16).to_le_bytes();
+                let bytes = (cpu.get(a.r1)? as u16).to_le_bytes();
                 cpu.memory
-                    .write_byte(cpu.get(a.r2) + u32::from(a.immediate), bytes[0]);
+                    .write_byte(cpu.get(a.r2)? + u32::from(a.immediate), bytes[0])?;
                 cpu.memory
-                    .write_byte(cpu.get(a.r2) + u32::from(a.immediate) + 1, bytes[1]);
+                    .write_byte(cpu.get(a.r2)? + u32::from(a.immediate) + 1, bytes[1])?;
             }
 
             // Stores a word from SrcReg in memory address (base + offset) The effective
             // address must be 4-byte-aligned.
             Self::StoreWord(a) => {
-                cpu.memory
+                cpu.memory.write_word(
-                    .write_word(cpu.get(a.r2) + u32::from(a.immediate), cpu.get(a.r1));
+                    cpu.get(a.r2)? + u32::from(a.immediate),
+                    cpu.get(a.r1)?,
+                )?;
             }
 
             // Loads a 16-bit literal value into reg, setting the bottom 16 bits of the
             // word. To populate the upper 16 bits, see LUI.
             Self::LoadLowerImmediate(a) => {
-                *cpu.reg(a.r1) = u32::from(a.immediate);
+                *cpu.reg(a.r1)? = u32::from(a.immediate);
             }
 
             // Loads a 16-bit literal value into reg, setting the top 16 bits of the word.
             // To populate the lower 16 bits, see LLI.
             Self::LoadUpperImmediate(a) => {
-                *cpu.reg(a.r1) =
+                *cpu.reg(a.r1)? =
-                    (cpu.get(a.r1) & 0x0000_FFFF) | (u32::from(a.immediate) << 16);
+                    (cpu.get(a.r1)? & 0x0000_FFFF) | (u32::from(a.immediate) << 16);
             }
 
             // Unconditionally jumps to the calculated address or direct address
-            Self::Jump(a) => cpu.jump(a.r1, a.immediate),
+            Self::Jump(a) => cpu.jump(a.r1, a.immediate)?,
 
             // Jumps to the calculated address or direct address if equal flag set.
             Self::JumpEq(a) => {
-                if cpu.get_flag(Flag::Equal) {
+                if cpu.get_flag(Flag::Equal)? {
-                    cpu.jump(a.r1, a.immediate);
+                    cpu.jump(a.r1, a.immediate)?;
                 }
             }
 
             // Jumps to the calculated address or direct address if equal flag not set.
             Self::JumpNeq(a) => {
-                if !cpu.get_flag(Flag::Equal) {
+                if !cpu.get_flag(Flag::Equal)? {
-                    cpu.jump(a.r1, a.immediate);
+                    cpu.jump(a.r1, a.immediate)?;
                 }
             }
 
             // Jumps to the calculated address or direct address if greater than flag set.
             Self::JumpGt(a) => {
-                if cpu.get_flag(Flag::GreaterThan) {
+                if cpu.get_flag(Flag::GreaterThan)? {
-                    cpu.jump(a.r1, a.immediate);
+                    cpu.jump(a.r1, a.immediate)?;
                 }
             }
 
             // Jumps to the calculated address or direct address if greater than flag or
             // equal flag set.
             Self::JumpGe(a) => {
-                if cpu.get_flag(Flag::GreaterThan) || cpu.get_flag(Flag::Equal) {
+                if cpu.get_flag(Flag::GreaterThan)? || cpu.get_flag(Flag::Equal)? {
-                    cpu.jump(a.r1, a.immediate);
+                    cpu.jump(a.r1, a.immediate)?;
                 }
             }
 
             // Jumps to the calculated address or direct address if less than flag set.
             Self::JumpLt(a) => {
-                if cpu.get_flag(Flag::LessThan) {
+                if cpu.get_flag(Flag::LessThan)? {
-                    cpu.jump(a.r1, a.immediate);
+                    cpu.jump(a.r1, a.immediate)?;
                 }
             }
 
             // Jumps to the calculated address or direct address if less than flag or
             // equal flag set.
             Self::JumpLe(a) => {
-                if cpu.get_flag(Flag::LessThan) || cpu.get_flag(Flag::Equal) {
+                if cpu.get_flag(Flag::LessThan)? || cpu.get_flag(Flag::Equal)? {
-                    cpu.jump(a.r1, a.immediate);
+                    cpu.jump(a.r1, a.immediate)?;
                 }
             }
 
             // Increments the value in the given register
-            Self::Increment(a) => *cpu.reg(a.sr1) = inc(cpu.get(a.sr1)),
+            Self::Increment(a) => *cpu.reg(a.sr1)? = inc(cpu.get(a.sr1)?),
 
             // Decrements the value in the given register
-            Self::Decrement(a) => *cpu.reg(a.sr1) = dec(cpu.get(a.sr1)),
+            Self::Decrement(a) => *cpu.reg(a.sr1)? = dec(cpu.get(a.sr1)?),
 
             // Left shifts the value in Reg by the given amount (either a register, or a
             // literal value)
             Self::ShiftLeft(a) => {
-                let regval = cpu.get(a.sr2);
+                let reg = cpu.get(a.sr1)?;
-                let val = cpu.get(a.sr1);
+                let val = a.shamt;
-
+                *cpu.reg(a.sr1)? = shl(reg, val);
-                *cpu.reg(a.sr1) =
-                    shl(val, if regval != 0 { regval as u8 } else { a.shamt });
             }
 
             // Right shifts the value in Reg by the given amount (either a register, or a
             // literal value).
             Self::ShiftRight(a) => {
-                let regval = cpu.get(a.sr2);
+                let regval = cpu.get(a.sr1)?;
-                let val = cpu.get(a.sr1);
+                let val = a.shamt;
-
+                *cpu.reg(a.sr1)? = shr(regval, val);
-                *cpu.reg(a.sr1) =
-                    shr(val, if regval != 0 { regval as u8 } else { a.shamt });
             }
 
             // Adds the value of Src2 to Src1 and writes the result to a.dr
             Self::Add(a) => {
-                *cpu.reg(a.dr) = add(cpu.get(a.sr1), cpu.get(a.sr2));
+                *cpu.reg(a.dr)? = add(cpu.get(a.sr1)?, cpu.get(a.sr2)?);
             }
 
             // Subtracts the value of Src2 from Src1 and writes the result to a.dr
             Self::Sub(a) => {
-                *cpu.reg(a.dr) = sub(cpu.get(a.sr1), cpu.get(a.sr2));
+                *cpu.reg(a.dr)? = sub(cpu.get(a.sr1)?, cpu.get(a.sr2)?);
             }
 
             Self::AddImmediate(a) => {
-                *cpu.reg(a.r2) = add(cpu.get(a.r1), u32::from(a.immediate));
+                *cpu.reg(a.r2)? = add(cpu.get(a.r1)?, u32::from(a.immediate));
             }
 
             Self::SubImmediate(a) => {
-                *cpu.reg(a.r2) = sub(cpu.get(a.r1), u32::from(a.immediate));
+                *cpu.reg(a.r2)? = sub(cpu.get(a.r1)?, u32::from(a.immediate));
             }
 
             // Performs bitwise AND on Src1 and Src2 storing the result in a.dr
-            Self::And(a) => *cpu.reg(a.dr) = and(cpu.get(a.sr1), cpu.get(a.sr2)),
+            Self::And(a) => *cpu.reg(a.dr)? = and(cpu.get(a.sr1)?, cpu.get(a.sr2)?),
 
             // Performs bitwise OR on Src1 and Src2 storing the result in a.dr
-            Self::Or(a) => *cpu.reg(a.dr) = or(cpu.get(a.sr1), cpu.get(a.sr2)),
+            Self::Or(a) => *cpu.reg(a.dr)? = or(cpu.get(a.sr1)?, cpu.get(a.sr2)?),
 
             // Performs bitwise NOT on Src storing the result in a.dr
-            Self::Not(a) => *cpu.reg(a.dr) = not(cpu.get(a.sr1)),
+            Self::Not(a) => *cpu.reg(a.dr)? = not(cpu.get(a.sr1)?),
 
             // Performs bitwise XOR on Src1 and Src2 storing the result in a.dr
-            Self::Xor(a) => *cpu.reg(a.dr) = xor(cpu.get(a.sr1), cpu.get(a.sr2)),
+            Self::Xor(a) => *cpu.reg(a.dr)? = xor(cpu.get(a.sr1)?, cpu.get(a.sr2)?),
 
             // Performs bitwise NAND on Src1 and Src2 storing the result in a.dr
-            Self::Nand(a) => *cpu.reg(a.dr) = nand(cpu.get(a.sr1), cpu.get(a.sr2)),
+            Self::Nand(a) => *cpu.reg(a.dr)? = nand(cpu.get(a.sr1)?, cpu.get(a.sr2)?),
 
             // Performs bitwise NOR on Src1 and Src2 storing the result in a.dr
-            Self::Nor(a) => *cpu.reg(a.dr) = nor(cpu.get(a.sr1), cpu.get(a.sr2)),
+            Self::Nor(a) => *cpu.reg(a.dr)? = nor(cpu.get(a.sr1)?, cpu.get(a.sr2)?),
 
             // Performs bitwise XNOR on Src1 and Src2 storing the result in a.dr
-            Self::Xnor(a) => *cpu.reg(a.dr) = xnor(cpu.get(a.sr1), cpu.get(a.sr2)),
+            Self::Xnor(a) => *cpu.reg(a.dr)? = xnor(cpu.get(a.sr1)?, cpu.get(a.sr2)?),
 
             // Compares the value of Reg1 to the value in Reg2. The results of the
             // comparisons are set in the Status register.
             Self::Compare(a) => {
-                cpu.cmp(cpu.get(a.sr1), cpu.get(a.sr2));
+                cpu.cmp(cpu.get(a.sr1)?, cpu.get(a.sr2)?);
             }
 
             // Initiates an interrupt with the given 8 bit interrupt code.
@@ -392,12 +412,12 @@ impl Executable for Instruction {
             //      - The return address is saved to the RET register.
             //      - The stack base ptr is set to the kernel stack.
             Self::Interrupt(interrupt_code) => {
-                cpu.begin_interrupt(interrupt_code);
+                cpu.begin_interrupt(interrupt_code)?;
             }
 
             // Returns from an interrupt,
             Self::IntReturn => {
-                cpu.end_interrupt();
+                cpu.end_interrupt()?;
             }
 
             // Halts the processor.
@@ -411,6 +431,7 @@ impl Executable for Instruction {
                 todo!()
             }
         }
+        Ok(())
     }
 }
 

emulator/src/emulator/system/processor/tests.rs

@@ -13,22 +13,32 @@ fn test_nop_instruction() {
     let mut cpu = create_test_processor();
     let initial_state = cpu.registers;
 
-    Instruction::Nop.execute(&mut cpu);
+    Instruction::Nop.execute(&mut cpu).expect(
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
 
     assert_eq!(
-        cpu.registers.get(Register::Rg0),
+        cpu.registers
-        initial_state.get(Register::Rg0)
+            .get(Register::Rg0)
+            .expect("Failed to get register Rg0"),
+        initial_state
+            .get(Register::Rg0)
+            .expect("Failed to get register Rg0")
     );
     assert_eq!(
-        cpu.registers.get(Register::Acc),
+        cpu.registers
-        initial_state.get(Register::Acc)
+            .get(Register::Acc)
+            .expect("Failed to get register Acc"),
+        initial_state
+            .get(Register::Acc)
+            .expect("Failed to get register Acc")
     );
 }
 
 #[test]
 fn test_mov_instruction() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 0x1234_5678;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 0x1234_5678;
 
     let mov_instr = Instruction::Mov(RTypeArgs::new(
         Some(Register::Rg1),
@@ -37,14 +47,19 @@ fn test_mov_instruction() {
         None,
     ));
 
-    mov_instr.execute(&mut cpu);
+    mov_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg2), 0x1234_5678);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg2).expect("Failed to get register Rg2"),
+        0x1234_5678
+    );
 }
 
 #[test]
 fn test_mov_signed_instruction() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 0x0000_00FF;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 0x0000_00FF;
 
     let mov_signed_instr = Instruction::MovSigned(RTypeArgs::new(
         Some(Register::Rg1),
@@ -53,16 +68,23 @@ fn test_mov_signed_instruction() {
         None,
     ));
 
-    mov_signed_instr.execute(&mut cpu);
+    mov_signed_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg2), 0xFFFF_FFFF);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg2).expect("Failed to get register Rg2"),
+        0xFFFF_FFFF
+    );
 }
 
 #[test]
 fn test_load_byte_instruction() {
     let mut cpu = create_test_processor();
     let addr = 0x100;
-    cpu.memory.write_byte(addr, 0xAB);
+    cpu.memory
-    *cpu.reg(Register::Rg1) = addr - 4;
+        .write_byte(addr, 0xAB)
+        .expect("Failed to write byte to memory");
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = addr - 4;
 
     let load_byte_instr = Instruction::LoadByte(ITypeArgs::new(
         4,
@@ -70,16 +92,23 @@ fn test_load_byte_instruction() {
         Some(Register::Rg2),
     ));
 
-    load_byte_instr.execute(&mut cpu);
+    load_byte_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg2), 0x0000_00AB);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg2).expect("Failed to get register Rg2"),
+        0x0000_00AB
+    );
 }
 
 #[test]
 fn test_load_byte_signed_instruction() {
     let mut cpu = create_test_processor();
     let addr = 0x100;
-    cpu.memory.write_byte(addr, 0xFF);
+    cpu.memory
-    *cpu.reg(Register::Rg1) = addr;
+        .write_byte(addr, 0xFF)
+        .expect("Failed to write byte to memory");
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = addr;
 
     let load_byte_signed_instr = Instruction::LoadByteSigned(ITypeArgs::new(
         0,
@@ -87,16 +116,23 @@ fn test_load_byte_signed_instruction() {
         Some(Register::Rg2),
     ));
 
-    load_byte_signed_instr.execute(&mut cpu);
+    load_byte_signed_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg2), 0xFFFF_FFFF);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg2).expect("Failed to get register Rg2"),
+        0xFFFF_FFFF
+    );
 }
 
 #[test]
 fn test_load_halfword_instruction() {
     let mut cpu = create_test_processor();
     let addr = 0x100;
-    cpu.memory.write_word(addr, 0x1234_5678);
+    cpu.memory
-    *cpu.reg(Register::Rg1) = addr;
+        .write_word(addr, 0x1234_5678)
+        .expect("Failed to write word to memory");
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = addr;
 
     let load_halfword_instr = Instruction::LoadHalfword(ITypeArgs::new(
         0,
@@ -104,16 +140,23 @@ fn test_load_halfword_instruction() {
         Some(Register::Rg2),
     ));
 
-    load_halfword_instr.execute(&mut cpu);
+    load_halfword_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg2), 0x0000_1234);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg2).expect("Failed to get register Rg2"),
+        0x0000_1234
+    );
 }
 
 #[test]
 fn test_load_word_instruction() {
     let mut cpu = create_test_processor();
     let addr = 0x100;
-    cpu.memory.write_word(addr, 0x1234_5678);
+    cpu.memory
-    *cpu.reg(Register::Rg1) = addr;
+        .write_word(addr, 0x1234_5678)
+        .expect("Failed to write word to memory");
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = addr;
 
     let load_word_instr = Instruction::LoadWord(ITypeArgs::new(
         0,
@@ -121,16 +164,21 @@ fn test_load_word_instruction() {
         Some(Register::Rg2),
     ));
 
-    load_word_instr.execute(&mut cpu);
+    load_word_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg2), 0x1234_5678);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg2).expect("Failed to get register Rg2"),
+        0x1234_5678
+    );
 }
 
 #[test]
 fn test_store_byte_instruction() {
     let mut cpu = create_test_processor();
     let addr = 0x100;
-    *cpu.reg(Register::Rg1) = addr;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = addr;
-    *cpu.reg(Register::Rg2) = 0xAB;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 0xAB;
 
     let store_byte_instr = Instruction::StoreByte(ITypeArgs::new(
         0,
@@ -138,16 +186,18 @@ fn test_store_byte_instruction() {
         Some(Register::Rg1),
     ));
 
-    store_byte_instr.execute(&mut cpu);
+    store_byte_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.memory.read_byte(addr), 0xAB);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(cpu.memory.read_byte(addr).expect("Emulator was slain by losing the game while attempting to execute instruction"), 0xAB);
 }
 
 #[test]
 fn test_store_word_instruction() {
     let mut cpu = create_test_processor();
     let addr = 0x100;
-    *cpu.reg(Register::Rg1) = addr;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = addr;
-    *cpu.reg(Register::Rg2) = 0x1234_5678;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 0x1234_5678;
 
     let store_word_instr = Instruction::StoreWord(ITypeArgs::new(
         0,
@@ -155,15 +205,17 @@ fn test_store_word_instruction() {
         Some(Register::Rg1),
     ));
 
-    store_word_instr.execute(&mut cpu);
+    store_word_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.memory.read_word(addr), 0x1234_5678);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(cpu.memory.read_word(addr).expect("Emulator was slain by losing the game while attempting to execute instruction"), 0x1234_5678);
 }
 
 #[test]
 fn test_add_instruction() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 15;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 15;
-    *cpu.reg(Register::Rg2) = 25;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 25;
 
     let add_instr = Instruction::Add(RTypeArgs::new(
         Some(Register::Rg1),
@@ -172,15 +224,20 @@ fn test_add_instruction() {
         None,
     ));
 
-    add_instr.execute(&mut cpu);
+    add_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg3), 40);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg3).expect("Failed to get register Rg3"),
+        40
+    );
 }
 
 #[test]
 fn test_sub_instruction() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 50;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 50;
-    *cpu.reg(Register::Rg2) = 20;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 20;
 
     let sub_instr = Instruction::Sub(RTypeArgs::new(
         Some(Register::Rg1),
@@ -189,15 +246,20 @@ fn test_sub_instruction() {
         None,
     ));
 
-    sub_instr.execute(&mut cpu);
+    sub_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg3), 30);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg3).expect("Failed to get register Rg3"),
+        30
+    );
 }
 
 #[test]
 fn test_and_instruction() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 0b1100;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 0b1100;
-    *cpu.reg(Register::Rg2) = 0b1010;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 0b1010;
 
     let and_instr = Instruction::And(RTypeArgs::new(
         Some(Register::Rg1),
@@ -206,15 +268,20 @@ fn test_and_instruction() {
         None,
     ));
 
-    and_instr.execute(&mut cpu);
+    and_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg3), 0b1000);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg3).expect("Failed to get register Rg3"),
+        0b1000
+    );
 }
 
 #[test]
 fn test_or_instruction() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 0b1100;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 0b1100;
-    *cpu.reg(Register::Rg2) = 0b1010;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 0b1010;
 
     let or_instr = Instruction::Or(RTypeArgs::new(
         Some(Register::Rg1),
@@ -223,15 +290,20 @@ fn test_or_instruction() {
         None,
     ));
 
-    or_instr.execute(&mut cpu);
+    or_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg3), 0b1110);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg3).expect("Failed to get register Rg3"),
+        0b1110
+    );
 }
 
 #[test]
 fn test_xor_instruction() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 0b1100;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 0b1100;
-    *cpu.reg(Register::Rg2) = 0b1010;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 0b1010;
 
     let xor_instr = Instruction::Xor(RTypeArgs::new(
         Some(Register::Rg1),
@@ -240,14 +312,19 @@ fn test_xor_instruction() {
         None,
     ));
 
-    xor_instr.execute(&mut cpu);
+    xor_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg3), 0b0110);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg3).expect("Failed to get register Rg3"),
+        0b0110
+    );
 }
 
 #[test]
 fn test_not_instruction() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 0x0F0F_0F0F;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 0x0F0F_0F0F;
 
     let not_instr = Instruction::Not(RTypeArgs::new(
         Some(Register::Rg1),
@@ -256,15 +333,20 @@ fn test_not_instruction() {
         None,
     ));
 
-    not_instr.execute(&mut cpu);
+    not_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg2), 0xF0F0_F0F0);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg2).expect("Failed to get register Rg2"),
+        0xF0F0_F0F0
+    );
 }
 
 #[test]
 fn test_compare_equal() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 42;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 42;
-    *cpu.reg(Register::Rg2) = 42;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 42;
 
     let cmp_instr = Instruction::Compare(RTypeArgs::new(
         Some(Register::Rg1),
@@ -273,18 +355,26 @@ fn test_compare_equal() {
         None,
     ));
 
-    cmp_instr.execute(&mut cpu);
+    cmp_instr.execute(&mut cpu).expect(
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
 
-    assert!(cpu.get_flag(Flag::Equal));
+    assert!(cpu.get_flag(Flag::Equal).expect("Failed to get flag Equal"));
-    assert!(!cpu.get_flag(Flag::GreaterThan));
+    assert!(
-    assert!(!cpu.get_flag(Flag::LessThan));
+        !cpu.get_flag(Flag::GreaterThan)
+            .expect("Failed to get flag GreaterThan")
+    );
+    assert!(
+        !cpu.get_flag(Flag::LessThan)
+            .expect("Failed to get flag LessThan")
+    );
 }
 
 #[test]
 fn test_compare_greater_than() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 50;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 50;
-    *cpu.reg(Register::Rg2) = 30;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 30;
 
     let cmp_instr = Instruction::Compare(RTypeArgs::new(
         Some(Register::Rg1),
@@ -293,18 +383,26 @@ fn test_compare_greater_than() {
         None,
     ));
 
-    cmp_instr.execute(&mut cpu);
+    cmp_instr.execute(&mut cpu).expect(
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
 
-    assert!(!cpu.get_flag(Flag::Equal));
+    assert!(!cpu.get_flag(Flag::Equal).expect("Failed to get flag Equal"));
-    assert!(cpu.get_flag(Flag::GreaterThan));
+    assert!(
-    assert!(!cpu.get_flag(Flag::LessThan));
+        cpu.get_flag(Flag::GreaterThan)
+            .expect("Failed to get flag GreaterThan")
+    );
+    assert!(
+        !cpu.get_flag(Flag::LessThan)
+            .expect("Failed to get flag LessThan")
+    );
 }
 
 #[test]
 fn test_compare_less_than() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 20;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 20;
-    *cpu.reg(Register::Rg2) = 30;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 30;
 
     let cmp_instr = Instruction::Compare(RTypeArgs::new(
         Some(Register::Rg1),
@@ -313,41 +411,59 @@ fn test_compare_less_than() {
         None,
     ));
 
-    cmp_instr.execute(&mut cpu);
+    cmp_instr.execute(&mut cpu).expect(
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
 
-    assert!(!cpu.get_flag(Flag::Equal));
+    assert!(!cpu.get_flag(Flag::Equal).expect("Failed to get flag Equal"));
-    assert!(!cpu.get_flag(Flag::GreaterThan));
+    assert!(
-    assert!(cpu.get_flag(Flag::LessThan));
+        !cpu.get_flag(Flag::GreaterThan)
+            .expect("Failed to get flag GreaterThan")
+    );
+    assert!(
+        cpu.get_flag(Flag::LessThan)
+            .expect("Failed to get flag LessThan")
+    );
 }
 
 #[test]
 fn test_increment_instruction() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 42;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 42;
 
     let inc_instr =
         Instruction::Increment(RTypeArgs::new(Some(Register::Rg1), None, None, None));
 
-    inc_instr.execute(&mut cpu);
+    inc_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg1), 43);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg1).expect("Failed to get register Rg1"),
+        43
+    );
 }
 
 #[test]
 fn test_decrement_instruction() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 42;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 42;
 
     let dec_instr =
         Instruction::Decrement(RTypeArgs::new(Some(Register::Rg1), None, None, None));
 
-    dec_instr.execute(&mut cpu);
+    dec_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg1), 41);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg1).expect("Failed to get register Rg1"),
+        41
+    );
 }
 
 #[test]
 fn test_shift_left_with_shamt() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 0b1010;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 0b1010;
 
     let shl_instr = Instruction::ShiftLeft(RTypeArgs::new(
         Some(Register::Rg1),
@@ -356,14 +472,19 @@ fn test_shift_left_with_shamt() {
         Some(2),
     ));
 
-    shl_instr.execute(&mut cpu);
+    shl_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg1), 0b10_1000);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg1).expect("Failed to get register Rg1"),
+        0b10_1000
+    );
 }
 
 #[test]
 fn test_shift_right_with_shamt() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 0b10_1000;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 0b10_1000;
 
     let shr_instr = Instruction::ShiftRight(RTypeArgs::new(
         Some(Register::Rg1),
@@ -372,26 +493,32 @@ fn test_shift_right_with_shamt() {
         Some(2),
     ));
 
-    shr_instr.execute(&mut cpu);
+    shr_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg1), 0b1010);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg1).expect("Failed to get register Rg1"),
+        0b1010
+    );
 }
 
-#[test]
+// #[test]
-fn test_shift_left_with_register() {
+// fn test_shift_left_with_register() {
-    let mut cpu = create_test_processor();
+//     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 0b1010;
+//     *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 0b1010;
-    *cpu.reg(Register::Rg2) = 3;
 
-    let shl_instr = Instruction::ShiftLeft(RTypeArgs::new(
+//     let shl_instr =
-        Some(Register::Rg1),
+//         Instruction::ShiftLeft(RTypeArgs::new(Some(Register::Rg1), None, None,
-        Some(Register::Rg2),
+// Some(3)));
-        None,
-        None,
-    ));
 
-    shl_instr.execute(&mut cpu);
+//     shl_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg1), 0b101_0000);
+//         "Emulator was slain by losing the game while attempting to execute
-}
+// instruction",     );
+//     assert_eq!(
+//         cpu.get(Register::Rg1).expect("Failed to get register Rg1"),
+//         0b101_0000
+//     );
+// }
 
 #[test]
 fn test_load_lower_immediate() {
@@ -403,14 +530,19 @@ fn test_load_lower_immediate() {
         None,
     ));
 
-    lli_instr.execute(&mut cpu);
+    lli_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg1), 0x0000_1234);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg1).expect("Failed to get register Rg1"),
+        0x0000_1234
+    );
 }
 
 #[test]
 fn test_load_upper_immediate() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 0x0000_5678;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 0x0000_5678;
 
     let lui_instr = Instruction::LoadUpperImmediate(ITypeArgs::new(
         0x1234,
@@ -418,48 +550,71 @@ fn test_load_upper_immediate() {
         None,
     ));
 
-    lui_instr.execute(&mut cpu);
+    lui_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg1), 0x1234_5678);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg1).expect("Failed to get register Rg1"),
+        0x1234_5678
+    );
 }
 
 #[test]
 fn test_jump_unconditional() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 0x1000;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 0x1000;
-    let initial_pc = cpu.get(Register::Pcx);
+    let initial_pc = cpu.get(Register::Pcx).expect("Failed to get register Pcx");
 
     let jump_instr = Instruction::Jump(ITypeArgs::new(0x100, Some(Register::Rg1), None));
 
-    jump_instr.execute(&mut cpu);
+    jump_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Pcx), 0x1100);
+        "Emulator was slain by losing the game while attempting to execute instruction",
-    assert_ne!(cpu.get(Register::Pcx), initial_pc);
+    );
+    assert_eq!(
+        cpu.get(Register::Pcx).expect("Failed to get register Pcx"),
+        0x1100
+    );
+    assert_ne!(
+        cpu.get(Register::Pcx).expect("Failed to get register Pcx"),
+        initial_pc
+    );
 }
 
 #[test]
 fn test_jump_equal_when_flag_set() {
     let mut cpu = create_test_processor();
     cpu.set_flag(Flag::Equal, true);
-    *cpu.reg(Register::Rg1) = 0x1000;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 0x1000;
 
     let jump_eq_instr =
         Instruction::JumpEq(ITypeArgs::new(0x100, Some(Register::Rg1), None));
 
-    jump_eq_instr.execute(&mut cpu);
+    jump_eq_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Pcx), 0x1100);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Pcx).expect("Failed to get register Pcx"),
+        0x1100
+    );
 }
 
 #[test]
 fn test_jump_equal_when_flag_not_set() {
     let mut cpu = create_test_processor();
     cpu.set_flag(Flag::Equal, false);
-    *cpu.reg(Register::Rg1) = 0x1000;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 0x1000;
-    let initial_pc = cpu.get(Register::Pcx);
+    let initial_pc = cpu.get(Register::Pcx).expect("Failed to get register Pcx");
 
     let jump_eq_instr =
         Instruction::JumpEq(ITypeArgs::new(0x100, Some(Register::Rg1), None));
 
-    jump_eq_instr.execute(&mut cpu);
+    jump_eq_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Pcx), initial_pc);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Pcx).expect("Failed to get register Pcx"),
+        initial_pc
+    );
 }
 
 #[test]
@@ -467,15 +622,17 @@ fn test_halt_instruction() {
     let mut cpu = create_test_processor();
     assert!(!cpu.halted);
 
-    Instruction::Halt.execute(&mut cpu);
+    Instruction::Halt.execute(&mut cpu).expect(
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
     assert!(cpu.halted);
 }
 
 #[test]
 fn test_nand_instruction() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 0b1100;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 0b1100;
-    *cpu.reg(Register::Rg2) = 0b1010;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 0b1010;
 
     let nand_instr = Instruction::Nand(RTypeArgs::new(
         Some(Register::Rg1),
@@ -484,15 +641,20 @@ fn test_nand_instruction() {
         None,
     ));
 
-    nand_instr.execute(&mut cpu);
+    nand_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg3), !0b1000);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg3).expect("Failed to get register Rg3"),
+        !0b1000
+    );
 }
 
 #[test]
 fn test_nor_instruction() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 0b1100;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 0b1100;
-    *cpu.reg(Register::Rg2) = 0b1010;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 0b1010;
 
     let nor_instr = Instruction::Nor(RTypeArgs::new(
         Some(Register::Rg1),
@@ -501,15 +663,20 @@ fn test_nor_instruction() {
         None,
     ));
 
-    nor_instr.execute(&mut cpu);
+    nor_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg3), !0b1110);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg3).expect("Failed to get register Rg3"),
+        !0b1110
+    );
 }
 
 #[test]
 fn test_xnor_instruction() {
     let mut cpu = create_test_processor();
-    *cpu.reg(Register::Rg1) = 0b1100;
+    *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 0b1100;
-    *cpu.reg(Register::Rg2) = 0b1010;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 0b1010;
 
     let xnor_instr = Instruction::Xnor(RTypeArgs::new(
         Some(Register::Rg1),
@@ -518,6 +685,11 @@ fn test_xnor_instruction() {
         None,
     ));
 
-    xnor_instr.execute(&mut cpu);
+    xnor_instr.execute(&mut cpu).expect(
-    assert_eq!(cpu.get(Register::Rg3), !0b0110);
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(
+        cpu.get(Register::Rg3).expect("Failed to get register Rg3"),
+        !0b0110
+    );
 }

emulator/src/emulator/ui/control_unit.rs

@@ -1,5 +1,3 @@
-use std::sync::mpsc::Sender;
-
 use crate::emulator::{
     system::model::{Command, Running, State},
     ui::interface::Component,
@@ -9,19 +7,27 @@ use common::{instructions::Register, prelude::Instruction};
 
 pub struct ControlPanel {
     visible: bool,
-    sender: Sender<Command>,
+    step_amount_input: String,
+    step_amount: usize,
 }
 
 impl ControlPanel {
-    #[must_use]
+    #[allow(clippy::must_use_candidate)]
-    pub const fn new(sender: Sender<Command>) -> Self {
+    pub fn new() -> Self {
         Self {
             visible: false,
-            sender,
+            step_amount_input: String::from("1"),
+            step_amount: 1,
         }
     }
 }
 
+impl Default for ControlPanel {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
 impl Component for ControlPanel {
     fn category(&self) -> super::interface::Category {
         super::interface::Category::Control
@@ -47,46 +53,76 @@ impl Component for ControlPanel {
                 .clicked()
             {
                 if state.running == Running::Running {
-                    self.sender.send(Command::Stop).unwrap_or_else(|_| {
+                    state.cmd_sender.send(Command::Stop).unwrap_or_else(|_| {
-                        state.error = Some("Failed to send command".to_string());
+                        state.error_log.push("Failed to send command".to_string());
                     });
                 } else {
-                    self.sender.send(Command::Start).unwrap_or_else(|_| {
+                    state.cmd_sender.send(Command::Start).unwrap_or_else(|_| {
-                        state.error = Some("Failed to send command".to_string());
+                        state.error_log.push("Failed to send command".to_string());
                     });
                 }
             }
 
             // Step
             if ui.button("Step").clicked() {
-                self.sender.send(Command::Step).unwrap_or_else(|_| {
+                state
-                    state.error = Some("Failed to send command".to_string());
+                    .cmd_sender
-                });
+                    .send(Command::Step(self.step_amount))
+                    .unwrap_or_else(|_| {
+                        state.error_log.push("Failed to send command".to_string());
+                    });
             }
 
             // Resets the emulator and all attached devices
             if ui.button("Reset All").clicked() {
-                self.sender.send(Command::Reset(0)).unwrap_or_else(|_| {
+                state
-                    state.error = Some("Failed to send command".to_string());
+                    .cmd_sender
-                });
+                    .send(Command::Reset(0))
+                    .unwrap_or_else(|_| {
+                        state.error_log.push("Failed to send command".to_string());
+                    });
             }
 
             // Resets the emulator and all attached devices
             if ui.button("Clear Registers").clicked() {
-                self.sender.send(Command::Reset(1)).unwrap_or_else(|_| {
+                state
-                    state.error = Some("Failed to send command".to_string());
+                    .cmd_sender
-                });
+                    .send(Command::Reset(1))
+                    .unwrap_or_else(|_| {
+                        state.error_log.push("Failed to send command".to_string());
+                    });
             }
 
             // Resets the emulator and all attached devices
             if ui.button("Clear RAM").clicked() {
-                self.sender.send(Command::Reset(2)).unwrap_or_else(|_| {
+                state
-                    state.error = Some("Failed to send command".to_string());
+                    .cmd_sender
-                });
+                    .send(Command::Reset(2))
+                    .unwrap_or_else(|_| {
+                        state.error_log.push("Failed to send command".to_string());
+                    });
             }
 
             ui.separator();
 
+            state.send(Command::RegisterRequest);
+            state.send(Command::RunningRequest);
+            state.send(Command::InstructionCountRequest);
+
+            if ui
+                .text_edit_singleline(&mut self.step_amount_input)
+                .changed()
+            {
+                self.step_amount = if let Ok(amount) = self.step_amount_input.parse() {
+                    amount
+                } else {
+                    state
+                        .error_log
+                        .push("Unable to parse step amount".to_string());
+                    1
+                }
+            }
+
             // Status info
             ui.label(format!(
                 "Status: {}",
@@ -97,17 +133,25 @@ impl Component for ControlPanel {
                 }
             ));
 
-            let pcx = state.reg_file.get(Register::Pcx);
+            let pcx = state
+                .reg_file
+                .get(Register::Pcx)
+                .expect("PCX should never be invalid");
             let instructions = state.instructions;
 
             ui.label(format!("Instructions: {instructions}"));
             ui.label(format!("PC: 0x{pcx:08X}"));
 
-            let instruction = Instruction::decode(state.reg_file.get(Register::Cir))
+            let instruction = Instruction::decode(
-                .map_or_else(
+                state
-                    |_| "Invalid Instruction".to_string(),
+                    .reg_file
-                    |instruction| instruction.to_string(),
+                    .get(Register::Cir)
-                );
+                    .expect("CIR should never be invalid"),
+            )
+            .map_or_else(
+                |_| "Invalid Instruction".to_string(),
+                |instruction| instruction.to_string(),
+            );
 
             ui.label(format!("Instruction: {instruction}"));
         });

emulator/src/emulator/ui/display.rs

@@ -1,5 +1,5 @@
 use crate::emulator::{
-    system::model::State,
+    system::model::{Command, State},
     ui::interface::{Category, Component},
 };
 
@@ -40,6 +40,8 @@ impl Component for Display {
     }
 
     fn render(&mut self, state: &mut State, ui: &mut egui::Ui, _ctx: &egui::Context) {
+        state.send(Command::DisplayRequest);
+
         let display: Vec<u8> = state.display_view.clone();
         let font_id = FontId::monospace(12.0);
 

emulator/src/emulator/ui/editor.rs

@@ -3,7 +3,6 @@ use std::{
     ffi::OsStr,
     fs,
     path::{Path, PathBuf},
-    sync::mpsc::Sender,
 };
 
 use common::prelude::Instruction;
@@ -19,6 +18,7 @@ use crate::emulator::{
 
 use assembler::prelude::*;
 
+#[derive(Default)]
 pub struct Editor {
     // editor state
     path: Option<PathBuf>,
@@ -41,7 +41,6 @@ pub struct Editor {
 
     // other
     visible: bool,
-    sender: Sender<Command>,
     error: Option<String>,
 }
 
@@ -94,14 +93,13 @@ impl Component for Editor {
 
 impl Editor {
     #[must_use]
-    pub const fn new(sender: Sender<Command>) -> Self {
+    pub const fn new() -> Self {
         Self {
             path: None,
             text: String::new(),
             buffer: String::new(),
             output: Vec::new(),
             unsaved: true,
-            sender,
             cursor_col: 1,
             cursor_line: 1,
             visible: false,
@@ -199,38 +197,6 @@ impl Editor {
             )
         });
 
-        // if let Some(path) = FileDialog::new()
-        //     .add_filter("Assembly Files or Binaries", &["dsa", "dsb"])
-        //     .add_filter("all", &["*"])
-        //     .set_directory(&work_dir)
-        //     .pick_file()
-        // {
-        //     match path.extension().and_then(|ext| ext.to_str()) {
-        //         Some("dsb") => {
-        //             let contents = match std::fs::read(&path) {
-        //                 Ok(contents) => contents,
-        //                 Err(why) => {
-        //                     self.error = Some(format!("Failed to read file: {why}"));
-        //                     return;
-        //                 }
-        //             };
-
-        //             self.path = Some(path.clone());
-        //             self.output = contents;
-        //             self.unsaved = false;
-        //             self.text = String::from("Loaded Binary File!");
-        //             self.buffer = self.text.clone();
-        //             self.unsaved = false;
-        //         }
-        //         _ => {
-        //             if let Ok(contents) = std::fs::read_to_string(&path) {
-        //                 self.path = Some(path.clone());
-        //                 self.text.clone_from(&contents);
-        //                 self.buffer = contents;
-        //                 self.unsaved = false;
-        //             }
-        //         }
-        //     }
         if self.save_file_dialog.is_some() {
             // TODO: Flash an error stating you can only have one menu open at once.
             self.save_file_dialog = None;
@@ -252,119 +218,92 @@ impl Editor {
 
     fn handle_file_dialogs(&mut self, ctx: &egui::Context) {
         // Handle open dialog
-        if let Some(dialog) = &mut self.open_file_dialog {
+        if let Some(dialog) = &mut self.open_file_dialog
-            if dialog.show(ctx).selected() {
+            && dialog.show(ctx).selected()
-                if let Some(file) = dialog.path() {
+        {
-                    // check if the file is a binary file
+            if let Some(file) = dialog.path() {
-                    if file.extension().is_some_and(|ext| ext == "dsb") {
+                // check if the file is a binary file
-                        match std::fs::read(file) {
+                if file.extension().is_some_and(|ext| ext == "dsb") {
-                            Ok(content) => {
+                    match std::fs::read(file) {
-                                let mut res = String::new();
+                        Ok(content) => {
-                                for (i, b) in content.iter().enumerate() {
+                            let mut res = String::new();
-                                    _ = write!(res, "{b:02x}");
+                            for (i, b) in content.iter().enumerate() {
-                                    if i % 4 == 3 {
+                                _ = write!(res, "{b:02x}");
-                                        res.push('\n');
+                                if i % 4 == 3 {
-                                    }
+                                    res.push('\n');
-                                }
-                                self.text = res.clone();
-                                self.buffer = res;
-                                self.path = Some(file.to_path_buf());
-                                self.unsaved = false;
-                                self.error = None;
-                            }
-                            Err(e) => {
-                                self.error = Some(format!("Failed to read file: {e}"));
-                            }
-                        }
-                    } else {
-                        match std::fs::read_to_string(file) {
-                            Ok(content) => {
-                                self.text = content.clone();
-                                self.buffer = content;
-                                self.path = Some(file.to_path_buf());
-                                self.unsaved = false;
-                                self.error = None;
-                            }
-                            Err(e) => {
-                                self.error = Some(format!("Failed to read file: {e}"));
-                            }
-                        }
-                    }
-                }
-                self.open_file_dialog = None;
-            }
-        }
-
-        // Handle save dialog
-        if let Some(dialog) = &mut self.save_file_dialog {
-            if dialog.show(ctx).selected() {
-                if let Some(file) = dialog.path() {
-                    self.buffer = self.text.clone();
-
-                    let content = if file.extension().is_some_and(|ext| ext == "dsb") {
-                        let mut res = Vec::new();
-                        for line in self.text.lines() {
-                            for line in line.split_whitespace() {
-                                match u32::from_str_radix(line, 16) {
-                                    Ok(num) => res.push(num),
-                                    Err(e) => {
-                                        self.error =
-                                            Some(format!("Failed to parse file: {e}"));
-                                        return;
-                                    }
                                 }
                             }
-                        }
+                            self.text = res.clone();
-                        res.into_iter()
+                            self.buffer = res;
-                            .flat_map(u32::to_be_bytes)
-                            .collect::<Vec<u8>>()
-                    } else {
-                        self.text.clone().as_bytes().to_vec()
-                    };
-
-                    match std::fs::write(file, content) {
-                        Ok(()) => {
                             self.path = Some(file.to_path_buf());
                             self.unsaved = false;
                             self.error = None;
                         }
                         Err(e) => {
-                            self.error = Some(format!("Failed to save file: {e}"));
+                            self.error = Some(format!("Failed to read file: {e}"));
+                        }
+                    }
+                } else {
+                    match std::fs::read_to_string(file) {
+                        Ok(content) => {
+                            self.text = content.clone();
+                            self.buffer = content;
+                            self.path = Some(file.to_path_buf());
+                            self.unsaved = false;
+                            self.error = None;
+                        }
+                        Err(e) => {
+                            self.error = Some(format!("Failed to read file: {e}"));
                         }
                     }
                 }
-                self.save_file_dialog = None;
             }
+            self.open_file_dialog = None;
+        }
+
+        // Handle save dialog
+        if let Some(dialog) = &mut self.save_file_dialog
+            && dialog.show(ctx).selected()
+        {
+            if let Some(file) = dialog.path() {
+                self.buffer = self.text.clone();
+
+                let content = if file.extension().is_some_and(|ext| ext == "dsb") {
+                    let mut res = Vec::new();
+                    for line in self.text.lines() {
+                        for line in line.split_whitespace() {
+                            match u32::from_str_radix(line, 16) {
+                                Ok(num) => res.push(num),
+                                Err(e) => {
+                                    self.error =
+                                        Some(format!("Failed to parse file: {e}"));
+                                    return;
+                                }
+                            }
+                        }
+                    }
+                    res.into_iter()
+                        .flat_map(u32::to_be_bytes)
+                        .collect::<Vec<u8>>()
+                } else {
+                    self.text.clone().as_bytes().to_vec()
+                };
+
+                match std::fs::write(file, content) {
+                    Ok(()) => {
+                        self.path = Some(file.to_path_buf());
+                        self.unsaved = false;
+                        self.error = None;
+                    }
+                    Err(e) => {
+                        self.error = Some(format!("Failed to save file: {e}"));
+                    }
+                }
+            }
+            self.save_file_dialog = None;
         }
     }
 
-    // fn open(&mut self) {
-    //     let work_dir = std::env::current_dir().unwrap_or_else(|_| {
-    //         dirs::home_dir().expect(
-    //             "Couldn't get your current working directory or your home directory.",
-    //         )
-    //     });
-
-    //     if let Some(path) = FileDialog::new()
-    //         .add_filter("Assembly Files or Binaries", &["dsa", "dsb"])
-    //         .add_filter("all", &["*"])
-    //         .set_directory(&work_dir)
-    //         .pick_file()
-    //     {
-    //         if let Ok(contents) = std::fs::read_to_string(&path) {
-    //             self.path = Some(path.clone());
-    //             self.text.clone_from(&contents);
-    //             self.buffer = contents;
-    //             self.unsaved = false;
-    //         }
-
-    //         std::env::set_current_dir(
-    //             path.parent().expect("A file should be in a directory!"),
-    //         )
-    //         .expect("ERROR: Failed to set current working directory.");
-    //     }
-    // }
-
     fn render_output(&self, _state: &mut State, ui: &mut Ui, _ctx: &Context) {
         // Output area with synchronized scrolling
         egui::ScrollArea::vertical()
@@ -454,8 +393,9 @@ impl Editor {
     fn render_editor(&mut self, _state: &mut State, ui: &mut Ui, _ctx: &Context) {
         let available_width = ui.available_width();
         let syntax = match self.extension() {
-            "dsa" => Some(Syntax::new("dsa")),
+            "dsa" => Syntax::dsa(),
-            _ => None,
+            "dsc" => Syntax::dsc(),
+            _ => Syntax::default(),
         };
 
         let ed = CodeEditor::default()
@@ -463,16 +403,12 @@ impl Editor {
             .with_fontsize(12.0)
             .with_rows(0)
             .with_theme(ColorTheme::default())
-            .with_syntax(Syntax::dsa())
+            .with_syntax(syntax)
             .with_numlines(true)
             .desired_width(available_width - 500.0);
 
         let mut editor = ed.clone();
 
-        if let Some(syntax) = syntax {
-            editor = ed.with_syntax(syntax);
-        }
-
         editor.show(ui, &mut self.text);
     }
 
@@ -512,6 +448,29 @@ impl Editor {
                         .flat_map(|i| i.encode().to_be_bytes().to_vec())
                         .collect();
                 }
+                Some("dsc") => {
+                    let output_path = Path::new(path).with_extension("dsa");
+                    if let Err(e) = compiler::compile_file(path, &output_path) {
+                        self.error = Some(format!("Compiler error: {}", e));
+                    }
+
+                    let mut compiler = CompilerEngine::new();
+                    compiler.start_compilation(&output_path);
+
+                    // Or block until done
+                    let instructions = match compiler.wait_for_result() {
+                        Ok(instructions) => instructions,
+                        Err(e) => {
+                            self.error = Some(format!("Assembler error: {}", e));
+                            return;
+                        }
+                    };
+
+                    self.output = instructions
+                        .iter()
+                        .flat_map(|i| i.encode().to_be_bytes().to_vec())
+                        .collect();
+                }
                 Some("dsb") => {
                     if let Ok(bytes) = fs::read(path) {
                         self.output = bytes;
@@ -526,7 +485,7 @@ impl Editor {
         }
     }
 
-    fn render_toolbar(&mut self, _state: &mut State, ui: &mut Ui, ctx: &Context) {
+    fn render_toolbar(&mut self, state: &State, ui: &mut Ui, ctx: &Context) {
         self.handle_file_dialogs(ctx);
 
         ui.horizontal(|ui| {
@@ -567,7 +526,8 @@ impl Editor {
                         Some("Can't load program at invalid offset!".to_string());
                 }
 
-                self.sender
+                state
+                    .cmd_sender
                     .send(Command::Write(self.load_offset, self.output.clone()))
                     .unwrap_or_else(|_| {
                         self.error = Some("Failed to send command".to_string());

emulator/src/emulator/ui/history.rs

@@ -1,6 +1,9 @@
 use egui::{Context, Ui};
 
-use crate::emulator::{system::model::State, ui::interface::Component};
+use crate::emulator::{
+    system::model::{Command, State},
+    ui::interface::Component,
+};
 
 pub struct History {
     visible: bool,
@@ -20,11 +23,13 @@ impl Component for History {
     }
 
     fn render(&mut self, state: &mut State, ui: &mut Ui, _ctx: &Context) {
+        state.send(Command::HistoryRequest);
+
         egui::ScrollArea::vertical()
             .id_salt("output_scroll")
             .max_width(400.0)
             .show(ui, |ui| {
-                if state.persistent.history.is_empty() {
+                if state.instruction_history.is_empty() {
                     ui.label(
                         egui::RichText::new("No output data")
                             .font(egui::FontId::monospace(12.0))
@@ -40,7 +45,7 @@ impl Component for History {
                     .show(ui, |ui| {
                         // Process bytes in chunks of 4
                         for (idx, instruction) in
-                            state.persistent.history.iter().enumerate()
+                            state.instruction_history.iter().enumerate()
                         {
                             ui.label(format!("{idx}: "));
 

emulator/src/emulator/ui/interface.rs

@@ -1,4 +1,4 @@
-use crate::emulator::system::model::{Command, PersistentState, Running, State};
+use crate::emulator::system::model::{Command, Running, State, StateUpdate};
 use std::sync::mpsc::{Receiver, Sender};
 
 pub trait Component {
@@ -34,21 +34,15 @@ impl Category {
 }
 
 pub struct EmulatorUI {
-    pub sender: Sender<Command>,
-    pub receiver: Receiver<State>,
     pub state: State,
-    pub persistent: PersistentState,
     pub components: Vec<Box<dyn Component>>,
 }
 
 impl EmulatorUI {
     #[must_use]
-    pub fn new(sender: Sender<Command>, receiver: Receiver<State>) -> Self {
+    pub fn new(sender: Sender<Command>, receiver: Receiver<StateUpdate>) -> Self {
         Self {
-            sender,
+            state: State::new(sender, receiver),
-            receiver,
-            state: State::default(),
-            persistent: PersistentState::default(),
             components: vec![],
         }
     }
@@ -56,19 +50,13 @@ impl EmulatorUI {
     pub fn add_component(&mut self, component: Box<dyn Component>) {
         self.components.push(component);
     }
-
-    fn update_state(&mut self) {
-        while let Ok(state) = self.receiver.try_recv() {
-            self.state = state;
-            self.persistent.update(&self.state.persistent);
-            self.state.persistent = self.persistent.clone();
-        }
-    }
 }
 
 impl eframe::App for EmulatorUI {
     fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) {
-        self.update_state();
+        if let Err(e) = self.state.update() {
+            self.state.error_log.push(e.to_string());
+        }
 
         if self.state.running == Running::Running {
             ctx.request_repaint();

emulator/src/emulator/ui/loader.rs

@@ -0,0 +1,294 @@
+use std::{
+    ffi::OsStr,
+    path::{Path, PathBuf},
+};
+
+use common::prelude::Instruction;
+use egui::{Context, Ui};
+use egui_file::FileDialog;
+
+use crate::emulator::{
+    system::model::{Command, State},
+    ui::interface::Component,
+};
+
+#[derive(Default)]
+pub struct Loader {
+    path: Option<PathBuf>,
+    output: Vec<u8>,
+    load_offset: u32,
+    offset_str: String,
+
+    // file dialogs
+    open_file_dialog: Option<FileDialog>,
+
+    // other
+    visible: bool,
+    error: Option<String>,
+}
+
+impl Component for Loader {
+    fn name(&self) -> &'static str {
+        "Loader"
+    }
+
+    fn visible(&mut self) -> &mut bool {
+        &mut self.visible
+    }
+
+    fn category(&self) -> super::interface::Category {
+        super::interface::Category::Programming
+    }
+
+    fn render(&mut self, state: &mut State, ui: &mut Ui, ctx: &Context) {
+        ui.vertical(|ui| {
+            self.render_toolbar(state, ui, ctx);
+
+            ui.add_space(4.0); // Add some spacing instead of just a separator
+            ui.separator();
+
+            egui::ScrollArea::vertical()
+                .auto_shrink([false; 2])
+                .max_height(ui.available_height() - 100.0)
+                .show(ui, |ui| {
+                    self.render_output(state, ui, ctx);
+                });
+
+            self.render_bottom_bar(state, ui, ctx);
+        });
+    }
+}
+
+impl Loader {
+    #[must_use]
+    pub const fn new() -> Self {
+        Self {
+            path: None,
+            output: Vec::new(),
+            visible: false,
+            load_offset: 0,
+            offset_str: String::new(),
+            error: None,
+            open_file_dialog: None,
+        }
+    }
+
+    fn filename(&self) -> &str {
+        if let Some(path) = &self.path {
+            return path
+                .file_name()
+                .unwrap_or_else(|| OsStr::new("Unnamed!"))
+                .to_str()
+                .map_or_else(
+                    || unreachable!("File name should be valid UTF-8."),
+                    |ext| ext,
+                );
+        }
+        "Unnamed!"
+    }
+
+    fn open(&mut self) {
+        let work_dir = std::env::current_dir().unwrap_or_else(|_| {
+            dirs::home_dir().expect(
+                "Couldn't get your current working directory or your home directory.",
+            )
+        });
+
+        if self.open_file_dialog.is_some() {
+            // TODO: Flash an error stating you can only have one menu open at once.
+            self.open_file_dialog = None;
+        }
+
+        if self.open_file_dialog.is_none() {
+            if let Some(p) = &self.path {
+                let path = p.parent().map(Path::to_path_buf);
+                let mut dialog = FileDialog::open_file(path);
+                dialog.open();
+                self.open_file_dialog = Some(dialog);
+            } else {
+                let mut dialog = FileDialog::open_file(Some(work_dir));
+                dialog.open();
+                self.open_file_dialog = Some(dialog);
+            }
+        }
+    }
+
+    fn handle_file_dialogs(&mut self, ctx: &egui::Context) {
+        // Handle open dialog
+        if let Some(dialog) = &mut self.open_file_dialog
+            && dialog.show(ctx).selected()
+        {
+            if let Some(file) = dialog.path() {
+                // check if the file is a binary file
+                if file.extension().is_some_and(|ext| ext == "dsb") {
+                    match std::fs::read(file) {
+                        Ok(content) => {
+                            self.output = content;
+                            self.error = None;
+                        }
+                        Err(e) => {
+                            self.error = Some(format!("Failed to read file: {e}"));
+                        }
+                    }
+                }
+            }
+            self.open_file_dialog = None;
+        }
+    }
+
+    fn render_output(&self, _state: &mut State, ui: &mut Ui, _ctx: &Context) {
+        // Output area with synchronized scrolling
+        egui::ScrollArea::vertical()
+            .id_salt("output_scroll")
+            .max_width(400.0)
+            .show(ui, |ui| {
+                if self.output.is_empty() {
+                    ui.label(
+                        egui::RichText::new("No output data")
+                            .font(egui::FontId::monospace(12.0))
+                            .color(egui::Color32::GRAY),
+                    );
+                    return;
+                }
+
+                egui::Grid::new("output_grid")
+                    .spacing([5.0, 2.0]) // Horizontal and vertical spacing
+                    .num_columns(4)
+                    .striped(false)
+                    .show(ui, |ui| {
+                        // Process bytes in chunks of 4
+                        for (line_num, chunk) in self.output.chunks(4).enumerate() {
+                            let address = line_num * 4;
+
+                            // Convert chunk to u32 (little-endian)
+                            let mut bytes = [0u8; 4];
+                            for (i, &byte) in chunk.iter().enumerate() {
+                                if i < 4 {
+                                    bytes[i] = byte;
+                                }
+                            }
+                            let value = u32::from_be_bytes(bytes);
+
+                            // Address column
+                            ui.with_layout(
+                                egui::Layout::left_to_right(egui::Align::Center),
+                                |ui| {
+                                    ui.set_min_width(80.0);
+                                    let style = ui.style_mut();
+                                    style.visuals.widgets.inactive.bg_fill =
+                                        egui::Color32::from_gray(30);
+                                    ui.label(
+                                        egui::RichText::new(format!("0x{address:04X}"))
+                                            .font(egui::FontId::monospace(12.0)),
+                                    );
+                                },
+                            );
+
+                            // Individual bytes column
+                            let byte_str = chunk
+                                .iter()
+                                .map(|b| format!("{b:02X}"))
+                                .collect::<Vec<_>>()
+                                .join(" ");
+
+                            ui.label(
+                                egui::RichText::new(format!("{byte_str:<11}"))
+                                    .font(egui::FontId::monospace(12.0))
+                                    .color(egui::Color32::from_rgb(200, 200, 255)),
+                            );
+
+                            // Hex column
+                            ui.label(
+                                egui::RichText::new(format!("0x{value:08X}"))
+                                    .font(egui::FontId::monospace(12.0))
+                                    .color(egui::Color32::from_rgb(255, 200, 200)),
+                            );
+
+                            // Instruction column
+                            let instruction = Instruction::decode(value).map_or_else(
+                                |_| format!("{value:10}"),
+                                |instruction| instruction.to_string(),
+                            );
+
+                            ui.label(
+                                egui::RichText::new(instruction)
+                                    .font(egui::FontId::monospace(12.0))
+                                    .color(egui::Color32::from_rgb(200, 255, 200)),
+                            );
+
+                            ui.end_row();
+                        }
+                    });
+            });
+    }
+
+    fn render_bottom_bar(&self, _state: &mut State, ui: &mut Ui, _ctx: &Context) {
+        ui.horizontal(|ui| {
+            // error display
+            ui.label(
+                egui::RichText::new(self.error.clone().unwrap_or_default())
+                    .color(egui::Color32::RED),
+            );
+        });
+    }
+
+    fn render_toolbar(&mut self, state: &State, ui: &mut Ui, ctx: &Context) {
+        self.handle_file_dialogs(ctx);
+
+        ui.horizontal(|ui| {
+            ui.label(format!("Filename: {}", self.filename()));
+        });
+
+        ui.horizontal(|ui| {
+            ui.spacing_mut().button_padding = egui::vec2(8.0, 4.0);
+            ui.spacing_mut().item_spacing.x = 6.0;
+
+            // Opens a file
+            if ui.button("Open").clicked() {
+                self.open();
+            }
+
+            // Loads the generated binary into the assembler at the provided offset
+            if ui.button("Load").clicked() {
+                if self.error.is_some() {
+                    self.error =
+                        Some("Can't load program at invalid offset!".to_string());
+                }
+
+                state
+                    .cmd_sender
+                    .send(Command::Write(self.load_offset, self.output.clone()))
+                    .unwrap_or_else(|_| {
+                        self.error = Some("Failed to send command".to_string());
+                    });
+            }
+
+            // Entry widget to enter a load offset
+            if ui.text_edit_singleline(&mut self.offset_str).changed() {
+                if let Some(offset) = parse_address(&self.offset_str) {
+                    self.load_offset = offset;
+                    self.error = None;
+                } else {
+                    self.error = Some("Invalid offset".to_string());
+                }
+            }
+        });
+    }
+}
+
+fn parse_address(address: &str) -> Option<u32> {
+    address.strip_prefix("0x").map_or_else(
+        || {
+            address.strip_prefix("0b").map_or_else(
+                || {
+                    address.strip_prefix("0o").map_or_else(
+                        || address.parse::<u32>().ok(),
+                        |oct| u32::from_str_radix(oct, 8).ok(),
+                    )
+                },
+                |bin| u32::from_str_radix(bin, 2).ok(),
+            )
+        },
+        |hex| u32::from_str_radix(hex, 16).ok(),
+    )
+}

emulator/src/emulator/ui/memory_inspector.rs

@@ -1,4 +1,4 @@
-use std::{num::ParseIntError, sync::mpsc::Sender};
+use std::num::ParseIntError;
 
 use common::prelude::Instruction;
 
@@ -7,23 +7,22 @@ use crate::emulator::{
     ui::interface::Component,
 };
 
+#[derive(Default)]
 pub struct MemoryInspector {
     view_size: u32,
     view_addr: u32,
     visible: bool,
     addr_input: String,
-    sender: Sender<Command>,
 }
 
 impl MemoryInspector {
     #[must_use]
-    pub const fn new(sender: Sender<Command>) -> Self {
+    pub const fn new() -> Self {
         Self {
             view_size: 256,
             view_addr: 0,
             visible: false,
             addr_input: String::new(),
-            sender,
         }
     }
 }
@@ -63,28 +62,26 @@ impl Component for MemoryInspector {
                 let search_clicked = ui.button("🔍 Search").clicked();
 
                 // Handle Enter key in text field
-                let enter_pressed =
+                let enter_pressed = address_response.lost_focus()
-                    address_response.lost_focus() && ctx.input(|i| i.key_pressed(egui::Key::Enter));
+                    && ctx.input(|i| i.key_pressed(egui::Key::Enter));
 
                 if search_clicked || enter_pressed {
                     if let Ok(new) = parse_address(&self.addr_input) {
                         self.view_addr = new;
-
-                        if let Err(why) = self.sender.send(Command::Read(new, self.view_size)) {
-                            panic!(
-                                "Error sending message across threads -- cannot be recovered: {why}"
-                            )
-                        }
                     } else {
-                        state.error = Some("Invalid address".to_string());
+                        state.error_log.push("Invalid address".to_string());
                     }
                 }
 
+                let _ = state
+                    .cmd_sender
+                    .send(Command::MemRequest(self.view_addr, self.view_size));
+
                 ui.label("(hex or decimal)");
             });
 
             // Show input error if any
-            if let Some(error) = &state.error {
+            if let Some(error) = state.error_log.last() {
                 ui.colored_label(egui::Color32::RED, format!("Error: {error}"));
             }
 
@@ -113,9 +110,12 @@ impl Component for MemoryInspector {
                             ui.end_row();
 
                             // Memory data (8 bytes per row)
-                            for (row, chunk) in (0u32..).zip(state.memory_view.chunks(4)) {
+                            for (row, chunk) in (0u32..).zip(state.memory_view.chunks(4))
+                            {
                                 let row_address = self.view_addr + (row * 4);
-                                ui.monospace(format!("0x{row_address:08X} ({row_address})"));
+                                ui.monospace(format!(
+                                    "0x{row_address:08X} ({row_address})"
+                                ));
                                 for &byte in chunk {
                                     ui.monospace(format!("{byte:02X}"));
                                 }
@@ -126,12 +126,16 @@ impl Component for MemoryInspector {
                                 }
 
                                 // combine all 4 bytes in the chunk into a u32
-                                let combined = chunk
+                                let combined = chunk.iter().fold(0u32, |acc, &byte| {
-                                    .iter()
+                                    (acc << 8) | u32::from(byte)
-                                    .fold(0u32, |acc, &byte| (acc << 8) | u32::from(byte));
+                                });
 
                                 ui.monospace(format!("{combined}"));
-                                ui.monospace(format!("{}", Instruction::decode(combined).unwrap_or(Instruction::Nop)));
+                                ui.monospace(format!(
+                                    "{}",
+                                    Instruction::decode(combined)
+                                        .unwrap_or(Instruction::Nop)
+                                ));
 
                                 ui.end_row();
                             }

emulator/src/emulator/ui/mod.rs

@@ -3,6 +3,7 @@ pub mod display;
 pub mod editor;
 pub mod history;
 pub mod interface;
+pub mod loader;
 pub mod memory_inspector;
 pub mod menu;
 pub mod stack_inspector;

emulator/src/emulator/ui/stack_inspector.rs

@@ -1,4 +1,7 @@
-use crate::emulator::{system::model::State, ui::interface::Component};
+use crate::emulator::{
+    system::model::{Command, State},
+    ui::interface::Component,
+};
 
 use common::instructions::Register;
 
@@ -33,6 +36,8 @@ impl Component for StackInspector {
     }
 
     fn render(&mut self, state: &mut State, ui: &mut egui::Ui, _ctx: &egui::Context) {
+        state.send(Command::StackRequest);
+
         ui.vertical(|ui| {
             ui.heading("Stack Inspector");
             egui::ScrollArea::vertical()
@@ -46,7 +51,6 @@ impl Component for StackInspector {
                             ui.label("Address");
                             ui.label("Value");
                             ui.end_row();
-
                             for (i, value) in
                                 state.stack_view.chunks(4).take(32).enumerate()
                             {
@@ -54,9 +58,9 @@ impl Component for StackInspector {
                                     "Could not read 4 byte instruction or data! Something is wrong.",
                                 ));
                                 ui.label(format!(
-                                    "{} [{}]",
+                                    "+{} [{}]",
-                                    i,
+                                    i*4,
-                                    state.reg_file.get(Register::Spr) - i as u32 * 4
+                                    state.reg_file.get(Register::Spr).expect("SPR should never be invalid") + i as u32 * 4
                                 ));
                                 ui.label(format!("0x{value:08X} ({value})"));
                                 ui.end_row();

emulator/src/lib.rs

@@ -30,7 +30,7 @@ use crate::emulator::{
     system::{
         emulator::run_emulator,
         memory::MainStore,
-        model::{Command, State},
+        model::{Command, StateUpdate},
         processor::Processor,
     },
     ui::{
@@ -86,7 +86,7 @@ pub fn android_main(app: AndroidApp) -> Result<(), Box<dyn std::error::Error>> {
 
 pub fn setup_emulator(
     cmd_receiver: Receiver<Command>,
-    state_sender: Sender<State>,
+    state_sender: Sender<StateUpdate>,
     rpc_client: Option<Arc<RpcClient>>,
 ) {
     let main_store = MainStore::new();
@@ -101,22 +101,22 @@ pub fn setup_emulator(
 #[must_use]
 pub fn setup_ui(
     cmd_sender: Sender<Command>,
-    state_reciever: Receiver<State>,
+    state_reciever: Receiver<StateUpdate>,
 ) -> EmulatorUI {
-    let mut ui = EmulatorUI::new(cmd_sender.clone(), state_reciever);
+    let mut ui = EmulatorUI::new(cmd_sender, state_reciever);
 
     // Create UI modules.
-    let control_unit = ControlPanel::new(cmd_sender.clone());
+    let control_unit = ControlPanel::new();
 
     ui.add_component(Box::new(control_unit));
 
-    let mem_inspector = MemoryInspector::new(cmd_sender.clone());
+    let mem_inspector = MemoryInspector::new();
     ui.add_component(Box::new(mem_inspector));
 
     let stack_inspector = StackInspector::new();
     ui.add_component(Box::new(stack_inspector));
 
-    let editor = Editor::new(cmd_sender);
+    let editor = Editor::new();
     ui.add_component(Box::new(editor));
 
     let display = Display::new();
@@ -125,5 +125,8 @@ pub fn setup_ui(
     let history = emulator::ui::history::History::new();
     ui.add_component(Box::new(history));
 
+    let loader = emulator::ui::loader::Loader::new();
+    ui.add_component(Box::new(loader));
+
     ui
 }

resources/concept/assemblerconcept.md

@@ -1,279 +0,0 @@
-
-
-```rust
-// src/assembler/source.rs
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct SourcePosition {
-    pub line: u32,
-    pub column: u32,
-    pub offset: usize,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct SourceSpan {
-    pub start: SourcePosition,
-    pub end: SourcePosition,
-    pub file_id: u64,  // Hash of the file path
-}
-
-impl SourceSpan {
-    pub fn new(start: SourcePosition, end: SourcePosition, file_id: u64) -> Self {
-        Self { start, end, file_id }
-    }
-    
-    pub fn single_char(pos: SourcePosition, file_id: u64) -> Self {
-        Self {
-            start: pos,
-            end: pos,
-            file_id,
-        }
-    }
-}
-2. Enhanced Token with Source Information
-Update the Token type to include source positions:
-
-```rust
-// src/assembler/model.rs
-pub struct Token {
-    pub kind: TokenKind,
-    pub span: SourceSpan,
-    pub raw: String,  // Original source text
-}
-
-pub enum TokenKind {
-    // ... existing variants ...
-}
-3. Enhanced CodeModule Structure
-Enhance the 
-CodeModule
- struct to track source information:
-
-```rust
-// src/assembler/mod.rs
-pub struct CodeModule {
-    pub path: PathBuf,
-    pub hash: u64,
-    pub source: String,
-    pub lines: Vec<usize>,  // Line start offsets for quick lookup
-    pub tokens: Vec<Token>,
-    pub nodes: Vec<Node>,
-    pub dependencies: Vec<CodeModule>,
-}
-
-impl CodeModule {
-    pub fn new(path: PathBuf, source: String) -> Self {
-        let hash = quick_hash(&path);
-        let lines = source.lines()
-            .scan(0, |offset, line| {
-                let start = *offset;
-                *offset += line.len() + 1;  // +1 for newline
-                Some(start)
-            })
-            .collect();
-            
-        Self {
-            path,
-            hash,
-            source,
-            lines,
-            tokens: Vec::new(),
-            nodes: Vec::new(),
-            dependencies: Vec::new(),
-        }
-    }
-    
-    pub fn position_from_offset(&self, offset: usize) -> (u32, u32) {
-        match self.lines.binary_search(&offset) {
-            Ok(line) => (line as u32 + 1, 1),
-            Err(0) => (1, offset as u32 + 1),
-            Err(line) => {
-                let line_start = self.lines[line - 1];
-                (line as u32, (offset - line_start + 1) as u32)
-            }
-        }
-    }
-}
-4. Enhanced Lexer with Source Positions
-Update the lexer to track source positions:
-
-```rust
-// src/assembler/lexer.rs
-pub fn lex(module: &mut CodeModule) -> Result<(), AssembleError> {
-    let source = &module.source;
-    let mut tokens = Vec::new();
-    let mut pos = 0;
-    let mut line_start = 0;
-    let mut line = 1;
-    
-    while pos < source.len() {
-        let c = source[pos..].chars().next().unwrap();
-        
-        if c == '\n' {
-            line += 1;
-            line_start = pos + 1;
-            pos += 1;
-            continue;
-        }
-        
-        if c.is_whitespace() {
-            pos += 1;
-            continue;
-        }
-        
-        let token_start = pos;
-        // ... existing token parsing logic ...
-        
-        // When creating a token:
-        let start_pos = SourcePosition {
-            line,
-            column: (token_start - line_start + 1) as u32,
-            offset: token_start,
-        };
-        
-        // Update pos based on token length
-        let token_length = /* calculate token length */;
-        pos += token_length;
-        
-        let end_pos = SourcePosition {
-            line,
-            column: (pos - line_start + 1) as u32,
-            offset: pos,
-        };
-        
-        tokens.push(Token {
-            kind: token_kind,
-            span: SourceSpan::new(start_pos, end_pos, module.hash),
-            raw: source[token_start..pos].to_string(),
-        });
-    }
-    
-    module.tokens = tokens;
-    Ok(())
-}
-5. Enhanced Error Reporting
-Create a structured error type with source context:
-
-```rust
-// src/assembler/error.rs
-#[derive(Debug)]
-pub struct AssemblerError {
-    pub kind: ErrorKind,
-    pub span: SourceSpan,
-    pub message: String,
-    pub context: Vec<String>,
-}
-
-impl AssemblerError {
-    pub fn new(kind: ErrorKind, span: SourceSpan, message: impl Into<String>) -> Self {
-        Self {
-            kind,
-            span,
-            message: message.into(),
-            context: Vec::new(),
-        }
-    }
-    
-    pub fn with_context(mut self, context: impl Into<String>) -> Self {
-        self.context.push(context.into());
-        self
-    }
-    
-    pub fn format(&self, module: &CodeModule) -> String {
-        let (line, col) = module.position_from_offset(self.span.start.offset);
-        let line_content = module.source.lines().nth(line as usize - 1).unwrap_or("");
-        
-        let mut output = format!(
-            "{}:{}:{}: {}\n",
-            module.path.display(),
-            line,
-            col,
-            self.message
-        );
-        
-        // Add source line with caret
-        output.push_str(&format!("{}\n", line_content));
-        output.push_str(&" ".repeat(col as usize - 1));
-        output.push_str("^\n");
-        
-        // Add context if any
-        for ctx in &self.context {
-            output.push_str(&format!("  = note: {}\n", ctx));
-        }
-        
-        output
-    }
-}
-6. Integration with Compilation Pipeline
-Update the compilation pipeline to use the enhanced types:
-
-```rust
-// src/assembler/mod.rs
-pub fn assemble(src: &Path) -> Result<Vec<Instruction>, AssemblerError> {
-    let source = std::fs::read_to_string(src)
-        .map_err(|e| AssemblerError::io_error(src, e))?;
-    
-    let mut module = CodeModule::new(src.to_path_buf(), source);
-    
-    // Lexing
-    lexer::lex(&mut module)?;
-    
-    // Parsing
-    parser::parse(&mut module)?;
-    
-    // Resolution
-    resolver::resolve(&mut module)?;
-    
-    // Code generation
-    codegen::generate(&module)
-}
-7. Logging Integration
-Enhance the logging system to include source context:
-
-```rust
-// src/util/logging.rs
-pub trait Loggable {
-    fn log(&self, level: LogLevel, message: impl std::fmt::Display);
-    fn log_with_span(&self, level: LogLevel, span: &SourceSpan, message: impl std::fmt::Display);
-}
-
-impl Loggable for CodeModule {
-    fn log_with_span(&self, level: LogLevel, span: &SourceSpan, message: impl std::fmt::Display) {
-        if span.file_id != self.hash {
-            if let Some(dep) = self.find_dependency(span.file_id) {
-                return dep.log_with_span(level, span, message);
-            }
-        }
-        
-        let (line, col) = self.position_from_offset(span.start.offset);
-        let line_content = self.source.lines().nth(line as usize - 1).unwrap_or("");
-        
-        log::log!(
-            level,
-            "{}:{}:{}: {}\n  {}\n  {}{}",
-            self.path.display(),
-            line,
-            col,
-            message,
-            line_content,
-            " ".repeat(col as usize - 1),
-            "^"
-        );
-    }
-}
-8. Usage Example
-Here's how you'd use this in practice:
-
-```rust
-// In your parser or code that needs to report errors
-fn parse_token(&mut self, module: &CodeModule) -> Result<Token, AssemblerError> {
-    // ...
-    if !is_valid_token(&token) {
-        return Err(AssemblerError::new(
-            ErrorKind::SyntaxError,
-            token.span,
-            "Invalid token"
-        ).with_context("Expected a valid instruction or directive"));
-    }
-    // ...
-}
-```

resources/dsa/bf.dsa

@@ -2,10 +2,38 @@
 // a simple brainf##k interpreter,
 // because I already wrote a compiler lol.
 
-include print "./lib/print.dsa"
+include print "./lib/io/print.dsa"
 
 // "print hello world"
-db program: "++++++[>++++++++++++<-]>.>++++++++++[>++++++++++<-]>+.+++++++..+++.>++++[>+++++++++++<-]>.<+++[>----<-]>.<<<<<+++[>+++++<-]>.>>.+++.------.--------.>>+."
+db program: "++++++++++++++++++++++++++++++++++++++++++++
+>++++++++++++++++++++++++++++++++
+>++++++++++++++++
+>
+>+
+<<
+[
+>>
+>
+>++++++++++
+<<
+[->+>-[>+>>]>[+[-<+>]>+>>]<<<<<<]
+>[<+>-]
+>[-]
+>>
+>++++++++++
+<
+[->-[>+>>]>[+[-<+>]>+>>]<<<<<]
+>[-]
+>>[++++++++++++++++++++++++++++++++++++++++++++++++.[-]]
+<[++++++++++++++++++++++++++++++++++++++++++++++++.[-]]
+<<<++++++++++++++++++++++++++++++++++++++++++++++++.[-]
+<<<<<<<.>.
+>>[>>+<<-]
+>[>+<<+>-]
+>[<+>-]
+<<<-
+]
+<<++..."
 
 db error: "Invalid Instruction!"
 dw stack: 0x10000
@@ -20,6 +48,7 @@ _init_stack:
 start:
     // load the start of the program into rg0
     lwi program, rg0
+	lwi data, rg1
 
     // rg0 is our instruction pointer
     // rg1 is our data pointer
@@ -40,13 +69,6 @@ loop_start:
     // load the current instruction into rg3
     ldb rg0, rg3
 
-
-    // pusha 2
-    // push rg3
-    // call print::print_byte
-    // pop zero
-    // popa 2
-
     // switch on the instruction
     // all cases will return to either loop_start or loop_end
     cmp rg3, rg8
@@ -68,19 +90,15 @@ loop_start:
     cmp rg3, zero
     jeq end
 
-    // if we get here, we don't know what the instruction is
+	// if we get here, we don't know what the instruction is
-    lwi error, rg0
+	lwi error, rg2
-    push rg0
-    call print::print
-    pop zero
-
-end:
-    lwi error, rg2
     pusha 2
     push rg2
     call print::print
     pop zero
     popa 2
+
+end:
     hlt
 
 loop_end:
@@ -110,7 +128,7 @@ inc_ptr:
 // ------------------------------------------
 // decrement the pointer
 dec_ptr:
-    stw rg1, rg2
+    stw rg2, rg1
     subi rg1, 4
     ldw rg1, rg2
     jmp loop_end

resources/dsa/example.dsa

@@ -0,0 +1,121 @@
+
+// GENERATED BY DSC COMPILER
+// Generated at 2026-02-05 00:42:40
+
+// Imports
+include print: "./lib/io/print.dsa"
+include arena: "./lib/memory/arena_alloc.dsa"
+
+// Globals & Reserved Memory
+
+
+// Entry Point
+dw stack: 0x10000
+db message: "Process Exited with code:"
+_init:
+	ldw stack, bpr
+	mov bpr, spr
+	push zero
+	call main
+	call print::print_newline
+	lwi message, rg0
+	push rg0
+	call print::print
+	pop zero
+	call print::print_hex_word
+	pop zero
+	hlt
+
+
+// Return
+_ret:
+	mov bpr, spr
+	pop bpr
+	return
+
+// Compiled Code Starts...
+main:
+	push bpr
+	mov spr, bpr
+
+	lli 0, rg0
+	push rg0 // bpr-4: x
+	subi bpr 4 rg1
+	lli 512, rg0
+	push rg1 // bpr-8: y
+	push rg0 // push arg 0
+	call arena::new
+	pop rg2
+	lli 32, rg0
+	push rg2 // bpr-12: alloc
+	push rg0 // push arg 1
+	push rg2 // push arg 0
+	call arena::alloc
+	pop rg3
+	pop zero
+	lli 32, rg0
+	subi bpr 12 rg2
+	ldw rg2, rg2 // bpr-20: alloc
+	push rg2 // bpr-16: alloc
+	push rg3 // bpr-20: ptr1
+	push rg0 // push arg 1
+	push rg2 // push arg 0
+	call arena::alloc
+	pop rg4
+	pop zero
+	subi bpr 16 rg0
+	ldw rg0, rg0 // bpr-24: alloc
+	push rg4 // bpr-24: ptr2
+	push rg0 // bpr-28: alloc
+	push rg0 // push arg 0
+	call print::print_hex_word
+	pop zero
+	call print::print_newline
+	subi bpr 20 rg0
+	ldw rg0, rg0 // bpr-28: ptr1
+	push rg0 // bpr-32: ptr1
+	push rg0 // push arg 0
+	call print::print_hex_word
+	pop zero
+	call print::print_newline
+	subi bpr 24 rg0
+	ldw rg0, rg0 // bpr-32: ptr2
+	push rg0 // bpr-36: ptr2
+	push rg0 // push arg 0
+	call print::print_hex_word
+	pop zero
+	call print::print_newline
+	subi bpr 36 rg0
+	ldw rg0, rg0 // bpr-44: ptr2
+	ldw rg0, rg2
+	push rg0 // bpr-40: ptr2
+	push rg2 // push arg 0
+	call print::print_num
+	pop zero
+	call print::print_newline
+	lli 42, rg2
+	subi bpr 40 rg5
+	ldw rg5, rg5 // bpr-48: ptr2
+	stw rg2, rg5
+	push rg5 // bpr-44: ptr2
+	push rg5 // push arg 0
+	call print::print_hex_word
+	pop zero
+	call print::print_newline
+	subi bpr 44 rg2
+	ldw rg2, rg2 // bpr-52: ptr2
+	ldw rg2, rg5
+	push rg2 // bpr-48: ptr2
+	push rg5 // push arg 0
+	call print::print_num
+	pop zero
+	call print::print_newline
+	db str_1: "end"
+	lwi str_1, rg5
+	push rg5 // push arg 0
+	call print::println
+	pop zero
+	lli 0, rg5
+	stw rg5, bpr, 8
+	jmp _ret
+

resources/dsa/example.dsc

@@ -0,0 +1,30 @@
+include print: "./lib/io/print.dsa";
+include arena: "./lib/memory/arena_alloc.dsa";
+
+fn main() -> u32 {
+
+    let x: u32 = 0;
+    let y: u32 = &x;
+
+    let alloc: u32 = arena::new(512);
+    let ptr1: u32 = arena::alloc(alloc, 32);
+    let ptr2: u32 = arena::alloc(alloc, 32);
+
+    print::print_hex_word(alloc);
+    print::print_newline();
+    print::print_hex_word(ptr1);
+    print::print_newline();
+    print::print_hex_word(ptr2);
+    print::print_newline();
+    print::print_num(*ptr2);
+    print::print_newline();
+    *ptr2 = 42;
+
+    print::print_hex_word(ptr2);
+    print::print_newline();
+    print::print_num(*ptr2);
+    print::print_newline();
+    print::println("end");
+
+    return 0;
+}

resources/dsa/lib/error/handlers.dsa

@@ -0,0 +1,34 @@
+include print "../io/print.dsa"
+
+dw idt: 0xFFFF0000
+
+setup_idt:
+    push bpr
+    mov spr, bpr
+
+    // load the IDT into the IDR
+	ldw idt, idr
+
+	mov bpr, spr
+	pop bpr
+	return
+
+setup_hard_fault_handler:
+    push bpr
+    mov spr, bpr
+
+    lwi handle_hard_fault, rg0
+    stw rg0, idr, 4
+
+    mov bpr, spr
+    pop bpr
+    return
+
+dw hard_fault_err: "FATAL: Illegal Instruction or Memory Access!"
+handle_hard_fault:
+	call print::reset
+	lwi hard_fault_err, rg0
+	push rg0
+	call print::print
+	pop zero
+	hlt

resources/dsa/lib/fib.dsa

@@ -1,18 +0,0 @@
-fib_n:
-    pop ret
-    pop rg0 // n
-
-    lli 0, rg1
-    lli 1, rg2
-    
-start:
-    add rg1, rg2, acc
-    push rg1
-    mov rg2, rg1
-    mov acc, rg2
-    
-    cmp rg0, zero
-    dec rg0
-    
-    jgt start
-    jmp 4, ret

resources/dsa/lib/io/print.dsa

@@ -0,0 +1,331 @@
+// lib:
+// print.dsa
+
+// usage:
+//
+// include print "<relative path>""
+//
+// usage for print:
+//      push (register containing address of string)
+//      push pcx
+//      jmp print::print
+//
+// usage for reset:
+//      push pcx
+//      jmp print::reset
+//
+// usage for clear:
+//      push pcx
+//      jmp print::clear
+//
+// usage for print_byte:
+//      push (register containing byte)
+//      push pcx
+//      jmp print::print_byte
+//
+// usage for print_word:
+//      push (register containing word)
+//      push pcx
+//      jmp print::print_word
+//
+// usage for print_num:
+//      push (register containing number to print in decimal)
+//      push pcx
+//      jmp print::print_num
+//
+
+include maths "../maths/core.dsa"
+
+dw display: 0x20000
+dw current: 0x20000
+
+// ------------------------------------------
+// prints the string at addr(arg[0]) to the screen. (no trailing whitespace unless explicitly provided)
+print:
+    push bpr
+    mov spr, bpr
+
+    ldw bpr, rg0, 8
+    ldw current, rg1
+
+_print_loop:
+	ldb rg0, acc
+	cmp acc, zero
+	jeq _end
+	stb acc, rg1
+
+	addi rg0, 1
+	addi rg1, 1
+
+	jmp _print_loop
+
+// ------------------------------------------
+println:
+    push bpr
+    mov spr, bpr
+
+    ldw bpr, rg0, 8
+    ldw current, rg1
+
+_println_loop:
+	ldb rg0, acc
+	cmp acc, zero
+	jeq _println_end
+	stb acc, rg1
+
+	addi rg0, 1
+	addi rg1, 1
+
+	jmp _println_loop
+
+_println_end:
+    call print_newline
+    jmp _end
+
+// ------------------------------------------
+// prints the value of arg[0] to the screen.
+print_word:
+    // initialise
+    push bpr
+    mov spr, bpr
+
+    // load byte into acc
+    ldw bpr, rg0, 8
+    ldw current, rg1
+
+    addi rg1, 3
+
+    stb rg0, rg1
+    subi rg1, 1
+    shr rg0, 8
+    stb rg0, rg1
+    subi rg1, 1
+    shr rg0, 8
+    stb rg0, rg1
+    subi rg1, 1
+    shr rg0, 8
+    stb rg0, rg1
+
+    addi rg1, 4
+    jmp _end
+
+// ------------------------------------------
+// prints the last byte of arg[0] to the screen.
+print_byte:
+    push bpr
+    mov spr, bpr
+
+    ldw bpr, rg0, 8
+    ldw current, rg1
+
+    stb rg0, rg1
+    addi rg1, 1
+    jmp _end
+
+// ------------------------------------------
+// prints the value of arg[0] to the screen in hex.
+print_hex_word:
+    push bpr
+    mov spr, bpr
+
+    ldw current, rg1
+
+    ldb bpr, rg0, 8
+    push rg0
+    call _print_hex_byte
+    addi spr, 4
+
+    ldb bpr, rg0, 9
+    push rg0
+    call _print_hex_byte
+    addi spr, 4
+
+    ldb bpr, rg0, 10
+    push rg0
+    call _print_hex_byte
+    addi spr, 4
+
+    ldb bpr, rg0, 11
+    push rg0
+    call _print_hex_byte
+    addi spr, 4
+
+    jmp _end
+
+// ------------------------------------------
+// prints the last byte of arg[0] to the screen in hex.
+print_hex_byte:
+    push bpr
+    mov spr, bpr
+
+    ldw bpr, rg0, 8
+    ldw current, rg1
+
+    call _print_hex_byte
+    jmp _end
+
+// function body
+_print_hex_byte:
+    // mask to get lower nibble
+    lli 0xF, rg2
+    // save rg0 state
+    push rg0
+
+    shr rg0, 4
+    and rg0, rg2, rg0
+    call _print_hex_nibble
+    pop rg0
+
+    and rg0, rg2, rg0
+    call _print_hex_nibble
+    return
+
+// print a hex digit
+_print_hex_nibble:
+    lli 10, rg3
+    cmp rg0, rg3
+    jlt _print_hex_nibble_number
+    addi rg0, 0x37, rg0
+    stb rg0, rg1
+    addi rg1, 1
+    return
+
+// helper function.
+_print_hex_nibble_number:
+    addi rg0, 0x30, rg0
+    stb rg0, rg1
+    addi rg1, 1
+    return
+
+// ------------------------------------------
+// print whitespace
+print_whitespace:
+    push bpr
+    mov spr, bpr
+
+    ldw current, rg1
+    lli 0x20, rg0
+    stb rg0, rg1
+    addi rg1, 1
+    jmp _end
+
+// ------------------------------------------
+// print newline
+print_newline:
+    push bpr
+    mov spr, bpr
+
+    // load variables into registers
+    ldw display, rg0
+    ldw current, rg1
+
+    // get the offset from the display base
+    sub rg1, rg0, rg0
+
+    lwi 80, rg2
+    pusha 3
+    push rg0
+    push rg2
+    call maths::divmod
+    pop zero  // result
+    pop rg3 // remainder
+    popa 3
+
+    sub rg1, rg3, rg2
+    addi rg2, 80, rg1
+
+    // _end saves the display state
+    jmp _end
+
+// ------------------------------------------
+// prints arg[0] as a decimal number to the screen.
+print_num:
+    push bpr
+    mov spr, bpr
+
+    ldw bpr, rg0, 8      // load number to print
+    lli 0, rg5           // rg5 = digit counter
+
+    // check if number is zero
+    cmp rg0, zero
+    jne _print_num_extract_digits
+
+    // special case: print '0' for zero
+    lli 0x30, rg6
+    push rg6             // push digit to stack buffer
+    lli 1, rg5           // we have 1 digit
+    jmp _print_num_output
+
+_print_num_extract_digits:
+    // divide by 10 repeatedly to get digits
+    cmp rg0, zero
+    jeq _print_num_output
+
+    // call divmod(rg0, 10)
+    push rg0             // dividend
+    lli 10, rg1
+    push rg1             // divisor (10)
+    call maths::divmod
+    pop rg0              // quotient (continue dividing this)
+    pop rg1              // remainder (the digit)
+
+    // convert digit to ASCII and push to stack buffer
+    addi rg1, 0x30, rg6  // convert to ASCII
+    push rg6             // push digit to stack
+    inc rg5              // increment digit counter
+
+    jmp _print_num_extract_digits
+
+_print_num_output:
+    // now print digits (pop them off in reverse order)
+    ldw current, rg1     // get display pointer
+
+_print_num_output_loop:
+    // check if we've printed all digits
+    cmp rg5, zero
+    jeq _print_num_done
+
+    // pop digit and print it
+    pop rg6
+    stb rg6, rg1
+    addi rg1, 1
+    dec rg5
+
+    jmp _print_num_output_loop
+
+_print_num_done:
+    jmp _end
+
+// ------------------------------------------
+// resets the cursor position on the screen to 0x20000. (0,0)
+reset:
+    push bpr
+    mov spr, bpr
+    ldw display, rg1
+    jmp _end
+
+// ------------------------------------------
+// clears the screen
+clear:
+    push bpr
+    mov spr, bpr
+    // display size = 2000 bytes / 500 words
+    lli 500 rg0
+    ldw display, rg1
+
+_clear_loop:
+    dec rg0
+    stw zero, rg1
+    addi rg1, 4
+    cmp rg0, zero
+    jgt _clear_loop
+    jmp _end
+
+// ------------------------------------------
+// return
+_end:
+    stw rg1, current
+
+    mov bpr, spr
+    pop bpr
+    return

resources/dsa/lib/maths/core.dsa

@@ -0,0 +1,104 @@
+// multiply.dsa
+// usage:
+//
+// include multiply "<relative path>"
+//
+// usage for multiply:
+// push (arg1)
+// push (arg0)
+// call multiply::multiply
+// pop (arg0)
+// pop (arg1)
+
+multiply:
+	push bpr
+	mov spr, bpr
+
+	ldw bpr, rg0, 8  // load op 2
+	ldw bpr, rg1, 12 // load op 1
+	lwi 0, rg2       // initialise rg2 to zero
+
+_multiply_loop:
+	add rg2, rg0, rg2
+	dec rg1
+
+	cmp rg1, zero
+	jgt _multiply_loop
+
+_multiply_end:
+	stw rg2, bpr, 8
+
+	mov bpr, spr
+	pop bpr
+	return
+
+divmod:
+	push bpr
+	mov spr, bpr
+
+	ldw bpr, rg1, 8  // load op 2
+	ldw bpr, rg0, 12 // load op 1
+
+	lli 0, rg3
+
+_divmod_loop:
+	cmp rg0, rg1
+	jlt _divmod_end
+
+	sub rg0, rg1, rg0
+	inc rg3
+
+	jmp _divmod_loop
+
+_divmod_end:
+	// store div in first arg
+	// store mod in second arg
+	stw rg3, bpr, 8
+	stw rg0, bpr, 12
+
+	mov bpr, spr
+	pop bpr
+	return
+
+// multiply.dsa - improved version
+// Multiplies two 32-bit numbers using shift-and-add
+//
+// Usage:
+// push operand2  (multiplier)
+// push operand1  (multiplicand)
+// call multiply::multiply
+// pop result
+// pop zero       (discard second argument)
+
+new_multiply:
+    push bpr
+    mov spr, bpr
+
+    ldw bpr, rg0, 8     // rg0 = multiplicand
+    ldw bpr, rg1, 12    // rg1 = multiplier
+
+    lli 0, rg2          // rg2 = result (accumulator)
+    lli 32, rg3         // rg3 = bit counter
+
+mult_loop:
+    // Check if lowest bit of multiplier is 1
+    lli 1, acc
+    and rg1, acc, acc   // acc = rg1 & 1
+    cmp acc, zero
+    jeq skip_add        // if (rg1 & 1) == 0, skip addition
+
+    // Add multiplicand to result
+    add rg2, rg0, rg2
+
+skip_add:
+    shl rg0, 1          // shift multiplicand left
+    shr rg1, 1          // shift multiplier right
+
+    dec rg3
+    cmp rg3, zero
+    jgt mult_loop
+
+    stw rg2, bpr, 8     // store result
+    mov bpr, spr
+    pop bpr
+    return

resources/dsa/lib/maths/fib.dsa

@@ -0,0 +1,24 @@
+include print "../io/print.dsa"
+
+fib_n:
+	push bpr
+	mov spr, bpr
+
+	ldw bpr, rg0, 8  // load arg
+    lwi 0, rg1
+    lwi 1, rg2
+
+_start:
+    add rg1, rg2, rg3
+
+    mov rg2, rg1
+    mov rg3, rg2
+
+    dec rg0
+    cmp rg0, zero
+    jgt _start
+
+    stw rg3, bpr, 8
+    mov bpr, spr
+    pop bpr
+    return

resources/dsa/lib/memory/arena_alloc.dsa

@@ -0,0 +1,100 @@
+dw heap_start: 196608
+dw heap_end: 262144
+dw heap_current: 196608
+
+new:
+	push bpr
+	mov spr, bpr
+
+	ldw bpr, rg0, 8
+	lli 12, rg1
+	add rg0, rg1, rg2
+	ldw heap_current, rg1
+	add rg1, rg2, rg3
+	ldw heap_end, rg4
+	cmp rg3, rg4
+	lli 0, rg5
+	jle _cmp_end_2
+	lli 1, rg5
+_cmp_end_2:
+	cmp rg5, zero
+	jeq _else_4
+_then_3:
+	lli 0, rg4
+	stw rg4, bpr, 8
+	jmp _ret
+	jmp _end_5
+_else_4:
+	nop
+_end_5:
+	lli 12, rg4
+	add rg1, rg4, rg5
+	add rg1, rg2, rg4
+	stw rg5, rg1
+	lli 4, rg6
+	add rg1, rg6, rg7
+	stw rg5, rg7
+	lli 8, rg6
+	add rg1, rg6, rg7
+	stw rg4, rg7
+	stw rg3, heap_current
+	stw rg1, bpr, 8
+	jmp _ret
+
+alloc:
+	push bpr
+	mov spr, bpr
+
+	ldw bpr, rg0, 8
+	ldw bpr, rg1, 12
+	lli 4, rg2
+	add rg0, rg2, rg3
+	ldw rg3, rg2
+	lli 8, rg3
+	add rg0, rg3, rg4
+	ldw rg4, rg3
+	add rg2, rg1, rg4
+	cmp rg4, rg3
+	lli 0, rg5
+	jle _cmp_end_6
+	lli 1, rg5
+_cmp_end_6:
+	cmp rg5, zero
+	jeq _else_8
+_then_7:
+	lli 0, rg5
+	stw rg5, bpr, 8
+	jmp _ret
+	jmp _end_9
+_else_8:
+	nop
+_end_9:
+	lli 4, rg5
+	add rg0, rg5, rg6
+	stw rg4, rg6
+	stw rg2, bpr, 8
+	jmp _ret
+
+destroy:
+	push bpr
+	mov spr, bpr
+
+	ldw bpr, rg0, 8
+	lli 0, rg1
+	stw rg1, bpr, 8
+	jmp _ret
+
+reset_all:
+	push bpr
+	mov spr, bpr
+
+	ldw heap_start, rg0
+	stw rg0, heap_current
+	lli 0, rg0
+	stw rg0, bpr, 8
+	jmp _ret
+
+_ret:
+    mov bpr, spr
+    pop bpr
+    return

resources/dsa/lib/memory/arena_alloc.dsc

@@ -0,0 +1,77 @@
+// Arena Allocator
+// Supports multiple arenas that can be destroyed independently
+// Much more practical than a simple bump allocator
+
+// Global heap management
+static heap_start: u32 = 0x30000;
+static heap_end: u32 = 0x40000;
+static heap_current: u32 = 0x30000;
+
+// Arena structure (stored at the start of each arena):
+// [0-3]: start_address (u32)
+// [4-7]: current_position (u32)
+// [8-11]: end_address (u32)
+// Total header size: 12 bytes
+
+// Create a new arena with given size
+// Returns pointer to arena handle (or 0 if failed)
+fn arena_create(size: u32) -> u32 {
+    let total_size: u32 = size + 12;
+    let arena_ptr: u32 = heap_current;
+    let new_current: u32 = arena_ptr + total_size;
+
+    // Check if we have space
+    if new_current > heap_end {
+        return 0;
+    }
+
+    // Calculate arena data region
+    let data_start: u32 = arena_ptr + 12;
+    let data_end: u32 = arena_ptr + total_size;
+
+    // Initialize arena header
+    // Note: In real implementation, you'd use pointer writes here
+    // For now, using placeholder comments:
+    *arena_ptr = data_start;        // start_address
+    *(arena_ptr + 4) = data_start;  // current_position
+    *(arena_ptr + 8) = data_end;    // end_address
+
+    heap_current = new_current;
+
+    return arena_ptr;
+}
+
+// Allocate from an arena
+// Returns pointer to allocated memory (or 0 if failed)
+fn arena_alloc(arena: u32, size: u32) -> u32 {
+    // Read current position from arena
+    let current: u32 = *(arena + 4);
+    let end: u32 = *(arena + 8);
+
+    let new_current: u32 = current + size;
+
+    // Check if arena has space
+    if new_current > end {
+        return 0;
+    }
+
+    // Update current position in arena
+    *(arena + 4) = new_current;
+
+    return current;
+}
+
+// Destroy an arena (in bump allocator, this is a no-op)
+// In a real allocator, you'd mark the memory as free
+fn arena_destroy(arena: u32) {
+    // In a true allocator, mark memory as reusable
+    // For bump allocator, we can't reclaim memory
+    // unless we destroy ALL arenas and reset
+    return 0;
+}
+
+// Reset entire heap (destroys ALL arenas)
+fn reset_all() {
+    heap_current = heap_start;
+    return 0;
+}

resources/dsa/lib/multiply.dsa

@@ -1,30 +0,0 @@
-// multiply.dsa
-// usage:
-//
-// include multiply "<relative path>"
-//
-// usage for multiply:
-// push (arg1)
-// push (arg0)
-// call multiply::multiply
-// pop (arg0)
-// pop (arg1)
-
-multiply:
-	push bpr
-	mov spr, bpr
-	
-	ldw bpr, rg0, 8  // load op 1
-	ldw bpr, rg1, 12 // load op 2
-
-start:	
-	add acc, rg0, acc
-	dec rg1
-	
-	cmp rg1, zero
-	jgt start
-
-end:
-	mov bpr, spr
-	pop bpr
-	return

resources/dsa/lib/print.dsa

@@ -1,115 +0,0 @@
-// lib:
-// print.dsa
-
-// usage:
-//
-// include print "<relative path>""
-//      
-// usage for print:
-//      push (register containing address of string)
-//      push pcx
-//      jmp print::print
-//
-// usage for reset:
-//      push pcx
-//      jmp print::reset
-//
-// usage for clear:
-//      push pcx
-//      jmp print::clear
-//
-// usage for print_byte:
-//      push (register containing byte)
-//      push pcx
-//      jmp print::print_byte
-//
-// usage for print_word:
-//      push (register containing word)
-//      push pcx
-//      jmp print::print_word
-//
-
-dw display: 0x20000
-dw current: 0x20000
-
-// ------------------------------------------
-// prints the string at addr(arg[0]) to the screen.
-print:
-    push bpr
-    mov spr, bpr
-
-    ldw bpr, rg0, 8
-    ldw current, rg1
-
-_print_loop:
-	ldb rg0, acc
-	stb acc, rg1
-
-	addi rg0, 1
-	addi rg1, 1
-
-    cmp acc, zero
-	jne _print_loop
-    jmp _end
-
-// ------------------------------------------
-// prints the value of arg[0] to the screen.
-print_word:
-    // initialise
-    push bpr
-    mov spr, bpr
-
-    // load byte into acc
-    ldw bpr, rg0, 8
-    ldw current, rg1
-
-    stw rg0, rg1
-    addi rg1, 4
-    jmp _end
-
-// ------------------------------------------
-// prints the last byte of arg[0] to the screen. 
-print_byte:
-    push bpr
-    mov spr, bpr
-
-    ldw bpr, rg0, 8
-    ldw current, rg1
-
-    stb rg0, rg1
-    addi rg1, 1
-    jmp _end
-
-// ------------------------------------------
-// resets the cursor position on the screen to 0x20000. (0,0)
-reset:
-    push bpr
-    mov spr, bpr
-    ldw display, rg1
-    jmp _end
-
-// ------------------------------------------
-// clears the screen
-clear:
-    push bpr
-    mov spr, bpr
-    // display size = 2000 bytes / 500 words
-    lli 500 rg0
-    ldw display, rg1
-
-_clear_loop:
-    dec rg0
-    stw zero, rg1
-    addi rg1, 4
-    cmp rg0, zero
-    jgt _clear_loop
-    jmp _end
-
-// ------------------------------------------
-// return
-_end:
-    stw rg1, current
-	
-    mov bpr, spr
-    pop bpr
-    return

resources/dsa/main.dsa

@@ -0,0 +1,50 @@
+
+// GENERATED BY DSC COMPILER
+// Generated at 2026-02-04 01:44:06
+
+// Imports
+include print: "./lib/io/print.dsa"
+include fib: "./lib/maths/fib.dsa"
+
+// Globals & Reserved Memory
+
+
+// Entry Point
+dw stack: 0x10000
+db message: "Process Exited with code:"
+_init:
+	ldw stack, bpr
+	mov bpr, spr
+	push zero
+	call main
+	call print::print_newline
+	lwi message, rg0
+	push rg0
+	call print::print
+	pop zero
+	call print::print_hex_word
+	pop zero
+	hlt
+
+
+// Return
+_ret:
+	mov bpr, spr
+	pop bpr
+	return
+
+// Compiled Code Starts...
+main:
+	push bpr
+	mov spr, bpr
+
+	lli 6, rg0
+	push rg0 // bpr-4: x
+	push rg0 // push arg 0
+	call fib::fib_n
+	pop rg1
+	push rg1 // bpr-8: y
+	push rg1 // push arg 0
+	call print::print_num
+	pop zero
+	jmp _ret

resources/dsa/main.dsc

@@ -0,0 +1,9 @@
+include print: "./lib/io/print.dsa";
+include fib: "./lib/maths/fib.dsa";
+
+fn main() -> u32 {
+	let x: u32 = 6;
+	
+	let y: u32 = fib::fib_n(x);
+	print::print_num(y);
+}

resources/dsa/output.dsa

@@ -0,0 +1,214 @@
+
+// GENERATED BY DSC COMPILER
+// Generated at 2026-02-03 23:37:16
+
+// Imports
+include print: "./lib/io/print.dsa"
+
+// Globals & Reserved Memory
+dw heap_start: 196608
+dw heap_end: 262144
+dw heap_current: 196608
+
+// Entry Point
+dw stack: 0x10000
+db message: "Process Exited with code:"
+_init:
+	ldw stack, bpr
+	mov bpr, spr
+	push zero
+	call main
+	call print::print_newline
+	lwi message, rg0
+	push rg0
+	call print::print
+	pop zero
+	call print::print_hex_word
+	pop zero
+	hlt
+
+
+// Return
+_ret:
+	mov bpr, spr
+	pop bpr
+	return
+
+// Compiled Code Starts...
+main:
+	push bpr
+	mov spr, bpr
+
+	lli 0, rg0
+	push rg0 // bpr-4: x
+	subi bpr 4 rg1
+	lli 512, rg0
+	push rg1 // bpr-8: y
+	push rg0 // push arg 0
+	call arena_create
+	pop rg2
+	lli 32, rg0
+	push rg2 // bpr-12: alloc
+	push rg0 // push arg 1
+	push rg2 // push arg 0
+	call arena_alloc
+	pop rg3
+	pop zero
+	lli 32, rg0
+	subi bpr 12 rg2
+	ldw rg2, rg2 // bpr-20: alloc
+	push rg3 // bpr-16: ptr1
+	push rg2 // bpr-20: alloc
+	push rg0 // push arg 1
+	push rg2 // push arg 0
+	call arena_alloc
+	pop rg4
+	pop zero
+	subi bpr 20 rg0
+	ldw rg0, rg0 // bpr-28: alloc
+	push rg4 // bpr-24: ptr2
+	push rg0 // bpr-28: alloc
+	push rg0 // push arg 0
+	call print::print_hex_word
+	pop zero
+	call print::print_newline
+	subi bpr 16 rg0
+	ldw rg0, rg0 // bpr-24: ptr1
+	push rg0 // bpr-32: ptr1
+	push rg0 // push arg 0
+	call print::print_hex_word
+	pop zero
+	call print::print_newline
+	subi bpr 24 rg0
+	ldw rg0, rg0 // bpr-32: ptr2
+	push rg0 // bpr-36: ptr2
+	push rg0 // push arg 0
+	call print::print_hex_word
+	pop zero
+	call print::print_newline
+	subi bpr 36 rg0
+	ldw rg0, rg0 // bpr-44: ptr2
+	ldw rg0, rg2
+	push rg0 // bpr-40: ptr2
+	push rg2 // push arg 0
+	call print::print_num
+	pop zero
+	call print::print_newline
+	lli 42, rg2
+	subi bpr 40 rg5
+	ldw rg5, rg5 // bpr-48: ptr2
+	stw rg2, rg5
+	push rg5 // bpr-44: ptr2
+	push rg5 // push arg 0
+	call print::print_hex_word
+	pop zero
+	call print::print_newline
+	subi bpr 44 rg2
+	ldw rg2, rg2 // bpr-52: ptr2
+	ldw rg2, rg5
+	push rg2 // bpr-48: ptr2
+	push rg5 // push arg 0
+	call print::print_num
+	pop zero
+	call print::print_newline
+	db str_1: "end"
+	lwi str_1, rg5
+	push rg5 // push arg 0
+	call print::println
+	pop zero
+	lli 0, rg5
+	stw rg5, bpr, 8
+	jmp _ret
+
+arena_create:
+	push bpr
+	mov spr, bpr
+
+	ldw bpr, rg0, 8
+	lli 12, rg1
+	add rg0, rg1, rg2
+	ldw heap_current, rg1
+	add rg1, rg2, rg3
+	ldw heap_end, rg4
+	cmp rg3, rg4
+	lli 0, rg5
+	jle _cmp_end_2
+	lli 1, rg5
+_cmp_end_2:
+	cmp rg5, zero
+	jeq _else_4
+_then_3:
+	lli 0, rg4
+	stw rg4, bpr, 8
+	jmp _ret
+	jmp _end_5
+_else_4:
+	nop
+_end_5:
+	lli 12, rg4
+	add rg1, rg4, rg5
+	add rg1, rg2, rg4
+	stw rg5, rg1
+	lli 4, rg6
+	add rg1, rg6, rg7
+	stw rg5, rg7
+	lli 8, rg6
+	add rg1, rg6, rg7
+	stw rg4, rg7
+	stw rg3, heap_current
+	stw rg1, bpr, 8
+	jmp _ret
+
+arena_alloc:
+	push bpr
+	mov spr, bpr
+
+	ldw bpr, rg0, 8
+	ldw bpr, rg1, 12
+	lli 4, rg2
+	add rg0, rg2, rg3
+	ldw rg3, rg2
+	lli 8, rg3
+	add rg0, rg3, rg4
+	ldw rg4, rg3
+	add rg2, rg1, rg4
+	cmp rg4, rg3
+	lli 0, rg5
+	jle _cmp_end_6
+	lli 1, rg5
+_cmp_end_6:
+	cmp rg5, zero
+	jeq _else_8
+_then_7:
+	lli 0, rg5
+	stw rg5, bpr, 8
+	jmp _ret
+	jmp _end_9
+_else_8:
+	nop
+_end_9:
+	lli 4, rg5
+	add rg0, rg5, rg6
+	stw rg4, rg6
+	stw rg2, bpr, 8
+	jmp _ret
+
+arena_destroy:
+	push bpr
+	mov spr, bpr
+
+	ldw bpr, rg0, 8
+	lli 0, rg1
+	stw rg1, bpr, 8
+	jmp _ret
+
+reset_all:
+	push bpr
+	mov spr, bpr
+
+	ldw heap_start, rg0
+	stw rg0, heap_current
+	lli 0, rg0
+	stw rg0, bpr, 8
+	jmp _ret
+

resources/dsa/test.dsa

@@ -1,18 +0,0 @@
-include print "./lib/print.dsa"
-
-dw stack: 0x10000
-db string: "Hello world"
-
-init:
-	// set up a stack.
-	ldw stack, bpr
-	mov bpr, spr
-
-start:
-	lwi string, rg1
-
-	push rg1
-	call print::print
-	pop rg1
-
-	hlt

resources/dsa/testprint.dsa

@@ -0,0 +1,80 @@
+include print "./lib/io/print.dsa"
+
+dw idt: 0xFFFF0000
+dw stack: 0x10000
+init:
+	// setup interrupt handlers
+	ldw idt, idr
+	lwi handle_hard_fault, rg0
+	stw rg0, idr, 4
+	// set up a stack.
+	ldw stack, bpr
+	mov bpr, spr
+
+
+db string: "I won,  the game!"
+db hexbyte: 0xab
+dw hexword: 0x1234abcd
+db replace: "I lost"
+
+start:
+	// test print string
+	lwi string, rg0
+	push rg0
+	call print::print
+	pop zero
+
+	// test print hex byte.
+	ldb hexbyte, rg0
+	push rg0
+	call print::print_hex_byte
+	pop zero
+
+	// test print hex word.
+	ldw hexword, rg0
+	push rg0
+	call print::print_hex_word
+	pop zero
+
+	// test print char
+	lli 0x40, rg0 // print @
+	push rg0
+	call print::print_byte
+	pop zero
+
+	// test newline
+	call print::print_newline
+
+	lwi string rg0
+	push rg0
+	call print::print
+
+	// test print word
+	lwi 0x31323334, rg0 // print 1234
+	push rg0
+	call print::print_word
+	pop zero
+
+	// test reset cursor pos
+	call print::reset
+	
+	// test print string at reset pos
+	lwi replace, rg0
+	push rg0
+	call print::print
+	pop zero
+
+	hlt
+
+
+
+// fault handler in case we fail DSA.
+dw hard_fault_err: "FATAL: Illegal Instruction or Memory Access!"
+handle_hard_fault:
+	call print::clear
+	call print::reset
+	lwi hard_fault_err, rg0
+	push rg0
+	call print::print
+	pop zero
+	hlt

resources/examples/brainf.bf

@@ -0,0 +1,29 @@
+++++++++++++++++++++++++++++++++++++++++++++
+>++++++++++++++++++++++++++++++++
+>++++++++++++++++
+>
+>+
+<<
+[
+>>
+>
+>++++++++++
+<<
+[->+>-[>+>>]>[+[-<+>]>+>>]<<<<<<]
+>[<+>-]
+>[-]
+>>
+>++++++++++
+<
+[->-[>+>>]>[+[-<+>]>+>>]<<<<<]
+>[-]
+>>[++++++++++++++++++++++++++++++++++++++++++++++++.[-]]
+<[++++++++++++++++++++++++++++++++++++++++++++++++.[-]]
+<<<++++++++++++++++++++++++++++++++++++++++++++++++.[-]
+<<<<<<<.>.
+>>[>>+<<-]
+>[>+<<+>-]
+>[<+>-]
+<<<-
+]
+<<++...

resources/examples/example.c

@@ -0,0 +1,11 @@
+int factorial(int n) {
+  if (n <= 1) {
+    return 1;
+  }
+  return n * factorial(n - 1);
+}
+
+int main() {
+  int res = factorial(3);
+  return res;
+}

src/main.rs

@@ -1,53 +0,0 @@
-use std::{
-    sync::{Arc, Mutex},
-    thread,
-};
-
-use dsa_rs::emulator::{
-    system::{emulator::run_emulator, memory::MainStore, processor::Processor},
-    ui::{
-        control_unit::ControlPanel, interface::EmulatorUI, memory_inspector::MemoryInspector,
-        stack_inspector::StackInspector,
-    },
-};
-
-fn main() -> Result<(), eframe::Error> {
-    // Initialize Channels
-    let (cmd_sender, cmd_receiver) = std::sync::mpsc::channel();
-    let (state_sender, state_receiver) = std::sync::mpsc::channel();
-
-    let mainstore = MainStore::new();
-    let processor = Processor::new(Box::new(mainstore), vec![]);
-
-    thread::spawn(move || {
-        run_emulator(&cmd_receiver, &state_sender, processor);
-    });
-
-    // Create UI
-    let mut ui = EmulatorUI::new(cmd_sender.clone(), state_receiver);
-
-    // Create UI modules
-    let control_unit = ControlPanel::new(cmd_sender.clone());
-    ui.add_component(Box::new(control_unit));
-
-    let mem_inspector = MemoryInspector::new(cmd_sender.clone());
-    ui.add_component(Box::new(mem_inspector));
-
-    let stack_inspector = StackInspector::new();
-    ui.add_component(Box::new(stack_inspector));
-
-    // Run UI
-    let options = eframe::NativeOptions {
-        viewport: egui::ViewportBuilder::default().with_inner_size([800.0, 600.0]),
-        ..Default::default()
-    };
-
-    eframe::run_native(
-        "DSA Simulator (Damn Simple Architecture 🔥)",
-        options,
-        Box::new(move |cc| {
-            cc.egui_ctx.set_visuals(egui::Visuals::default());
-            Ok(Box::new(ui))
-        }),
-    )
-}