initial commit

.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"

.dsa.emulator.toml

@@ -0,0 +1,5 @@
+# The configuration file for the emulator. Here is an example file with all of the options you may want to set.
+
+[misc]
+# Defaults to false, here for testing purposes.
+use_discord_rpc = true

.gitignore

@@ -0,0 +1,2 @@
+/target
+**/*.env

.idea/.gitignore

@@ -0,0 +1,8 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

.idea/damn_simple_architecture.iml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="EMPTY_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/assembler/src" isTestSource="false" />
+      <sourceFolder url="file://$MODULE_DIR$/common/src" isTestSource="false" />
+      <sourceFolder url="file://$MODULE_DIR$/dsa_editor/src" isTestSource="false" />
+      <sourceFolder url="file://$MODULE_DIR$/emulator/src" isTestSource="false" />
+      <excludeFolder url="file://$MODULE_DIR$/target" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/damn_simple_architecture.iml" filepath="$PROJECT_DIR$/.idea/damn_simple_architecture.iml" />
+    </modules>
+  </component>
+</project>

.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

.rustfmt.toml

@@ -0,0 +1,3 @@
+max_width = 90
+comment_width = 90
+wrap_comments = true

.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+  "rust-analyzer.check.command": "clippy",
+  "editor.formatOnSave": true,
+  "rust-analyzer.cargo.features": "all",
+  "files.eol": "\n",
+  "files.insertFinalNewline": true,
+  "files.trimFinalNewlines": true,
+  "files.trimTrailingWhitespace": true,
+  "gitea.owner": "LowLevelDevs",
+  "gitea.repo": "damn_simple_architecture",
+}

Cargo.toml

@@ -0,0 +1,17 @@
+cargo-features = ["codegen-backend"]
+
+[workspace]
+members = ["emulator", "common", "assembler", "dsa_editor"]
+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.

README.md

@@ -0,0 +1 @@
+We failing DSA with this one

assembler/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "assembler"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+
+[[bin]]
+name = "assembler_runner"
+path = "src/main.rs"
+
+[lib]
+name = "assembler"
+path = "src/lib.rs"
+
+[dependencies]
+common = { path = "../common" }
+num_cpus = "1.17.0"
+threadpool = "1.8.1"

assembler/brainf.bf

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

assembler/src/assembler/assembler.rs

@@ -0,0 +1,264 @@
+use std::{
+    collections::HashSet,
+    fs,
+    path::{self, Path, PathBuf},
+    sync::{Arc, Mutex},
+    thread::{self, JoinHandle},
+};
+
+use crate::assembler::{AssembleError, Token, expand_pseudo_ops, lexer, quick_hash};
+use crate::assembler::{Node, Parser, resolve_dependencies};
+use crate::util::logging::Logger;
+
+// pub fn new_assemble(path: &Path) {
+//     let program = Program::new();
+//     let program_ref = ProgramRef::new(program);
+
+//     let task = Module::build(path.to_path_buf(), program_ref.clone());
+//     program_ref.add_task(task);
+
+//     // wait on all tasks to finish
+//     for task in program_ref.get_tasks() {
+//         let module = task.module.join().unwrap();
+//         program_ref.add_module(module);
+//     }
+// }
+
+pub struct Program {
+    pub main_path: PathBuf,
+    registry: HashSet<u64>,
+    modules: Vec<Module>,
+    tasks: Vec<Task>,
+    logger: Logger,
+}
+
+impl Program {
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            registry: HashSet::new(),
+            modules: Vec::new(),
+            tasks: Vec::new(),
+            main_path: PathBuf::new(),
+            logger: Logger::new(),
+        }
+    }
+
+    pub fn add_task(&mut self, task: Task) {
+        self.tasks.push(task);
+    }
+}
+
+impl Default for Program {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+pub struct ProgramRef {
+    program: Arc<Mutex<Program>>,
+}
+
+impl ProgramRef {
+    #[must_use]
+    pub fn new(program: Program) -> Self {
+        Self {
+            program: Arc::new(Mutex::new(program)),
+        }
+    }
+
+    pub fn register(&self, path: &Path) {
+        self.program
+            .lock()
+            .expect("Failed to acquire program lock")
+            .registry
+            .insert(quick_hash(path));
+    }
+
+    #[must_use]
+    pub fn is_registered(&self, path: &Path) -> bool {
+        self.program
+            .lock()
+            .expect("Failed to acquire program lock")
+            .registry
+            .contains(&quick_hash(path))
+    }
+
+    // pub fn get_tasks(&self) -> Vec<&Task> {
+    //     self.program.lock().unwrap().tasks.iter().collect()
+    // }
+
+    pub fn add_task(&self, task: Task) {
+        self.program
+            .lock()
+            .expect("Failed to acquire program lock")
+            .add_task(task);
+    }
+
+    pub fn add_module(&self, module: Module) {
+        self.program
+            .lock()
+            .expect("Failed to acquire program lock")
+            .modules
+            .push(module);
+    }
+
+    pub fn log(&self, message: &str) {
+        self.program
+            .lock()
+            .expect("Failed to acquire program lock")
+            .logger
+            .log(message);
+    }
+}
+
+impl Clone for ProgramRef {
+    fn clone(&self) -> Self {
+        Self {
+            program: self.program.clone(),
+        }
+    }
+}
+
+pub struct Module {
+    pub path: PathBuf,
+    pub hash: u64,
+    pub nodes: Vec<Node>,
+    program: ProgramRef,
+}
+
+impl Module {
+    #[must_use]
+    pub const fn new(
+        path: PathBuf,
+        hash: u64,
+        nodes: Vec<Node>,
+        program: ProgramRef,
+    ) -> Self {
+        Self {
+            path,
+            hash,
+            nodes,
+            program,
+        }
+    }
+
+    pub fn build(path: PathBuf, program: ProgramRef) -> Result<Task, AssembleError> {
+        // Spawn a thread that creates the main function and executes the lexer and parser.
+        let handle = thread::spawn(move || {
+            let mut module =
+                Self::new(path.clone(), quick_hash(&path), Vec::new(), program.clone());
+
+            match module.lex() {
+                Ok(tokens) => {
+                    module.parse(tokens);
+                    module.expand();
+                    module.prepare_dependencies();
+                    module
+                }
+                Err(why) => {
+                    eprintln!(
+                        "Error building program at path `{}`: {why}",
+                        path.display()
+                    );
+
+                    // TODO: Find a way to make this work without panicking.
+                    unreachable!()
+                }
+            }
+        });
+
+        Ok(Task { module: handle })
+    }
+
+    fn lex(&self) -> Result<Vec<Token>, AssembleError> {
+        if let Ok(path) = self.path.canonicalize() {
+            self.program.log(&format!(
+                "{:20} {:20} [{}]",
+                "Building",
+                self.get_filename(),
+                path.display()
+            ));
+        }
+
+        let src = fs::read_to_string(&self.path)
+            .map_err(|_| AssembleError::InvalidFile(self.path.clone()))?;
+
+        let file_hash = quick_hash(&self.path);
+
+        self.program
+            .log(&format!("{:20} {:20}", "Tokenising", self.get_filename()));
+
+        lexer::lexer(src, file_hash)
+    }
+
+    fn parse(&mut self, tokens: Vec<Token>) -> Result<(), AssembleError> {
+        self.program
+            .log(&format!("{:20} {:20}", "Parsing", self.get_filename()));
+
+        let parsed = Parser::parse_nodes(tokens)?;
+        self.nodes = parsed;
+
+        Ok(())
+    }
+
+    fn expand(&mut self) -> Result<(), AssembleError> {
+        self.program
+            .log(&format!("{:20} {:20}", "Expanding", self.get_filename()));
+
+        let expanded = expand_pseudo_ops(self.nodes.clone(), self.hash)?;
+        self.nodes = expanded;
+
+        Ok(())
+    }
+
+    fn prepare_dependencies(&self) -> Result<(), AssembleError> {
+        let nodes = resolve_dependencies(
+            self.nodes.clone(),
+            self.path.parent().expect("File should have a parent path!"),
+        )?;
+
+        let dependencies = Parser::get_dependencies(&nodes, &self.path)?;
+
+        for dep in dependencies {
+            if self.program.is_registered(&dep) {
+                // we have already built this module!
+                continue;
+            }
+
+            self.program.register(&dep);
+
+            // create new module
+            // add the task to the program
+
+            match Self::build(dep, self.program.clone()) {
+                Ok(task) => self.program.add_task(task),
+                Err(why) => {
+                    eprintln!("Error building program: {why}");
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    /// Gets the filename from a [`PathBuf`].
+    fn get_filename(&self) -> &str {
+        self.path
+            .file_name()
+            .and_then(|f| f.to_str())
+            .unwrap_or_default()
+    }
+
+    /// Gets the parent filepath from a [`PathBuf`].
+    fn get_parent(&self) -> &str {
+        self.path
+            .parent()
+            .and_then(|f| f.to_str())
+            .unwrap_or_default()
+    }
+}
+
+pub struct Task {
+    module: JoinHandle<Module>,
+}

assembler/src/assembler/codegen.rs

@@ -0,0 +1,348 @@
+use common::{args, prelude::*};
+
+use crate::assembler::model::{Node, Opcode};
+use crate::{assembler::AssembleError, expect_token};
+
+fn log(message: &str) {
+    println!("\x1b[32mINFO:\x1b[0m {message}");
+}
+
+pub fn codegen(nodes: Vec<Node>) -> Result<Vec<Instruction>, AssembleError> {
+    let mut instructions = vec![];
+
+    for node in nodes {
+        instructions.push(build_instruction(&node)?);
+    }
+
+    println!("------------------------");
+    log("Compilation Success ✅");
+
+    Ok(instructions)
+}
+
+fn build_instruction(node: &Node) -> Result<Instruction, AssembleError> {
+    let opcode = node.opcode();
+    let args = node.args();
+
+    match opcode {
+        Opcode::Nop => Ok(Instruction::Nop),
+        Opcode::Mov | Opcode::Movs => build_mov_instruction(opcode, &args),
+        Opcode::Ldb
+        | Opcode::Ldw
+        | Opcode::Ldh
+        | Opcode::Ldbs
+        | Opcode::Ldhs
+        | Opcode::Stb
+        | Opcode::Stw
+        | Opcode::Sth => build_memory_instruction(opcode, &args),
+        Opcode::Lli | Opcode::Lui => build_load_immediate_instruction(opcode, &args),
+        Opcode::Jmp
+        | Opcode::Jeq
+        | Opcode::Jne
+        | Opcode::Jgt
+        | Opcode::Jge
+        | Opcode::Jlt
+        | Opcode::Jle => build_jump_instruction(opcode, &args),
+        Opcode::Cmp => build_compare_instruction(&args),
+        Opcode::Inc | Opcode::Dec => build_inc_dec_instruction(opcode, &args),
+        Opcode::Shl | Opcode::Shr => build_shift_instruction(opcode, &args),
+        Opcode::Add
+        | Opcode::Sub
+        | Opcode::And
+        | Opcode::Or
+        | Opcode::Xor
+        | Opcode::Nand
+        | Opcode::Nor
+        | Opcode::Xnor => build_arithmetic_instruction(opcode, &args),
+        Opcode::AddI | Opcode::SubI => {
+            build_arithmetic_immediate_instruction(opcode, &args)
+        }
+        Opcode::Not => build_not_instruction(&args),
+        Opcode::Int => build_interrupt_instruction(&args),
+        Opcode::Irt => Ok(Instruction::IntReturn),
+        Opcode::Hlt => Ok(Instruction::Halt),
+        Opcode::Data => build_data_instruction(&args),
+        Opcode::Segment => build_segment_instruction(&args),
+        // These pseudo-instructions should have been expanded!
+        Opcode::Db
+        | Opcode::Dh
+        | Opcode::Dw
+        | Opcode::Resb
+        | Opcode::Resh
+        | Opcode::Resw
+        | Opcode::Push
+        | Opcode::Pop
+        | Opcode::Lwi
+        | Opcode::Include
+        | Opcode::Call
+        | Opcode::Return
+        | Opcode::Pusha
+        | Opcode::Popa => Err(AssembleError::InvalidArg),
+    }
+}
+
+fn build_mov_instruction(
+    opcode: Opcode,
+    args: &[crate::assembler::model::Token],
+) -> Result<Instruction, AssembleError> {
+    let Some(src_token) = args.first() else {
+        return Err(AssembleError::MissingArgument(0));
+    };
+    let Some(dest_token) = args.get(1) else {
+        return Err(AssembleError::MissingArgument(1));
+    };
+
+    let src = expect_token!(src_token, Register)?;
+    let dest = expect_token!(dest_token, Register)?;
+
+    match opcode {
+        Opcode::Mov => Ok(Instruction::Mov(args!(R, sr1: src, dr: dest))),
+        Opcode::Movs => Ok(Instruction::MovSigned(args!(R, sr1: src, dr: dest))),
+        _ => unreachable!(),
+    }
+}
+
+fn build_memory_instruction(
+    opcode: Opcode,
+    args: &[crate::assembler::model::Token],
+) -> Result<Instruction, AssembleError> {
+    let Some(base_token) = args.first() else {
+        return Err(AssembleError::MissingArgument(0));
+    };
+    let Some(dest_token) = args.get(1) else {
+        return Err(AssembleError::MissingArgument(1));
+    };
+    let Some(offset_token) = args.get(2) else {
+        return Err(AssembleError::MissingArgument(2));
+    };
+
+    let base = expect_token!(base_token, Register)?;
+    let dest = expect_token!(dest_token, Register)?;
+    let offset = expect_token!(offset_token, Immediate)?;
+    let instruction_args = args!(I, immediate: offset as u16, r1: base, r2: dest);
+
+    match opcode {
+        Opcode::Ldb => Ok(Instruction::LoadByte(instruction_args)),
+        Opcode::Ldw => Ok(Instruction::LoadWord(instruction_args)),
+        Opcode::Ldh => Ok(Instruction::LoadHalfword(instruction_args)),
+        Opcode::Ldbs => Ok(Instruction::LoadByteSigned(instruction_args)),
+        Opcode::Ldhs => Ok(Instruction::LoadHalfwordSigned(instruction_args)),
+        Opcode::Stb => Ok(Instruction::StoreByte(instruction_args)),
+        Opcode::Stw => Ok(Instruction::StoreWord(instruction_args)),
+        Opcode::Sth => Ok(Instruction::StoreHalfword(instruction_args)),
+        _ => unreachable!(),
+    }
+}
+
+fn build_load_immediate_instruction(
+    opcode: Opcode,
+    args: &[crate::assembler::model::Token],
+) -> Result<Instruction, AssembleError> {
+    let Some(value_token) = args.first() else {
+        return Err(AssembleError::MissingArgument(0));
+    };
+    let Some(dest_token) = args.get(1) else {
+        return Err(AssembleError::MissingArgument(1));
+    };
+
+    let value = expect_token!(value_token, Immediate)?;
+    let dest = expect_token!(dest_token, Register)?;
+
+    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;
+            let instruction_args = args!(I, immediate: upper_value as u16, r1: dest);
+            Ok(Instruction::LoadUpperImmediate(instruction_args))
+        }
+        _ => unreachable!(),
+    }
+}
+
+fn build_jump_instruction(
+    opcode: Opcode,
+    args: &[crate::assembler::model::Token],
+) -> Result<Instruction, AssembleError> {
+    let Some(address_token) = args.first() else {
+        return Err(AssembleError::MissingArgument(0));
+    };
+    let Some(offset_token) = args.get(1) else {
+        return Err(AssembleError::MissingArgument(1));
+    };
+
+    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);
+
+    match opcode {
+        Opcode::Jmp => Ok(Instruction::Jump(instruction_args)),
+        Opcode::Jeq => Ok(Instruction::JumpEq(instruction_args)),
+        Opcode::Jne => Ok(Instruction::JumpNeq(instruction_args)),
+        Opcode::Jgt => Ok(Instruction::JumpGt(instruction_args)),
+        Opcode::Jge => Ok(Instruction::JumpGe(instruction_args)),
+        Opcode::Jlt => Ok(Instruction::JumpLt(instruction_args)),
+        Opcode::Jle => Ok(Instruction::JumpLe(instruction_args)),
+        _ => unreachable!(),
+    }
+}
+
+fn build_compare_instruction(
+    args: &[crate::assembler::model::Token],
+) -> Result<Instruction, AssembleError> {
+    let Some(left_token) = args.first() else {
+        return Err(AssembleError::MissingArgument(0));
+    };
+    let Some(right_token) = args.get(1) else {
+        return Err(AssembleError::MissingArgument(1));
+    };
+
+    let left = expect_token!(left_token, Register)?;
+    let right = expect_token!(right_token, Register)?;
+    Ok(Instruction::Compare(args!(R, sr1: left, sr2: right)))
+}
+
+fn build_inc_dec_instruction(
+    opcode: Opcode,
+    args: &[crate::assembler::model::Token],
+) -> Result<Instruction, AssembleError> {
+    let Some(reg_token) = args.first() else {
+        return Err(AssembleError::MissingArgument(0));
+    };
+
+    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))),
+        _ => unreachable!(),
+    }
+}
+
+fn build_shift_instruction(
+    opcode: Opcode,
+    args: &[crate::assembler::model::Token],
+) -> Result<Instruction, AssembleError> {
+    let Some(reg_token) = args.first() else {
+        return Err(AssembleError::MissingArgument(0));
+    };
+    let Some(amount_token) = args.get(1) else {
+        return Err(AssembleError::MissingArgument(1));
+    };
+
+    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))),
+        Opcode::Shr => Ok(Instruction::ShiftRight(args!(R, sr1: reg, shamt: amount))),
+        _ => unreachable!(),
+    }
+}
+
+fn build_arithmetic_instruction(
+    opcode: Opcode,
+    args: &[crate::assembler::model::Token],
+) -> Result<Instruction, AssembleError> {
+    let Some(left_token) = args.first() else {
+        return Err(AssembleError::MissingArgument(0));
+    };
+    let Some(right_token) = args.get(1) else {
+        return Err(AssembleError::MissingArgument(1));
+    };
+    let Some(dest_token) = args.get(2) else {
+        return Err(AssembleError::MissingArgument(2));
+    };
+
+    let left = expect_token!(left_token, Register)?;
+    let right = expect_token!(right_token, Register)?;
+    let dest = expect_token!(dest_token, Register)?;
+    let instruction_args = args!(R, sr1: left, sr2: right, dr: dest);
+
+    match opcode {
+        Opcode::Add => Ok(Instruction::Add(instruction_args)),
+        Opcode::Sub => Ok(Instruction::Sub(instruction_args)),
+        Opcode::And => Ok(Instruction::And(instruction_args)),
+        Opcode::Or => Ok(Instruction::Or(instruction_args)),
+        Opcode::Xor => Ok(Instruction::Xor(instruction_args)),
+        Opcode::Nand => Ok(Instruction::Nand(instruction_args)),
+        Opcode::Nor => Ok(Instruction::Nor(instruction_args)),
+        Opcode::Xnor => Ok(Instruction::Xnor(instruction_args)),
+        _ => unreachable!(),
+    }
+}
+
+fn build_arithmetic_immediate_instruction(
+    opcode: Opcode,
+    args: &[crate::assembler::model::Token],
+) -> Result<Instruction, AssembleError> {
+    let Some(reg_token) = args.first() else {
+        return Err(AssembleError::MissingArgument(0));
+    };
+    let Some(immediate_token) = args.get(1) else {
+        return Err(AssembleError::MissingArgument(1));
+    };
+    let Some(dest_token) = args.get(2) else {
+        return Err(AssembleError::MissingArgument(2));
+    };
+
+    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);
+
+    match opcode {
+        Opcode::AddI => Ok(Instruction::AddImmediate(instruction_args)),
+        Opcode::SubI => Ok(Instruction::SubImmediate(instruction_args)),
+        _ => unreachable!(),
+    }
+}
+
+fn build_not_instruction(
+    args: &[crate::assembler::model::Token],
+) -> Result<Instruction, AssembleError> {
+    let Some(reg_token) = args.first() else {
+        return Err(AssembleError::MissingArgument(0));
+    };
+    let Some(dest_token) = args.get(1) else {
+        return Err(AssembleError::MissingArgument(1));
+    };
+
+    let reg = expect_token!(reg_token, Register)?;
+    let dest = expect_token!(dest_token, Register)?;
+    Ok(Instruction::Not(args!(R, sr1: reg, dr: dest)))
+}
+
+fn build_interrupt_instruction(
+    args: &[crate::assembler::model::Token],
+) -> Result<Instruction, AssembleError> {
+    let Some(code_token) = args.first() else {
+        return Err(AssembleError::MissingArgument(0));
+    };
+
+    let code = expect_token!(code_token, Immediate)? as u8;
+    Ok(Instruction::Interrupt(Interrupt::Software(code)))
+}
+
+fn build_data_instruction(
+    args: &[crate::assembler::model::Token],
+) -> Result<Instruction, AssembleError> {
+    let Some(immediate_token) = args.first() else {
+        return Err(AssembleError::MissingArgument(0));
+    };
+
+    let immediate = expect_token!(immediate_token, Immediate)?;
+    Ok(Instruction::Data(immediate))
+}
+
+fn build_segment_instruction(
+    args: &[crate::assembler::model::Token],
+) -> Result<Instruction, AssembleError> {
+    let Some(immediate_token) = args.first() else {
+        return Err(AssembleError::MissingArgument(0));
+    };
+
+    let immediate = expect_token!(immediate_token, Immediate)?;
+    Ok(Instruction::Segment(immediate))
+}

assembler/src/assembler/expand.rs

@@ -0,0 +1,368 @@
+use common::prelude::Register;
+
+use crate::assembler::model::{Node, Opcode, Token};
+use crate::{assembler::AssembleError, expect_token, expect_type, node};
+
+pub fn expand_pseudo_ops(
+    mut nodes: Vec<Node>,
+    module: u64,
+) -> Result<Vec<Node>, AssembleError> {
+    let mut result = Vec::<Node>::with_capacity(nodes.len());
+
+    for node in &mut nodes {
+        if try_expand(node.clone(), &mut result, module).is_err() {
+            result.push(node.clone());
+        }
+    }
+
+    Ok(result)
+}
+
+fn try_expand(
+    node: Node,
+    result: &mut Vec<Node>,
+    _module: u64,
+) -> Result<(), AssembleError> {
+    match node.opcode() {
+        Opcode::Push => expand_push(&node, result)?,
+        Opcode::Pop => expand_pop(&node, result)?,
+        Opcode::Pusha => expand_pusha(&node, result)?,
+        Opcode::Popa => expand_popa(&node, result)?,
+        Opcode::Call => expand_call(&node, result)?,
+        Opcode::Return => expand_return(&node, result),
+        Opcode::Ldb | Opcode::Ldbs | Opcode::Ldh | Opcode::Ldhs | Opcode::Ldw => {
+            expand_ldx(&node, result)?;
+        }
+        Opcode::Stb | Opcode::Sth | Opcode::Stw => expand_stx(&node, result)?,
+
+        Opcode::Lwi => expand_lwi(&node, result)?,
+        Opcode::Resb | Opcode::Resh | Opcode::Resw => expand_resx(&node, result)?,
+        Opcode::Db | Opcode::Dh | Opcode::Dw => expand_dx(&node, result)?,
+        _ => result.push(node),
+    }
+    Ok(())
+}
+
+fn expand_push(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    let label = current.label();
+    let Ok(arg0) = current.arg(0) else {
+        return Err(AssembleError::Generic);
+    };
+
+    let reg = expect_type!(arg0, Register)?;
+    let spr = Token::Register(Register::Spr);
+
+    nodes.extend(vec![
+        node!(label, Opcode::SubI, spr, 4, spr),
+        node!(None, Opcode::Stw, reg, spr, 0),
+    ]);
+
+    Ok(())
+}
+
+fn expand_pusha(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    let label = current.label();
+    let Ok(arg0) = current.arg(0) else {
+        return Err(AssembleError::Generic);
+    };
+
+    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)
+        )
+    }));
+
+    Ok(())
+}
+
+fn expand_popa(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    let label = current.label();
+
+    let Ok(arg0) = current.arg(0) else {
+        return Err(AssembleError::Generic);
+    };
+
+    let count = expect_token!(arg0, Immediate)?;
+    let spr = Token::Register(Register::Spr);
+    let registers: Vec<Register> = Register::general();
+
+    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
+    ));
+
+    Ok(())
+}
+
+fn expand_call(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    let label = current.label();
+
+    let Ok(arg0) = current.arg(0) else {
+        return Err(AssembleError::Generic);
+    };
+
+    let addr = expect_type!(arg0, Symbol)?;
+    let spr = Token::Register(Register::Spr);
+    let pcx = Token::Register(Register::Pcx);
+    let zero = Token::Register(Register::Zero);
+
+    nodes.extend(vec![
+        node!(label, Opcode::SubI, spr, 4, spr),
+        node!(None, Opcode::Stw, pcx, spr, 0),
+        node!(None, Opcode::Jmp, addr, zero),
+    ]);
+
+    Ok(())
+}
+
+fn expand_return(current: &Node, nodes: &mut Vec<Node>) {
+    let label = current.label();
+    let spr = Token::Register(Register::Spr);
+    let ret = Token::Register(Register::Ret);
+
+    nodes.extend(vec![
+        node!(label, Opcode::Ldw, spr, ret, 0),
+        node!(None, Opcode::AddI, spr, 4, spr),
+        node!(None, Opcode::Jmp, 4, ret),
+    ]);
+}
+
+fn expand_pop(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    let label = current.label();
+
+    let Ok(arg0) = current.arg(0) else {
+        return Err(AssembleError::Generic);
+    };
+
+    let reg = expect_type!(arg0, Register)?;
+    let spr = Token::Register(Register::Spr);
+
+    nodes.extend(vec![
+        node!(label, Opcode::Ldw, spr, reg, 0),
+        node!(None, Opcode::AddI, spr, 4, spr),
+    ]);
+
+    Ok(())
+}
+
+fn expand_ldx(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    let opcode = current.opcode();
+    let args: Vec<Token> = current.args().into_iter().take(3).collect();
+
+    let Some(name) = args.first() else {
+        return Err(AssembleError::MissingArgument(0));
+    };
+
+    let Some(reg) = args.get(1) else {
+        return Err(AssembleError::MissingArgument(1));
+    };
+
+    let Some(offset) = args.get(2) else {
+        return Err(AssembleError::MissingArgument(2));
+    };
+
+    let name = expect_type!(name, Symbol)?;
+    let reg = expect_type!(reg, Register)?;
+    let offset = expect_type!(offset, Immediate)?;
+
+    nodes.extend(vec![
+        node!(current.label(), Opcode::Lli, name, reg),
+        node!(None, Opcode::Lui, name, reg),
+        node!(None, opcode, reg, reg, offset),
+    ]);
+
+    Ok(())
+}
+
+fn expand_stx(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    let opcode = current.opcode();
+
+    let args: Vec<Token> = current.args().into_iter().take(3).collect();
+
+    let Some(base) = args.first() else {
+        return Err(AssembleError::MissingArgument(0));
+    };
+
+    let Some(dest) = args.get(1) else {
+        return Err(AssembleError::MissingArgument(1));
+    };
+
+    let Some(offset) = args.get(2) else {
+        return Err(AssembleError::MissingArgument(2));
+    };
+
+    let base = expect_type!(base, Register)?;
+    let dest = expect_type!(dest, Symbol)?;
+    let offset = expect_type!(offset, Immediate)?;
+    let temp = Token::Register(Register::Acc);
+
+    nodes.extend(vec![
+        node!(current.label(), Opcode::Lli, dest, temp),
+        node!(None, Opcode::Lui, dest, temp),
+        node!(None, opcode, base, temp, offset),
+    ]);
+
+    Ok(())
+}
+
+fn expand_lwi(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    let Ok(val) = current.arg(0) else {
+        return Err(AssembleError::MissingArgument(0));
+    };
+
+    let Ok(reg) = current.arg(1) else {
+        return Err(AssembleError::MissingArgument(1));
+    };
+
+    let val = expect_type!(val, Symbol, Immediate)?;
+    let reg = expect_type!(reg, Register)?;
+
+    nodes.extend(vec![
+        node!(current.label(), Opcode::Lli, val, reg),
+        node!(None, Opcode::Lui, val, reg),
+    ]);
+
+    Ok(())
+}
+
+fn expand_resx(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    let Ok(region_label) = current.arg(0) else {
+        return Err(AssembleError::MissingArgument(0));
+    };
+
+    let Ok(size) = current.arg(1) else {
+        return Err(AssembleError::MissingArgument(1));
+    };
+
+    let region_label = expect_token!(region_label, Symbol)?;
+    let size = expect_token!(size, Immediate)?;
+
+    let units_per = match current.opcode() {
+        Opcode::Resb => 4,
+        Opcode::Resh => 2,
+        Opcode::Resw => 1,
+        _ => unreachable!(),
+    };
+
+    let mut buffer = vec![];
+    // push the inital node with the label
+    for _ in 0..size.div_ceil(units_per) {
+        // push the rest of the nodes
+        buffer.push(node!(None, Opcode::Data, 0));
+    }
+    buffer[0].symbol = Some(region_label);
+    nodes.extend(buffer);
+
+    Ok(())
+}
+
+fn expand_dx(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    let Ok(region_label) = current.arg(0) else {
+        return Err(AssembleError::MissingArgument(0));
+    };
+
+    let region_label = expect_token!(region_label, Symbol)?;
+    let size = match current.opcode() {
+        Opcode::Db => 4,
+        Opcode::Dh => 2,
+        Opcode::Dw => 1,
+        _ => unreachable!(),
+    };
+
+    let mut buffer = vec![];
+
+    let mut args = current.args();
+    let _label = args.remove(0);
+
+    for word in process_dx_data(args, size)? {
+        buffer.push(node!(None, Opcode::Data, Token::Immediate(word)));
+    }
+    buffer[0].symbol = Some(region_label);
+
+    nodes.extend(buffer);
+    Ok(())
+}
+
+fn process_dx_data(args: Vec<Token>, size: usize) -> Result<Vec<u32>, AssembleError> {
+    assert!(matches!(size, 1 | 2 | 4));
+
+    let mut buffer = Vec::<u8>::new();
+
+    // Process each token
+    for token in args {
+        match token {
+            Token::StringLit(mut s) => {
+                s.push('\0');
+                // Split string into chars and write as bytes
+                for ch in s.chars() {
+                    // Convert char to bytes (UTF-8 encoding)
+                    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) => {
+                // Split u32 into bytes (little-endian)
+                buffer.extend_from_slice(&value.to_be_bytes());
+            }
+            _ => {
+                return Err(AssembleError::Generic);
+            }
+        }
+
+        // Pad buffer to alignment boundary with zeros
+        let remainder = buffer.len() % size;
+        if remainder != 0 {
+            let padding = size - remainder;
+            buffer.resize(buffer.len() + padding, 0);
+        }
+    }
+
+    // Convert byte buffer to u32 chunks
+    // Pad final buffer to u32 boundary if needed
+    let remainder = buffer.len() % 4;
+    if remainder != 0 {
+        let padding = 4 - remainder;
+        buffer.resize(buffer.len() + padding, 0);
+    }
+
+    // Convert bytes to u32s efficiently using chunks_exact
+    let result = buffer
+        .chunks_exact(4)
+        .map(|chunk| {
+            // Convert 4 bytes to u32 (little-endian)
+            u32::from_be_bytes([chunk[0], chunk[1], chunk[2], chunk[3]])
+        })
+        .collect();
+
+    Ok(result)
+}

assembler/src/assembler/lexer.rs

@@ -0,0 +1,173 @@
+use std::str::FromStr;
+
+use crate::assembler::AssembleError;
+use crate::assembler::model::{Module, Opcode, Symbol, Token};
+use common::prelude::Register;
+
+pub fn lexer(mut program: String, module: u64) -> Result<Vec<Token>, AssembleError> {
+    let mut tokens = Vec::new();
+
+    let lines = program.lines();
+    let mut literal = String::new();
+
+    for line in lines {
+        for (i, token) in line.split_whitespace().enumerate() {
+            if token.starts_with("//") {
+                break;
+            }
+
+            if let Some(stripped) = token.strip_prefix('"') {
+                literal.push_str(stripped);
+            }
+
+            if !literal.is_empty() {
+                if !token.starts_with('"') {
+                    if i > 0 {
+                        literal.push(' ');
+                    }
+                    literal.push_str(token);
+                }
+
+                if token.ends_with('"') {
+                    literal.pop(); // remove the closing quote
+
+                    tokens.push(Token::StringLit(literal));
+                    literal = String::new();
+                }
+
+                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)? {
+                tokens.push(token);
+            } else if let Some(token) = parse_hex(token)? {
+                tokens.push(token);
+            } else if let Some(token) = parse_octal(token)? {
+                tokens.push(token);
+            } else if let Some(token) = parse_binary(token)? {
+                tokens.push(token);
+            } else if let Some(token) = parse_decimal(token)? {
+                tokens.push(token);
+            } else if let Some(token) = parse_label(token, module)? {
+                tokens.push(token);
+            } else if let Some(token) = parse_symbol(token, module)? {
+                tokens.push(token);
+            } else {
+                return Err(AssembleError::Generic);
+            }
+        }
+    }
+
+    println!("{:#?}", tokens);
+
+    Ok(tokens)
+}
+pub fn parse_register(token: &str) -> Result<Option<Token>, AssembleError> {
+    Ok(Register::try_from(token).map(Token::Register).ok())
+}
+
+pub fn parse_opcode(token: &str) -> Result<Option<Token>, AssembleError> {
+    if Opcode::OPCODES.contains(&token) {
+        Ok(Some(Token::Opcode(Opcode::from_str(token).expect(
+            "Opcode::from_str failed for a valid opcode token",
+        ))))
+    } else {
+        Ok(None)
+    }
+}
+
+pub fn parse_hex(token: &str) -> Result<Option<Token>, AssembleError> {
+    if (token.len() < 3) | !token.starts_with("0x") {
+        return Ok(None);
+    }
+
+    let Some(lit) = &token.get(2..) else {
+        return Err(AssembleError::InvalidArg);
+    };
+
+    u32::from_str_radix(lit, 16).map_or(Err(AssembleError::Generic), |value| {
+        Ok(Some(Token::Immediate(value)))
+    })
+}
+
+pub fn parse_octal(token: &str) -> Result<Option<Token>, AssembleError> {
+    if (token.len() < 3) | !token.starts_with("0o") {
+        return Ok(None);
+    }
+
+    let Some(lit) = &token.get(2..) else {
+        return Err(AssembleError::InvalidArg);
+    };
+
+    u32::from_str_radix(lit, 8).map_or(Err(AssembleError::Generic), |value| {
+        Ok(Some(Token::Immediate(value)))
+    })
+}
+
+pub fn parse_binary(token: &str) -> Result<Option<Token>, AssembleError> {
+    if (token.len() < 3) | !token.starts_with("0b") {
+        return Ok(None);
+    }
+
+    let Some(lit) = &token.get(2..) else {
+        return Err(AssembleError::InvalidArg);
+    };
+
+    u32::from_str_radix(lit, 2).map_or(Err(AssembleError::Generic), |value| {
+        Ok(Some(Token::Immediate(value)))
+    })
+}
+
+pub fn parse_decimal(token: &str) -> Result<Option<Token>, AssembleError> {
+    let Ok(tok) = token.parse::<u32>() else {
+        return Ok(None);
+    };
+
+    Ok(Some(Token::Immediate(tok)))
+}
+
+pub fn parse_label(token: &str, module: u64) -> Result<Option<Token>, AssembleError> {
+    if token.ends_with(':') {
+        Ok(Some(Token::Symbol(Symbol {
+            name: token[0..token.len() - 1].to_string(),
+            module: Module::Resolved(module),
+        })))
+    } else {
+        Ok(None)
+    }
+}
+
+pub fn parse_symbol(token: &str, module: u64) -> Result<Option<Token>, AssembleError> {
+    let Some(tokc) = token.chars().next() else {
+        return Err(AssembleError::Generic); // TODO: What is this error?
+    };
+
+    if tokc.is_numeric() {
+        return Ok(None);
+    }
+
+    let mut split = token.splitn(2, "::");
+    let Some(symbol1) = split.next() else {
+        return Err(AssembleError::InvalidArg);
+    };
+    let symbol1 = symbol1.to_string();
+
+    if let Some(symbol2) = split.next() {
+        Ok(Some(Token::Symbol(Symbol {
+            name: symbol2.to_string(),
+            module: Module::Unresolved(symbol1),
+        })))
+    } else {
+        Ok(Some(Token::Symbol(Symbol {
+            name: symbol1,
+            module: Module::Resolved(module),
+        })))
+    }
+}

assembler/src/assembler/macros.rs

@@ -0,0 +1,138 @@
+//! Macros used throughout the assembler
+
+use crate::assembler::model::{Node, Opcode, Symbol, Token};
+/// Parse DSA assembly code with optional formatting
+///
+/// # Examples
+/// ```
+/// // With formatting:
+/// let nodes = dsa!(hash, "mov r1, {}", 42)?;
+///
+/// // Without formatting:
+/// let nodes = dsa!(hash, "mov r1, 42")?;
+/// ```
+#[macro_export]
+macro_rules! dsa {
+    // Version with formatting arguments
+    ($hash:expr, $input:expr, $($args:expr),+) => {{
+        let input = format!($input, $($args),+);
+        let tokens = $crate::lexer::lexer(input, $hash)?;
+        let parsed = $crate::parser::Parser::parse_nodes(tokens)?;
+        parsed
+    }};
+    // Version without formatting
+    ($hash:expr, $input:expr) => {{
+        let input = String::from($input);
+        let tokens = $crate::lexer::lexer(input, $hash)?;
+        let parsed = $crate::parser::Parser::parse_nodes(tokens)?;
+        parsed
+    }};
+}
+
+/// Creates a new Node with the given symbol, opcode, and tokens
+#[macro_export]
+macro_rules! node {
+    ($symbol: expr, $opcode: expr, args: $tokens: expr) => {
+        $crate::assembler::model::Node::new($symbol.clone(), $opcode.clone(), $tokens.clone())
+    };
+
+    ($symbol: expr, $opcode: expr, $($tokens: expr),+) => {
+        $crate::assembler::model::Node::new(
+            $symbol.clone(),
+            $opcode.clone(),
+            vec![$(node!(@convert_token $tokens)),+]
+        )
+    };
+
+    ($symbol: expr, $opcode: expr) => {
+        $crate::assembler::model::Node::new(
+            $symbol.clone(),
+            $opcode.clone(),
+            Vec::new()
+        )
+    };
+
+    (@convert_token $token: literal) => {
+        $crate::assembler::model::Token::Immediate($token)
+    };
+
+    (@convert_token $token: expr) => {
+        $token.clone()
+    };
+}
+
+/// Extracts a specific token type from a token
+#[macro_export]
+macro_rules! expect_token {
+    ($token:expr, Symbol) => {
+        match $token {
+            $crate::assembler::model::Token::Symbol(value) => Ok(value.clone()),
+            other => Err($crate::assembler::AssembleError::UnexpectedToken(
+                other.clone(),
+                $crate::assembler::model::TokenType::Symbol,
+            )),
+        }
+    };
+    ($token:expr, Register) => {
+        match $token {
+            $crate::assembler::model::Token::Register(value) => Ok(value.clone()),
+            other => Err($crate::assembler::AssembleError::UnexpectedToken(
+                other.clone(),
+                $crate::assembler::model::TokenType::Register,
+            )),
+        }
+    };
+    ($token:expr, Immediate) => {
+        match $token {
+            $crate::assembler::model::Token::Immediate(value) => Ok(value.clone()),
+            other => Err($crate::assembler::AssembleError::UnexpectedToken(
+                other.clone(),
+                $crate::assembler::model::TokenType::Immediate,
+            )),
+        }
+    };
+    ($token:expr, StringLit) => {
+        match $token {
+            $crate::assembler::model::Token::StringLit(value) => Ok(value.clone()),
+            other => Err($crate::assembler::AssembleError::UnexpectedToken(
+                other.clone(),
+                $crate::assembler::model::TokenType::StringLit,
+            )),
+        }
+    };
+    ($token:expr, Opcode) => {
+        match $token {
+            $crate::assembler::model::Token::Opcode(value) => Ok(value.clone()),
+            other => Err($crate::assembler::AssembleError::UnexpectedToken(
+                other.clone(),
+                $crate::assembler::model::TokenType::Opcode,
+            )),
+        }
+    };
+}
+
+/// Checks if a token matches any of the specified types
+#[macro_export]
+macro_rules! expect_type {
+    ($token:expr, $($variant:ident),+) => {{
+        let token = $token;
+        match &token {
+            $(
+                $crate::assembler::model::Token::$variant(_) => Ok(token.clone()),
+            )+
+            other => {
+                let expected_type = expect_type!(@get_first_type $($variant),+);
+                Err($crate::assembler::AssembleError::UnexpectedToken(
+                    other.clone().clone(),
+                    expected_type,
+                ))
+            }
+        }
+    }};
+
+    (@get_first_type Symbol $(, $rest:ident)*) => { $crate::assembler::model::TokenType::Symbol };
+    (@get_first_type Register $(, $rest:ident)*) => { $crate::assembler::model::TokenType::Register };
+    (@get_first_type Immediate $(, $rest:ident)*) => { $crate::assembler::model::TokenType::Immediate };
+    (@get_first_type StringLit $(, $rest:ident)*) => { $crate::assembler::model::TokenType::StringLit };
+    (@get_first_type Opcode $(, $rest:ident)*) => { $crate::assembler::model::TokenType::Opcode };
+}

assembler/src/assembler/mod.rs

@@ -0,0 +1,266 @@
+#![allow(dead_code, unused)]
+
+use std::{
+    collections::HashSet,
+    fmt, fs,
+    hash::{DefaultHasher, Hash, Hasher},
+    path::{Path, PathBuf},
+    sync::{Arc, Mutex, mpsc},
+    thread,
+};
+
+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;
+
+#[allow(clippy::module_inception)]
+pub mod assembler;
+pub mod codegen;
+pub mod expand;
+pub mod lexer;
+pub mod model;
+pub mod parser;
+pub mod resolver;
+
+// Re-exports
+pub use self::{
+    codegen::codegen,
+    expand::expand_pseudo_ops,
+    lexer::lexer,
+    model::{Module, Node, Opcode, Symbol, Token, TokenType},
+    parser::{Parser, Program},
+    resolver::{create_sections, resolve_dependencies, resolve_symbols},
+};
+
+use crate::util::logging::{Entry, Logger};
+
+pub struct CompilerEngine {
+    result_tx: mpsc::Sender<Result<Vec<Instruction>, AssembleError>>,
+    result_rx: Option<mpsc::Receiver<Result<Vec<Instruction>, AssembleError>>>,
+    is_running: bool,
+}
+
+impl CompilerEngine {
+    #[must_use]
+    pub fn new() -> Self {
+        let (tx, rx) = mpsc::channel();
+        Self {
+            result_tx: tx,
+            result_rx: Some(rx),
+            is_running: false,
+        }
+    }
+
+    /// Start the compilation process in a separate thread
+    pub fn start_compilation(&mut self, src: &Path) {
+        if self.is_running {
+            return;
+        }
+
+        let src = src.to_path_buf();
+        let tx = self.result_tx.clone();
+
+        thread::spawn(move || {
+            let result = assemble(&src);
+            tx.send(result)
+                .expect("Failed to send compilation result from worker thread");
+        });
+
+        self.is_running = true;
+    }
+
+    /// Check if compilation is complete and get the result
+    pub fn try_get_result(&mut self) -> Option<Result<Vec<Instruction>, AssembleError>> {
+        if !self.is_running {
+            return None;
+        }
+
+        match self
+            .result_rx
+            .as_ref()
+            .expect("result_rx should be Some while compilation is running")
+            .try_recv()
+        {
+            Ok(result) => {
+                self.is_running = false;
+                Some(result)
+            }
+            Err(mpsc::TryRecvError::Empty) => None,
+            Err(mpsc::TryRecvError::Disconnected) => {
+                self.is_running = false;
+                Some(Err(AssembleError::Generic))
+            }
+        }
+    }
+
+    /// Block until compilation is complete and return the result
+    pub fn wait_for_result(&mut self) -> Result<Vec<Instruction>, AssembleError> {
+        if !self.is_running {
+            return Err(AssembleError::Generic);
+        }
+
+        if let Ok(result) = self
+            .result_rx
+            .take()
+            .expect("result_rx should be Some while waiting for compilation result")
+            .recv()
+        {
+            self.is_running = false;
+            result
+        } else {
+            self.is_running = false;
+            Err(AssembleError::Generic)
+        }
+    }
+}
+
+fn assemble(src: &Path) -> Result<Vec<Instruction>, AssembleError> {
+    let mut modules = HashSet::new();
+    let mut program = Program::new();
+
+    let hash = quick_hash(src);
+
+    if modules.contains(&hash) {
+        return Ok(vec![]);
+    }
+
+    prepare_dependency(src, &mut modules, &mut program)?;
+
+    let mut nodes = program.nodes.clone();
+
+    create_sections(&mut nodes)?;
+    resolve_symbols(&mut nodes)?;
+
+    let instructions = codegen(nodes)?;
+    Ok(instructions)
+}
+
+impl Default for CompilerEngine {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+fn prepare_dependency(
+    path: &Path,
+    modules: &mut HashSet<u64>,
+    program: &mut Program,
+) -> Result<(), AssembleError> {
+    let filename = path
+        .file_name()
+        .and_then(|n| n.to_str())
+        .expect("Failed to get file name from path");
+
+    if let Ok(path) = path.canonicalize() {
+        log(&format!(
+            "{:20} {:20} [{}]",
+            "Building",
+            filename,
+            path.display()
+        ));
+    }
+
+    let src = fs::read_to_string(path)
+        .map_err(|_| AssembleError::InvalidFile(path.to_path_buf()))?;
+    let file_hash = quick_hash(path);
+
+    log(&format!("{:20} {:20}", "Tokenising", filename));
+    let tokens = lexer::lexer(src, file_hash)?;
+
+    log(&format!("{:20} {:20}", "Parsing", filename));
+    let parsed = Parser::parse_nodes(tokens)?;
+
+    log(&format!("{:20} {:20}", "Resolving Deps", filename));
+    // Get the parent directory of the source file to use as the base directory
+    let base_dir = path
+        .parent()
+        .ok_or_else(|| AssembleError::InvalidFile(path.to_path_buf()))?;
+    let mut nodes = expand_pseudo_ops(parsed, file_hash)?;
+    nodes = resolve_dependencies(nodes, base_dir)?;
+
+    let deps = Parser::get_dependencies(&nodes, path)?;
+
+    log(&format!(
+        "{:20} {:20}",
+        "Expanding PseudoInstructions", filename
+    ));
+
+    // add a section instruction
+    nodes.insert(
+        0,
+        node!(None, Opcode::Segment, Token::Immediate(file_hash as u32)),
+    );
+
+    for n in &nodes {
+        println!("{n}");
+    }
+
+    program.add_module(nodes);
+
+    for dep in deps {
+        log(&format!(
+            "{:20} {:20}",
+            "Including",
+            dep.file_name()
+                .and_then(|f| f.to_str())
+                .expect("Dependency path has no file name or is not valid UTF-8")
+        ));
+
+        let dep_hash = quick_hash(&dep);
+        if modules.insert(dep_hash) {
+            prepare_dependency(dep.as_path(), modules, program)?;
+        }
+    }
+
+    Ok(())
+}
+
+#[derive(Debug, Clone)]
+pub enum AssembleError {
+    Generic,
+    UnexpectedEof,
+    InvalidFile(PathBuf),
+    UnexpectedToken(Token, TokenType),
+    InvalidArg,
+    UndefinedSymbol(Symbol),
+    /// Contains the nth element missing from the instruction.
+    MissingArgument(u8),
+}
+
+impl fmt::Display for AssembleError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Generic => write!(f, "Generic error"),
+            Self::UnexpectedToken(tok, expected) => {
+                write!(f, "Unexpected token {tok:?}, expected {expected:?}")
+            }
+            Self::UnexpectedEof => write!(f, "Unexpected end of file"),
+            Self::InvalidFile(path) => write!(f, "Invalid file `{}`", path.display()),
+            Self::InvalidArg => write!(f, "Invalid argument"),
+            Self::UndefinedSymbol(symbol) => {
+                write!(f, "Undefined symbol {symbol}")
+            }
+            Self::MissingArgument(n) => {
+                write!(f, "Missing argument #{n} from instruction arguments.")
+            }
+        }
+    }
+}
+
+fn quick_hash(value: &Path) -> u64 {
+    let mut hasher = DefaultHasher::new();
+    value
+        .canonicalize()
+        .expect("Failed to canonicalize path for quick_hash")
+        .to_str()
+        .hash(&mut hasher);
+
+    hasher.finish()
+}

assembler/src/assembler/model.rs

@@ -0,0 +1,438 @@
+use std::{fmt, str::FromStr};
+
+use common::prelude::Register;
+
+use crate::assembler::AssembleError;
+
+#[derive(Debug, Clone)]
+pub struct Node {
+    pub symbol: Option<Symbol>,
+    pub opcode: Opcode,
+    pub tokens: Vec<Token>,
+}
+
+impl Node {
+    #[must_use]
+    pub const fn new(symbol: Option<Symbol>, opcode: Opcode, tokens: Vec<Token>) -> Self {
+        Self {
+            symbol,
+            opcode,
+            tokens,
+        }
+    }
+
+    #[must_use]
+    pub fn label(&self) -> Option<Symbol> {
+        self.symbol.clone()
+    }
+
+    #[must_use]
+    pub const fn opcode(&self) -> Opcode {
+        self.opcode
+    }
+
+    #[must_use]
+    pub fn args(&self) -> Vec<Token> {
+        self.tokens.clone()
+    }
+
+    pub fn arg(&self, index: usize) -> Result<Token, AssembleError> {
+        self.args()
+            .get(index)
+            .cloned()
+            .ok_or(AssembleError::InvalidArg)
+    }
+}
+
+impl fmt::Display for Node {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        let symbol = self
+            .label()
+            .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",
+            symbol,
+            self.opcode(),
+            args,
+        )
+    }
+}
+
+impl fmt::Display for Symbol {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "{} [ID:{}]", self.name, self.module)
+    }
+}
+
+impl fmt::Display for Module {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match self {
+            Self::Unresolved(name) => write!(f, "{name}"),
+            Self::Resolved(name) => write!(f, "{name}"),
+        }
+    }
+}
+
+impl fmt::Display for Opcode {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match self {
+            Self::Nop => write!(f, "nop"),
+            Self::Mov => write!(f, "mov"),
+            Self::Movs => write!(f, "movs"),
+            Self::Ldb => write!(f, "ldb"),
+            Self::Ldbs => write!(f, "ldbs"),
+            Self::Ldh => write!(f, "ldh"),
+            Self::Ldhs => write!(f, "ldhs"),
+            Self::Ldw => write!(f, "ldw"),
+            Self::Stb => write!(f, "stb"),
+            Self::Sth => write!(f, "sth"),
+            Self::Stw => write!(f, "stw"),
+            Self::Lli => write!(f, "lli"),
+            Self::Lui => write!(f, "lui"),
+            Self::Jmp => write!(f, "jmp"),
+            Self::Jeq => write!(f, "jeq"),
+            Self::Jne => write!(f, "jne"),
+            Self::Jgt => write!(f, "jgt"),
+            Self::Jge => write!(f, "jge"),
+            Self::Jlt => write!(f, "jlt"),
+            Self::Jle => write!(f, "jle"),
+            Self::Cmp => write!(f, "cmp"),
+            Self::Inc => write!(f, "inc"),
+            Self::Dec => write!(f, "dec"),
+            Self::Shl => write!(f, "shl"),
+            Self::Shr => write!(f, "shr"),
+            Self::Add => write!(f, "add"),
+            Self::Sub => write!(f, "sub"),
+            Self::And => write!(f, "and"),
+            Self::Or => write!(f, "or"),
+            Self::Not => write!(f, "not"),
+            Self::Xor => write!(f, "xor"),
+            Self::Nand => write!(f, "nand"),
+            Self::Nor => write!(f, "nor"),
+            Self::Xnor => write!(f, "xnor"),
+            Self::Int => write!(f, "int"),
+            Self::Irt => write!(f, "irt"),
+            Self::Hlt => write!(f, "hlt"),
+            Self::AddI => write!(f, "addi"),
+            Self::SubI => write!(f, "subi"),
+            Self::Db => write!(f, "db"),
+            Self::Dh => write!(f, "dh"),
+            Self::Dw => write!(f, "dw"),
+            Self::Resb => write!(f, "resb"),
+            Self::Resh => write!(f, "resh"),
+            Self::Resw => write!(f, "resw"),
+            Self::Push => write!(f, "push"),
+            Self::Pop => write!(f, "pop"),
+            Self::Lwi => write!(f, "lwi"),
+            Self::Call => write!(f, "call"),
+            Self::Return => write!(f, "return"),
+            Self::Pusha => write!(f, "pusha"),
+            Self::Popa => write!(f, "popa"),
+
+            // meta instructions
+            Self::Include => write!(f, "include"),
+            Self::Data => write!(f, "data"),
+            Self::Segment => write!(f, "[SEGMENT]"),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Eq)]
+pub struct Symbol {
+    pub name: String,
+    pub module: Module,
+}
+
+impl std::hash::Hash for Symbol {
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        self.name.hash(state);
+        self.module.hash(state);
+    }
+}
+
+impl PartialEq for Symbol {
+    fn eq(&self, other: &Self) -> bool {
+        self.name == other.name && self.module == other.module
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub enum Module {
+    Resolved(u64),
+    Unresolved(String),
+}
+
+#[derive(Debug, Clone)]
+pub enum Token {
+    Symbol(Symbol),
+    Register(Register),
+    Immediate(u32),
+    StringLit(String),
+    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,
+    Register,
+    Immediate,
+    StringLit,
+    Opcode,
+}
+
+impl TokenType {
+    #[must_use]
+    pub const fn from_token(token: &Token) -> Self {
+        match token {
+            Token::Symbol(_) => Self::Symbol,
+            Token::Register(_) => Self::Register,
+            Token::Immediate(_) => Self::Immediate,
+            Token::StringLit(_) => Self::StringLit,
+            Token::Opcode(_) => Self::Opcode,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Opcode {
+    // Real instructions (0x00-0x26)
+    Nop,
+    Mov,
+    Movs,
+    Ldb,
+    Ldbs,
+    Ldh,
+    Ldhs,
+    Ldw,
+    Stb,
+    Sth,
+    Stw,
+    Lli,
+    Lui,
+    Jmp,
+    Jeq,
+    Jne,
+    Jgt,
+    Jge,
+    Jlt,
+    Jle,
+    Cmp,
+    Inc,
+    Dec,
+    Shl,
+    Shr,
+    Add,
+    Sub,
+    And,
+    Or,
+    Not,
+    Xor,
+    Nand,
+    Nor,
+    Xnor,
+    Int,
+    Irt,
+    Hlt,
+    AddI,
+    SubI,
+
+    // Pseudo-instructions
+    Db,
+    Dh,
+    Dw,
+    Resb,
+    Resh,
+    Resw,
+    Push,
+    Pop,
+    Pusha,
+    Popa,
+    Lwi,
+    Call,
+    Return,
+
+    // meta instructions (these aren't present in the binary as instructions)
+    Include,
+    Data,
+    Segment,
+}
+
+#[derive(Debug)]
+pub enum OpcodeFromStrError {
+    InvalidRegister(&'static str),
+    InvalidOpcode(String),
+}
+
+impl std::fmt::Display for OpcodeFromStrError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::InvalidRegister(reg) => write!(f, "register does not exist: {reg}"),
+            Self::InvalidOpcode(op) => write!(f, "instruction does not exist: {op}"),
+        }
+    }
+}
+
+impl std::error::Error for OpcodeFromStrError {}
+
+impl FromStr for Opcode {
+    type Err = OpcodeFromStrError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s.to_lowercase().as_str() {
+            "nop" => Ok(Self::Nop),
+            "mov" => Ok(Self::Mov),
+            "movs" => Ok(Self::Movs),
+            "ldb" => Ok(Self::Ldb),
+            "ldbs" => Ok(Self::Ldbs),
+            "ldh" => Ok(Self::Ldh),
+            "ldhs" => Ok(Self::Ldhs),
+            "ldw" => Ok(Self::Ldw),
+            "stb" => Ok(Self::Stb),
+            "sth" => Ok(Self::Sth),
+            "stw" => Ok(Self::Stw),
+            "lli" => Ok(Self::Lli),
+            "lui" => Ok(Self::Lui),
+            "jmp" => Ok(Self::Jmp),
+            "jeq" => Ok(Self::Jeq),
+            "jne" => Ok(Self::Jne),
+            "jgt" => Ok(Self::Jgt),
+            "jge" => Ok(Self::Jge),
+            "jlt" => Ok(Self::Jlt),
+            "jle" => Ok(Self::Jle),
+            "cmp" => Ok(Self::Cmp),
+            "inc" => Ok(Self::Inc),
+            "dec" => Ok(Self::Dec),
+            "shl" => Ok(Self::Shl),
+            "shr" => Ok(Self::Shr),
+            "add" => Ok(Self::Add),
+            "sub" => Ok(Self::Sub),
+            "and" => Ok(Self::And),
+            "or" => Ok(Self::Or),
+            "not" => Ok(Self::Not),
+            "xor" => Ok(Self::Xor),
+            "nand" => Ok(Self::Nand),
+            "nor" => Ok(Self::Nor),
+            "xnor" => Ok(Self::Xnor),
+            "int" => Ok(Self::Int),
+            "irt" => Ok(Self::Irt),
+            "hlt" => Ok(Self::Hlt),
+            "addi" => Ok(Self::AddI),
+            "subi" => Ok(Self::SubI),
+            "db" => Ok(Self::Db),
+            "dh" => Ok(Self::Dh),
+            "dw" => Ok(Self::Dw),
+            "resb" => Ok(Self::Resb),
+            "resh" => Ok(Self::Resh),
+            "resw" => Ok(Self::Resw),
+            "push" => Ok(Self::Push),
+            "pop" => Ok(Self::Pop),
+            "lwi" => Ok(Self::Lwi),
+            "include" => Ok(Self::Include),
+            "call" => Ok(Self::Call),
+            "return" => Ok(Self::Return),
+            "pusha" => Ok(Self::Pusha),
+            "popa" => Ok(Self::Popa),
+            _ => Err(OpcodeFromStrError::InvalidOpcode(s.to_string())),
+        }
+    }
+}
+
+impl Opcode {
+    pub const OPCODES: &[&str] = &[
+        // Real instructions (0x00-0x26)
+        "nop", "mov", "movs", "ldb", "ldbs", "ldh", "ldhs", "ldw", "stb", "sth", "stw",
+        "lli", "lui", "jmp", "jeq", "jne", "jgt", "jge", "jlt", "jle", "cmp", "inc",
+        "dec", "shl", "shr", "add", "sub", "and", "or", "not", "xor", "nand", "nor",
+        "xnor", "int", "irt", "hlt", "addi", "subi", // Pseudo-instructions
+        "db", "dh", "dw", "resb", "resh", "resw", "push", "pop", "lwi", "call", "return",
+        "pusha", "popa", // meta instructions
+        "include",
+    ];
+
+    #[must_use]
+    pub const fn to_opcode_value(&self) -> Option<u8> {
+        match self {
+            Self::Nop => Some(0x00),
+            Self::Mov => Some(0x01),
+            Self::Movs => Some(0x02),
+            Self::Ldb => Some(0x03),
+            Self::Ldbs => Some(0x04),
+            Self::Ldh => Some(0x05),
+            Self::Ldhs => Some(0x06),
+            Self::Ldw => Some(0x07),
+            Self::Stb => Some(0x08),
+            Self::Sth => Some(0x09),
+            Self::Stw => Some(0x0A),
+            Self::Lli => Some(0x0B),
+            Self::Lui => Some(0x0C),
+            Self::Jmp => Some(0x0D),
+            Self::Jeq => Some(0x0E),
+            Self::Jne => Some(0x0F),
+            Self::Jgt => Some(0x10),
+            Self::Jge => Some(0x11),
+            Self::Jlt => Some(0x12),
+            Self::Jle => Some(0x13),
+            Self::Cmp => Some(0x14),
+            Self::Inc => Some(0x15),
+            Self::Dec => Some(0x16),
+            Self::Shl => Some(0x17),
+            Self::Shr => Some(0x18),
+            Self::Add => Some(0x19),
+            Self::Sub => Some(0x1A),
+            Self::And => Some(0x1B),
+            Self::Or => Some(0x1C),
+            Self::Not => Some(0x1D),
+            Self::Xor => Some(0x1E),
+            Self::Nand => Some(0x1F),
+            Self::Nor => Some(0x20),
+            Self::Xnor => Some(0x21),
+            Self::Int => Some(0x22),
+            Self::Irt => Some(0x23),
+            Self::Hlt => Some(0x24),
+            Self::AddI => Some(0x25),
+            Self::SubI => Some(0x26),
+            Self::Segment => Some(0x27),
+
+            // Pseudo-instructions don't have opcode values
+            _ => None,
+        }
+    }
+
+    #[must_use]
+    pub const fn is_pseudo_instruction(&self) -> bool {
+        matches!(
+            self,
+            Self::Db
+                | Self::Dh
+                | Self::Dw
+                | Self::Resb
+                | Self::Resh
+                | Self::Resw
+                | Self::Push
+                | Self::Pop
+                | Self::Lwi
+        )
+    }
+}

assembler/src/assembler/parser.rs

@@ -0,0 +1,368 @@
+use std::path::{Path, PathBuf};
+
+use crate::{assembler::AssembleError, expect_token, expect_type, node};
+
+use crate::assembler::model::{Node, Opcode, Token};
+use common::prelude::*;
+
+pub struct Parser {
+    tokens: Vec<Token>,
+    nodes: Vec<Node>,
+}
+
+#[derive(Debug)]
+pub struct Program {
+    pub nodes: Vec<Node>,
+}
+
+impl Program {
+    #[must_use]
+    pub const fn new() -> Self {
+        Self { nodes: vec![] }
+    }
+
+    pub fn add_module(&mut self, module: Vec<Node>) {
+        self.nodes.extend(module);
+    }
+
+    pub fn parser(&mut self) -> Parser {
+        Parser {
+            tokens: vec![],
+            nodes: self.nodes.clone(),
+        }
+    }
+}
+
+impl Default for Program {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Parser {
+    pub fn parse_nodes(tokens: Vec<Token>) -> Result<Vec<Node>, AssembleError> {
+        let mut self_ = Self {
+            tokens: tokens.into_iter().rev().collect(),
+            nodes: vec![],
+        };
+
+        while !self_.tokens.is_empty() {
+            let ins = self_.parse_instruction()?;
+            self_.nodes.push(ins);
+        }
+
+        Ok(self_.nodes.clone())
+    }
+
+    pub fn get_dependencies(
+        nodes: &Vec<Node>,
+        source_path: &Path,
+    ) -> Result<Vec<PathBuf>, AssembleError> {
+        let mut dependencies = Vec::new();
+        // Get the parent directory of the source file to use as the base directory
+        let base_dir = source_path
+            .parent()
+            .ok_or_else(|| AssembleError::InvalidFile(source_path.to_path_buf()))?;
+
+        for node in nodes {
+            if node.opcode() == Opcode::Include {
+                let path_str = expect_token!(
+                    node.args().get(1).ok_or(AssembleError::Generic)?,
+                    StringLit
+                )?;
+                let path = PathBuf::from(path_str);
+
+                // If the path is not absolute, make it relative to the base directory
+                let full_path = if path.is_absolute() {
+                    path
+                } else {
+                    base_dir.join(path)
+                };
+
+                dependencies.push(full_path);
+            }
+        }
+        Ok(dependencies)
+    }
+
+    #[expect(clippy::too_many_lines, clippy::cognitive_complexity)]
+    fn parse_instruction(&mut self) -> Result<Node, AssembleError> {
+        if self.tokens.is_empty() {
+            unreachable!();
+        }
+
+        // check if the Node starts with a label
+        let label = expect_token!(self.peek_next()?, Symbol).ok();
+        if label.is_some() {
+            self.tokens.pop();
+        }
+
+        let opcode = expect_token!(self.next()?, Opcode)?;
+        let args: Vec<Token>;
+
+        match opcode {
+            // R-type instructions
+            Opcode::Mov | Opcode::Movs => {
+                let reg1 = expect_type!(self.next()?, Register, Symbol)?;
+                let reg2 = expect_type!(self.next()?, Register, Symbol)?;
+                args = vec![reg1, reg2];
+            }
+
+            Opcode::Ldb | Opcode::Ldbs | Opcode::Ldh | Opcode::Ldhs | Opcode::Ldw => {
+                let base = expect_type!(self.next()?, Register, Symbol)?;
+                let dest = expect_type!(self.next()?, Register)?;
+
+                let mut offset = Token::Immediate(0);
+                if let Ok(next) = self.peek_next()
+                    && expect_type!(next, Immediate).is_ok() {
+                        offset = self.next()?;
+                    }
+
+                args = vec![base, dest, offset];
+            }
+            Opcode::Stb | Opcode::Sth | Opcode::Stw => {
+                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()
+                    && expect_type!(next, Immediate).is_ok() {
+                        offset = self.next()?;
+                    }
+                args = vec![base, dest, offset];
+            }
+
+            Opcode::Add
+            | Opcode::Sub
+            | Opcode::And
+            | Opcode::Or
+            | Opcode::Xor
+            | Opcode::Nand
+            | Opcode::Nor
+            | Opcode::Xnor => {
+                let src1 = expect_type!(self.next()?, Register, Symbol)?;
+                let src2 = expect_type!(self.next()?, Register, Symbol)?;
+                let dest = expect_type!(self.next()?, Register, Symbol)?;
+                args = vec![src1, src2, dest];
+            }
+
+            Opcode::Not | Opcode::Cmp => {
+                let reg1 = expect_type!(self.next()?, Register, Symbol)?;
+                let reg2 = expect_type!(self.next()?, Register, Symbol)?;
+                args = vec![reg1, reg2];
+            }
+
+            Opcode::Shl | Opcode::Shr => {
+                let reg = expect_type!(self.next()?, Register, Symbol)?;
+                let num = expect_type!(self.next()?, Immediate)?;
+                args = vec![reg, num];
+            }
+
+            Opcode::Inc | Opcode::Dec => {
+                let reg = expect_type!(self.next()?, Register, Symbol)?;
+                args = vec![reg];
+            }
+
+            Opcode::Include => {
+                let mod_name = expect_type!(self.next()?, Symbol)?;
+                let path = expect_type!(self.next()?, StringLit)?;
+                args = vec![mod_name, path];
+            }
+
+            // J-type instructions
+            Opcode::Jmp
+            | Opcode::Jeq
+            | Opcode::Jne
+            | Opcode::Jgt
+            | Opcode::Jge
+            | Opcode::Jlt
+            | Opcode::Jle => {
+                let imm = expect_type!(self.next()?, Immediate, Symbol)?;
+                let offset = match self.peek_next() {
+                    Ok(token) => {
+                        if expect_type!(token, Register).is_ok() {
+                            self.next()?
+                        } else {
+                            Token::Register(Register::Zero)
+                        }
+                    }
+                    Err(_) => Token::Register(Register::Zero),
+                };
+                args = vec![imm, offset];
+            }
+
+            Opcode::Call => {
+                let addr = expect_type!(self.next()?, Symbol)?;
+                args = vec![addr];
+            }
+
+            // I-type instructions
+            Opcode::Lui | Opcode::Lli | Opcode::Lwi => {
+                let imm = expect_type!(self.next()?, Immediate, Symbol)?;
+                let reg = expect_type!(self.next()?, Register)?;
+                args = vec![imm, reg];
+            }
+
+            // Immediate Arithmetic
+            Opcode::AddI | Opcode::SubI => {
+                let reg = expect_type!(self.next()?, Register)?;
+                let imm = expect_type!(self.next()?, Immediate)?;
+                let reg2 = if expect_type!(self.peek_next()?, Register).is_ok() {
+                    self.next()?
+                } else {
+                    reg.clone()
+                };
+                args = vec![reg, imm, reg2];
+            }
+
+            // D-type pseudoinstructions (data definition)
+            Opcode::Resb | Opcode::Resh | Opcode::Resw => {
+                let name = expect_type!(self.next()?, Symbol)?;
+                let num = expect_type!(self.next()?, Immediate)?;
+                args = vec![name, num];
+            }
+
+            Opcode::Db | Opcode::Dh | Opcode::Dw => {
+                args = self.parse_data_definition(opcode)?;
+            }
+
+            // E-type pseudoinstructions (stack operations)
+            Opcode::Push | Opcode::Pop => {
+                let reg = expect_type!(self.next()?, Register, Symbol)?;
+                args = vec![reg];
+            }
+
+            Opcode::Pusha | Opcode::Popa => {
+                let count =
+                    expect_type!(self.next()?, Immediate).unwrap_or(Token::Immediate(8));
+                args = vec![count];
+            }
+
+            // Special instructions
+            Opcode::Int => {
+                let val = expect_type!(self.next()?, Immediate)?;
+                args = vec![val];
+            }
+
+            // Instructions with no arguments
+            Opcode::Hlt | Opcode::Nop | Opcode::Irt | Opcode::Return => {
+                args = vec![];
+            }
+
+            Opcode::Data | Opcode::Segment => {
+                return Err(AssembleError::Generic);
+            }
+        }
+
+        Ok(node!(label, opcode, args: args))
+    }
+
+    fn parse_data_definition(
+        &mut self,
+        opcode: Opcode,
+    ) -> Result<Vec<Token>, AssembleError> {
+        let mut values = Vec::new();
+
+        let name = expect_type!(self.next()?, Symbol)?;
+        values.push(name);
+
+        match opcode {
+            Opcode::Db => {
+                // db can take string literals or u8 immediates
+                while !self.tokens.is_empty() {
+                    let token = self
+                        .tokens
+                        .last()
+                        .expect("Expected a token for data definition, but found none");
+
+                    match token {
+                        Token::StringLit(_) => {
+                            values.push(self.tokens.pop().expect(
+                                "Expected a token for data definition, but found none",
+                            ));
+                        }
+                        Token::Immediate(val) if u8::try_from(*val).is_ok() => {
+                            values.push(self.tokens.pop().expect(
+                                "Expected a token for data definition, but found none",
+                            ));
+                        }
+                        _ => break,
+                    }
+                }
+            }
+
+            Opcode::Dh => {
+                // dh can take u16 immediates
+                while !self.tokens.is_empty() {
+                    let token = self
+                        .tokens
+                        .last()
+                        .expect("Expected a token for data definition, but found none");
+
+                    match token {
+                        Token::StringLit(_) => {
+                            values.push(self.tokens.pop().expect(
+                                "Expected a token for data definition, but found none",
+                            ));
+                        }
+                        Token::Immediate(val) if u16::try_from(*val).is_ok() => {
+                            values.push(self.tokens.pop().expect(
+                                "Expected a token for data definition, but found none",
+                            ));
+                        }
+                        _ => break,
+                    }
+                }
+            }
+
+            Opcode::Dw => {
+                // dw can take u32 immediates
+                while !self.tokens.is_empty() {
+                    match self
+                        .tokens
+                        .last()
+                        .expect("Expected a token for data definition, but found none")
+                    {
+                        Token::StringLit(_) => {
+                            values.push(self.tokens.pop().expect(
+                                "Expected a token for data definition, but found none",
+                            ));
+                        }
+                        Token::Immediate(val) => {
+                            values.push(self.tokens.pop().expect(
+                                "Expected a token for data definition, but found none",
+                            ));
+                        }
+                        _ => break,
+                    }
+                }
+            }
+
+            _ => unreachable!(),
+        }
+
+        Ok(values)
+    }
+
+    fn next(&mut self) -> Result<Token, AssembleError> {
+        if self.tokens.is_empty() {
+            Err(AssembleError::UnexpectedEof)
+        } else {
+            Ok(self
+                .tokens
+                .pop()
+                .expect("tokens vector was unexpectedly empty in next()"))
+        }
+    }
+
+    fn peek_next(&self) -> Result<Token, AssembleError> {
+        if self.tokens.is_empty() {
+            Err(AssembleError::UnexpectedEof)
+        } else {
+            Ok(self
+                .tokens
+                .last()
+                .expect("peek_next called on empty tokens vector")
+                .clone())
+        }
+    }
+}

assembler/src/assembler/resolver.rs

@@ -0,0 +1,156 @@
+use std::{
+    collections::HashMap,
+    fs::canonicalize,
+    path::{Path, PathBuf},
+};
+
+use common::prelude::Register;
+
+use crate::assembler::quick_hash;
+use crate::assembler::{
+    log,
+    model::{Module, Node, Opcode, Symbol, Token},
+};
+use crate::{assembler::AssembleError, node};
+
+pub fn resolve_symbols(nodes: &mut [Node]) -> Result<(), AssembleError> {
+    let symbol_table = generate_symbol_table(nodes);
+
+    for node in nodes.iter_mut() {
+        match node.opcode() {
+            Opcode::Jmp
+            | Opcode::Jeq
+            | Opcode::Jne
+            | Opcode::Jgt
+            | Opcode::Jge
+            | Opcode::Jlt
+            | Opcode::Jle
+            | Opcode::Lli
+            | Opcode::Lui => {
+                if let Token::Symbol(symbol) = node
+                    .arg(0)
+                    .expect("Expected argument 0 for jump-like opcode")
+                {
+                    if let Some(address) = symbol_table.get(&symbol) {
+                        node.tokens[0] = Token::Immediate(*address);
+                    } else {
+                        return Err(AssembleError::UndefinedSymbol(symbol));
+                    }
+                }
+            }
+            _ => (),
+        }
+    }
+
+    Ok(())
+}
+
+fn generate_symbol_table(nodes: &[Node]) -> HashMap<Symbol, u32> {
+    let mut table = HashMap::new();
+
+    for (i, node) in nodes.iter().enumerate() {
+        if let Some(symbol) = node.label() {
+            table.insert(symbol, 4 * i as u32);
+        }
+    }
+
+    table
+}
+
+pub fn resolve_dependencies(
+    mut nodes: Vec<Node>,
+    base_dir: &Path,
+) -> Result<Vec<Node>, AssembleError> {
+    // First we get a list of imports.
+    let mut dependencies = Vec::new();
+    for node in &nodes {
+        if node.opcode() == Opcode::Include {
+            // we want the path, and the name
+            let name = if let Token::Symbol(name) = node
+                .arg(0)
+                .expect("Expected argument #0 for Include directive.")
+            {
+                name.name.clone()
+            } else {
+                unreachable!()
+            }; //node.2.get(0).unwrap()
+
+            let Ok(Token::StringLit(path)) = node.arg(1) else {
+                unreachable!()
+            };
+
+            let full_path = base_dir.join(path);
+            let canonical_path = full_path
+                .canonicalize()
+                .map_err(|_| AssembleError::InvalidFile(full_path.clone()))?;
+
+            let hash = quick_hash(&canonical_path);
+
+            dependencies.push((name, hash));
+        }
+    }
+
+    let mut changes = Vec::<(u32, u32, Symbol)>::new();
+    // now we resolve the symbols on all the nodes
+    // we need to check all operands for unresolved signals
+    for (i, node) in nodes.clone().iter().enumerate() {
+        let Node {
+            tokens: operands, ..
+        } = node;
+        for (j, token) in operands.iter().enumerate() {
+            if let Token::Symbol(symbol) = token {
+                for d in &dependencies {
+                    if let Module::Unresolved(name) = symbol.module.clone() {
+                        if name != d.0 {
+                            continue;
+                        }
+
+                        let symbol = Symbol {
+                            name: symbol.name.clone(),
+                            module: Module::Resolved(d.1),
+                        };
+                        changes.push((i as u32, j as u32, symbol));
+                    }
+                }
+            }
+        }
+    }
+
+    for (i, j, symbol) in changes {
+        nodes[i as usize].tokens[j as usize] = Token::Symbol(symbol);
+    }
+
+    Ok(nodes)
+}
+
+pub fn create_sections(nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
+    let mut res = Vec::<Node>::with_capacity(nodes.len());
+
+    res.push(node!(None, Opcode::Segment, Token::Immediate(0)));
+
+    for n in nodes.iter() {
+        if n.opcode() == Opcode::Data {
+            res.push(n.clone());
+        }
+    }
+
+    let start = res.len() + 1;
+    res.insert(
+        0,
+        node!(
+            None,
+            Opcode::Jmp,
+            Token::Immediate(start as u32 * 4),
+            Token::Register(Register::Zero)
+        ),
+    );
+    for n in nodes.iter() {
+        if !matches!(n.opcode(), Opcode::Data | Opcode::Include) {
+            res.push(n.clone());
+        }
+    }
+
+    *nodes = res;
+
+    Ok(())
+}

assembler/src/lib.rs

@@ -0,0 +1,28 @@
+#![deny(
+    clippy::unwrap_used,
+    clippy::nursery,
+    clippy::perf,
+    clippy::pedantic,
+    clippy::complexity
+)]
+#![allow(
+    clippy::cast_possible_truncation,
+    clippy::missing_panics_doc,
+    clippy::missing_errors_doc,
+    clippy::match_wildcard_for_single_variants
+)]
+
+pub mod assembler;
+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 num_cpus as _;
+use threadpool as _;

assembler/src/main.rs

@@ -0,0 +1,64 @@
+use common as _;
+use num_cpus as _;
+use threadpool as _;
+
+use assembler::{
+    prelude::*,
+    tooling::{brainf, project},
+};
+use std::{fs, io::Write, path::PathBuf};
+
+fn main() {
+    // Parse command line arguments
+    let args: Vec<String> = std::env::args().collect();
+
+    if args.len() == 2 && args[1] == "init" {
+        project::tool_libcreate();
+        std::process::exit(0);
+    }
+
+    if args.len() == 2 && args[1] == "brainf" {
+        let src = PathBuf::from("brainf.bf");
+        let result = brainf::build(&src);
+
+        let mut file = match fs::File::create("brainf.dsb") {
+            Err(e) => {
+                eprintln!("Failed to create output file: {e}");
+                std::process::exit(1);
+            }
+            Ok(file) => file,
+        };
+
+        for instruction in result {
+            if let Err(e) = file.write(&instruction.encode().to_be_bytes()) {
+                eprintln!("Failed to write to output file: {e}");
+                std::process::exit(1);
+            }
+        }
+
+        std::process::exit(0);
+    }
+
+    if args.len() != 5 || args[1] != "-i" || args[3] != "-o" {
+        eprintln!("Usage: {} -i input_path -o output_path", args[0]);
+        std::process::exit(1);
+    }
+
+    let input_path = &args[2];
+    let output_path = &args[4];
+    let src = PathBuf::from(input_path);
+
+    // 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/brainf.rs

@@ -0,0 +1,280 @@
+use std::{fs, path::Path};
+
+use common::prelude::*;
+
+use crate::{
+    assembler::{
+        Module, Node, Opcode, Symbol, Token, codegen, create_sections, expand_pseudo_ops,
+        resolve_symbols,
+    },
+    node,
+};
+
+#[must_use]
+pub fn build(src: &Path) -> Vec<Instruction> {
+    let src = fs::read_to_string(src).expect("Failed to read source file");
+    let mut nodes = parse(&src);
+
+    // we need to expand pseudoinstructions etc now
+    nodes = expand_pseudo_ops(nodes, 0).expect("Failed to expand pseudo-operations");
+
+    create_sections(&mut nodes).expect("Failed to create sections");
+
+    for n in &nodes {
+        println!("{n}");
+    }
+
+    resolve_symbols(&mut nodes).expect("Failed to resolve symbols");
+
+    codegen(nodes).expect("Failed to generate code from nodes")
+}
+
+#[must_use]
+#[expect(clippy::too_many_lines)]
+pub fn parse(src: &str) -> Vec<Node> {
+    let stack = Token::Immediate(0x10000);
+    let acc = Token::Register(Register::Acc);
+    let rga = Token::Register(Register::Rga);
+
+    let bpr = Token::Register(Register::Bpr);
+    let spr = Token::Register(Register::Spr);
+    let mut nodes = Vec::<Node>::new();
+
+    // Define symbols
+    let print_start = Symbol {
+        name: "print".to_string(),
+        module: Module::Resolved(0),
+    };
+
+    let tokens = lex(src);
+
+    // let _id = 0;
+    let mut idstack = Vec::<u32>::new();
+
+    nodes.extend(vec![
+        // set up a stack
+        node!(None, Opcode::Lwi, stack, bpr),
+        node!(None, Opcode::Mov, bpr, spr),
+        // set up the data pointer
+        node!(
+            Some(Symbol {
+                name: "main".to_string(),
+                module: Module::Resolved(0)
+            }),
+            Opcode::Lwi,
+            Token::Immediate(0x30000),
+            rga
+        ),
+    ]);
+
+    for (id, tok) in tokens.iter().enumerate() {
+        match tok {
+            BfToken::Inc => {
+                // inc acc
+                nodes.extend(vec![node!(None, Opcode::Inc, acc)]);
+            }
+            BfToken::Dec => {
+                // dec acc
+                nodes.extend(vec![node!(None, Opcode::Dec, acc)]);
+            }
+            BfToken::IncPtr => {
+                // stb acc, rga
+                // add rga, 4
+                // ldb rga, acc
+                nodes.extend(vec![
+                    node!(None, Opcode::Stw, acc, rga, 0),
+                    node!(None, Opcode::AddI, rga, 4, rga),
+                    node!(None, Opcode::Ldw, rga, acc, 0),
+                ]);
+            }
+            BfToken::DecPtr => {
+                // stb acc, rga
+                // sub rga, 4
+                // ldb rga, acc
+                nodes.extend(vec![
+                    node!(None, Opcode::Stw, acc, rga, 0),
+                    node!(None, Opcode::SubI, rga, 4, rga),
+                    node!(None, Opcode::Ldw, rga, acc, 0),
+                ]);
+            }
+            BfToken::Out => {
+                // push rga
+                // call print
+                // pop zero
+                nodes.extend(vec![
+                    node!(None, Opcode::Push, acc),
+                    node!(None, Opcode::Call, Token::Symbol(print_start.clone())),
+                    node!(None, Opcode::Pop, Token::Register(Register::Zero)),
+                ]);
+            }
+            BfToken::In => {
+                // Read a byte from input and store it at the current data pointer
+                // Assuming we have an input function mapped to a specific memory location or I/O port
+                nodes.extend(vec![
+                    // Read input (assuming input is mapped to memory address 0x40000)
+                    node!(None, Opcode::Ldw, Token::Immediate(0x40000), acc, 0),
+                    // Store the input byte at the current data pointer
+                ]);
+            }
+            BfToken::Forward => {
+                // Start of loop [
+                let loop_start = format!("loop_start_{id}");
+                let loop_end = format!("loop_end_{id}");
+
+                // Push the current position for the matching ]
+                idstack.push(id as u32);
+
+                // Load current cell value and check if zero
+                nodes.extend(vec![
+                    // Compare with zero
+                    node!(None, Opcode::Cmp, acc, Token::Register(Register::Zero)),
+                    // If zero, jump to end of loop
+                    node!(
+                        None,
+                        Opcode::Jeq,
+                        Token::Symbol(Symbol {
+                            name: loop_end,
+                            module: Module::Resolved(0),
+                        }),
+                        Token::Register(Register::Zero)
+                    ),
+                ]);
+
+                // Add label for loop start
+                nodes.push(node!(
+                    Some(Symbol {
+                        name: loop_start,
+                        module: Module::Resolved(0),
+                    }),
+                    Opcode::Nop
+                ));
+            }
+            BfToken::Back => {
+                // End of loop ]
+                if let Some(start_id) = idstack.pop() {
+                    let loop_start = format!("loop_start_{start_id}");
+                    let loop_end = format!("loop_end_{start_id}");
+
+                    // Jump back to the start of the loop
+                    nodes.extend(vec![
+                        // Compare with zero
+                        node!(None, Opcode::Cmp, acc, Token::Register(Register::Zero)),
+                        // If not zero, jump back to start of loop
+                        node!(
+                            None,
+                            Opcode::Jne,
+                            Token::Symbol(Symbol {
+                                name: loop_start,
+                                module: Module::Resolved(0),
+                            }),
+                            Token::Register(Register::Zero)
+                        ),
+                        // Add label for loop end
+                        node!(
+                            Some(Symbol {
+                                name: loop_end,
+                                module: Module::Resolved(0),
+                            }),
+                            Opcode::Nop
+                        ),
+                    ]);
+                } else {
+                    // Unmatched closing bracket - could add error handling here
+                    eprintln!("Warning: Unmatched ']' at position {id}");
+                }
+            }
+        }
+    }
+
+    nodes.push(node!(None, Opcode::Hlt));
+
+    insert_lib(&mut nodes);
+
+    nodes
+}
+
+fn insert_lib(nodes: &mut Vec<Node>) {
+    let bpr = Token::Register(Register::Bpr);
+    let spr = Token::Register(Register::Spr);
+    let rg0 = Token::Register(Register::Rg0);
+    let rg1 = Token::Register(Register::Rg1);
+
+    let print_start = Symbol {
+        name: "print".to_string(),
+        module: Module::Resolved(0),
+    };
+    let current = Symbol {
+        name: "current".to_string(),
+        module: Module::Resolved(0),
+    };
+    // set up the program framework.
+    nodes.extend(vec![
+        // set display to 0x20000
+        node!(
+            None,
+            Opcode::Dw,
+            Token::Symbol(current.clone()),
+            Token::Immediate(0x20000)
+        ),
+        // print function
+        // initialisation
+        node!(Some(print_start), Opcode::Push, bpr),
+        node!(None, Opcode::Mov, spr, bpr),
+        // function body
+        node!(None, Opcode::Ldw, bpr, rg0, Token::Immediate(8)),
+        node!(
+            None,
+            Opcode::Ldw,
+            Token::Symbol(current.clone()), // Load address of current
+            rg1,
+            Token::Immediate(0)
+        ),
+        node!(None, Opcode::Stb, rg0, rg1, Token::Immediate(0)),
+        node!(None, Opcode::AddI, rg1, Token::Immediate(1), rg1),
+        // function return according to spec.
+        node!(
+            None,
+            Opcode::Stw,
+            rg1,
+            Token::Symbol(current), // Store back to current
+            Token::Immediate(0)
+        ),
+        node!(None, Opcode::Mov, bpr, spr),
+        node!(None, Opcode::Pop, bpr),
+        node!(None, Opcode::Return),
+    ]);
+}
+
+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) -> Symbol {
+    Symbol {
+        name: format!("label_{id}"),
+        module: Module::Resolved(0),
+    }
+}

assembler/src/tooling/mod.rs

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

assembler/src/tooling/project.rs

@@ -0,0 +1,93 @@
+use crate::util::input;
+
+pub fn tool_libcreate() {
+    let mut ptype: String;
+    loop {
+        ptype = input("Enter project type (bin|lib)");
+        if ptype == "bin" || ptype == "lib" {
+            break;
+        }
+    }
+
+    let project_name = input("Enter project name");
+    let project_path = input("Enter Directory to create project in");
+
+    println!("[ Creating new {ptype} project {project_name} in {project_path} ]");
+
+    let template = match ptype.as_str() {
+        "bin" => generate_bin_template(&project_name),
+        "lib" => generate_lib_template(&project_name),
+        _ => panic!("Invalid project type"),
+    };
+
+    let path = format!("{project_path}/{project_name}.dsa");
+    std::fs::write(path, template).expect("Unable to write file");
+}
+
+fn generate_lib_template(module_name: &str) -> String {
+    format!(
+        r#"// {module_name}.dsa
+// usage:
+//
+// include {module_name} "<relative path>"
+//
+// usage for {module_name}_main:
+// push (arg1)
+// push (arg0)
+// call {module_name}::{module_name}_main
+// pop (arg0)
+// pop (arg1)
+
+// Example data declarations
+// dw example_data: 0x0000
+
+// Main function template
+{module_name}_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 generate_bin_template(project_name: &str) -> String {
+    format!(
+        r#"// {project_name}.dsa
+// Binary executable project
+
+// Example Dependencies
+// include math "libs/math/math.dsa"
+include print "../resources/dsa/print.dsa"
+
+// Data declarations - It is best practice to include these before any code!
+dw message: "Hello from {project_name}.dsa!" // strings are automatically null terminated!
+
+// Program entry point - execution starts at the first non-definition line
+{project_name}:
+    // Getting started: Calling external functions
+    // Syntax: push (arg1), push (arg0), call namespace::function, pop (arg0), pop (arg1)
+    
+    // Example: Print a string (if print library is included)
+    ldw message, rg0    // load address of message
+    push rg0            // push argument
+    call print::print   // call the print function
+    pop rg0             // clean up stack
+
+    // Program must end with halt instruction
+    halt
+"#,
+    )
+}

assembler/src/util/logging.rs

@@ -0,0 +1,108 @@
+#![allow(dead_code)]
+#![allow(unused)]
+use std::{fmt, sync::mpsc::Sender};
+
+pub struct Logger {}
+
+impl Logger {
+    pub const fn new() -> Self {
+        Self {}
+    }
+
+    pub fn log(&self, message: &str) {
+        _ = self;
+        println!("\x1b[32mINFO:\x1b[0m {message}");
+    }
+}
+
+// #[derive(Debug)]=
+// pub struct Logger {
+//     pub sender: Sender<Entry>,
+// }
+
+// impl Logger {
+//     pub fn new(sender: Sender<Entry>) -> Self {
+//         Self { sender }
+//     }
+
+//     pub fn debug<T: fmt::Display>(&self, message: T) {
+//         self.sender
+//             .send(Entry {
+//                 etype: EntryType::Debug,
+//                 message: message.to_string(),
+//             })
+//             .unwrap();
+//     }
+
+//     pub fn info<T: fmt::Display>(&self, message: T) {
+//         self.sender
+//             .send(Entry {
+//                 etype: EntryType::Info,
+//                 message: message.to_string(),
+//             })
+//             .unwrap();
+//     }
+
+//     pub fn warn<T: fmt::Display>(&self, message: T) {
+//         self.sender
+//             .send(Entry {
+//                 etype: EntryType::Warn,
+//                 message: message.to_string(),
+//             })
+//             .unwrap();
+//     }
+
+//     pub fn error<T: fmt::Display>(&self, message: T) {
+//         self.sender
+//             .send(Entry {
+//                 etype: EntryType::Error,
+//                 message: message.to_string(),
+//             })
+//             .unwrap();
+//     }
+
+//     pub fn fatal<T: fmt::Display>(&self, message: T) {
+//         self.sender
+//             .send(Entry {
+//                 etype: EntryType::Fatal,
+//                 message: message.to_string(),
+//             })
+//             .unwrap();
+//     }
+// }
+
+pub struct Entry {
+    etype: EntryType,
+    pub message: String,
+}
+
+#[derive(Copy, Clone, Eq, PartialEq)]
+enum EntryType {
+    Debug,
+    Info,
+    Warn,
+    Error,
+    Fatal,
+}
+
+impl fmt::Display for EntryType {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "{:<5}",
+            match self {
+                Self::Debug => "DEBUG",
+                Self::Info => "INFO",
+                Self::Warn => "WARN",
+                Self::Error => "ERROR",
+                Self::Fatal => "FATAL",
+            }
+        )
+    }
+}
+
+impl fmt::Display for Entry {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}: {}", self.etype, self.message)
+    }
+}

assembler/src/util/mod.rs

@@ -0,0 +1,13 @@
+pub mod logging;
+
+use std::io::Write;
+
+pub fn input(prompt: &str) -> String {
+    print!("{prompt}\n > ");
+    std::io::stdout().flush().expect("Failed to flush stdout");
+    let mut input = String::new();
+    std::io::stdin()
+        .read_line(&mut input)
+        .expect("Failed to read line from stdin");
+    input.trim().to_string()
+}

common/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "common"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+
+[dependencies]

common/src/instructions.rs

@@ -0,0 +1,517 @@
+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 {
+    // 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,
+        }
+    }
+}
+
+// TODO: This should be TryFrom.
+impl From<u8> for Interrupt {
+    #[allow(unreachable_code)]
+    fn from(code: u8) -> Self {
+        match code {
+            0 => Self::Breakpoint,
+            1 => Self::HardFault,
+            _ => Self::Software(code),
+        }
+    }
+}
+
+/// Whether an [`Instruction`] is an I-type or R-type instruction.
+#[non_exhaustive]
+pub enum InstructionType {
+    Register,
+    Immediate,
+}
+
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum Register {
+    // general purpose registers
+    Rg0,
+    Rg1,
+    Rg2,
+    Rg3,
+    Rg4,
+    Rg5,
+    Rg6,
+    Rg7,
+    Rg8,
+    Rg9,
+    Rga,
+    Rgb,
+    Rgc,
+    Rgd,
+    Rge,
+    Rgf,
+
+    // special purpose registers
+    Acc,
+    Spr,
+    Bpr,
+    Ret,
+    Idr,
+    Mmr,
+    Zero,
+    NoReg,
+
+    // system registers - can't be written to by instructions.
+    Mar,
+    Mdr,
+    Sts,
+    Cir,
+    Pcx,
+}
+
+impl Register {
+    // 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,
+            Self::Rg1,
+            Self::Rg2,
+            Self::Rg3,
+            Self::Rg4,
+            Self::Rg5,
+            Self::Rg6,
+            Self::Rg7,
+            Self::Rg8,
+            Self::Rg9,
+            Self::Rga,
+            Self::Rgb,
+            Self::Rgc,
+            Self::Rgd,
+            Self::Rge,
+            Self::Rgf,
+        ]
+    }
+}
+
+impl Default for Register {
+    fn default() -> Self {
+        Self::NoReg
+    }
+}
+
+impl TryFrom<u8> for Register {
+    type Error = RegisterParseError;
+
+    fn try_from(idx: u8) -> Result<Self, Self::Error> {
+        if idx > 0x1C {
+            return Err(RegisterParseError::InvalidIndex(idx));
+        }
+
+        Ok(match idx {
+            // System registers are not indexable in the reg file so they cannot be
+            // modified by instructions.
+            0x0 => Self::Rg0,
+            0x1 => Self::Rg1,
+            0x2 => Self::Rg2,
+            0x3 => Self::Rg3,
+            0x4 => Self::Rg4,
+            0x5 => Self::Rg5,
+            0x6 => Self::Rg6,
+            0x7 => Self::Rg7,
+            0x8 => Self::Rg8,
+            0x9 => Self::Rg9,
+            0xA => Self::Rga,
+            0xB => Self::Rgb,
+            0xC => Self::Rgc,
+            0xD => Self::Rgd,
+            0xE => Self::Rge,
+            0xF => Self::Rgf,
+            0x10 => Self::Acc,
+            0x11 => Self::Spr,
+            0x12 => Self::Bpr,
+            0x13 => Self::Ret,
+            0x14 => Self::Idr,
+            0x15 => Self::Mmr,
+            0x16 => Self::Zero,
+            0x17 => Self::NoReg,
+            0x18 => Self::Mar,
+            0x19 => Self::Mdr,
+            0x1A => Self::Sts,
+            0x1B => Self::Cir,
+            0x1C => Self::Pcx,
+            _ => unreachable!("This is already checked for in top `if` branch."),
+        })
+    }
+}
+
+impl TryFrom<&str> for Register {
+    type Error = RegisterParseError;
+
+    fn try_from(value: &str) -> Result<Self, Self::Error> {
+        match value.to_lowercase().as_str() {
+            "rg0" => Ok(Self::Rg0),
+            "rg1" => Ok(Self::Rg1),
+            "rg2" => Ok(Self::Rg2),
+            "rg3" => Ok(Self::Rg3),
+            "rg4" => Ok(Self::Rg4),
+            "rg5" => Ok(Self::Rg5),
+            "rg6" => Ok(Self::Rg6),
+            "rg7" => Ok(Self::Rg7),
+            "rg8" => Ok(Self::Rg8),
+            "rg9" => Ok(Self::Rg9),
+            "rga" => Ok(Self::Rga),
+            "rgb" => Ok(Self::Rgb),
+            "rgc" => Ok(Self::Rgc),
+            "rgd" => Ok(Self::Rgd),
+            "rge" => Ok(Self::Rge),
+            "rgf" => Ok(Self::Rgf),
+            "acc" => Ok(Self::Acc),
+            "spr" => Ok(Self::Spr),
+            "bpr" => Ok(Self::Bpr),
+            "ret" => Ok(Self::Ret),
+            "idr" => Ok(Self::Idr),
+            "mmr" => Ok(Self::Mmr),
+            "zero" => Ok(Self::Zero),
+            "null" => Ok(Self::NoReg),
+            "pcx" => Ok(Self::Pcx),
+            _ => Err(RegisterParseError::InvalidName(value.to_string())),
+        }
+    }
+}
+
+impl std::fmt::Display for Register {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Rg0 => write!(f, "rg0"),
+            Self::Rg1 => write!(f, "rg1"),
+            Self::Rg2 => write!(f, "rg2"),
+            Self::Rg3 => write!(f, "rg3"),
+            Self::Rg4 => write!(f, "rg4"),
+            Self::Rg5 => write!(f, "rg5"),
+            Self::Rg6 => write!(f, "rg6"),
+            Self::Rg7 => write!(f, "rg7"),
+            Self::Rg8 => write!(f, "rg8"),
+            Self::Rg9 => write!(f, "rg9"),
+            Self::Rga => write!(f, "rga"),
+            Self::Rgb => write!(f, "rgb"),
+            Self::Rgc => write!(f, "rgc"),
+            Self::Rgd => write!(f, "rgd"),
+            Self::Rge => write!(f, "rge"),
+            Self::Rgf => write!(f, "rgf"),
+            Self::Acc => write!(f, "acc"),
+            Self::Spr => write!(f, "spr"),
+            Self::Bpr => write!(f, "bpr"),
+            Self::Ret => write!(f, "ret"),
+            Self::Idr => write!(f, "idr"),
+            Self::Mmr => write!(f, "mmr"),
+            Self::Zero => write!(f, "zero"),
+            Self::NoReg => write!(f, "noreg"),
+            Self::Mar => write!(f, "mar"),
+            Self::Mdr => write!(f, "mdr"),
+            Self::Sts => write!(f, "sts"),
+            Self::Cir => write!(f, "cir"),
+            Self::Pcx => write!(f, "pcx"),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, Eq)]
+#[repr(u8)]
+#[non_exhaustive]
+/// A list of all current instructions in the DSA.
+///
+/// # Note
+///
+/// This is subject to change and is therefore marked non exhaustive.
+pub enum Instruction {
+    // No-op
+    Nop = 0x0,
+
+    // Data transfer instructions
+    Mov(args::RTypeArgs) = 0x1,
+    MovSigned(args::RTypeArgs) = 0x2,
+
+    LoadByte(args::ITypeArgs) = 0x3,
+    LoadByteSigned(args::ITypeArgs) = 0x4,
+    LoadHalfword(args::ITypeArgs) = 0x5,
+    LoadHalfwordSigned(args::ITypeArgs) = 0x6,
+    LoadWord(args::ITypeArgs) = 0x7,
+
+    StoreByte(args::ITypeArgs) = 0x8,
+    StoreHalfword(args::ITypeArgs) = 0x9,
+    StoreWord(args::ITypeArgs) = 0xA,
+
+    LoadLowerImmediate(args::ITypeArgs) = 0xB,
+    LoadUpperImmediate(args::ITypeArgs) = 0xC,
+
+    // Jump Instructions
+    Jump(args::ITypeArgs) = 0xD,
+    JumpEq(args::ITypeArgs) = 0xE,
+    JumpNeq(args::ITypeArgs) = 0xF,
+    JumpGt(args::ITypeArgs) = 0x10,
+    JumpGe(args::ITypeArgs) = 0x11,
+    JumpLt(args::ITypeArgs) = 0x12,
+    JumpLe(args::ITypeArgs) = 0x13,
+
+    // Comparison
+    Compare(args::RTypeArgs) = 0x14,
+
+    // Arithmetic
+    Add(args::RTypeArgs) = 0x19,
+    Sub(args::RTypeArgs) = 0x1A,
+    Increment(args::RTypeArgs) = 0x15,
+    Decrement(args::RTypeArgs) = 0x16,
+    ShiftLeft(args::RTypeArgs) = 0x17,
+    ShiftRight(args::RTypeArgs) = 0x18,
+
+    // Logical
+    And(args::RTypeArgs) = 0x1B,
+    Or(args::RTypeArgs) = 0x1C,
+    Not(args::RTypeArgs) = 0x1D,
+    Xor(args::RTypeArgs) = 0x1E,
+    Nand(args::RTypeArgs) = 0x1F,
+    Nor(args::RTypeArgs) = 0x20,
+    Xnor(args::RTypeArgs) = 0x21,
+
+    // Misc
+    Interrupt(Interrupt) = 0x22,
+    IntReturn = 0x23,
+    Halt = 0x24,
+
+    // Immediate Arithmetic
+    AddImmediate(args::ITypeArgs) = 0x25,
+    SubImmediate(args::ITypeArgs) = 0x26,
+
+    // Fake Instructions
+    Data(u32) = 0x3E,
+    Segment(u32) = 0x3F,
+}
+
+impl PartialEq for Instruction {
+    fn eq(&self, other: &Self) -> bool {
+        self.encode() == other.encode()
+    }
+}
+
+impl Instruction {
+    /// Returns the opcode of an instruction.
+    ///
+    /// # Notes
+    ///
+    /// The top two bits shall be 0, opcodes are 6-bits long.
+    #[must_use]
+    pub const fn opcode(&self) -> u8 {
+        unsafe { *std::ptr::from_ref::<Self>(self).cast::<u8>() }
+    }
+
+    /// Encodes an [`Instruction`] into a word.
+    #[must_use]
+    pub fn encode(&self) -> u32 {
+        Encode::encode(*self, self.opcode())
+    }
+
+    /// Decodes an [`Instruction`] from a word `data`.
+    pub fn decode(data: u32) -> Result<Self, InstructionDecodeError> {
+        data.try_into()
+    }
+
+    /// Returns the mnemonic for a given [`Instruction`].
+    #[must_use]
+    pub const fn mnemonic(self) -> &'static str {
+        match self {
+            Self::Add(_) => "add",
+            Self::Sub(_) => "sub",
+            Self::Increment(_) => "inc",
+            Self::Decrement(_) => "dec",
+            Self::Compare(_) => "cmp",
+            Self::Halt => "hlt",
+            Self::And(_) => "and",
+            Self::IntReturn => "intr",
+            Self::Interrupt(_) => "int",
+            Self::Jump(_) => "jmp",
+            Self::JumpEq(_) => "jeq",
+            Self::JumpNeq(_) => "jneq",
+            Self::JumpGt(_) => "jgt",
+            Self::JumpGe(_) => "jge",
+            Self::JumpLt(_) => "jlt",
+            Self::JumpLe(_) => "jle",
+            Self::Mov(_) => "mov",
+            Self::MovSigned(_) => "movs",
+            Self::LoadByte(_) => "ldb",
+            Self::LoadByteSigned(_) => "ldbs",
+            Self::LoadHalfword(_) => "ldh",
+            Self::LoadHalfwordSigned(_) => "ldhs",
+            Self::LoadWord(_) => "ldw",
+            Self::StoreByte(_) => "stb",
+            Self::StoreHalfword(_) => "sth",
+            Self::StoreWord(_) => "stw",
+            Self::LoadLowerImmediate(_) => "lli",
+            Self::LoadUpperImmediate(_) => "lui",
+            Self::ShiftLeft(_) => "shl",
+            Self::ShiftRight(_) => "shr",
+            Self::Or(_) => "or",
+            Self::Not(_) => "not",
+            Self::Nop => "nop",
+            Self::Xor(_) => "xor",
+            Self::Nand(_) => "nand",
+            Self::Nor(_) => "nor",
+            Self::Xnor(_) => "xnor",
+            Self::Data(_) => "data",
+            Self::AddImmediate(_) => "addi",
+            Self::SubImmediate(_) => "subi",
+            Self::Segment(_) => "[SEGMENT]",
+        }
+    }
+
+    /// Returns the [`InstructionType`] for the given [`Instruction`].
+    #[must_use]
+    pub const fn instruction_type(self) -> InstructionType {
+        Self::instruction_type_from_opcode(self.opcode())
+    }
+
+    /// Returns the [`InstructionType`] for the given `opcode`.
+    #[must_use]
+    pub const fn instruction_type_from_opcode(opcode: u8) -> InstructionType {
+        match opcode {
+            0x3..=0x13 => InstructionType::Immediate,
+            _ => InstructionType::Register,
+        }
+    }
+}
+
+// Instruction decoding logic goes here.
+impl std::fmt::Display for Instruction {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.mnemonic())?;
+
+        match self {
+            Self::Mov(args) | Self::MovSigned(args) => {
+                write!(f, " {}, {}", args.sr1, args.dr)
+            }
+            Self::LoadByte(args)
+            | Self::LoadByteSigned(args)
+            | Self::LoadHalfword(args)
+            | Self::LoadHalfwordSigned(args)
+            | Self::LoadWord(args)
+            | Self::StoreByte(args)
+            | Self::StoreHalfword(args)
+            | Self::StoreWord(args) => {
+                write!(
+                    f,
+                    " {}({:x}/{}), {}",
+                    args.r1, args.immediate, args.immediate, args.r2
+                )
+            }
+            Self::Jump(args)
+            | Self::JumpEq(args)
+            | Self::JumpNeq(args)
+            | Self::JumpGt(args)
+            | Self::JumpGe(args)
+            | Self::JumpLt(args)
+            | Self::JumpLe(args) => {
+                write!(f, " 0x{:x}/{}({})", args.immediate, args.immediate, args.r1)
+            }
+            Self::LoadLowerImmediate(args) | Self::LoadUpperImmediate(args) => {
+                write!(f, " 0x{:x}, {}, {}", args.immediate, args.r1, args.r2)
+            }
+            Self::Compare(args) | Self::Not(args) => {
+                write!(f, " {}, {}", args.sr1, args.sr2)
+            }
+
+            Self::Add(args)
+            | Self::Sub(args)
+            | Self::Xor(args)
+            | Self::Nand(args)
+            | Self::Nor(args)
+            | Self::Xnor(args)
+            | Self::ShiftLeft(args)
+            | Self::ShiftRight(args)
+            | Self::And(args)
+            | Self::Or(args) => {
+                write!(f, " {}, {}, {}", args.sr1, args.sr2, args.dr)
+            }
+
+            Self::AddImmediate(args) | Self::SubImmediate(args) => {
+                write!(f, " {}, {}, {}", args.r1, args.immediate, args.r2)
+            }
+
+            Self::Increment(a) | Self::Decrement(a) => write!(f, " {}", a.sr1),
+            Self::Interrupt(a) => write!(f, " {}", a.as_u8()),
+            Self::Data(a) => write!(f, " {a}"),
+            Self::Segment(x) => write!(f, " [SEGMENT {x}]"),
+            _ => Ok(()),
+        }
+    }
+}
+
+impl TryFrom<u32> for Instruction {
+    type Error = InstructionDecodeError;
+
+    /// Instruction decoding can be using using [`Instruction::try_from`]
+    fn try_from(data: u32) -> Result<Self, Self::Error> {
+        // Pull the opcode out so we can parse it correctly.
+        let opcode = ((data >> 26) & 0x3F) as u8;
+
+        match opcode {
+            0x0 => Ok(Self::Nop),
+            0x1 => Ok(Self::Mov(RTypeArgs::try_from(data)?)),
+            0x2 => Ok(Self::MovSigned(RTypeArgs::try_from(data)?)),
+            0x3 => Ok(Self::LoadByte(ITypeArgs::try_from(data)?)),
+            0x4 => Ok(Self::LoadByteSigned(ITypeArgs::try_from(data)?)),
+            0x5 => Ok(Self::LoadHalfword(ITypeArgs::try_from(data)?)),
+            0x6 => Ok(Self::LoadHalfwordSigned(ITypeArgs::try_from(data)?)),
+            0x7 => Ok(Self::LoadWord(ITypeArgs::try_from(data)?)),
+            0x8 => Ok(Self::StoreByte(ITypeArgs::try_from(data)?)),
+            0x9 => Ok(Self::StoreHalfword(ITypeArgs::try_from(data)?)),
+            0xA => Ok(Self::StoreWord(ITypeArgs::try_from(data)?)),
+            0xB => Ok(Self::LoadLowerImmediate(ITypeArgs::try_from(data)?)),
+            0xC => Ok(Self::LoadUpperImmediate(ITypeArgs::try_from(data)?)),
+            0xD => Ok(Self::Jump(ITypeArgs::try_from(data)?)),
+            0xE => Ok(Self::JumpEq(ITypeArgs::try_from(data)?)),
+            0xF => Ok(Self::JumpNeq(ITypeArgs::try_from(data)?)),
+            0x10 => Ok(Self::JumpGt(ITypeArgs::try_from(data)?)),
+            0x11 => Ok(Self::JumpGe(ITypeArgs::try_from(data)?)),
+            0x12 => Ok(Self::JumpLt(ITypeArgs::try_from(data)?)),
+            0x13 => Ok(Self::JumpLe(ITypeArgs::try_from(data)?)),
+            0x14 => Ok(Self::Compare(RTypeArgs::try_from(data)?)),
+            0x15 => Ok(Self::Increment(RTypeArgs::try_from(data)?)),
+            0x16 => Ok(Self::Decrement(RTypeArgs::try_from(data)?)),
+            0x17 => Ok(Self::ShiftLeft(RTypeArgs::try_from(data)?)),
+            0x18 => Ok(Self::ShiftRight(RTypeArgs::try_from(data)?)),
+            0x19 => Ok(Self::Add(RTypeArgs::try_from(data)?)),
+            0x1A => Ok(Self::Sub(RTypeArgs::try_from(data)?)),
+            0x1B => Ok(Self::And(RTypeArgs::try_from(data)?)),
+            0x1C => Ok(Self::Or(RTypeArgs::try_from(data)?)),
+            0x1D => Ok(Self::Not(RTypeArgs::try_from(data)?)),
+            0x1E => Ok(Self::Xor(RTypeArgs::try_from(data)?)),
+            0x1F => Ok(Self::Nand(RTypeArgs::try_from(data)?)),
+            0x20 => Ok(Self::Nor(RTypeArgs::try_from(data)?)),
+            0x21 => Ok(Self::Xnor(RTypeArgs::try_from(data)?)),
+            0x22 => Ok(Self::Interrupt(Interrupt::from((data & 0xFF) as u8))),
+            0x23 => Ok(Self::IntReturn),
+            0x24 => Ok(Self::Halt),
+            0x25 => Ok(Self::AddImmediate(ITypeArgs::try_from(data)?)),
+            0x26 => Ok(Self::SubImmediate(ITypeArgs::try_from(data)?)),
+            0x3F => Ok(Self::Segment(u32::from(data as u8))),
+            _ => Err(InstructionDecodeError::InvalidOpcode(opcode)),
+        }
+    }
+}
+
+pub mod args;
+mod encode;
+pub mod errors;
+
+#[cfg(test)]
+mod tests;

common/src/instructions/args.rs

@@ -0,0 +1,208 @@
+//! Various types of arguments that instructions can take, alongside encoding and decoding logic.
+
+use crate::{
+    instructions::{RegisterParseError, encode::Encode},
+    prelude::Register,
+};
+
+/// A list of errors that can be returned when decoding instruction arguments.
+#[derive(Debug)]
+pub enum ArgsDecodeError {
+    /// The register was not valid.
+    InvalidRegister(u8),
+}
+
+impl From<RegisterParseError> for ArgsDecodeError {
+    fn from(value: RegisterParseError) -> Self {
+        match value {
+            RegisterParseError::InvalidIndex(idx) => Self::InvalidRegister(idx),
+            RegisterParseError::InvalidName(_) => Self::InvalidRegister(0xFF),
+        }
+    }
+}
+
+impl std::fmt::Display for ArgsDecodeError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::InvalidRegister(idx) => {
+                write!(f, "invalid register index, got {idx:x}")?;
+            }
+        }
+
+        Ok(())
+    }
+}
+
+impl std::error::Error for ArgsDecodeError {}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+/// Used by instructions with 2 registers and an immediate argument.
+pub struct ITypeArgs {
+    pub immediate: u16,
+    pub r1: Register,
+    /// May not actually be used by some instructions taking an immediate e.g. LUI. This is solved by making the constructor take Options.
+    pub r2: Register,
+}
+
+impl ITypeArgs {
+    #[must_use]
+    /// Creates a new [`ITypeArgs`]. If r1 or r2 is unset, they will be replaced with [`Register::NoReg`].
+    pub fn new(immediate: u16, r1: Option<Register>, r2: Option<Register>) -> Self {
+        let r1 = r1.unwrap_or_default();
+        let r2 = r2.unwrap_or_default();
+
+        Self { immediate, r1, r2 }
+    }
+}
+
+impl Encode for ITypeArgs {
+    /// Encodes an I-type instruction from its fields. These must have some unused high-order
+    /// bits set to 0 else the bit shifting logic gets fucked.
+    fn encode(self, opcode: u8) -> u32 {
+        let opcode = u32::from(opcode);
+        let r1 = self.r1 as u32;
+        let dr = self.r2 as u32;
+        let immediate = u32::from(self.immediate);
+
+        (opcode << 26) | (r1 << 21) | (dr << 16) | immediate
+    }
+}
+
+impl TryFrom<u32> for ITypeArgs {
+    type Error = ArgsDecodeError;
+
+    fn try_from(data: u32) -> Result<Self, Self::Error> {
+        let r1 = ((data >> 21) & 0x1F) as u8;
+        let r2 = ((data >> 16) & 0x1F) as u8;
+        let immediate = data as u16;
+
+        let r1 = r1.try_into()?;
+        let r2 = r2.try_into()?;
+
+        Ok(Self { immediate, r1, r2 })
+    }
+}
+
+/// Used by instructions not using immediates (besides 5 bit shift values).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct RTypeArgs {
+    pub sr1: Register,
+    pub sr2: Register,
+    pub dr: Register,
+    /// 5 bit shift amount.
+    pub shamt: u8,
+}
+
+impl RTypeArgs {
+    #[must_use]
+    /// Creates a new [`RTypeArgs`]. If any registers are unset, they will be replaced with [`Register::NoReg`]. If `shamt` is unset, it will be set to 0.
+    pub fn new(
+        sr1: Option<Register>,
+        sr2: Option<Register>,
+        dr: Option<Register>,
+        shamt: Option<u8>,
+    ) -> Self {
+        let sr1 = sr1.unwrap_or_default();
+        let shamt = shamt.unwrap_or_default();
+        let sr2 = sr2.unwrap_or_default();
+        let dr = dr.unwrap_or_default();
+
+        Self {
+            sr1,
+            sr2,
+            dr,
+            shamt,
+        }
+    }
+}
+
+impl Encode for RTypeArgs {
+    /// Encodes an R-type instruction from its fields. These must have unused high-order
+    /// bits set to 0 else the bit shifting logic is fucked.
+    ///
+    /// # Arguments
+    ///
+    /// - `shamt`: The amount to shift value (used only in shift instructions, otherwise 0).
+    fn encode(self, opcode: u8) -> u32 {
+        let opcode = u32::from(opcode);
+        let sr1 = self.sr1 as u32;
+        let sr2 = self.sr2 as u32;
+        let dr = self.dr as u32;
+        let shamt = u32::from(self.shamt);
+
+        (opcode << 26) | (sr1 << 21) | (sr2 << 16) | (dr << 11) | (shamt << 6)
+    }
+}
+
+impl TryFrom<u32> for RTypeArgs {
+    type Error = ArgsDecodeError;
+
+    fn try_from(data: u32) -> Result<Self, Self::Error> {
+        let sr1 = ((data >> 21) & 0x1F) as u8;
+        let sr2 = ((data >> 16) & 0x1F) as u8;
+        let dr = ((data >> 11) & 0x1F) as u8;
+        let shamt = ((data >> 6) & 0x1F) as u8;
+
+        let sr1_reg = sr1.try_into()?;
+        let sr2_reg = sr2.try_into()?;
+        let dr_reg = dr.try_into()?;
+
+        Ok(Self {
+            sr1: sr1_reg,
+            sr2: sr2_reg,
+            dr: dr_reg,
+            shamt,
+        })
+    }
+}
+
+#[macro_export]
+macro_rules! args {
+    // R-type arguments - allows omitting any field
+    (R $(, $field:ident: $value:expr)* $(,)?) => {{
+        let mut sr1: Option<Register> = None;
+        let mut sr2: Option<Register> = None;
+        let mut dr: Option<Register> = None;
+        let mut shamt: Option<u8> = None;
+
+        $(
+            args!(@assign_r_option sr1, sr2, dr, shamt, $field, $value);
+        )*
+
+        RTypeArgs::new(sr1, sr2, dr, shamt)
+    }};
+
+    // I-type arguments - requires immediate, allows omitting registers
+    (I, immediate: $immediate:expr $(, $field:ident: $value:expr)* $(,)?) => {{
+        let mut r1: Option<Register> = None;
+        let mut r2: Option<Register> = None;
+
+        $(
+            args!(@assign_i_option r1, r2, $field, $value);
+        )*
+
+        ITypeArgs::new($immediate, r1, r2)
+    }};
+
+    // Internal helpers (same as above for R-type)
+    (@assign_r_option $sr1:ident, $sr2:ident, $dr:ident, $shamt:ident, sr1, $value:expr) => {
+        $sr1 = Some($value);
+    };
+    (@assign_r_option $sr1:ident, $sr2:ident, $dr:ident, $shamt:ident, sr2, $value:expr) => {
+        $sr2 = Some($value);
+    };
+    (@assign_r_option $sr1:ident, $sr2:ident, $dr:ident, $shamt:ident, dr, $value:expr) => {
+        $dr = Some($value);
+    };
+    (@assign_r_option $sr1:ident, $sr2:ident, $dr:ident, $shamt:ident, shamt, $value:expr) => {
+        $shamt = Some($value);
+    };
+
+    // Internal helpers for I-type (without immediate handling)
+    (@assign_i_option $r1:ident, $r2:ident, r1, $value:expr) => {
+        $r1 = Some($value);
+    };
+    (@assign_i_option $r1:ident, $r2:ident, r2, $value:expr) => {
+        $r2 = Some($value);
+    };
+}

common/src/instructions/encode.rs

@@ -0,0 +1,72 @@
+use crate::prelude::*;
+
+/// Not to be used directly, just call [`Instruction::encode`].
+pub trait Encode {
+    fn encode(self, opcode: u8) -> u32;
+}
+
+/// Encodes a zero argument instruction.
+fn encode_no_args(opcode: u8) -> u32 {
+    let opcode = u32::from(opcode);
+    let sr1 = Register::NoReg as u32;
+    let sr2 = Register::NoReg as u32;
+    let dr = Register::NoReg as u32;
+    let shamt = 0;
+
+    (opcode << 26) | (sr1 << 21) | (sr2 << 16) | (dr << 11) | (shamt << 6)
+}
+
+/// Expands to a match statement that calls encode on instructions that implement
+/// [`Encode`]:
+///
+/// # Usage
+///
+/// ```rs
+/// encode_instruction!(self, with_args: [...], no_args: [...], special: [...] )
+/// ```
+macro_rules! encode_instruction {
+    ($self:expr, with_args: [$($variant:ident),+ $(,)?], no_args: [$($no_arg_variant:ident),* $(,)?] $(, special: [$($special:pat => $body:expr),* $(,)?])?) => {
+        match $self {
+            $(
+                Instruction::$variant(args) => args.encode($self.opcode()),
+            )+
+            $(
+                Instruction::$no_arg_variant => encode_no_args($self.opcode()),
+            )*
+            $($(
+                $special => $body,
+            )*)?
+        }
+    };
+}
+
+impl Encode for Instruction {
+    fn encode(self, _: u8) -> u32 {
+        encode_instruction!(
+            self,
+            with_args: [
+                Mov, MovSigned, LoadByte, LoadByteSigned, LoadHalfword,
+                LoadHalfwordSigned, LoadWord, StoreByte, StoreHalfword,
+                StoreWord, LoadLowerImmediate, LoadUpperImmediate, Jump,
+                JumpEq, JumpNeq, JumpGt, JumpGe, JumpLt, JumpLe, Compare,
+                Add, Sub, Increment, Decrement, ShiftLeft, ShiftRight,
+                And, Or, Not, Xor, Nand, Nor, Xnor, AddImmediate, SubImmediate
+            ],
+            no_args: [Nop, IntReturn, Halt],
+            special: [
+                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());
+                    (opcode << 26) | u32::from(segment as u8)
+                }
+            ]
+        )
+    }
+}
+
+#[cfg(test)]
+mod tests;

common/src/instructions/encode/tests.rs

@@ -0,0 +1,98 @@
+use crate::prelude::*;
+
+#[test]
+fn test_encode_nop() {
+    let no_reg = Register::NoReg as u32;
+    let no_op = u32::from(Instruction::Nop.opcode());
+
+    let expected = (no_op << 26) | (no_reg << 21) | (no_reg << 16) | (no_reg << 11);
+    let got = Instruction::Nop.encode();
+
+    assert_eq!(expected, got);
+}
+
+#[test]
+fn test_encode_mov() {
+    let rg0 = Register::Rg0 as u32;
+    let rg1 = Register::Rg1 as u32;
+    let no_reg = Register::NoReg as u32;
+
+    let instruction = Instruction::Mov(RTypeArgs::new(
+        Some(Register::Rg0),
+        None,
+        Some(Register::Rg1),
+        None,
+    ));
+    let mov = u32::from(instruction.opcode());
+
+    let expected = (mov << 26) | (rg0 << 21) | (no_reg << 16) | (rg1 << 11);
+    let got = instruction.encode();
+
+    assert_eq!(expected, got);
+}
+
+#[test]
+fn test_encode_load_byte() {
+    let rg0 = Register::Rg0 as u32;
+    let rg1 = Register::Rg1 as u32;
+    let immediate = 100;
+
+    let instruction = Instruction::LoadByte(ITypeArgs::new(
+        immediate,
+        Some(Register::Rg0),
+        Some(Register::Rg1),
+    ));
+    let load_byte = u32::from(instruction.opcode());
+
+    let expected = (load_byte << 26) | (rg0 << 21) | (rg1 << 16) | u32::from(immediate);
+    let got = instruction.encode();
+
+    assert_eq!(expected, got);
+}
+
+#[test]
+fn test_encode_shift_left_shamt() {
+    let rg0 = Register::Rg0 as u32;
+    let no_reg = Register::NoReg as u32;
+
+    let shift_amount = 5;
+
+    let instruction = Instruction::ShiftLeft(RTypeArgs::new(
+        Some(Register::Rg0),
+        None,
+        None,
+        Some(shift_amount),
+    ));
+    let shift_left = u32::from(instruction.opcode());
+
+    let expected = (shift_left << 26)
+        | (rg0 << 21)
+        | (no_reg << 16)
+        | (no_reg << 11)
+        | (u32::from(shift_amount) << 6);
+
+    let got = instruction.encode();
+
+    assert_eq!(expected, got);
+}
+
+#[test]
+fn test_encode_shift_left_reg() {
+    let rg0 = Register::Rg0 as u32;
+    let rg1 = Register::Rg1 as u32;
+    let no_reg = Register::NoReg as u32;
+
+    let instruction = Instruction::ShiftLeft(RTypeArgs::new(
+        Some(Register::Rg0),
+        Some(Register::Rg1),
+        None,
+        None,
+    ));
+    let shift_left = u32::from(instruction.opcode());
+
+    let expected = (shift_left << 26) | (rg0 << 21) | (rg1 << 16) | (no_reg << 11);
+
+    let got = instruction.encode();
+
+    assert_eq!(expected, got);
+}

common/src/instructions/errors.rs

@@ -0,0 +1,56 @@
+//! All the errors that may be returned from [`instructions`].
+
+use crate::prelude::*;
+
+#[derive(Debug)]
+/// Error type for parsing register numbers.
+pub enum RegisterParseError {
+    InvalidIndex(u8),
+    InvalidName(String),
+}
+
+impl std::fmt::Display for RegisterParseError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::InvalidIndex(idx) => write!(f, "invalid index given ({idx})"),
+            Self::InvalidName(name) => write!(f, "invalid name given ({name})"),
+        }
+    }
+}
+
+impl std::error::Error for RegisterParseError {}
+
+/// A list of errors that can be returned when decoding instructions.
+#[derive(Debug)]
+pub enum InstructionDecodeError {
+    /// Some field was incorrect. Returns an error for debugging purposes.
+    InvalidArgument(ArgsDecodeError),
+    /// Some opcode was invalid. Returns the offending opcode for debugging purposes etc.
+    InvalidOpcode(u8),
+}
+
+impl From<ArgsDecodeError> for InstructionDecodeError {
+    fn from(err: ArgsDecodeError) -> Self {
+        Self::InvalidArgument(err)
+    }
+}
+
+impl std::fmt::Display for InstructionDecodeError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::InvalidOpcode(code) => write!(f, "invalid opcode, got {code:x}")?,
+            Self::InvalidArgument(err) => write!(f, "invalid arguments, got an error {err}")?,
+        }
+
+        Ok(())
+    }
+}
+
+impl std::error::Error for InstructionDecodeError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::InvalidArgument(err) => Some(err),
+            _ => None,
+        }
+    }
+}

common/src/instructions/tests.rs

@@ -0,0 +1,215 @@
+#![allow(clippy::unwrap_used)]
+use crate::prelude::*;
+
+#[test]
+fn test_opcode_nop() {
+    let instr = Instruction::Nop;
+    assert_eq!(instr.opcode(), 0x0);
+}
+
+#[test]
+fn test_opcode_data_transfer() {
+    let args = RTypeArgs::new(None, None, None, None);
+    assert_eq!(Instruction::Mov(args).opcode(), 0x1);
+    assert_eq!(Instruction::MovSigned(args).opcode(), 0x2);
+
+    let iargs = ITypeArgs::new(0, None, None);
+    assert_eq!(Instruction::LoadByte(iargs).opcode(), 0x3);
+    assert_eq!(Instruction::LoadByteSigned(iargs).opcode(), 0x4);
+    assert_eq!(Instruction::LoadHalfword(iargs).opcode(), 0x5);
+    assert_eq!(Instruction::LoadHalfwordSigned(iargs).opcode(), 0x6);
+    assert_eq!(Instruction::LoadWord(iargs).opcode(), 0x7);
+    assert_eq!(Instruction::StoreByte(iargs).opcode(), 0x8);
+    assert_eq!(Instruction::StoreHalfword(iargs).opcode(), 0x9);
+    assert_eq!(Instruction::StoreWord(iargs).opcode(), 0xA);
+    assert_eq!(Instruction::LoadLowerImmediate(iargs).opcode(), 0xB);
+    assert_eq!(Instruction::LoadUpperImmediate(iargs).opcode(), 0xC);
+}
+
+#[test]
+fn test_opcode_jump_instructions() {
+    let args = ITypeArgs::new(0, None, None);
+    assert_eq!(Instruction::Jump(args).opcode(), 0xD);
+    assert_eq!(Instruction::JumpEq(args).opcode(), 0xE);
+    assert_eq!(Instruction::JumpNeq(args).opcode(), 0xF);
+    assert_eq!(Instruction::JumpGt(args).opcode(), 0x10);
+    assert_eq!(Instruction::JumpGe(args).opcode(), 0x11);
+    assert_eq!(Instruction::JumpLt(args).opcode(), 0x12);
+    assert_eq!(Instruction::JumpLe(args).opcode(), 0x13);
+}
+
+#[test]
+fn test_opcode_arithmetic() {
+    let args = RTypeArgs::new(None, None, None, None);
+    assert_eq!(Instruction::Compare(args).opcode(), 0x14);
+    assert_eq!(Instruction::Increment(args).opcode(), 0x15);
+    assert_eq!(Instruction::Decrement(args).opcode(), 0x16);
+    assert_eq!(Instruction::ShiftLeft(args).opcode(), 0x17);
+    assert_eq!(Instruction::ShiftRight(args).opcode(), 0x18);
+    assert_eq!(Instruction::Add(args).opcode(), 0x19);
+    assert_eq!(Instruction::Sub(args).opcode(), 0x1A);
+}
+
+#[test]
+fn test_opcode_logical() {
+    let args = RTypeArgs::new(None, None, None, None);
+    assert_eq!(Instruction::And(args).opcode(), 0x1B);
+    assert_eq!(Instruction::Or(args).opcode(), 0x1C);
+    assert_eq!(Instruction::Not(args).opcode(), 0x1D);
+    assert_eq!(Instruction::Xor(args).opcode(), 0x1E);
+    assert_eq!(Instruction::Nand(args).opcode(), 0x1F);
+    assert_eq!(Instruction::Nor(args).opcode(), 0x20);
+    assert_eq!(Instruction::Xnor(args).opcode(), 0x21);
+}
+
+#[test]
+fn test_opcode_misc() {
+    let interrupt = Interrupt::Software(5);
+    assert_eq!(Instruction::Interrupt(interrupt).opcode(), 0x22);
+    assert_eq!(Instruction::IntReturn.opcode(), 0x23);
+    assert_eq!(Instruction::Halt.opcode(), 0x24);
+}
+
+#[test]
+fn test_opcode_with_different_args() {
+    let args1 = RTypeArgs::new(
+        Some(Register::Rg0),
+        Some(Register::Rg1),
+        Some(Register::Rg2),
+        Some(5),
+    );
+    let args2 = RTypeArgs::new(
+        Some(Register::Acc),
+        Some(Register::Spr),
+        Some(Register::Bpr),
+        Some(31),
+    );
+
+    // Opcode should be the same regardless of arguments
+    assert_eq!(
+        Instruction::Add(args1).opcode(),
+        Instruction::Add(args2).opcode()
+    );
+    assert_eq!(
+        Instruction::Sub(args1).opcode(),
+        Instruction::Sub(args2).opcode()
+    );
+}
+
+#[test]
+fn test_opcode_boundary_values() {
+    // Test highest opcode value
+    assert_eq!(Instruction::Halt.opcode(), 0x24);
+
+    // Test lowest opcode value
+    assert_eq!(Instruction::Nop.opcode(), 0x0);
+}
+
+#[test]
+fn test_instruction_decode_nop() {
+    let instr = Instruction::Nop;
+    let encoded = instr.encode();
+    let decoded = Instruction::decode(encoded).unwrap();
+    assert_eq!(instr, decoded);
+}
+
+#[test]
+fn test_instruction_decode_data_transfer() {
+    let args = RTypeArgs::new(
+        Some(Register::Rg0),
+        Some(Register::Rg1),
+        Some(Register::Rg2),
+        Some(5),
+    );
+    let instr = Instruction::Mov(args);
+    let encoded = instr.encode();
+    let decoded = Instruction::decode(encoded).unwrap();
+    assert_eq!(instr, decoded);
+
+    let iargs = ITypeArgs::new(100, Some(Register::Rg3), Some(Register::Rg4));
+    let instr = Instruction::LoadWord(iargs);
+    let encoded = instr.encode();
+    let decoded = Instruction::decode(encoded).unwrap();
+    assert_eq!(instr, decoded);
+}
+
+#[test]
+fn test_instruction_decode_jump() {
+    let args = ITypeArgs::new(200, Some(Register::Acc), Some(Register::Spr));
+    let instr = Instruction::Jump(args);
+    let encoded = instr.encode();
+    let decoded = Instruction::decode(encoded).unwrap();
+    assert_eq!(instr, decoded);
+
+    let instr = Instruction::JumpEq(args);
+    let encoded = instr.encode();
+    let decoded = Instruction::decode(encoded).unwrap();
+    assert_eq!(instr, decoded);
+}
+
+#[test]
+fn test_instruction_decode_arithmetic() {
+    let args = RTypeArgs::new(
+        Some(Register::Bpr),
+        Some(Register::Rg7),
+        Some(Register::Rgf),
+        Some(31),
+    );
+    let instr = Instruction::Add(args);
+    let encoded = instr.encode();
+    let decoded = Instruction::decode(encoded).unwrap();
+    assert_eq!(instr, decoded);
+
+    let instr = Instruction::Compare(args);
+    let encoded = instr.encode();
+    let decoded = Instruction::decode(encoded).unwrap();
+    assert_eq!(instr, decoded);
+}
+
+#[test]
+fn test_instruction_decode_logical() {
+    let args = RTypeArgs::new(
+        Some(Register::Rg8),
+        Some(Register::Rg9),
+        Some(Register::Rga),
+        Some(15),
+    );
+    let instr = Instruction::And(args);
+    let encoded = instr.encode();
+    let decoded = Instruction::decode(encoded).unwrap();
+    assert_eq!(instr, decoded);
+
+    let instr = Instruction::Xor(args);
+    let encoded = instr.encode();
+    let decoded = Instruction::decode(encoded).unwrap();
+    assert_eq!(instr, decoded);
+}
+
+#[test]
+fn test_instruction_decode_misc() {
+    let instr = Instruction::Halt;
+    let encoded = instr.encode();
+    let decoded = Instruction::decode(encoded).unwrap();
+    assert_eq!(instr, decoded);
+}
+
+#[test]
+fn test_instruction_decode_invalid() {
+    // Test with invalid opcode.
+    let invalid_encoded = 0xF500_0000;
+    let decode = Instruction::decode(invalid_encoded);
+
+    dbg!(&decode);
+
+    assert!(decode.is_err());
+}
+
+// TODO: Get interrupts working.
+// #[test]
+// fn test_instruction_decode_interrupt() {
+//     let interrupt = Interrupt::Software(10);
+//     let instr = Instruction::Interrupt(interrupt);
+//     let encoded = instr.encode();
+//     let decoded = Instruction::decode(encoded).unwrap();
+//     assert_eq!(instr, decoded);
+// }

common/src/lib.rs

@@ -0,0 +1,22 @@
+#![deny(
+    clippy::unwrap_used,
+    clippy::nursery,
+    clippy::perf,
+    clippy::pedantic,
+    clippy::complexity
+)]
+#![allow(
+    clippy::cast_possible_truncation,
+    clippy::missing_panics_doc,
+    clippy::missing_errors_doc,
+    clippy::match_wildcard_for_single_variants
+)]
+
+pub mod instructions;
+
+pub mod prelude {
+    //! A collection of types you should definitely import when working with this crate.
+    pub use super::instructions::{
+        Address, Instruction, InstructionType, Interrupt, Register, args::*, errors::*,
+    };
+}

dsa_editor/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "dsa_editor"
+version = "0.1.0"
+edition = "2024"
+description = "a fork of a code editor egui widget adapted to work with DSA syntax."
+
+[dependencies]
+egui = { version = "0.31", optional = true }
+serde = { version = "1", optional = true }
+
+[lib]
+name = "dsa_editor"
+path = "src/lib.rs"
+
+[features]
+default = ["egui", "editor"]
+egui = ["dep:egui"]
+editor = []
+serde = ["dep:serde"]
+
+[dev-dependencies]
+eframe = "0.31"
+colorful = "0.3"

dsa_editor/src/highlighting.rs

@@ -0,0 +1,253 @@
+#[cfg(feature = "editor")]
+use super::Editor;
+
+use super::syntax::{QUOTES, SEPARATORS, Syntax, TokenType};
+use std::mem;
+
+#[derive(Default, Debug, PartialEq, PartialOrd, Eq, Ord)]
+/// Lexer and Token
+pub struct Token {
+    ty: TokenType,
+    buffer: String,
+}
+
+impl Token {
+    pub fn new<S: Into<String>>(ty: TokenType, buffer: S) -> Self {
+        Token {
+            ty,
+            buffer: buffer.into(),
+        }
+    }
+    pub fn ty(&self) -> TokenType {
+        self.ty
+    }
+    pub fn buffer(&self) -> &str {
+        &self.buffer
+    }
+
+    fn first(&mut self, c: char, syntax: &Syntax) -> Option<Self> {
+        self.buffer.push(c);
+        let mut token = None;
+        self.ty = match c {
+            c if c.is_whitespace() => {
+                self.ty = TokenType::Whitespace(c);
+                token = self.drain(self.ty);
+                TokenType::Whitespace(c)
+            }
+            c if syntax.is_keyword(c.to_string().as_str()) => TokenType::Keyword,
+            c if syntax.is_type(c.to_string().as_str()) => TokenType::Type,
+            c if syntax.is_special(c.to_string().as_str()) => TokenType::Special,
+            c if syntax.comment == c.to_string().as_str() => TokenType::Comment(false),
+            c if syntax.comment_multiline[0] == c.to_string().as_str() => {
+                TokenType::Comment(true)
+            }
+            _ => TokenType::from(c),
+        };
+        token
+    }
+
+    fn drain(&mut self, ty: TokenType) -> Option<Self> {
+        let mut token = None;
+        if !self.buffer().is_empty() {
+            token = Some(Token {
+                buffer: mem::take(&mut self.buffer),
+                ty: self.ty,
+            });
+        }
+        self.ty = ty;
+        token
+    }
+
+    fn push_drain(&mut self, c: char, ty: TokenType) -> Option<Self> {
+        self.buffer.push(c);
+        self.drain(ty)
+    }
+
+    fn drain_push(&mut self, c: char, ty: TokenType) -> Option<Self> {
+        let token = self.drain(self.ty);
+        self.buffer.push(c);
+        self.ty = ty;
+        token
+    }
+
+    #[cfg(feature = "egui")]
+    /// Syntax highlighting
+    pub fn highlight<T: Editor>(&mut self, editor: &T, text: &str) -> LayoutJob {
+        *self = Token::default();
+        let mut job = LayoutJob::default();
+        for c in text.chars() {
+            for token in self.automata(c, editor.syntax()) {
+                editor.append(&mut job, &token);
+            }
+        }
+        editor.append(&mut job, self);
+        job
+    }
+
+    /// Lexer
+    pub fn tokens(&mut self, syntax: &Syntax, text: &str) -> Vec<Self> {
+        let mut tokens: Vec<Self> = text
+            .chars()
+            .flat_map(|c| self.automata(c, syntax))
+            .collect();
+
+        if !self.buffer.is_empty() {
+            tokens.push(mem::take(self));
+        }
+        tokens
+    }
+
+    fn automata(&mut self, c: char, syntax: &Syntax) -> Vec<Self> {
+        use TokenType as Ty;
+        let mut tokens = vec![];
+        match (self.ty, Ty::from(c)) {
+            (Ty::Comment(false), Ty::Whitespace('\n')) => {
+                self.buffer.push(c);
+                let n = self.buffer.pop();
+                tokens.extend(self.drain(Ty::Whitespace(c)));
+                if let Some(n) = n {
+                    tokens.extend(self.push_drain(n, self.ty));
+                }
+            }
+            (Ty::Comment(false), _) => {
+                self.buffer.push(c);
+            }
+            (Ty::Comment(true), _) => {
+                self.buffer.push(c);
+                if self.buffer.ends_with(syntax.comment_multiline[1]) {
+                    tokens.extend(self.drain(Ty::Unknown));
+                }
+            }
+            (Ty::Literal | Ty::Punctuation(_), Ty::Whitespace(_)) => {
+                tokens.extend(self.drain(Ty::Whitespace(c)));
+                tokens.extend(self.first(c, syntax));
+            }
+            (Ty::Hyperlink, Ty::Whitespace(_)) => {
+                tokens.extend(self.drain(Ty::Whitespace(c)));
+                tokens.extend(self.first(c, syntax));
+            }
+            (Ty::Hyperlink, _) => {
+                self.buffer.push(c);
+            }
+            (Ty::Literal, _) => match c {
+                c if c == '(' => {
+                    self.ty = Ty::Function;
+                    tokens.extend(self.drain(Ty::Punctuation(c)));
+                    tokens.extend(self.push_drain(c, Ty::Unknown));
+                }
+                c if !c.is_alphanumeric() && !SEPARATORS.contains(&c) => {
+                    tokens.extend(self.drain(self.ty));
+                    self.buffer.push(c);
+                    self.ty = if QUOTES.contains(&c) {
+                        Ty::Str(c)
+                    } else {
+                        Ty::Punctuation(c)
+                    };
+                }
+                _ => {
+                    self.buffer.push(c);
+                    self.ty = {
+                        if self.buffer.starts_with(syntax.comment) {
+                            Ty::Comment(false)
+                        } else if self.buffer.starts_with(syntax.comment_multiline[0]) {
+                            Ty::Comment(true)
+                        } else if syntax.is_hyperlink(&self.buffer) {
+                            Ty::Hyperlink
+                        } else if syntax.is_keyword(&self.buffer) {
+                            Ty::Keyword
+                        } else if syntax.is_type(&self.buffer) {
+                            Ty::Type
+                        } else if syntax.is_special(&self.buffer) {
+                            Ty::Special
+                        } else {
+                            Ty::Literal
+                        }
+                    };
+                }
+            },
+            (Ty::Numeric(false), Ty::Punctuation('.')) => {
+                self.buffer.push(c);
+                self.ty = Ty::Numeric(true);
+            }
+            (Ty::Numeric(_), Ty::Numeric(_)) => {
+                self.buffer.push(c);
+            }
+            (Ty::Numeric(_), Ty::Literal) => {
+                tokens.extend(self.drain(self.ty));
+                self.buffer.push(c);
+            }
+            (Ty::Numeric(_), _) | (Ty::Punctuation(_), Ty::Literal | Ty::Numeric(_)) => {
+                tokens.extend(self.drain(self.ty));
+                tokens.extend(self.first(c, syntax));
+            }
+            (Ty::Punctuation(_), Ty::Str(_)) => {
+                tokens.extend(self.drain_push(c, Ty::Str(c)));
+            }
+            (Ty::Punctuation(_), _) => {
+                if !(syntax.comment.starts_with(&self.buffer)
+                    || syntax.comment_multiline[0].starts_with(&self.buffer))
+                {
+                    tokens.extend(self.drain(self.ty));
+                    tokens.extend(self.first(c, syntax));
+                } else {
+                    self.buffer.push(c);
+                    if self.buffer.starts_with(syntax.comment) {
+                        self.ty = Ty::Comment(false);
+                    } else if self.buffer.starts_with(syntax.comment_multiline[0]) {
+                        self.ty = Ty::Comment(true);
+                    } else if let Some(c) = self.buffer.pop() {
+                        tokens.extend(self.drain(Ty::Punctuation(c)));
+                        tokens.extend(self.first(c, syntax));
+                    }
+                }
+            }
+            (Ty::Str(q), _) => {
+                let control = self.buffer.ends_with('\\');
+                self.buffer.push(c);
+                if c == q && !control {
+                    tokens.extend(self.drain(Ty::Unknown));
+                }
+            }
+            (Ty::Whitespace(_) | Ty::Unknown, _) => {
+                tokens.extend(self.first(c, syntax));
+            }
+            // Keyword, Type, Special
+            (_reserved, Ty::Literal | Ty::Numeric(_)) => {
+                self.buffer.push(c);
+                self.ty = if syntax.is_keyword(&self.buffer) {
+                    Ty::Keyword
+                } else if syntax.is_type(&self.buffer) {
+                    Ty::Type
+                } else if syntax.is_special(&self.buffer) {
+                    Ty::Special
+                } else {
+                    Ty::Literal
+                };
+            }
+            (reserved, _) => {
+                self.ty = reserved;
+                tokens.extend(self.drain(self.ty));
+                tokens.extend(self.first(c, syntax));
+            }
+        }
+        tokens
+    }
+}
+
+#[cfg(feature = "egui")]
+use egui::text::LayoutJob;
+
+#[cfg(feature = "egui")]
+impl<T: Editor> egui::util::cache::ComputerMut<(&T, &str), LayoutJob> for Token {
+    fn compute(&mut self, (cache, text): (&T, &str)) -> LayoutJob {
+        self.highlight(cache, text)
+    }
+}
+
+#[cfg(feature = "egui")]
+pub type HighlightCache = egui::util::cache::FrameCache<LayoutJob, Token>;
+
+#[cfg(feature = "egui")]
+pub fn highlight<T: Editor>(ctx: &egui::Context, cache: &T, text: &str) -> LayoutJob {
+    ctx.memory_mut(|mem| mem.caches.cache::<HighlightCache>().get((cache, text)))
+}

dsa_editor/src/lib.rs

@@ -0,0 +1,296 @@
+pub mod highlighting;
+mod syntax;
+mod themes;
+
+#[cfg(feature = "egui")]
+use egui::text::LayoutJob;
+#[cfg(feature = "egui")]
+use egui::widgets::text_edit::TextEditOutput;
+pub use highlighting::Token;
+#[cfg(feature = "egui")]
+use highlighting::highlight;
+#[cfg(feature = "editor")]
+use std::hash::{Hash, Hasher};
+pub use syntax::{Syntax, TokenType};
+pub use themes::ColorTheme;
+pub use themes::DEFAULT_THEMES;
+
+#[cfg(feature = "egui")]
+pub trait Editor: Hash {
+    fn append(&self, job: &mut LayoutJob, token: &Token);
+    fn syntax(&self) -> &Syntax;
+}
+
+#[cfg(feature = "editor")]
+#[derive(Clone, Debug, PartialEq)]
+/// CodeEditor struct which stores settings for highlighting.
+pub struct CodeEditor {
+    id: String,
+    theme: ColorTheme,
+    syntax: Syntax,
+    numlines: bool,
+    numlines_shift: isize,
+    numlines_only_natural: bool,
+    fontsize: f32,
+    rows: usize,
+    stick_to_bottom: bool,
+    desired_width: f32,
+}
+
+#[cfg(feature = "editor")]
+impl Hash for CodeEditor {
+    fn hash<H: Hasher>(&self, state: &mut H) {
+        self.theme.hash(state);
+        #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
+        (self.fontsize as u32).hash(state);
+        self.syntax.hash(state);
+    }
+}
+
+#[cfg(feature = "editor")]
+impl Default for CodeEditor {
+    fn default() -> CodeEditor {
+        CodeEditor {
+            id: String::from("Code Editor"),
+            theme: ColorTheme::THEME,
+            syntax: Syntax::dsa(),
+            numlines: true,
+            numlines_shift: 0,
+            numlines_only_natural: false,
+            fontsize: 10.0,
+            rows: 10,
+            stick_to_bottom: false,
+            desired_width: f32::INFINITY,
+        }
+    }
+}
+
+#[cfg(feature = "editor")]
+impl CodeEditor {
+    pub fn id_source(self, id_source: impl Into<String>) -> Self {
+        CodeEditor {
+            id: id_source.into(),
+            ..self
+        }
+    }
+
+    /// Minimum number of rows to show.
+    ///
+    /// **Default: 10**
+    pub fn with_rows(self, rows: usize) -> Self {
+        CodeEditor { rows, ..self }
+    }
+
+    /// Use custom Color Theme
+    ///
+    /// **Default: Gruvbox**
+    pub fn with_theme(self, theme: ColorTheme) -> Self {
+        CodeEditor { theme, ..self }
+    }
+
+    /// Use custom font size
+    ///
+    /// **Default: 10.0**
+    pub fn with_fontsize(self, fontsize: f32) -> Self {
+        CodeEditor { fontsize, ..self }
+    }
+
+    #[cfg(feature = "egui")]
+    /// Use UI font size
+    pub fn with_ui_fontsize(self, ui: &mut egui::Ui) -> Self {
+        CodeEditor {
+            fontsize: egui::TextStyle::Monospace.resolve(ui.style()).size,
+            ..self
+        }
+    }
+
+    /// Show or hide lines numbering
+    ///
+    /// **Default: true**
+    pub fn with_numlines(self, numlines: bool) -> Self {
+        CodeEditor { numlines, ..self }
+    }
+
+    /// Shift lines numbering by this value
+    ///
+    /// **Default: 0**
+    pub fn with_numlines_shift(self, numlines_shift: isize) -> Self {
+        CodeEditor {
+            numlines_shift,
+            ..self
+        }
+    }
+
+    /// Show lines numbering only above zero, useful for enabling numbering since nth row
+    ///
+    /// **Default: false**
+    pub fn with_numlines_only_natural(self, numlines_only_natural: bool) -> Self {
+        CodeEditor {
+            numlines_only_natural,
+            ..self
+        }
+    }
+
+    /// Use custom syntax for highlighting
+    ///
+    /// **Default: Rust**
+    pub fn with_syntax(self, syntax: Syntax) -> Self {
+        CodeEditor { syntax, ..self }
+    }
+
+    /// Should the containing area shrink if the content is small?
+    ///
+    /// **Default: false**
+    pub fn auto_shrink(self, shrink: bool) -> Self {
+        CodeEditor {
+            desired_width: if shrink { 0.0 } else { self.desired_width },
+            ..self
+        }
+    }
+
+    /// Sets the desired width of the code editor
+    ///
+    /// **Default: `f32::INFINITY`**
+    pub fn desired_width(self, width: f32) -> Self {
+        CodeEditor {
+            desired_width: width,
+            ..self
+        }
+    }
+
+    /// Stick to bottom
+    /// The scroll handle will stick to the bottom position even while the content size
+    /// changes dynamically. This can be useful to simulate terminal UIs or log/info scrollers.
+    /// The scroll handle remains stuck until user manually changes position. Once "unstuck"
+    /// it will remain focused on whatever content viewport the user left it on. If the scroll
+    /// handle is dragged to the bottom it will again become stuck and remain there until manually
+    /// pulled from the end position.
+    ///
+    /// **Default: false**
+    pub fn stick_to_bottom(self, stick_to_bottom: bool) -> Self {
+        CodeEditor {
+            stick_to_bottom,
+            ..self
+        }
+    }
+
+    #[cfg(feature = "egui")]
+    pub fn format(&self, ty: TokenType) -> egui::text::TextFormat {
+        let font_id = egui::FontId::monospace(self.fontsize);
+        let color = self.theme.type_color(ty);
+        egui::text::TextFormat::simple(font_id, color)
+    }
+
+    #[cfg(feature = "egui")]
+    fn numlines_show(&self, ui: &mut egui::Ui, text: &str) {
+        let total = if text.ends_with('\n') || text.is_empty() {
+            text.lines().count() + 1
+        } else {
+            text.lines().count()
+        }
+        .max(self.rows) as isize;
+        let max_indent = total.to_string().len().max(
+            !self.numlines_only_natural as usize * self.numlines_shift.to_string().len(),
+        );
+        let mut counter = (1..=total)
+            .map(|i| {
+                let num = i + self.numlines_shift;
+                if num <= 0 && self.numlines_only_natural {
+                    String::new()
+                } else {
+                    let label = num.to_string();
+                    format!(
+                        "{}{label}",
+                        " ".repeat(max_indent.saturating_sub(label.len()))
+                    )
+                }
+            })
+            .collect::<Vec<String>>()
+            .join("\n");
+
+        #[allow(clippy::cast_precision_loss)]
+        let width = max_indent as f32
+            * self.fontsize
+            * 0.5
+            * !(total + self.numlines_shift <= 0 && self.numlines_only_natural) as u8
+                as f32;
+
+        let mut layouter = |ui: &egui::Ui, string: &str, _wrap_width: f32| {
+            let layout_job = egui::text::LayoutJob::single_section(
+                string.to_string(),
+                egui::TextFormat::simple(
+                    egui::FontId::monospace(self.fontsize),
+                    self.theme.type_color(TokenType::Comment(true)),
+                ),
+            );
+            ui.fonts(|f| f.layout_job(layout_job))
+        };
+
+        ui.add(
+            egui::TextEdit::multiline(&mut counter)
+                .id_source(format!("{}_numlines", self.id))
+                .font(egui::TextStyle::Monospace)
+                .interactive(false)
+                .frame(false)
+                .desired_rows(self.rows)
+                .desired_width(width)
+                .layouter(&mut layouter),
+        );
+    }
+
+    #[cfg(feature = "egui")]
+    /// Show Code Editor
+    pub fn show(
+        &mut self,
+        ui: &mut egui::Ui,
+        text: &mut dyn egui::TextBuffer,
+    ) -> TextEditOutput {
+        let mut text_edit_output: Option<TextEditOutput> = None;
+        let code_editor = |ui: &mut egui::Ui| {
+            ui.horizontal_top(|h| {
+                self.theme.modify_style(h, self.fontsize);
+                if self.numlines {
+                    self.numlines_show(h, text.as_str());
+                }
+                egui::ScrollArea::horizontal()
+                    .hscroll(true)
+                    .id_salt(format!("{}_inner_scroll", self.id))
+                    .show(h, |ui| {
+                        let mut layouter =
+                            |ui: &egui::Ui, string: &str, _wrap_width: f32| {
+                                let layout_job = highlight(ui.ctx(), self, string);
+                                ui.fonts(|f| f.layout_job(layout_job))
+                            };
+                        let output = egui::TextEdit::multiline(text)
+                            .id_source(&self.id)
+                            .lock_focus(true)
+                            .desired_rows(self.rows)
+                            .frame(false)
+                            .desired_width(self.desired_width)
+                            .layouter(&mut layouter)
+                            .show(ui);
+                        text_edit_output = Some(output);
+                    });
+            });
+        };
+
+        egui::ScrollArea::vertical()
+            .id_salt(format!("{}_outer_scroll", self.id))
+            .stick_to_bottom(self.stick_to_bottom)
+            .show(ui, code_editor);
+
+        text_edit_output.expect("TextEditOutput should exist at this point")
+    }
+}
+
+#[cfg(feature = "editor")]
+#[cfg(feature = "egui")]
+impl Editor for CodeEditor {
+    fn append(&self, job: &mut LayoutJob, token: &Token) {
+        job.append(token.buffer(), 0.0, self.format(token.ty()));
+    }
+
+    fn syntax(&self) -> &Syntax {
+        &self.syntax
+    }
+}

dsa_editor/src/syntax/dsa.rs

@@ -0,0 +1,29 @@
+use super::Syntax;
+use std::collections::BTreeSet;
+
+impl Syntax {
+    pub fn dsa() -> Self {
+        Syntax {
+            language: "Assembly",
+            case_sensitive: false,
+            comment: "//",
+            comment_multiline: ["/*", "*/"],
+            hyperlinks: BTreeSet::from(["http"]),
+            keywords: BTreeSet::from([
+                "nop", "mov", "movs", "ldb", "ldbs", "ldh", "ldhs", "ldw", "stb", "sth",
+                "stw", "lli", "lui", "jmp", "jeq", "jne", "jgt", "jge", "jlt", "jle",
+                "cmp", "inc", "dec", "shl", "shr", "add", "sub", "and", "or", "not",
+                "xor", "nand", "nor", "xnor", "irt", "int", "hlt",
+                // pseduo-instructions
+                "db", "dh", "dw", "resb", "resh", "resw", "push", "pop", "lwi", "call",
+                "include",
+            ]),
+            types: BTreeSet::from([]),
+            special: BTreeSet::from([
+                "rg0", "rg1", "rg2", "rg3", "rg4", "rg5", "rg6", "rg7", "rg8", "rg9",
+                "rga", "rgb", "rgc", "rgd", "rge", "rgf", "acc", "spr", "bpr", "ret",
+                "idr", "mmr", "zero", "null", "pcx", "mdr", "mar", "sts", "cir",
+            ]),
+        }
+    }
+}

dsa_editor/src/syntax/mod.rs

@@ -0,0 +1,204 @@
+#![allow(dead_code)]
+pub mod dsa;
+
+use std::collections::BTreeSet;
+use std::hash::{Hash, Hasher};
+
+pub const SEPARATORS: [char; 1] = ['_'];
+pub const QUOTES: [char; 3] = ['\'', '"', '`'];
+
+type MultiLine = bool;
+type Float = bool;
+
+#[derive(Default, Clone, Copy, PartialEq, PartialOrd, Eq, Ord)]
+#[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
+pub enum TokenType {
+    Comment(MultiLine),
+    Function,
+    Keyword,
+    Literal,
+    Hyperlink,
+    Numeric(Float),
+    Punctuation(char),
+    Special,
+    Str(char),
+    Type,
+    Whitespace(char),
+    #[default]
+    Unknown,
+}
+impl std::fmt::Debug for TokenType {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let mut name = String::new();
+        match &self {
+            TokenType::Comment(multiline) => {
+                name.push_str("Comment");
+                {
+                    if *multiline {
+                        name.push_str(" MultiLine");
+                    } else {
+                        name.push_str(" SingleLine");
+                    }
+                }
+            }
+            TokenType::Function => name.push_str("Function"),
+            TokenType::Keyword => name.push_str("Keyword"),
+            TokenType::Literal => name.push_str("Literal"),
+            TokenType::Hyperlink => name.push_str("Hyperlink"),
+            TokenType::Numeric(float) => {
+                name.push_str("Numeric");
+                if *float {
+                    name.push_str(" Float");
+                } else {
+                    name.push_str(" Integer");
+                }
+            }
+            TokenType::Punctuation(_) => name.push_str("Punctuation"),
+            TokenType::Special => name.push_str("Special"),
+            TokenType::Str(quote) => {
+                name.push_str("Str ");
+                name.push(*quote);
+            }
+            TokenType::Type => name.push_str("Type"),
+            TokenType::Whitespace(c) => {
+                name.push_str("Whitespace");
+                match c {
+                    ' ' => name.push_str(" Space"),
+                    '\t' => name.push_str(" Tab"),
+                    '\n' => name.push_str(" New Line"),
+                    _ => (),
+                };
+            }
+            TokenType::Unknown => name.push_str("Unknown"),
+        };
+        write!(f, "{name}")
+    }
+}
+impl From<char> for TokenType {
+    fn from(c: char) -> Self {
+        match c {
+            c if c.is_whitespace() => TokenType::Whitespace(c),
+            c if QUOTES.contains(&c) => TokenType::Str(c),
+            c if c.is_numeric() => TokenType::Numeric(false),
+            c if c.is_alphabetic() || SEPARATORS.contains(&c) => TokenType::Literal,
+            c if c.is_ascii_punctuation() => TokenType::Punctuation(c),
+            _ => TokenType::Unknown,
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq)]
+/// Rules for highlighting.
+pub struct Syntax {
+    pub language: &'static str,
+    pub case_sensitive: bool,
+    pub comment: &'static str,
+    pub comment_multiline: [&'static str; 2],
+    pub hyperlinks: BTreeSet<&'static str>,
+    pub keywords: BTreeSet<&'static str>,
+    pub types: BTreeSet<&'static str>,
+    pub special: BTreeSet<&'static str>,
+}
+impl Default for Syntax {
+    fn default() -> Self {
+        Syntax::dsa()
+    }
+}
+impl Hash for Syntax {
+    fn hash<H: Hasher>(&self, state: &mut H) {
+        self.language.hash(state);
+    }
+}
+impl Syntax {
+    pub fn new(language: &'static str) -> Self {
+        Syntax {
+            language,
+            ..Default::default()
+        }
+    }
+    pub fn with_case_sensitive(self, case_sensitive: bool) -> Self {
+        Syntax {
+            case_sensitive,
+            ..self
+        }
+    }
+    pub fn with_comment(self, comment: &'static str) -> Self {
+        Syntax { comment, ..self }
+    }
+    pub fn with_comment_multiline(self, comment_multiline: [&'static str; 2]) -> Self {
+        Syntax {
+            comment_multiline,
+            ..self
+        }
+    }
+    pub fn with_hyperlinks<T: Into<BTreeSet<&'static str>>>(self, hyperlinks: T) -> Self {
+        Syntax {
+            hyperlinks: hyperlinks.into(),
+            ..self
+        }
+    }
+    pub fn with_keywords<T: Into<BTreeSet<&'static str>>>(self, keywords: T) -> Self {
+        Syntax {
+            keywords: keywords.into(),
+            ..self
+        }
+    }
+    pub fn with_types<T: Into<BTreeSet<&'static str>>>(self, types: T) -> Self {
+        Syntax {
+            types: types.into(),
+            ..self
+        }
+    }
+    pub fn with_special<T: Into<BTreeSet<&'static str>>>(self, special: T) -> Self {
+        Syntax {
+            special: special.into(),
+            ..self
+        }
+    }
+
+    pub fn language(&self) -> &str {
+        self.language
+    }
+    pub fn comment(&self) -> &str {
+        self.comment
+    }
+    pub fn is_hyperlink(&self, word: &str) -> bool {
+        self.hyperlinks.contains(word.to_ascii_lowercase().as_str())
+    }
+    pub fn is_keyword(&self, word: &str) -> bool {
+        if self.case_sensitive {
+            self.keywords.contains(&word)
+        } else {
+            self.keywords.contains(word.to_ascii_lowercase().as_str())
+        }
+    }
+    pub fn is_type(&self, word: &str) -> bool {
+        if self.case_sensitive {
+            self.types.contains(&word)
+        } else {
+            self.types.contains(word.to_ascii_lowercase().as_str())
+        }
+    }
+    pub fn is_special(&self, word: &str) -> bool {
+        if self.case_sensitive {
+            self.special.contains(&word)
+        } else {
+            self.special.contains(word.to_ascii_lowercase().as_str())
+        }
+    }
+}
+
+impl Syntax {
+    pub fn simple(comment: &'static str) -> Self {
+        Syntax {
+            language: "",
+            case_sensitive: false,
+            comment,
+            comment_multiline: [comment; 2],
+            hyperlinks: BTreeSet::new(),
+            keywords: BTreeSet::new(),
+            types: BTreeSet::new(),
+            special: BTreeSet::new(),
+        }
+    }
+}

dsa_editor/src/themes/mod.rs

@@ -0,0 +1,147 @@
+#![allow(dead_code)]
+pub mod theme;
+
+use super::syntax::TokenType;
+#[cfg(feature = "egui")]
+use egui::Color32;
+
+#[cfg(feature = "egui")]
+pub const ERROR_COLOR: Color32 = Color32::from_rgb(255, 0, 255);
+
+/// Array of default themes.
+pub const DEFAULT_THEMES: [ColorTheme; 1] = [ColorTheme::THEME];
+
+#[cfg(feature = "egui")]
+fn color_from_hex(hex: &str) -> Option<Color32> {
+    if hex == "none" {
+        return Some(Color32::from_rgba_premultiplied(255, 0, 255, 0));
+    }
+    let rgb = (1..hex.len())
+        .step_by(2)
+        .filter_map(|i| u8::from_str_radix(&hex[i..i + 2], 16).ok())
+        .collect::<Vec<u8>>();
+    let color = Color32::from_rgb(*rgb.first()?, *rgb.get(1)?, *rgb.get(2)?);
+    Some(color)
+}
+
+#[derive(Hash, Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
+/// Colors in hexadecimal notation as used in HTML and CSS.
+pub struct ColorTheme {
+    pub name: &'static str,
+    pub dark: bool,
+    pub bg: &'static str,
+    pub cursor: &'static str,
+    pub selection: &'static str,
+    pub comments: &'static str,
+    pub functions: &'static str,
+    pub keywords: &'static str,
+    pub literals: &'static str,
+    pub numerics: &'static str,
+    pub punctuation: &'static str,
+    pub strs: &'static str,
+    pub types: &'static str,
+    pub special: &'static str,
+}
+
+impl Default for ColorTheme {
+    fn default() -> Self {
+        ColorTheme::THEME
+    }
+}
+impl ColorTheme {
+    pub fn name(&self) -> &str {
+        self.name
+    }
+
+    pub fn is_dark(&self) -> bool {
+        self.dark
+    }
+
+    #[cfg(feature = "egui")]
+    pub fn bg(&self) -> Color32 {
+        color_from_hex(self.bg).unwrap_or(ERROR_COLOR)
+    }
+
+    #[cfg(feature = "egui")]
+    pub fn cursor(&self) -> Color32 {
+        color_from_hex(self.cursor).unwrap_or(ERROR_COLOR)
+    }
+
+    #[cfg(feature = "egui")]
+    pub fn selection(&self) -> Color32 {
+        color_from_hex(self.selection).unwrap_or(ERROR_COLOR)
+    }
+
+    #[cfg(feature = "egui")]
+    pub fn modify_style(&self, ui: &mut egui::Ui, fontsize: f32) {
+        let style = ui.style_mut();
+        style.visuals.widgets.noninteractive.bg_fill = self.bg();
+        style.visuals.window_fill = self.bg();
+        style.visuals.selection.stroke.color = self.cursor();
+        style.visuals.selection.bg_fill = self.selection();
+        style.visuals.extreme_bg_color = self.bg();
+        style.override_font_id = Some(egui::FontId::monospace(fontsize));
+        style.visuals.text_cursor.stroke.width = fontsize * 0.1;
+    }
+
+    pub const fn type_color_str(&self, ty: TokenType) -> &'static str {
+        match ty {
+            TokenType::Comment(_) => self.comments,
+            TokenType::Function => self.functions,
+            TokenType::Keyword => self.keywords,
+            TokenType::Literal => self.literals,
+            TokenType::Hyperlink => self.special,
+            TokenType::Numeric(_) => self.numerics,
+            TokenType::Punctuation(_) => self.punctuation,
+            TokenType::Special => self.special,
+            TokenType::Str(_) => self.strs,
+            TokenType::Type => self.types,
+            TokenType::Whitespace(_) | TokenType::Unknown => self.comments,
+        }
+    }
+
+    #[cfg(feature = "egui")]
+    pub fn type_color(&self, ty: TokenType) -> Color32 {
+        match ty {
+            TokenType::Comment(_) => color_from_hex(self.comments),
+            TokenType::Function => color_from_hex(self.functions),
+            TokenType::Keyword => color_from_hex(self.keywords),
+            TokenType::Literal => color_from_hex(self.literals),
+            TokenType::Hyperlink => color_from_hex(self.special),
+            TokenType::Numeric(_) => color_from_hex(self.numerics),
+            TokenType::Punctuation(_) => color_from_hex(self.punctuation),
+            TokenType::Special => color_from_hex(self.special),
+            TokenType::Str(_) => color_from_hex(self.strs),
+            TokenType::Type => color_from_hex(self.types),
+            TokenType::Whitespace(_) | TokenType::Unknown => {
+                color_from_hex(self.comments)
+            }
+        }
+        .unwrap_or(ERROR_COLOR)
+    }
+
+    pub fn monocolor(
+        dark: bool,
+        bg: &'static str,
+        fg: &'static str,
+        cursor: &'static str,
+        selection: &'static str,
+    ) -> Self {
+        ColorTheme {
+            name: "monocolor",
+            dark,
+            bg,
+            cursor,
+            selection,
+            literals: fg,
+            numerics: fg,
+            keywords: fg,
+            functions: fg,
+            punctuation: fg,
+            types: fg,
+            strs: fg,
+            comments: fg,
+            special: fg,
+        }
+    }
+}

dsa_editor/src/themes/theme.rs

@@ -0,0 +1,22 @@
+use super::ColorTheme;
+
+impl ColorTheme {
+    /// Author : Jakub Bartodziej <kubabartodziej@gmail.com>
+    /// Theme uses the gruvbox dark palette with standard contrast <https://github.com/morhetz/gruvbox>
+    pub const THEME: ColorTheme = ColorTheme {
+        name: "Theme",
+        dark: true,
+        bg: "#1b1b1b",
+        cursor: "#de5252",      // fg4
+        selection: "#28323B",   // bg2
+        comments: "#444444",    // gray1
+        functions: "#7CCCC7",   // green1
+        keywords: "#6C81E0",    // red1
+        literals: "#A3ABFF",    // fg1
+        numerics: "#8A46CF",    // purple1
+        punctuation: "#99C9C9", // orange1
+        strs: "#618c84",        // aqua1
+        types: "#B8B9D4",       // yellow1
+        special: "#de5252",     // blue1
+    };
+}

emulator/Cargo.toml

@@ -0,0 +1,42 @@
+[package]
+name = "emulator"
+version = "0.1.0"
+edition = "2024"
+default-run = "emulator"
+
+[lib]
+name = "dsa_rs"
+path = "src/lib.rs"
+crate-type = ["cdylib", "rlib"]
+
+[[bin]]
+name = "emulator"
+required-features = ["config"]
+
+[dependencies]
+common = { path = "../common" }
+assembler = { path = "../assembler" }
+dsa_editor = { path = "../dsa_editor" }
+egui = "0.31.1"
+dirs = "6.0.0"
+discord-presence = { version = "1.6.0", optional = true }
+toml = { version = "0.8.23", optional = true }
+serde = { version = "1.0.219", features = ["derive"], optional = true }
+egui_file = "0.22.1"
+
+[features]
+default = ["config"]
+discord-rpc = ["dep:discord-presence"]
+config = ["dep:toml", "dep:serde"]
+
+# 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"
+
+[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/config.rs

@@ -0,0 +1,38 @@
+//! Loads configuration information from a TOML file in the current working directory.
+//! Currently doesn't do much but this may be expanded.
+
+use std::path::Path;
+
+use serde::Deserialize;
+
+#[derive(Deserialize, Default)]
+pub struct Config {
+    pub misc: MiscTable,
+}
+
+/// For config options where you aren't sure what table it should go under.
+#[derive(Deserialize, Default)]
+pub struct MiscTable {
+    /// Whether or not we can enable Discord RPC for fun.
+    #[cfg(feature = "discord-rpc")]
+    pub use_discord_rpc: bool,
+}
+
+impl Config {
+    pub fn load(path: &Path) -> Result<Self, toml::de::Error> {
+        let file_contents = match std::fs::read_to_string(path) {
+            Ok(file_contents) => file_contents,
+            Err(why) => {
+                eprintln!(
+                    "WARN: Expected to read config file from '{}' with error '{}'. Using default settings.",
+                    path.display(),
+                    why
+                );
+
+                return Ok(Self::default());
+            }
+        };
+
+        Self::deserialize(toml::Deserializer::new(&file_contents))
+    }
+}

emulator/src/emulator/misc/mod.rs

@@ -0,0 +1 @@
+pub mod rpc;

emulator/src/emulator/misc/rpc.rs

@@ -0,0 +1,221 @@
+//! Just for fun I thought I would add a Discord RPC client to the emulator.
+//!
+//! This will display information like the current value of PCX, architecture name and
+//! GitHub repo links to show off the ISA. Perhaps in the future if we cross-compile to
+//! WASM we could include a link to run this software in the browser.
+//!
+//!
+//! # Configuration
+//!
+//! This may be disabled like so in your `.dsa.emulator.toml` file:
+//!
+//! ```toml
+//! [misc]
+//! use_discord_rpc = false
+//! ```
+//!
+//! Alternatively, you can hide this in your Discord settings.
+
+#[cfg(feature = "discord-rpc")]
+use std::{path::PathBuf, sync::Arc, time::Duration};
+
+use std::sync::mpsc::{Receiver, Sender};
+
+#[cfg(feature = "discord-rpc")]
+use discord_presence::{Client, DiscordError, models::ActivityTimestamps};
+
+use crate::emulator::config::Config;
+
+#[derive(Debug)]
+#[cfg(feature = "discord-rpc")]
+pub enum RpcClientError {
+    Client(DiscordError),
+}
+
+#[cfg(feature = "discord-rpc")]
+impl std::fmt::Display for RpcClientError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Client(why) => write!(f, "discord RPC error: {why}"),
+        }
+    }
+}
+
+#[cfg(feature = "discord-rpc")]
+impl std::error::Error for RpcClientError {}
+
+#[cfg(feature = "discord-rpc")]
+impl From<DiscordError> for RpcClientError {
+    fn from(err: DiscordError) -> Self {
+        Self::Client(err)
+    }
+}
+
+/// The type of activity the user is currently doing.
+#[derive(Debug, Clone)]
+#[cfg(feature = "discord-rpc")]
+pub enum Activity {
+    Idle,
+    EditingFile(PathBuf),
+}
+
+/// Messages to send over the wire.
+#[derive(Debug)]
+#[cfg(feature = "discord-rpc")]
+pub enum Message {
+    /// Sent when we want to update the [`Context`].
+    Update(Activity),
+    /// Sent when the main program wants to exit.
+    Stop,
+}
+
+#[cfg(feature = "discord-rpc")]
+unsafe impl Send for Message {}
+
+#[derive(Debug, Clone)]
+#[cfg(feature = "discord-rpc")]
+pub struct RpcClient {
+    /// Sends updates to [`Context`] (our state).
+    sender: Sender<Message>,
+    /// Stored for later cleanup on Drop.
+    thread_handle: Option<Arc<std::thread::JoinHandle<()>>>,
+}
+
+#[cfg(feature = "discord-rpc")]
+impl RpcClient {
+    #[expect(clippy::unreadable_literal)]
+    /// Sets up the [`RpcClient`].
+    pub fn new(
+        sender: Sender<Message>,
+        reciever: Receiver<Message>,
+    ) -> Result<Self, RpcClientError> {
+        // TODO: Put client id into a .env file.
+        let mut client = discord_presence::Client::new(1384303074088190042);
+
+        let thread_handle = std::thread::spawn(move || {
+            client.start();
+
+            eprintln!("INFO: Started Discord RPC client.");
+
+            std::thread::sleep(Duration::from_millis(1000));
+
+            // Recieve updates and do shit.
+            for message in &reciever {
+                match message {
+                    Message::Update(activity) => {
+                        Self::handle_activity(&mut client, &activity);
+                    }
+                    Message::Stop => {
+                        eprintln!("INFO: Stopping discord RPC client.");
+                        if let Err(why) = client.shutdown() {
+                            eprintln!("ERROR: Stopping discord RPC client failed: {why}");
+                        }
+
+                        break;
+                    }
+                }
+            }
+        });
+
+        Ok(Self {
+            sender,
+            thread_handle: Some(Arc::new(thread_handle)),
+        })
+    }
+
+    fn handle_activity(client: &mut Client, activity: &Activity) {
+        let current_time = std::time::SystemTime::now();
+        let timestamps = ActivityTimestamps::new().start(
+            current_time
+                .duration_since(std::time::UNIX_EPOCH)
+                .expect("Failed to get UNIX timestamp for activity.")
+                .as_secs(),
+        );
+
+        match activity {
+            Activity::Idle => {
+                client
+                    .set_activity(|act| act.details("Idle").timestamps(|_| timestamps))
+                    .expect("TODO: Exponential backoff.");
+            }
+            Activity::EditingFile(file_path) => {
+                client
+                    .set_activity(|act| {
+                        act.details(format!("Editing file: {}", file_path.display()))
+                            .timestamps(|_| timestamps)
+                    })
+                    .expect("TODO: Exponential backoff.");
+            }
+        }
+
+        eprintln!("INFO: RPC sent: {activity:?}");
+    }
+
+    /// Stops the [`RpcClient`].
+    ///
+    /// # Panics
+    ///
+    /// May panic if the reciever was deallocated. This should not happen.
+    fn stop(&self) {
+        self.sender
+            .send(Message::Stop)
+            .expect("Failed to send stop message to RPC client.");
+    }
+
+    /// Send an update with a given [`Activity`] to the [`RpcClient`].
+    ///
+    /// # Panics
+    ///
+    /// May panic if the reciever was deallocated. This should not happen.
+    pub fn update(&self, activity: Activity) {
+        self.sender
+            .send(Message::Update(activity))
+            .expect("Failed to send update to RPC client. This should not happen.");
+    }
+}
+
+// Possibly unneeded but good practice.
+#[cfg(feature = "discord-rpc")]
+impl Drop for RpcClient {
+    fn drop(&mut self) {
+        self.stop();
+
+        if let Some(handle) = self.thread_handle.take() {
+            if let Some(handle) = Arc::into_inner(handle) {
+                let _ = handle.join();
+            }
+        }
+    }
+}
+
+/// Stub for when the feature is disabled.
+#[cfg(not(feature = "discord-rpc"))]
+pub struct RpcClient {}
+
+/// Stub for when the feature is disabled.
+#[cfg(not(feature = "discord-rpc"))]
+pub enum Message {}
+
+/// Stub for when the feature is disabled.
+#[cfg(not(feature = "discord-rpc"))]
+pub enum Activity {}
+
+/// Gets the discord [`RpcClient`] or returns None if this has been disabled in the config
+/// options.
+#[cfg(feature = "config")]
+#[allow(clippy::needless_pass_by_value, unused_variables)]
+pub fn get_rpc_client_or_none(
+    config: &Config,
+    rpc_sender: Sender<Message>,
+    rpc_reciever: Receiver<Message>,
+) -> Result<Option<RpcClient>, Box<dyn std::error::Error + 'static>> {
+    #[cfg(not(feature = "discord-rpc"))]
+    return Ok(None);
+
+    #[cfg(feature = "discord-rpc")]
+    if config.misc.use_discord_rpc {
+        Ok(Some(RpcClient::new(rpc_sender, rpc_reciever)?))
+    } else {
+        Ok(None)
+    }
+}

emulator/src/emulator/mod.rs

@@ -0,0 +1,5 @@
+#[cfg(feature = "config")]
+pub mod config;
+pub mod misc;
+pub mod system;
+pub mod ui;

emulator/src/emulator/system/emulator.rs

@@ -0,0 +1,245 @@
+use std::sync::Arc;
+use std::sync::mpsc::{self, Receiver, Sender};
+
+#[allow(unused_imports)]
+use crate::emulator::misc::rpc::{Activity, RpcClient};
+
+use crate::emulator::system::model::StateUpdate;
+use crate::emulator::system::{
+    model::{Command, Running},
+    processor::Processor,
+};
+
+use common::prelude::*;
+
+#[expect(clippy::too_many_lines)]
+#[allow(unused_variables)]
+pub fn run_emulator(
+    cmd_rx: &Receiver<Command>,
+    state_tx: &Sender<StateUpdate>,
+    mut processor: Processor,
+    rpc_client: Option<&Arc<RpcClient>>,
+) {
+    println!("INFO: Starting emulator.");
+
+    let mut running = Running::Paused;
+    let mut step = 0;
+    let mut addr;
+    let mut history = Vec::<(u32, Instruction)>::new();
+    let size = 256;
+
+    state_tx
+        .send(StateUpdate::Running(Running::Paused))
+        .expect("Failed to send initial state!");
+
+    let mut instruction_count = 0;
+    let mut update = false;
+
+    loop {
+        let cmd = if running == Running::Running || step > 0 {
+            match cmd_rx.try_recv() {
+                Ok(cmd) => Some(cmd),
+                Err(mpsc::TryRecvError::Empty) => {
+                    update = false;
+                    None
+                }
+                Err(mpsc::TryRecvError::Disconnected) => break,
+            }
+        } else {
+            match cmd_rx.recv() {
+                Ok(cmd) => Some(cmd),
+                Err(_) => break,
+            }
+        };
+
+        if let Some(cmd) = cmd {
+            match cmd {
+                Command::Start => {
+                    running = Running::Running;
+
+                    // Update RPC with current state. TODO: Make this only occur on state
+                    // changes.
+                    #[cfg(feature = "discord-rpc")]
+                    if let Some(rpc_client) = rpc_client {
+                        use std::{path::PathBuf, str::FromStr};
+
+                        rpc_client.update(Activity::EditingFile(
+                            PathBuf::from_str("test")
+                                .expect("This is a valid path, WTF."),
+                        ));
+                    }
+                }
+                Command::Stop => {
+                    running = Running::Paused;
+                }
+                Command::Reset(x) => {
+                    running = Running::Paused;
+
+                    match x {
+                        0 => {
+                            processor.clear();
+                            processor.reset();
+                            instruction_count = 0;
+                        }
+                        1 => {
+                            processor.reset();
+                            instruction_count = 0;
+                        }
+                        2 => {
+                            processor.clear();
+                        }
+                        _ => unreachable!(),
+                    }
+
+                    processor.reset();
+                }
+                Command::Step(x) => {
+                    step = x;
+                }
+                Command::Write(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,
+                            );
+                        });
+                }
+
+                _ => {}
+            }
+        }
+
+        if step > 0 {
+            step -= 1;
+            update = true;
+            running = Running::Paused;
+
+            // Execute one cycle.
+            match processor.cycle() {
+                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 {
+            update = true;
+
+            // Execute one cycle.
+            let instruction = match processor.cycle() {
+                Ok(instruction) => instruction,
+                Err(why) => {
+                    let pcx = processor
+                        .get(Register::Pcx)
+                        .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);
+            if matches!(instruction.1, Instruction::Halt) {
+                running = Running::Halted;
+            }
+
+            instruction_count += 1;
+        }
+    }
+}
+
+fn report_err(state_tx: &Sender<StateUpdate>, why: &str, processor: &mut Processor) {
+    processor
+        .begin_interrupt(Interrupt::HardFault)
+        .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.");
+    let _ = state_tx.send(StateUpdate::Error(why.to_string()));
+}

emulator/src/emulator/system/memory.rs

@@ -0,0 +1,170 @@
+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) -> Result<u8, ProcessorError>;
+    fn write_byte(&mut self, addr: u32, value: u8) -> Result<(), ProcessorError>;
+    fn read_word(&mut self, addr: u32) -> Result<u32, ProcessorError>;
+    fn write_word(&mut self, addr: u32, value: u32) -> Result<(), ProcessorError>;
+
+    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 {
+    pub data: HashMap<u32, Block>,
+}
+
+pub struct Block {
+    data: [u8; 256],
+}
+
+impl Default for MainStore {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl MainStore {
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            data: HashMap::new(),
+        }
+    }
+
+    const fn segment_addr(addr: u32) -> (u32, u8) {
+        (addr / 256, (addr % 256) as u8)
+    }
+
+    fn mut_block(&mut self, addr: u32) -> &mut Block {
+        self.data
+            .entry(addr)
+            .or_insert_with(|| Block { data: [0; 256] });
+
+        self.data.get_mut(&addr).map_or_else(
+            || panic!("Could not fetch block with address {addr:x?}"),
+            |block| block,
+        )
+    }
+
+    fn block(&mut self, addr: u32) -> &Block {
+        self.data
+            .entry(addr)
+            .or_insert_with(|| Block { data: [0; 256] });
+
+        self.data.get(&addr).map_or_else(
+            || panic!("Could not fetch block with address {addr:x?}"),
+            |block| block,
+        )
+    }
+}
+
+impl MemoryUnit for MainStore {
+    fn reset(&mut self) {
+        self.data.clear();
+    }
+
+    fn read_byte(&mut self, addr: u32) -> Result<u8, ProcessorError> {
+        let (block_addr, offset) = Self::segment_addr(addr);
+        let block = self.block(block_addr);
+        Ok(block.data[offset as usize])
+    }
+
+    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);
+        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];
+        Ok(u32::from_be_bytes(bytes))
+    }
+
+    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_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) -> 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>) -> Result<(), ProcessorError> {
+        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/mod.rs

@@ -0,0 +1,4 @@
+pub mod emulator;
+pub mod memory;
+pub mod model;
+pub mod processor;

emulator/src/emulator/system/model.rs

@@ -0,0 +1,327 @@
+use std::sync::mpsc::{self, Receiver, Sender};
+
+use common::prelude::*;
+
+#[derive(PartialEq, Eq, Debug, Clone, Copy)]
+pub enum Running {
+    Running,
+    Paused,
+    Halted,
+}
+
+pub trait IODevice: Send + Sync {
+    fn read_byte(&mut self, addr: u32) -> u8;
+    fn write_byte(&mut self, addr: u32, value: u8);
+    fn read_range(&mut self, addr: u32, size: u32) -> Vec<u8>;
+    fn write_range(&mut self, addr: u32, value: Vec<u8>);
+}
+
+#[derive(PartialEq, Eq, Debug, Clone)]
+pub enum Command {
+    // set emulator state.
+    Start,
+    Stop,
+    Step(usize),
+    Reset(usize),
+    Interrupt(Interrupt),
+    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)]
+pub struct RegFile {
+    // General Purpose Registers
+    rg0: u32,
+    rg1: u32,
+    rg2: u32,
+    rg3: u32,
+    rg4: u32,
+    rg5: u32,
+    rg6: u32,
+    rg7: u32,
+    rg8: u32,
+    rg9: u32,
+    rga: u32,
+    rgb: u32,
+    rgc: u32,
+    rgd: u32,
+    rge: u32,
+    rgf: u32,
+
+    // Special Purpose Registers
+    acc: u32,
+    spr: u32,
+    bpr: u32,
+    ret: u32,
+    idr: u32,
+    mmr: u32,
+
+    // System Registers
+    mar: u32,
+    mdr: u32,
+    sts: u32,
+    cir: u32,
+    pcx: u32,
+}
+
+impl RegFile {
+    #[must_use]
+    pub fn all(&self) -> Vec<(&str, u32)> {
+        vec![
+            ("Rg0", self.rg0),
+            ("Rg1", self.rg1),
+            ("Rg2", self.rg2),
+            ("Rg3", self.rg3),
+            ("Rg4", self.rg4),
+            ("Rg5", self.rg5),
+            ("Rg6", self.rg6),
+            ("Rg7", self.rg7),
+            ("Rg8", self.rg8),
+            ("Rg9", self.rg9),
+            ("Rga", self.rga),
+            ("Rgb", self.rgb),
+            ("Rgc", self.rgc),
+            ("Rgd", self.rgd),
+            ("Rge", self.rge),
+            ("Rgf", self.rgf),
+            ("Acc", self.acc),
+            ("Spr", self.spr),
+            ("Bpr", self.bpr),
+            ("Ret", self.ret),
+            ("Idr", self.idr),
+            ("Mmr", self.mmr),
+            ("Mar", self.mar),
+            ("Mdr", self.mdr),
+            ("Sts", self.sts),
+            ("Cir", self.cir),
+            ("Pcx", self.pcx),
+        ]
+    }
+
+    pub const fn reset(&mut self) {
+        self.rg0 = 0;
+        self.rg1 = 0;
+        self.rg2 = 0;
+        self.rg3 = 0;
+        self.rg4 = 0;
+        self.rg5 = 0;
+        self.rg6 = 0;
+        self.rg7 = 0;
+        self.rg8 = 0;
+        self.rg9 = 0;
+        self.rga = 0;
+        self.rgb = 0;
+        self.rgc = 0;
+        self.rgd = 0;
+        self.rge = 0;
+        self.rgf = 0;
+        self.acc = 0;
+        self.spr = 0;
+        self.bpr = 0;
+        self.ret = 0;
+        self.idr = 0;
+        self.mmr = 0;
+        self.mar = 0;
+        self.mdr = 0;
+        self.sts = 0;
+        self.cir = 0;
+        self.pcx = 0;
+    }
+
+    pub const fn reg(&mut self, reg: Register) -> Result<&mut u32, ProcessorError> {
+        Ok(match reg {
+            Register::Rg0 => &mut self.rg0,
+            Register::Rg1 => &mut self.rg1,
+            Register::Rg2 => &mut self.rg2,
+            Register::Rg3 => &mut self.rg3,
+            Register::Rg4 => &mut self.rg4,
+            Register::Rg5 => &mut self.rg5,
+            Register::Rg6 => &mut self.rg6,
+            Register::Rg7 => &mut self.rg7,
+            Register::Rg8 => &mut self.rg8,
+            Register::Rg9 => &mut self.rg9,
+            Register::Rga => &mut self.rga,
+            Register::Rgb => &mut self.rgb,
+            Register::Rgc => &mut self.rgc,
+            Register::Rgd => &mut self.rgd,
+            Register::Rge => &mut self.rge,
+            Register::Rgf => &mut self.rgf,
+            Register::Acc => &mut self.acc,
+            Register::Spr => &mut self.spr,
+            Register::Bpr => &mut self.bpr,
+            Register::Ret => &mut self.ret,
+            Register::Idr => &mut self.idr,
+            Register::Mmr => &mut self.mmr,
+            Register::Mar => &mut self.mar,
+            Register::Mdr => &mut self.mdr,
+            Register::Sts => &mut self.sts,
+            Register::Cir => &mut self.cir,
+            Register::Pcx => &mut self.pcx,
+            _ => return Err(ProcessorError::InvalidRegister(Register::NoReg as u8)),
+        })
+    }
+
+    #[must_use]
+    pub const fn get(&self, reg: Register) -> Result<u32, ProcessorError> {
+        Ok(match reg {
+            Register::Rg0 => self.rg0,
+            Register::Rg1 => self.rg1,
+            Register::Rg2 => self.rg2,
+            Register::Rg3 => self.rg3,
+            Register::Rg4 => self.rg4,
+            Register::Rg5 => self.rg5,
+            Register::Rg6 => self.rg6,
+            Register::Rg7 => self.rg7,
+            Register::Rg8 => self.rg8,
+            Register::Rg9 => self.rg9,
+            Register::Rga => self.rga,
+            Register::Rgb => self.rgb,
+            Register::Rgc => self.rgc,
+            Register::Rgd => self.rgd,
+            Register::Rge => self.rge,
+            Register::Rgf => self.rgf,
+            Register::Acc => self.acc,
+            Register::Spr => self.spr,
+            Register::Bpr => self.bpr,
+            Register::Ret => self.ret,
+            Register::Idr => self.idr,
+            Register::Mmr => self.mmr,
+            Register::Mar => self.mar,
+            Register::Mdr => self.mdr,
+            Register::Sts => self.sts,
+            Register::Cir => self.cir,
+            Register::Pcx => self.pcx,
+            Register::Zero => 0,
+            _ => return Err(ProcessorError::InvalidRegister(Register::NoReg as u8)),
+        })
+    }
+}

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

@@ -0,0 +1,507 @@
+use std::{
+    cmp::{max, min},
+    sync::Arc,
+};
+
+use crate::emulator::system::{
+    memory::MemoryUnit,
+    model::{IODevice, ProcessorError, RegFile},
+};
+
+use common::instructions::{Instruction, Interrupt, Register};
+
+pub struct Processor {
+    pub memory: Box<dyn MemoryUnit>,
+    pub registers: RegFile,
+    pub halted: bool,
+    pub io_devices: Vec<Arc<dyn IODevice>>,
+
+    pub void: u32,
+}
+
+fn log(message: &str) {
+    println!("\x1b[32mINFO:\x1b[0m {message}");
+}
+
+impl Processor {
+    #[must_use]
+    pub fn new(memory: Box<dyn MemoryUnit>, io_devices: Vec<Arc<dyn IODevice>>) -> Self {
+        Self {
+            memory,
+            registers: RegFile::default(),
+            halted: false,
+            io_devices,
+            void: 0,
+        }
+    }
+
+    pub const fn reset(&mut self) {
+        // set all registers to zero
+        // run memory.reset()
+        self.registers.reset();
+    }
+
+    pub fn clear(&mut self) {
+        self.memory.reset();
+    }
+
+    pub fn cycle(&mut self) -> Result<(u32, Instruction), ProcessorError> {
+        self.halted = false;
+
+        // Get value from PCX.
+        let addr = self.fetch()?;
+        // Increment PCX.
+        self.advance();
+
+        // Set MAR to the previous value of PCX.
+        *self.reg(Register::Mar)? = addr;
+        let val = self.memory.read_word(addr)?;
+
+        // Set CIR to the value of RAM[MAR].
+        *self.reg(Register::Mar)? = val;
+
+        // Decode and execute the instruction.
+        let instruction = Instruction::decode(val)
+            .map_err(|_| ProcessorError::InvalidInstruction(val))?;
+
+        instruction.execute(self)?;
+        Ok((addr, instruction))
+    }
+
+    const fn fetch(&self) -> Result<u32, ProcessorError> {
+        self.get(Register::Pcx)
+    }
+
+    pub const fn get(&self, reg: Register) -> Result<u32, ProcessorError> {
+        self.registers.get(reg)
+    }
+
+    pub const fn reg(&mut self, reg: Register) -> Result<&mut u32, ProcessorError> {
+        match reg {
+            Register::Zero => Ok(&mut self.void),
+            _ => self.registers.reg(reg),
+        }
+    }
+
+    pub fn display(&mut self) -> Result<Vec<u8>, ProcessorError> {
+        self.memory.read_range(0x20000, 2000)
+    }
+
+    pub fn cmp(&mut self, a: u32, b: u32) {
+        self.set_flag(Flag::Equal, a == b);
+        self.set_flag(Flag::GreaterThan, a > b);
+        self.set_flag(Flag::LessThan, a < b);
+    }
+
+    // functions to set new state
+    fn set_flag(&mut self, flag: Flag, value: bool) {
+        if value {
+            *self
+                .reg(Register::Sts)
+                .expect("STS should never be invalid") |= flag as u32;
+        } else {
+            *self
+                .reg(Register::Sts)
+                .expect("STS should never be invalid") &= !(flag as u32);
+        }
+    }
+
+    fn get_flag(&self, flag: Flag) -> Result<bool, ProcessorError> {
+        Ok(self.get(Register::Sts)? & (flag as u32) != 0)
+    }
+
+    fn advance(&mut self) -> Result<(), ProcessorError> {
+        // increment PCX
+        *self.reg(Register::Pcx)? += 4;
+        Ok(())
+    }
+
+    fn jump(&mut self, reg: Register, offset: u16) -> Result<(), ProcessorError> {
+        *self.reg(Register::Pcx)? = self.get(reg)? + u32::from(offset);
+        Ok(())
+    }
+
+    pub fn begin_interrupt(
+        &mut self,
+        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 push(&mut self, val: u32) -> Result<(), ProcessorError> {
+        *self.reg(Register::Spr)? -= 4;
+        let reg = *self.reg(Register::Spr)?;
+        self.memory.write_word(reg, val)
+    }
+
+    fn pop(&mut self) -> Result<u32, ProcessorError> {
+        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(
+            max(addr, 0),    // ensures that we cannot read from a negative address
+            min(size, addr), // ensures we don't read above the top of the stack
+        )
+    }
+}
+
+#[derive(Debug)]
+#[expect(dead_code)]
+enum Flag {
+    Equal = 1,
+    GreaterThan = 2,
+    LessThan = 4,
+    Zero = 8,
+    Positive = 16,
+    Negative = 32,
+    Carry = 64,
+    UserMode = 128,
+    InterruptsEnabled = 256,
+}
+
+trait Executable {
+    fn execute(self, cpu: &mut Processor) -> Result<(), ProcessorError>;
+}
+
+impl Executable for Instruction {
+    #[allow(clippy::too_many_lines)]
+    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)?;
+            }
+
+            // 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)?);
+            }
+
+            // 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.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.memory
+                        .read_byte(cpu.get(a.r1)? + u32::from(a.immediate))?,
+                ));
+            }
+
+            // Loads a half-word from memory address (base + offset) into a.drReg. The
+            // effective address must be 2-byte-aligned.
+            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
+                    .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.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
+                    .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.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();
+                cpu.memory
+                    .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])?;
+            }
+
+            // Stores a word from SrcReg in memory address (base + offset) The effective
+            // address must be 4-byte-aligned.
+            Self::StoreWord(a) => {
+                cpu.memory.write_word(
+                    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);
+            }
+
+            // 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.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)?,
+
+            // Jumps to the calculated address or direct address if equal flag set.
+            Self::JumpEq(a) => {
+                if cpu.get_flag(Flag::Equal)? {
+                    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)? {
+                    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)? {
+                    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)? {
+                    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)? {
+                    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)? {
+                    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)?),
+
+            // Decrements the value in the given register
+            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 reg = cpu.get(a.sr1)?;
+                let val = a.shamt;
+                *cpu.reg(a.sr1)? = shl(reg, val);
+            }
+
+            // 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.sr1)?;
+                let val = a.shamt;
+                *cpu.reg(a.sr1)? = shr(regval, val);
+            }
+
+            // 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)?);
+            }
+
+            // 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)?);
+            }
+
+            Self::AddImmediate(a) => {
+                *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));
+            }
+
+            // 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)?),
+
+            // 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)?),
+
+            // Performs bitwise NOT on Src storing the result in a.dr
+            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)?),
+
+            // 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)?),
+
+            // 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)?),
+
+            // 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)?),
+
+            // 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)?);
+            }
+
+            // Initiates an interrupt with the given 8 bit interrupt code.
+            // Triggering an interrupt invokes the following behaviour:
+            //      - 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)?;
+            }
+
+            // Returns from an interrupt,
+            Self::IntReturn => {
+                cpu.end_interrupt()?;
+            }
+
+            // Halts the processor.
+            Self::Halt => {
+                cpu.halted = true;
+            }
+
+            Self::Segment(_) | Self::Nop | Self::Data(_) => {}
+            _ => {
+                eprintln!("WARN: unimplemented instruction: {self}");
+                todo!()
+            }
+        }
+        Ok(())
+    }
+}
+
+// mathematical and logical functions & other operations
+const fn add(a: u32, b: u32) -> u32 {
+    a.wrapping_add(b)
+}
+
+const fn sub(a: u32, b: u32) -> u32 {
+    a.wrapping_sub(b)
+}
+
+const fn and(a: u32, b: u32) -> u32 {
+    a & b
+}
+
+const fn inc(a: u32) -> u32 {
+    a.wrapping_add(1)
+}
+
+const fn dec(a: u32) -> u32 {
+    a.wrapping_sub(1)
+}
+
+const fn shl(a: u32, amount: u8) -> u32 {
+    a << amount
+}
+
+const fn shr(a: u32, amount: u8) -> u32 {
+    a >> amount
+}
+
+const fn or(a: u32, b: u32) -> u32 {
+    a | b
+}
+
+const fn not(a: u32) -> u32 {
+    !a
+}
+
+const fn xor(a: u32, b: u32) -> u32 {
+    a ^ b
+}
+
+const fn nand(a: u32, b: u32) -> u32 {
+    !(a & b)
+}
+
+const fn nor(a: u32, b: u32) -> u32 {
+    !(a | b)
+}
+
+const fn xnor(a: u32, b: u32) -> u32 {
+    !(a ^ b)
+}
+
+const fn sign_extend(val: u32) -> u32 {
+    let (mask, sign_bit): (u32, u8) = match val {
+        0..=0xFF => (0xFFFF_FF00, 7),
+        // I presume this was the intended behaviour?
+        0x100..=0xFFFF => (0xFFFF_0000, 15),
+        _ => (0x0000_0000, 31),
+    };
+
+    if val & (1 << sign_bit) != 0 {
+        val | mask
+    } else {
+        val
+    }
+}
+
+#[cfg(test)]
+mod tests;

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

@@ -0,0 +1,695 @@
+use super::*;
+use crate::emulator::system::memory::*;
+
+use common::prelude::*;
+
+fn create_test_processor() -> Processor {
+    let memory = Box::new(MainStore::new());
+    Processor::new(memory, Vec::new())
+}
+
+#[test]
+fn test_nop_instruction() {
+    let mut cpu = create_test_processor();
+    let initial_state = cpu.registers;
+
+    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)
+            .expect("Failed to get register Rg0"),
+        initial_state
+            .get(Register::Rg0)
+            .expect("Failed to get register Rg0")
+    );
+    assert_eq!(
+        cpu.registers
+            .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).expect("Failed to get register Rg1") = 0x1234_5678;
+
+    let mov_instr = Instruction::Mov(RTypeArgs::new(
+        Some(Register::Rg1),
+        None,
+        Some(Register::Rg2),
+        None,
+    ));
+
+    mov_instr.execute(&mut cpu).expect(
+        "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).expect("Failed to get register Rg1") = 0x0000_00FF;
+
+    let mov_signed_instr = Instruction::MovSigned(RTypeArgs::new(
+        Some(Register::Rg1),
+        None,
+        Some(Register::Rg2),
+        None,
+    ));
+
+    mov_signed_instr.execute(&mut cpu).expect(
+        "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)
+        .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,
+        Some(Register::Rg1),
+        Some(Register::Rg2),
+    ));
+
+    load_byte_instr.execute(&mut cpu).expect(
+        "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)
+        .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,
+        Some(Register::Rg1),
+        Some(Register::Rg2),
+    ));
+
+    load_byte_signed_instr.execute(&mut cpu).expect(
+        "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)
+        .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,
+        Some(Register::Rg1),
+        Some(Register::Rg2),
+    ));
+
+    load_halfword_instr.execute(&mut cpu).expect(
+        "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)
+        .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,
+        Some(Register::Rg1),
+        Some(Register::Rg2),
+    ));
+
+    load_word_instr.execute(&mut cpu).expect(
+        "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).expect("Failed to get register Rg1") = addr;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 0xAB;
+
+    let store_byte_instr = Instruction::StoreByte(ITypeArgs::new(
+        0,
+        Some(Register::Rg2),
+        Some(Register::Rg1),
+    ));
+
+    store_byte_instr.execute(&mut cpu).expect(
+        "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).expect("Failed to get register Rg1") = addr;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 0x1234_5678;
+
+    let store_word_instr = Instruction::StoreWord(ITypeArgs::new(
+        0,
+        Some(Register::Rg2),
+        Some(Register::Rg1),
+    ));
+
+    store_word_instr.execute(&mut cpu).expect(
+        "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).expect("Failed to get register Rg1") = 15;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 25;
+
+    let add_instr = Instruction::Add(RTypeArgs::new(
+        Some(Register::Rg1),
+        Some(Register::Rg2),
+        Some(Register::Rg3),
+        None,
+    ));
+
+    add_instr.execute(&mut cpu).expect(
+        "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).expect("Failed to get register Rg1") = 50;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 20;
+
+    let sub_instr = Instruction::Sub(RTypeArgs::new(
+        Some(Register::Rg1),
+        Some(Register::Rg2),
+        Some(Register::Rg3),
+        None,
+    ));
+
+    sub_instr.execute(&mut cpu).expect(
+        "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).expect("Failed to get register Rg1") = 0b1100;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 0b1010;
+
+    let and_instr = Instruction::And(RTypeArgs::new(
+        Some(Register::Rg1),
+        Some(Register::Rg2),
+        Some(Register::Rg3),
+        None,
+    ));
+
+    and_instr.execute(&mut cpu).expect(
+        "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).expect("Failed to get register Rg1") = 0b1100;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 0b1010;
+
+    let or_instr = Instruction::Or(RTypeArgs::new(
+        Some(Register::Rg1),
+        Some(Register::Rg2),
+        Some(Register::Rg3),
+        None,
+    ));
+
+    or_instr.execute(&mut cpu).expect(
+        "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).expect("Failed to get register Rg1") = 0b1100;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 0b1010;
+
+    let xor_instr = Instruction::Xor(RTypeArgs::new(
+        Some(Register::Rg1),
+        Some(Register::Rg2),
+        Some(Register::Rg3),
+        None,
+    ));
+
+    xor_instr.execute(&mut cpu).expect(
+        "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).expect("Failed to get register Rg1") = 0x0F0F_0F0F;
+
+    let not_instr = Instruction::Not(RTypeArgs::new(
+        Some(Register::Rg1),
+        None,
+        Some(Register::Rg2),
+        None,
+    ));
+
+    not_instr.execute(&mut cpu).expect(
+        "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).expect("Failed to get register Rg1") = 42;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 42;
+
+    let cmp_instr = Instruction::Compare(RTypeArgs::new(
+        Some(Register::Rg1),
+        Some(Register::Rg2),
+        None,
+        None,
+    ));
+
+    cmp_instr.execute(&mut cpu).expect(
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+
+    assert!(cpu.get_flag(Flag::Equal).expect("Failed to get flag Equal"));
+    assert!(
+        !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).expect("Failed to get register Rg1") = 50;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 30;
+
+    let cmp_instr = Instruction::Compare(RTypeArgs::new(
+        Some(Register::Rg1),
+        Some(Register::Rg2),
+        None,
+        None,
+    ));
+
+    cmp_instr.execute(&mut cpu).expect(
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+
+    assert!(!cpu.get_flag(Flag::Equal).expect("Failed to get flag Equal"));
+    assert!(
+        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).expect("Failed to get register Rg1") = 20;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 30;
+
+    let cmp_instr = Instruction::Compare(RTypeArgs::new(
+        Some(Register::Rg1),
+        Some(Register::Rg2),
+        None,
+        None,
+    ));
+
+    cmp_instr.execute(&mut cpu).expect(
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+
+    assert!(!cpu.get_flag(Flag::Equal).expect("Failed to get flag Equal"));
+    assert!(
+        !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).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).expect(
+        "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).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).expect(
+        "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).expect("Failed to get register Rg1") = 0b1010;
+
+    let shl_instr = Instruction::ShiftLeft(RTypeArgs::new(
+        Some(Register::Rg1),
+        Some(Register::Zero),
+        None,
+        Some(2),
+    ));
+
+    shl_instr.execute(&mut cpu).expect(
+        "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).expect("Failed to get register Rg1") = 0b10_1000;
+
+    let shr_instr = Instruction::ShiftRight(RTypeArgs::new(
+        Some(Register::Rg1),
+        Some(Register::Zero),
+        None,
+        Some(2),
+    ));
+
+    shr_instr.execute(&mut cpu).expect(
+        "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]
+// fn test_shift_left_with_register() {
+//     let mut cpu = create_test_processor();
+//     *cpu.reg(Register::Rg1).expect("Failed to get register Rg1") = 0b1010;
+
+//     let shl_instr =
+//         Instruction::ShiftLeft(RTypeArgs::new(Some(Register::Rg1), None, None,
+// Some(3)));
+
+//     shl_instr.execute(&mut cpu).expect(
+//         "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() {
+    let mut cpu = create_test_processor();
+
+    let lli_instr = Instruction::LoadLowerImmediate(ITypeArgs::new(
+        0x1234,
+        Some(Register::Rg1),
+        None,
+    ));
+
+    lli_instr.execute(&mut cpu).expect(
+        "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).expect("Failed to get register Rg1") = 0x0000_5678;
+
+    let lui_instr = Instruction::LoadUpperImmediate(ITypeArgs::new(
+        0x1234,
+        Some(Register::Rg1),
+        None,
+    ));
+
+    lui_instr.execute(&mut cpu).expect(
+        "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).expect("Failed to get register Rg1") = 0x1000;
+    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).expect(
+        "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
+    );
+    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).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).expect(
+        "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).expect("Failed to get register Rg1") = 0x1000;
+    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).expect(
+        "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]
+fn test_halt_instruction() {
+    let mut cpu = create_test_processor();
+    assert!(!cpu.halted);
+
+    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).expect("Failed to get register Rg1") = 0b1100;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 0b1010;
+
+    let nand_instr = Instruction::Nand(RTypeArgs::new(
+        Some(Register::Rg1),
+        Some(Register::Rg2),
+        Some(Register::Rg3),
+        None,
+    ));
+
+    nand_instr.execute(&mut cpu).expect(
+        "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).expect("Failed to get register Rg1") = 0b1100;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 0b1010;
+
+    let nor_instr = Instruction::Nor(RTypeArgs::new(
+        Some(Register::Rg1),
+        Some(Register::Rg2),
+        Some(Register::Rg3),
+        None,
+    ));
+
+    nor_instr.execute(&mut cpu).expect(
+        "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).expect("Failed to get register Rg1") = 0b1100;
+    *cpu.reg(Register::Rg2).expect("Failed to get register Rg2") = 0b1010;
+
+    let xnor_instr = Instruction::Xnor(RTypeArgs::new(
+        Some(Register::Rg1),
+        Some(Register::Rg2),
+        Some(Register::Rg3),
+        None,
+    ));
+
+    xnor_instr.execute(&mut cpu).expect(
+        "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

@@ -0,0 +1,197 @@
+use crate::emulator::{
+    system::model::{Command, Running, State},
+    ui::interface::Component,
+};
+
+use common::{instructions::Register, prelude::Instruction};
+
+pub struct ControlPanel {
+    visible: bool,
+    step_amount_input: String,
+    step_amount: usize,
+}
+
+impl ControlPanel {
+    #[allow(clippy::must_use_candidate)]
+    pub fn new() -> Self {
+        Self {
+            visible: false,
+            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
+    }
+
+    fn visible(&mut self) -> &mut bool {
+        &mut self.visible
+    }
+
+    fn name(&self) -> &'static str {
+        "Control Panel"
+    }
+
+    fn render(&mut self, state: &mut State, ui: &mut egui::Ui, ctx: &egui::Context) {
+        ui.horizontal(|ui| {
+            // Pause / Run
+            if ui
+                .button(if state.running == Running::Running {
+                    "Pause"
+                } else {
+                    "Run"
+                })
+                .clicked()
+            {
+                if state.running == Running::Running {
+                    state.cmd_sender.send(Command::Stop).unwrap_or_else(|_| {
+                        state.error_log.push("Failed to send command".to_string());
+                    });
+                } else {
+                    state.cmd_sender.send(Command::Start).unwrap_or_else(|_| {
+                        state.error_log.push("Failed to send command".to_string());
+                    });
+                }
+            }
+
+            // Step
+            if ui.button("Step").clicked() {
+                state
+                    .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() {
+                state
+                    .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() {
+                state
+                    .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() {
+                state
+                    .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: {}",
+                match state.running {
+                    Running::Running => "Running",
+                    Running::Paused => "Paused",
+                    Running::Halted => "Halted",
+                }
+            ));
+
+            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)
+                    .expect("CIR should never be invalid"),
+            )
+            .map_or_else(
+                |_| "Invalid Instruction".to_string(),
+                |instruction| instruction.to_string(),
+            );
+
+            ui.label(format!("Instruction: {instruction}"));
+        });
+
+        render_register_table(state, ui, ctx);
+    }
+}
+
+fn render_register_table(state: &State, ui: &mut egui::Ui, _ctx: &egui::Context) {
+    // Left column - Registers
+    ui.vertical(|ui| {
+        ui.heading("Registers");
+
+        egui::ScrollArea::vertical()
+            .id_salt("register_inspector_scroll")
+            .show(ui, |ui| {
+                egui::Grid::new("registers_grid")
+                    .num_columns(8)
+                    .spacing([40.0, 4.0])
+                    .striped(true)
+                    .show(ui, |ui| {
+                        ui.label("Register");
+                        ui.label("Value");
+                        ui.label("Register");
+                        ui.label("Value");
+                        ui.label("Register");
+                        ui.label("Value");
+                        ui.label("Register");
+                        ui.label("Value");
+                        ui.end_row();
+
+                        // iterate over state.reg_file.iter() in chunks of 4 registers
+                        for chunk in state.reg_file.all().chunks(4) {
+                            for reg in chunk {
+                                ui.label(reg.0.to_string());
+                                ui.label(format!("0x{:08X} ({})", reg.1, reg.1,));
+                            }
+                            ui.end_row();
+                        }
+                    });
+            })
+    });
+}

emulator/src/emulator/ui/display.rs

@@ -0,0 +1,92 @@
+use crate::emulator::{
+    system::model::{Command, State},
+    ui::interface::{Category, Component},
+};
+
+use eframe::egui;
+use egui::{Color32, FontId, Vec2};
+
+const VGA_WIDTH: usize = 80;
+const VGA_HEIGHT: usize = 25;
+
+pub struct Display {
+    visible: bool,
+}
+
+impl Display {
+    #[must_use]
+    pub const fn new() -> Self {
+        Self { visible: false }
+    }
+}
+
+impl Default for Display {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Component for Display {
+    fn name(&self) -> &'static str {
+        "Display"
+    }
+
+    fn category(&self) -> Category {
+        Category::IO
+    }
+
+    fn visible(&mut self) -> &mut bool {
+        &mut self.visible
+    }
+
+    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);
+
+        let char_width = ui.fonts(|f| f.glyph_width(&font_id, 'W'));
+        let line_height = ui.fonts(|f| f.row_height(&font_id));
+
+        #[expect(clippy::cast_precision_loss)]
+        let display_size = Vec2::new(
+            char_width * VGA_WIDTH as f32,
+            line_height * VGA_HEIGHT as f32,
+        );
+
+        let (rect, _response) = ui.allocate_exact_size(display_size, egui::Sense::all());
+
+        // Fill background
+        // ui.painter().rect_filled(rect, 0.0, Color32::BLACK);
+
+        // Draw text
+        for y in 0..VGA_HEIGHT {
+            let mut row_text = String::with_capacity(VGA_WIDTH);
+            for x in 0..VGA_WIDTH {
+                let index = y * VGA_WIDTH + x;
+                if index < display.len() {
+                    let byte = display[index];
+                    let ch = if (32..=126).contains(&byte) {
+                        byte as char
+                    } else {
+                        ' '
+                    };
+                    row_text.push(ch);
+                } else {
+                    row_text.push(' ');
+                }
+            }
+
+            #[expect(clippy::cast_precision_loss)]
+            let text_pos = rect.min + Vec2::new(0.0, y as f32 * line_height);
+
+            ui.painter().text(
+                text_pos,
+                egui::Align2::LEFT_TOP,
+                row_text,
+                font_id.clone(),
+                Color32::WHITE,
+            );
+        }
+    }
+}

emulator/src/emulator/ui/editor.rs

@@ -0,0 +1,545 @@
+use std::fmt::Write;
+use std::{
+    ffi::OsStr,
+    fs,
+    path::{Path, PathBuf},
+};
+
+use common::prelude::Instruction;
+use egui::{Align, Context, Key, Layout, Ui};
+
+use dsa_editor::{CodeEditor, ColorTheme, Syntax};
+use egui_file::FileDialog;
+
+use crate::emulator::{
+    system::model::{Command, State},
+    ui::interface::Component,
+};
+
+use assembler::prelude::*;
+
+#[derive(Default)]
+pub struct Editor {
+    // editor state
+    path: Option<PathBuf>,
+    unsaved: bool,
+    text: String,
+    buffer: String,
+
+    // output / loading
+    output: Vec<u8>,
+    load_offset: u32,
+    offset_str: String,
+
+    // cursor - currently unused
+    cursor_col: usize,
+    cursor_line: usize,
+
+    // file dialogs
+    open_file_dialog: Option<FileDialog>,
+    save_file_dialog: Option<FileDialog>,
+
+    // other
+    visible: bool,
+    error: Option<String>,
+}
+
+impl Component for Editor {
+    fn name(&self) -> &'static str {
+        "Editor"
+    }
+
+    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) {
+        if self.buffer != self.text {
+            self.unsaved = true;
+        }
+
+        ui.vertical(|ui| {
+            // Top bar
+
+            if ui.input(|i| i.key_pressed(Key::S) && i.modifiers.ctrl) {
+                self.save();
+            }
+
+            self.render_toolbar(state, ui, ctx);
+
+            ui.add_space(4.0); // Add some spacing instead of just a separator
+            ui.separator();
+
+            let remaining_height = f32::max(ui.available_height() - 100.0, 100.0);
+
+            ui.allocate_ui_with_layout(
+                egui::Vec2::new(ui.available_width(), remaining_height),
+                Layout::left_to_right(Align::Min),
+                |ui| {
+                    self.render_editor(state, ui, ctx);
+                    ui.separator();
+                    self.render_output(state, ui, ctx);
+                },
+            );
+
+            self.render_bottom_bar(state, ui, ctx);
+        });
+    }
+}
+
+impl Editor {
+    #[must_use]
+    pub const fn new() -> Self {
+        Self {
+            path: None,
+            text: String::new(),
+            buffer: String::new(),
+            output: Vec::new(),
+            unsaved: true,
+            cursor_col: 1,
+            cursor_line: 1,
+            visible: false,
+            load_offset: 0,
+            offset_str: String::new(),
+            error: None,
+            open_file_dialog: None,
+            save_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 extension(&self) -> &str {
+        if let Some(path) = &self.path {
+            return path
+                .extension()
+                .map_or_else(|| OsStr::new("Unknown!"), |ext| ext)
+                .to_str()
+                .map_or_else(
+                    || unreachable!("File name should be valid UTF-8."),
+                    |ext| ext,
+                );
+        }
+        "Unknown!"
+    }
+
+    fn save(&mut self) {
+        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 let Some(path) = &self.path {
+            // Save to existing path
+            self.buffer = self.text.clone();
+
+            let text = if path.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.as_bytes().to_vec()
+            };
+
+            if let Err(why) = std::fs::write(path, text) {
+                self.error = Some(format!("Failed to save file: {why}"));
+            } else {
+                self.unsaved = false;
+            }
+        } else {
+            // Open the save dialog.
+            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.save_file_dialog.is_none() {
+                let mut dialog = FileDialog::save_file(Some(work_dir));
+                dialog.open();
+                self.save_file_dialog = Some(dialog);
+            }
+        }
+    }
+
+    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.save_file_dialog.is_some() {
+            // TODO: Flash an error stating you can only have one menu open at once.
+            self.save_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) => {
+                            let mut res = String::new();
+                            for (i, b) in content.iter().enumerate() {
+                                _ = write!(res, "{b:02x}");
+                                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
+            && 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 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_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")),
+            _ => None,
+        };
+
+        let ed = CodeEditor::default()
+            .id_source("editor")
+            .with_fontsize(12.0)
+            .with_rows(0)
+            .with_theme(ColorTheme::default())
+            .with_syntax(Syntax::dsa())
+            .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);
+    }
+
+    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),
+            );
+
+            // line and col
+            ui.with_layout(egui::Layout::right_to_left(egui::Align::Center), |ui| {
+                ui.label(format!("Ln {}, Col {}", self.cursor_line, self.cursor_col));
+            });
+        });
+    }
+
+    fn build(&mut self) {
+        if let Some(path) = &self.path {
+            match path.extension().and_then(|ext| ext.to_str()) {
+                Some("dsa") => {
+                    let mut compiler = CompilerEngine::new();
+                    compiler.start_compilation(path);
+
+                    // Or block until done
+                    let instructions = match compiler.wait_for_result() {
+                        Ok(instructions) => instructions,
+                        Err(e) => {
+                            self.error = Some(e.to_string());
+                            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;
+                    } else {
+                        self.error = Some("Failed to read file".to_string());
+                    }
+                }
+                _ => {
+                    self.error = Some(format!("Invalid file type: {}", self.filename()));
+                }
+            }
+        }
+    }
+
+    fn render_toolbar(&mut self, state: &State, ui: &mut Ui, ctx: &Context) {
+        self.handle_file_dialogs(ctx);
+
+        ui.horizontal(|ui| {
+            ui.label(format!("File type: {}", self.extension()));
+            ui.label(format!("Filename: {}", self.filename()));
+            ui.label(format!("Unsaved: {}", self.unsaved));
+
+            // number of lines in the file
+            ui.with_layout(egui::Layout::right_to_left(egui::Align::Center), |ui| {
+                let line_count = self.text.lines().count();
+                ui.label(format!("Lines: {line_count}"));
+            });
+        });
+
+        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();
+            }
+
+            // Saves the current file
+            if ui.button("Save").clicked() {
+                self.save();
+            }
+
+            // builds the current file
+            if ui.button("Build").clicked() && !self.unsaved {
+                self.build();
+            }
+
+            // 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/history.rs

@@ -0,0 +1,84 @@
+use egui::{Context, Ui};
+
+use crate::emulator::{
+    system::model::{Command, State},
+    ui::interface::Component,
+};
+
+pub struct History {
+    visible: bool,
+}
+
+impl Component for History {
+    fn name(&self) -> &'static str {
+        "Instruction History"
+    }
+
+    fn visible(&mut self) -> &mut bool {
+        &mut self.visible
+    }
+
+    fn category(&self) -> super::interface::Category {
+        super::interface::Category::Control
+    }
+
+    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.instruction_history.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 (idx, instruction) in
+                            state.instruction_history.iter().enumerate()
+                        {
+                            ui.label(format!("{idx}: "));
+
+                            // Hex column
+                            let addr = instruction.0;
+                            ui.label(
+                                egui::RichText::new(format!("0x{addr:08X}"))
+                                    .font(egui::FontId::monospace(12.0))
+                                    .color(egui::Color32::from_rgb(255, 200, 200)),
+                            );
+
+                            ui.label(
+                                egui::RichText::new(instruction.1.to_string())
+                                    .font(egui::FontId::monospace(12.0))
+                                    .color(egui::Color32::from_rgb(200, 255, 200)),
+                            );
+
+                            ui.end_row();
+                        }
+                    });
+            });
+    }
+}
+
+impl Default for History {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl History {
+    #[must_use]
+    pub const fn new() -> Self {
+        Self { visible: false }
+    }
+}

emulator/src/emulator/ui/interface.rs

@@ -0,0 +1,128 @@
+use crate::emulator::system::model::{Command, Running, State, StateUpdate};
+use std::sync::mpsc::{Receiver, Sender};
+
+pub trait Component {
+    fn render(&mut self, state: &mut State, ui: &mut egui::Ui, ctx: &egui::Context);
+    fn visible(&mut self) -> &mut bool;
+    fn name(&self) -> &'static str;
+    fn category(&self) -> Category;
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Category {
+    Control,
+    Memory,
+    IO,
+    Programming,
+}
+
+impl Category {
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::Control => "Control Systems",
+            Self::Memory => "Memory Systems",
+            Self::IO => "I/O Systems",
+            Self::Programming => "Programming",
+        }
+    }
+
+    #[must_use]
+    pub fn list() -> Vec<Self> {
+        vec![Self::Control, Self::Memory, Self::IO, Self::Programming]
+    }
+}
+
+pub struct EmulatorUI {
+    pub state: State,
+    pub components: Vec<Box<dyn Component>>,
+}
+
+impl EmulatorUI {
+    #[must_use]
+    pub fn new(sender: Sender<Command>, receiver: Receiver<StateUpdate>) -> Self {
+        Self {
+            state: State::new(sender, receiver),
+            components: vec![],
+        }
+    }
+
+    pub fn add_component(&mut self, component: Box<dyn Component>) {
+        self.components.push(component);
+    }
+}
+
+impl eframe::App for EmulatorUI {
+    fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) {
+        if let Err(e) = self.state.update() {
+            self.state.error_log.push(e.to_string());
+        }
+
+        if self.state.running == Running::Running {
+            ctx.request_repaint();
+        }
+
+        egui::TopBottomPanel::top("top_panel").show(ctx, |ui| {
+            ui.with_layout(
+                egui::Layout::top_down_justified(egui::Align::Center)
+                    .with_main_align(egui::Align::Min),
+                |ui| {
+                    ui.allocate_space(egui::vec2(0.0, 15.0));
+                    ui.heading("DSA Simulator (Damn Simple Architecture 🔥)");
+                    ui.allocate_space(egui::vec2(0.0, 15.0));
+                },
+            );
+        });
+
+        egui::CentralPanel::default().show(ctx, |ui| {
+            ui.with_layout(egui::Layout::left_to_right(egui::Align::Center), |_ui| {
+                egui::Window::new("Main Menu")
+                    .resizable(false)
+                    .default_width(300.0)
+                    .show(ctx, |ui| {
+                        super::menu::render_menu(self, ui, ctx);
+                    });
+
+                for c in &mut self.components {
+                    let mut visible = *c.visible();
+                    if visible {
+                        egui::Window::new(c.name())
+                            .open(&mut visible)
+                            .show(ctx, |ui| {
+                                c.render(&mut self.state, ui, ctx);
+                            });
+                    }
+                    *c.visible() = visible;
+                }
+            });
+        });
+
+        egui::TopBottomPanel::bottom("bottom_panel").show(ctx, |ui| {
+            ui.horizontal_centered(|ui| {
+                ui.group(|ui| {
+                    ui.add_space(10.0);
+                    ui.strong("Authors:");
+                    ui.add_space(5.0);
+                    ui.label("zxq5");
+                    ui.label("nullndvoid");
+                    ui.add_space(10.0);
+                    ui.separator();
+                    ui.add_space(10.0);
+                    ui.strong("Version");
+                    ui.add_space(5.0);
+                    ui.label("1.0.0");
+                    ui.add_space(10.0);
+                    ui.separator();
+                    ui.add_space(10.0);
+                    ui.strong("Source:");
+                    ui.add_space(5.0);
+                    ui.hyperlink_to(
+                        "https://git.zxq5.dev/LowLevelDevs/damn_simple_architecture",
+                        "https://git.zxq5.dev/LowLevelDevs/damn_simple_architecture",
+                    );
+                    ui.add_space(10.0);
+                });
+            });
+        });
+    }
+}

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

@@ -0,0 +1,162 @@
+use std::num::ParseIntError;
+
+use common::prelude::Instruction;
+
+use crate::emulator::{
+    system::model::{Command, State},
+    ui::interface::Component,
+};
+
+#[derive(Default)]
+pub struct MemoryInspector {
+    view_size: u32,
+    view_addr: u32,
+    visible: bool,
+    addr_input: String,
+}
+
+impl MemoryInspector {
+    #[must_use]
+    pub const fn new() -> Self {
+        Self {
+            view_size: 256,
+            view_addr: 0,
+            visible: false,
+            addr_input: String::new(),
+        }
+    }
+}
+
+impl Component for MemoryInspector {
+    fn category(&self) -> super::interface::Category {
+        super::interface::Category::Memory
+    }
+
+    fn name(&self) -> &'static str {
+        "Memory Inspector"
+    }
+
+    fn visible(&mut self) -> &mut bool {
+        &mut self.visible
+    }
+
+    fn render(&mut self, state: &mut State, ui: &mut egui::Ui, ctx: &egui::Context) {
+        // Right column - Memory
+        ui.vertical(|ui| {
+            ui.heading("Memory Inspector");
+            ui.add_space(10.0);
+
+            // Address input section
+            ui.horizontal(|ui| {
+                ui.label("Address:");
+
+                let address_response = ui.add(
+                    egui::TextEdit::singleline(&mut self.addr_input)
+                        .hint_text("0x1000 or 4096")
+                        .desired_width(150.0),
+                );
+
+                ui.add_space(10.0);
+
+                // Search button
+                let search_clicked = ui.button("🔍 Search").clicked();
+
+                // Handle Enter key in text field
+                let enter_pressed = address_response.lost_focus()
+                    && 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;
+                    } else {
+                        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_log.last() {
+                ui.colored_label(egui::Color32::RED, format!("Error: {error}"));
+            }
+
+            ui.add_space(10.0);
+
+            // Memory table
+            egui::ScrollArea::vertical()
+                .auto_shrink(true)
+                .id_salt("memory_inspector_scroll")
+                .show(ui, |ui| {
+                    egui::Grid::new("memory_grid")
+                        .spacing([12.0, 2.0])
+                        .min_col_width(5.0)
+                        .striped(true)
+                        .show(ui, |ui| {
+                            // Header
+                            ui.strong("Address");
+
+                            for i in 0..4 {
+                                ui.strong(format!("{i:X}"));
+                            }
+
+                            ui.strong("Decimal");
+                            ui.strong("Instruction");
+
+                            ui.end_row();
+
+                            // Memory data (8 bytes per row)
+                            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})"
+                                ));
+                                for &byte in chunk {
+                                    ui.monospace(format!("{byte:02X}"));
+                                }
+
+                                // Fill remaining columns if last row is incomplete
+                                for _ in chunk.len()..4 {
+                                    ui.label("");
+                                }
+
+                                // combine all 4 bytes in the chunk into a u32
+                                let combined = chunk.iter().fold(0u32, |acc, &byte| {
+                                    (acc << 8) | u32::from(byte)
+                                });
+
+                                ui.monospace(format!("{combined}"));
+                                ui.monospace(format!(
+                                    "{}",
+                                    Instruction::decode(combined)
+                                        .unwrap_or(Instruction::Nop)
+                                ));
+
+                                ui.end_row();
+                            }
+                        });
+                });
+        });
+    }
+}
+
+fn parse_address(address: &str) -> Result<u32, ParseIntError> {
+    if let Some(hex_part) = address.strip_prefix("0x") {
+        return u32::from_str_radix(hex_part, 16);
+    }
+
+    if let Some(bin_part) = address.strip_prefix("0b") {
+        return u32::from_str_radix(bin_part, 2);
+    }
+
+    if let Some(oct_part) = address.strip_prefix("0o") {
+        return u32::from_str_radix(oct_part, 8);
+    }
+
+    address.parse::<u32>()
+}

emulator/src/emulator/ui/menu.rs

@@ -0,0 +1,30 @@
+use crate::emulator::ui::interface::{Category, EmulatorUI};
+
+pub fn render_menu(state: &mut EmulatorUI, ui: &mut egui::Ui, _ctx: &egui::Context) {
+    ui.with_layout(
+        egui::Layout::top_down_justified(egui::Align::Center),
+        |ui| {
+            ui.set_max_width(300.0);
+            ui.set_min_width(300.0);
+            ui.spacing_mut().button_padding = egui::vec2(10.0, 5.0);
+
+            for cat in Category::list() {
+                ui.add_space(10.0);
+                ui.heading(cat.as_str());
+                ui.add_space(10.0);
+
+                for comp in &mut state.components {
+                    let name = comp.name();
+                    if comp.category() == cat {
+                        ui.toggle_value(comp.visible(), name);
+                    }
+                }
+
+                ui.add_space(10.0);
+                ui.separator();
+            }
+
+            ui.add_space(10.0);
+        },
+    );
+}

emulator/src/emulator/ui/mod.rs

@@ -0,0 +1,9 @@
+pub mod control_unit;
+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

@@ -0,0 +1,79 @@
+use crate::emulator::{
+    system::model::{Command, State},
+    ui::interface::Component,
+};
+
+use common::instructions::Register;
+
+pub struct StackInspector {
+    visible: bool,
+}
+
+impl Default for StackInspector {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl StackInspector {
+    #[must_use]
+    pub const fn new() -> Self {
+        Self { visible: false }
+    }
+}
+
+impl Component for StackInspector {
+    fn visible(&mut self) -> &mut bool {
+        &mut self.visible
+    }
+
+    fn name(&self) -> &'static str {
+        "Stack Inspector"
+    }
+
+    fn category(&self) -> super::interface::Category {
+        super::interface::Category::Memory
+    }
+
+    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()
+                .id_salt("stack_inspector_scroll")
+                .show(ui, |ui| {
+                    egui::Grid::new("stack_grid")
+                        .num_columns(2)
+                        .spacing([40.0, 4.0])
+                        .striped(true)
+                        .show(ui, |ui| {
+                            ui.label("Address");
+                            ui.label("Value");
+                            ui.end_row();
+
+                            for (i, value) in
+                                state.stack_view.chunks(4).take(32).enumerate()
+                            {
+                                let value = u32::from_be_bytes(value.try_into().expect(
+                                    "Could not read 4 byte instruction or data! Something is wrong.",
+                                ));
+                                ui.label(format!(
+                                    "{} [{}]",
+                                    i,
+                                    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();
+                            }
+
+                            if state.stack_view.is_empty() {
+                                ui.label("(empty)");
+                                ui.label("-");
+                                ui.end_row();
+                            }
+                        });
+                });
+        });
+    }
+}

emulator/src/lib.rs

@@ -0,0 +1,132 @@
+#![deny(
+    clippy::unwrap_used,
+    clippy::nursery,
+    clippy::perf,
+    clippy::pedantic,
+    clippy::complexity
+)]
+#![allow(
+    clippy::cast_possible_truncation,
+    clippy::missing_panics_doc,
+    clippy::missing_errors_doc,
+    clippy::match_wildcard_for_single_variants
+)]
+
+pub mod emulator;
+
+use std::{
+    sync::{
+        Arc,
+        mpsc::{Receiver, Sender},
+    },
+    thread,
+};
+
+#[cfg(target_os = "android")]
+use winit::platform::android::{EventLoopBuilderExtAndroid, activity::AndroidApp};
+
+use crate::emulator::{
+    misc::rpc::RpcClient,
+    system::{
+        emulator::run_emulator,
+        memory::MainStore,
+        model::{Command, StateUpdate},
+        processor::Processor,
+    },
+    ui::{
+        control_unit::ControlPanel, display::Display, editor::Editor,
+        interface::EmulatorUI, memory_inspector::MemoryInspector,
+        stack_inspector::StackInspector,
+    },
+};
+
+#[cfg(target_os = "android")]
+#[unsafe(no_mangle)]
+pub fn android_main(app: AndroidApp) -> Result<(), Box<dyn std::error::Error>> {
+    use crate::emulator::{config::Config, misc::rpc::get_rpc_client_or_none};
+    use std::path::Path;
+
+    // Initialize channels and read in configuration.
+    let (cmd_sender, cmd_receiver) = std::sync::mpsc::channel();
+    let (state_sender, state_reciever) = std::sync::mpsc::channel();
+    let config = Config::load(Path::new(".dsa.emulator.toml"))?;
+
+    // Setup RPC if enabled.
+    let (rpc_sender, rpc_reciever) = std::sync::mpsc::channel();
+
+    let rpc_client =
+        get_rpc_client_or_none(&config, rpc_sender, rpc_reciever)?.map(Arc::new);
+
+    setup_emulator(cmd_receiver, state_sender, rpc_client);
+
+    let ui = setup_ui(cmd_sender, state_reciever);
+
+    // Run UI.
+    #[allow(unused_variables)]
+    let options = eframe::NativeOptions {
+        viewport: egui::ViewportBuilder::default().with_inner_size([800.0, 600.0]),
+        event_loop_builder: Some(Box::new(move |builder| {
+            #[cfg(target_os = "android")]
+            builder.with_android_app(app);
+        })),
+        ..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))
+        }),
+    )?;
+
+    Ok(())
+}
+
+pub fn setup_emulator(
+    cmd_receiver: Receiver<Command>,
+    state_sender: Sender<StateUpdate>,
+    rpc_client: Option<Arc<RpcClient>>,
+) {
+    let main_store = MainStore::new();
+    let processor = Processor::new(Box::new(main_store), vec![]);
+
+    thread::spawn(move || {
+        run_emulator(&cmd_receiver, &state_sender, processor, rpc_client.as_ref());
+    });
+}
+
+/// Creates the [`EmulatorUI`].
+#[must_use]
+pub fn setup_ui(
+    cmd_sender: Sender<Command>,
+    state_reciever: Receiver<StateUpdate>,
+) -> EmulatorUI {
+    let mut ui = EmulatorUI::new(cmd_sender, state_reciever);
+
+    // Create UI modules.
+    let control_unit = ControlPanel::new();
+
+    ui.add_component(Box::new(control_unit));
+
+    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();
+    ui.add_component(Box::new(editor));
+
+    let display = Display::new();
+    ui.add_component(Box::new(display));
+
+    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
+}

emulator/src/main.rs

@@ -0,0 +1,39 @@
+use std::path::Path;
+use std::sync::Arc;
+
+use dsa_rs::emulator::{config::Config, misc::rpc::get_rpc_client_or_none};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Initialize channels and read in configuration.
+    let (cmd_sender, cmd_receiver) = std::sync::mpsc::channel();
+    let (state_sender, state_reciever) = std::sync::mpsc::channel();
+    let config = Config::load(Path::new(".dsa.emulator.toml"))?;
+
+    // Setup RPC if enabled.
+    let (rpc_sender, rpc_reciever) = std::sync::mpsc::channel();
+
+    let rpc_client =
+        get_rpc_client_or_none(&config, rpc_sender, rpc_reciever)?.map(Arc::new);
+
+    dsa_rs::setup_emulator(cmd_receiver, state_sender, rpc_client);
+
+    let ui = dsa_rs::setup_ui(cmd_sender, state_reciever);
+
+    // Run UI.
+    #[allow(unused_variables)]
+    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))
+        }),
+    )?;
+
+    Ok(())
+}

resources/dsa/bf.dsa

@@ -0,0 +1,224 @@
+
+// a simple brainf##k interpreter,
+// because I already wrote a compiler lol.
+
+include print "./lib/io/print.dsa"
+
+// "print hello world"
+db program: "++++++++++++++++++++++++++++++++++++++++++++
+>++++++++++++++++++++++++++++++++
+>++++++++++++++++
+>
+>+
+<<
+[
+>>
+>
+>++++++++++
+<<
+[->+>-[>+>>]>[+[-<+>]>+>>]<<<<<<]
+>[<+>-]
+>[-]
+>>
+>++++++++++
+<
+[->-[>+>>]>[+[-<+>]>+>>]<<<<<]
+>[-]
+>>[++++++++++++++++++++++++++++++++++++++++++++++++.[-]]
+<[++++++++++++++++++++++++++++++++++++++++++++++++.[-]]
+<<<++++++++++++++++++++++++++++++++++++++++++++++++.[-]
+<<<<<<<.>.
+>>[>>+<<-]
+>[>+<<+>-]
+>[<+>-]
+<<<-
+]
+<<++..."
+
+db error: "Invalid Instruction!"
+dw stack: 0x10000
+dw input: 0x30000
+resb data: 1024
+
+// set up a stack so we can call functions
+_init_stack:
+    ldw stack, bpr
+    mov bpr, spr
+
+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
+    // rg2 is the value at the data pointer
+    // rg3 stores the current instruction
+    // rg4 is the expression nesting level.
+
+    lli 43, rg8 // + = 43 increment
+    lli 45, rg9 // - = 45 decrement
+    lli 62, rga // > = 62 increment pointer
+    lli 60, rgb // < = 60 decrement pointer
+    lli 46, rgc // . = 46 output
+    lli 44, rgd // , = 44 input
+    lli 91, rge // [ = 91 loop start
+    lli 93, rgf // ] = 93 loop end
+
+loop_start:
+    // load the current instruction into rg3
+    ldb rg0, rg3
+
+    // switch on the instruction
+    // all cases will return to either loop_start or loop_end
+    cmp rg3, rg8
+    jeq increment
+    cmp rg3, rg9
+    jeq decrement
+    cmp rg3, rga
+    jeq inc_ptr
+    cmp rg3, rgb
+    jeq dec_ptr
+    cmp rg3, rgc
+    jeq output
+    cmp rg3, rgd
+    jeq input
+    cmp rg3, rge
+    jeq expr_start
+    cmp rg3, rgf
+    jeq expr_end
+    cmp rg3, zero
+    jeq end
+
+	// if we get here, we don't know what the instruction is
+	lwi error, rg2
+    pusha 2
+    push rg2
+    call print::print
+    pop zero
+    popa 2
+
+end:
+    hlt
+
+loop_end:
+    inc rg0
+    jmp loop_start
+
+// ------------------------------------------
+// increment the current cell
+increment:
+    inc rg2
+    jmp loop_end
+
+// ------------------------------------------
+// decrement the current cell
+decrement:
+    dec rg2
+    jmp loop_end
+
+// ------------------------------------------
+// increment the pointer
+inc_ptr:
+    stw rg2, rg1
+    addi rg1, 4
+    ldw rg1, rg2
+    jmp loop_end
+
+// ------------------------------------------
+// decrement the pointer
+dec_ptr:
+    stw rg2, rg1
+    subi rg1, 4
+    ldw rg1, rg2
+    jmp loop_end
+
+// ------------------------------------------
+// print the byte in the current cell
+output:
+    pusha 2
+    push rg2
+    call print::print_byte
+    pop zero
+    popa 2
+    jmp loop_end
+
+// ------------------------------------------
+// read a byte into the current cell
+input:
+    ldw input, rg2
+    jmp loop_end
+
+// ------------------------------------------
+// handle an open bracket instruction
+expr_start:
+    cmp rg2, zero
+    jne loop_end
+
+_traverse_right_start:
+    // push a register that definitely has a nonzero value
+    // when we pop this value from the stack
+    // we know we've finished traversing.
+    push rg8
+
+_traverse_right:
+    inc rg0
+    ldb rg0, rg3
+
+    cmp rg3, rge
+    jeq open_right
+    cmp rg3, rgf
+    jeq close_right
+    cmp rg3, zero
+    jeq end
+    jmp _traverse_right
+
+open_right:
+    // push zero to the stack
+    push zero
+    jmp _traverse_right
+
+close_right:
+    // check if we've reached the bottom of the stack
+    pop rg4
+    cmp rg4, zero
+    jeq _traverse_right
+
+    // go to next instruction after closing bracket
+    inc rg0
+    jmp loop_start
+
+// ------------------------------------------
+// handle the close bracket instruction
+expr_end:
+    cmp rg2, zero
+    jeq loop_end
+
+_traverse_left_start:
+	push rg8
+_traverse_left:
+	dec rg0
+	ldb rg0, rg3
+
+	cmp rg3, rge
+	jeq open_left
+	cmp rg3, rgf
+	jeq close_left
+	cmp rg3, zero
+	jeq end
+	jmp _traverse_left
+
+open_left:
+    // check if we've reached the bottom of the stack
+    pop rg4
+    cmp rg4, zero
+    jeq _traverse_left
+
+    // go to next instruction after open bracket
+    inc rg0
+    jmp loop_start
+
+close_left:
+    // push zero to the stack
+    push zero
+    jmp _traverse_left

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
+	irt
+
+setup_hard_fault_handler:
+    push bpr
+    mov spr, bpr
+
+    lwi handle_hard_fault, rg0
+    stw rg0, idr, 4
+
+    mov bpr, spr
+    pop bpr
+    irt
+
+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/io/print.dsa

@@ -0,0 +1,244 @@
+// 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
+//
+
+include maths "../maths/core.dsa"
+
+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
+
+    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
+
+// ------------------------------------------
+// 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,60 @@
+// 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
+
+_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

resources/dsa/lib/maths/fib.dsa

@@ -0,0 +1,31 @@
+include print "../io/print.dsa"
+
+fib_n:
+	push bpr
+	mov spr, bpr
+
+	ldw bpr, rg0, 8  // load arg
+    mov rg1, rg2
+    lwi 1, rg1
+
+start:
+    add rg1, rg2, rg3
+
+    pusha 4
+    push rg1
+    call print::print_hex_byte
+    call print::print_newline
+    pop zero
+    popa 4
+
+    mov rg2, rg1
+    mov rg3, rg2
+
+    dec rg0
+    cmp rg0, zero
+    jgt start
+
+    stw rg1, bpr, 8
+    mov bpr, spr
+    pop bpr
+    return

resources/dsa/main.dsa

@@ -0,0 +1,80 @@
+include fib: "./lib/maths/fib.dsa" 
+include maths: "./lib/maths/core.dsa"
+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
+
+dw string: "hello world"
+start:
+
+	lwi 37, rg0
+	lwi 12, rg1
+	push rg0
+	push rg1
+	call maths::divmod
+	pop rg0 // result
+	pop rg1 // remainder
+
+	push rg1
+	push rg0
+	call print::print_hex_byte
+	call print::print_whitespace
+	pop zero
+	call print::print_hex_byte
+	call print::print_newline
+
+	lwi string, rg0
+    //lwi 10, rg0
+    pusha 4
+	push rg0
+	call print::print
+    //call fib::fib_n
+    pop zero
+	call print::print_newline
+	popa 4
+
+	pusha 4
+	push rg0
+	call print::print
+    //call fib::fib_n
+    pop zero
+	call print::print_newline
+	popa 4
+
+	pusha 4
+	push rg0
+	call print::print
+    //call fib::fib_n
+    pop zero
+	call print::print_newline
+	popa 4
+
+	pusha 4
+	push rg0
+	call print::print
+    //call fib::fib_n
+    pop zero
+	call print::print_newline
+	popa 4
+
+    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/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/emulator/AndroidManifest.xml

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="utf-8"?>
+<?xml-model href="http://schemas.android.com/apk/res/android"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.dsa.emulator"
+    android:versionCode="1"
+    android:versionName="1.0">
+
+    <uses-sdk android:minSdkVersion="23" android:targetSdkVersion="35" />
+    <uses-feature android:glEsVersion="0x00020000" android:required="true" />
+    <!-- <uses-permission android:name="android.permission.INTERNET" /> -->
+    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
+    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
+
+    <application
+        android:label="DSA Emulator"
+        android:icon="@mipmap/ic_launcher"
+        android:hasCode="false"
+        android:hardwareAccelerated="true">
+        <activity
+            android:name="android.app.NativeActivity"
+            android:label="DSA Emulator"
+            android:exported="true"
+            android:configChanges="orientation|keyboardHidden|screenSize"
+            android:screenOrientation="unspecified"
+            android:launchMode="singleInstance">
+            <meta-data
+                android:name="android.app.lib_name"
+                android:value="dsa_rs" />
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+</manifest>

resources/emulator/build_android.ps1

@@ -0,0 +1,74 @@
+#!/usr/bin/env pwsh
+
+$env:ANDROID_HOME = "C:\Users\jacob\AppData\Local\Android\Sdk"
+$TOOL_PREFIX = "$env:ANDROID_HOME\build-tools\33.0.0"
+
+# Only really works on Windows, for aarch64.
+
+# Create directories
+New-Item -ItemType Directory -Force -Path "..\target\apk_build\lib\arm64-v8a"
+New-Item -ItemType Directory -Force -Path "..\target\apk_build\res\values"
+New-Item -ItemType Directory -Force -Path "..\target\apk_build\res\mipmap-hdpi"
+New-Item -ItemType Directory -Force -Path "..\target\apk_build\res\mipmap-mdpi"
+New-Item -ItemType Directory -Force -Path "..\target\apk_build\res\mipmap-xhdpi"
+New-Item -ItemType Directory -Force -Path "..\target\apk_build\res\mipmap-xxhdpi"
+
+# Copy the shared library
+Copy-Item "..\target\aarch64-linux-android\release\libdsa_rs.so" "..\target\apk_build\lib\arm64-v8a\"
+
+# Copy the manifest
+Copy-Item "..\resources\emulator\AndroidManifest.xml" "..\target\apk_build\AndroidManifest.xml"
+
+# Copy the icons
+Copy-Item "..\resources\emulator\AppIcon.png" "..\target\apk_build\res\mipmap-hdpi\ic_launcher.png"
+Copy-Item "..\resources\emulator\AppIcon.png" "..\target\apk_build\res\mipmap-mdpi\ic_launcher.png"
+Copy-Item "..\resources\emulator\AppIcon.png" "..\target\apk_build\res\mipmap-xhdpi\ic_launcher.png"
+Copy-Item "..\resources\emulator\AppIcon.png" "..\target\apk_build\res\mipmap-xxhdpi\ic_launcher.png"
+
+# Create strings.xml
+@"
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="app_name">DSA Emulator</string>
+</resources>
+"@ | Out-File -FilePath "..\target\apk_build\res\values\strings.xml" -Encoding utf8
+
+# Change to build directory
+Push-Location "..\target\apk_build"
+
+try {
+    # Compile resources
+    & "$TOOL_PREFIX\aapt2.exe" compile --dir res -o compiled_resources.zip
+
+    # Link resources
+    & "$TOOL_PREFIX\aapt2.exe" link -o unaligned.apk `
+        -I "$env:ANDROID_HOME\platforms\android-35\android.jar" `
+        --manifest AndroidManifest.xml `
+        compiled_resources.zip
+
+    # Add native libraries to APK
+    & "C:\Program Files\7-Zip\7z.exe" a -tzip unaligned.apk lib\*
+
+    # Align APK
+    & "$TOOL_PREFIX\zipalign.exe" -v 4 unaligned.apk aligned.apk
+
+    # Generate debug keystore if it doesn't exist
+    if (-not (Test-Path "debug.keystore")) {
+        & keytool -genkey -v -keystore debug.keystore -alias androiddebugkey -keyalg RSA -keysize 2048 -validity 10000 -storepass android -keypass android -dname "CN=Android Debug,O=Android,C=US"
+    }
+
+    # Sign APK
+    & "$TOOL_PREFIX\apksigner.bat" sign --ks debug.keystore --ks-key-alias androiddebugkey --ks-pass pass:android --key-pass pass:android --out dsa_emulator.apk aligned.apk
+
+    # Copy final APK
+    Copy-Item "dsa_emulator.apk" "..\dsa_emulator.apk"
+
+    Write-Host "APK created successfully at: ..\target\dsa_emulator.apk" -ForegroundColor Green
+}
+catch {
+    Write-Error "Build failed: $_"
+}
+finally {
+    # Return to original directory
+    Pop-Location
+}

resources/emulator/build_android.sh

@@ -0,0 +1,46 @@
+#!/bin/sh
+
+export ANDROID_HOME="/mnt/c/Users/jacob/AppData/Local/Android/Sdk"
+export TOOL_PREFIX="$ANDROID_HOME/build-tools/35.0.1"
+
+# Only really works on Linux, for aarch64.
+
+mkdir -p ../target/apk_build/lib/arm64-v8a
+mkdir -p ../target/apk_build/res/values
+mkdir -p ../target/apk_build/res/mipmap-hdpi
+mkdir -p ../target/apk_build/res/mipmap-mdpi
+mkdir -p ../target/apk_build/res/mipmap-xhdpi
+mkdir -p ../target/apk_build/res/mipmap-xxhdpi
+
+# Copy the shared library.
+cp ../target/aarch64-linux-android/release/libdsa_rs.so ../target/apk_build/lib/arm64-v8a/
+
+# Copy the manifest.
+cp AndroidManifest.xml ../target/apk_build/AndroidManifest.xml
+
+cat << EOF > ../target/apk_build/res/values/strings.xml
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="app_name">DSA Emulator</string>
+</resources>
+EOF
+
+pushd ../target/apk_build
+
+$TOOL_PREFIX/aapt2 compile --dir res -o compiled_resources.zip
+$TOOL_PREFIX/aapt2 link -o unaligned.apk \
+    -I "$ANDROID_HOME/platforms/android-35/android.jar" \
+    --manifest AndroidManifest.xml \
+    compiled_resources.zip
+
+zip -r unaligned.apk lib/
+
+$TOOL_PREFIX/zipalign -v 4 unaligned.apk aligned.apk
+
+keytool -genkey -v -keystore debug.keystore -alias androiddebugkey -keyalg RSA -keysize 2048 -validity 10000 -storepass android -keypass android -dname "CN=Android Debug,O=Android,C=US"
+
+$TOOL_PREFIX/apksigner sign --ks debug.keystore --ks-key-alias androiddebugkey --ks-pass pass:android --key-pass pass:android --out dsa_emulator.apk aligned.apk
+
+cp dsa_emulator.apk ../dsa_emulator.apk
+
+popd

src/main.rs

@@ -0,0 +1,53 @@
+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))
+        }),
+    )
+}