misc: update release profile for optimised builds

TODO: Verify output is as expected, perhaps I can dump to file and compare token stream with known valid one?

Will add some extra tests of course!

.cargo/config.toml

@@ -0,0 +1,11 @@
+[build]
+rustc-wrapper = "sccache"
+# Enable to cut unused deps.
+# rustflags = ["-D", "unused-crate-dependencies"]
+
+[future-incompat-report]
+frequency = "always"
+
+[profile.profiling]
+inherits = "release"
+debug = true

.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

@@ -1,2 +1,2 @@
-book
-target
+/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,9 @@
+{
+  "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
+}

Cargo.toml

@@ -0,0 +1,21 @@
+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.
+
+[profile.release]
+incremental = true
+lto = "fat"

README.md

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

assembler/Cargo.toml

@@ -0,0 +1,21 @@
+[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]
+clap = { version = "4.5.40", features = ["derive"] }
+common = { path = "../common" }
+num_cpus = "1.17.0"
+regex = "1.11.1"
+threadpool = "1.8.1"
+uuid = { version = "1.17.0", features = ["v4"] }

assembler/brainf.bf

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

assembler/src/args.rs

@@ -0,0 +1,21 @@
+use clap::{Parser, ValueEnum};
+
+#[derive(Debug, Parser, Default)]
+pub struct Args {
+    /// The output format to assemble to. Currently just ELF or a flat binary.
+    #[arg(value_enum)]
+    output_format: Option<OutputFormat>,
+    /// Whether the relocatable object files should be statically linked into a single
+    /// executable or library.
+    link: bool,
+}
+
+#[derive(Debug, Clone, Copy, ValueEnum, Default)]
+/// The executable format the output should take.
+pub enum OutputFormat {
+    /// An ELF file.
+    #[default]
+    Elf,
+    /// A flat binary file.
+    Flat,
+}

assembler/src/compiler_engine.rs

@@ -0,0 +1,374 @@
+//! Simple compiler engine that orchestrates the entire compilation process.
+
+use std::collections::{HashMap, HashSet};
+use std::fmt;
+use std::path::Path;
+use std::sync::mpsc;
+use std::thread;
+
+use crate::error::{AssembleErrorKind, IoErrorKind};
+use crate::{
+    context::AssemblerContext,
+    error::AssembleError,
+    model::module::ModuleId,
+    source::{token::Token, tokeniser::Tokeniser},
+};
+
+use common::instructions::Instruction;
+
+/// Error type for the `CompilerEngine`
+#[derive(Debug)]
+pub enum EngineError {
+    /// Assembly error during compilation
+    Assembly(AssembleError),
+    /// Channel communication error
+    Channel(String),
+    /// Other generic error
+    Other(String),
+}
+
+impl fmt::Display for EngineError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Assembly(e) => write!(f, "Assembly error: {e}"),
+            Self::Channel(msg) => write!(f, "Channel error: {msg}"),
+            Self::Other(msg) => write!(f, "Engine error: {msg}"),
+        }
+    }
+}
+
+impl std::error::Error for EngineError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Assembly(e) => Some(e),
+            Self::Channel(_) | Self::Other(_) => None,
+        }
+    }
+}
+
+// Convert from AssembleError
+impl From<AssembleError> for EngineError {
+    fn from(error: AssembleError) -> Self {
+        Self::Assembly(error)
+    }
+}
+
+// Convert from mpsc::SendError
+impl<T> From<mpsc::SendError<T>> for EngineError {
+    fn from(error: mpsc::SendError<T>) -> Self {
+        Self::Channel(format!("Send error: {error}"))
+    }
+}
+
+// Convert from mpsc::RecvError
+impl From<mpsc::RecvError> for EngineError {
+    fn from(error: mpsc::RecvError) -> Self {
+        Self::Channel(format!("Receive error: {error}"))
+    }
+}
+
+// Convert from mpsc::TryRecvError
+impl From<mpsc::TryRecvError> for EngineError {
+    fn from(error: mpsc::TryRecvError) -> Self {
+        Self::Channel(format!("Try receive error: {error}"))
+    }
+}
+
+// Convert from String for generic errors
+impl From<String> for EngineError {
+    fn from(error: String) -> Self {
+        Self::Other(error)
+    }
+}
+
+// Convert from &str for convenience
+impl From<&str> for EngineError {
+    fn from(error: &str) -> Self {
+        Self::Other(error.to_string())
+    }
+}
+
+/// Simple compiler engine that orchestrates the entire compilation process.
+pub struct CompilerEngine {
+    result_tx: mpsc::Sender<Result<Vec<Instruction>, EngineError>>,
+    result_rx: Option<mpsc::Receiver<Result<Vec<Instruction>, EngineError>>>,
+    is_running: bool,
+}
+
+impl CompilerEngine {
+    /// Create a new compiler engine
+    #[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<P: AsRef<Path>>(&mut self, src: P) {
+        if self.is_running {
+            return;
+        }
+
+        let src = src.as_ref().to_path_buf();
+        let tx = self.result_tx.clone();
+
+        thread::spawn(move || {
+            let result = assemble(&src).map_err(EngineError::from);
+            let _ = tx.send(result); // Ignore send errors if receiver is dropped
+        });
+
+        self.is_running = true;
+    }
+
+    /// Check if compilation is complete and get the result
+    pub fn try_get_result(&mut self) -> Option<Result<Vec<Instruction>, EngineError>> {
+        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(EngineError::Channel(
+                    "Compilation thread disconnected".to_string(),
+                )))
+            }
+        }
+    }
+
+    /// Block until compilation is complete and return the result
+    pub fn wait_for_result(&mut self) -> Result<Vec<Instruction>, EngineError> {
+        if !self.is_running {
+            return Err(EngineError::Other("No compilation in progress".to_string()));
+        }
+
+        let result = self
+            .result_rx
+            .take()
+            .expect("result_rx should be Some while waiting for compilation result")
+            .recv()
+            .map_err(EngineError::from)?;
+
+        self.is_running = false;
+        result
+    }
+
+    /// Add a source file to be compiled (for compatibility with old interface)
+    pub fn add_source_file<P: AsRef<Path>>(
+        &mut self,
+        path: P,
+    ) -> Result<(), EngineError> {
+        let path = path.as_ref().to_path_buf();
+
+        // Verify file exists
+        if !path.exists() {
+            return Err(EngineError::Assembly(AssembleError::new_other_error(
+                AssembleErrorKind::Io(crate::error::IoError::new(
+                    IoErrorKind::NotFound,
+                    Some(format!("Source file not found: {}", path.display())),
+                )),
+            )));
+        }
+
+        // For now, just validate the file exists
+        // TODO: Could store multiple files for batch compilation
+        Ok(())
+    }
+
+    /// Compile all added source files (synchronous version)
+    pub fn compile(&mut self) -> Result<CompileResult, EngineError> {
+        // This is a placeholder that matches the old interface
+        // For now, return empty result since we don't have a specific file to compile
+        Ok(CompileResult {
+            modules: Vec::new(),
+            tokens: HashMap::new(),
+        })
+    }
+
+    /// Get access to the assembler context (placeholder)
+    pub fn context(&self) -> Result<&AssemblerContext, EngineError> {
+        // For now, return an error since we're using the threaded approach
+        // TODO: Integrate context properly when we have more compilation phases
+        Err(EngineError::Other(
+            "Context not available in threaded mode".to_string(),
+        ))
+    }
+}
+
+impl Default for CompilerEngine {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// Main assembly function that orchestrates the compilation process
+fn assemble(src: &Path) -> Result<Vec<Instruction>, AssembleError> {
+    // Verify the file exists
+    if !src.exists() {
+        return Err(AssembleError::new_other_error(AssembleErrorKind::Io(
+            crate::error::IoError::new(
+                IoErrorKind::NotFound,
+                Some(format!("Source file not found: {}", src.display())),
+            ),
+        )));
+    }
+
+    let mut modules = HashSet::new();
+    let mut all_tokens = HashMap::new();
+    let mut module_ids = Vec::new();
+
+    // Create a new assembler context for this compilation
+    let context = AssemblerContext::new();
+
+    // Process the main file and its dependencies
+    prepare_dependency(
+        src,
+        &mut modules,
+        &mut all_tokens,
+        &mut module_ids,
+        &context,
+    )?;
+
+    // Phase 2: Parse tokens into AST (placeholder for now)
+    // TODO: Add parser here when implemented
+    println!("Phase 2: Parsing {} modules...", module_ids.len());
+
+    // Phase 3: Symbol resolution (placeholder for now)
+    // TODO: Add symbol resolution here when implemented
+    println!("Phase 3: Resolving symbols...");
+
+    // Phase 4: Code generation (placeholder for now)
+    // TODO: Add code generation here when implemented
+    println!("Phase 4: Generating code...");
+
+    // For now, return empty instructions since we don't have the full pipeline yet
+    Ok(Vec::new())
+}
+
+/// Prepare a dependency (file) for compilation
+fn prepare_dependency(
+    path: &Path,
+    modules: &mut HashSet<u64>,
+    all_tokens: &mut HashMap<ModuleId, Vec<Token>>,
+    module_ids: &mut Vec<ModuleId>,
+    context: &AssemblerContext,
+) -> Result<(), AssembleError> {
+    let filename = path.file_name().and_then(|n| n.to_str()).ok_or_else(|| {
+        AssembleError::new_other_error(AssembleErrorKind::Io(crate::error::IoError::new(
+            IoErrorKind::InvalidData,
+            Some("Failed to get file name from path".to_string()),
+        )))
+    })?;
+
+    // Calculate a simple hash for the file (similar to quick_hash)
+    let file_hash = calculate_file_hash(path);
+
+    // Skip if we've already processed this module
+    if modules.contains(&file_hash) {
+        return Ok(());
+    }
+    modules.insert(file_hash);
+
+    if let Ok(canonical_path) = path.canonicalize() {
+        println!("Building {} [{}]", filename, canonical_path.display());
+    }
+
+    // Phase 1: Tokenize the file
+    println!("Tokenising {filename}");
+    let tokeniser = Tokeniser::new(path, context)?;
+    let tokens = tokeniser.tokenise()?;
+
+    // Get the module ID that was registered during tokenization
+    let module_id = get_module_id_for_file(path, context)?;
+
+    all_tokens.insert(module_id, tokens);
+    module_ids.push(module_id);
+
+    // TODO: Parse tokens to find dependencies (.include directives, etc.)
+    // For now, we'll just process the single file
+    println!("Resolving dependencies for {filename}");
+
+    Ok(())
+}
+
+/// Calculate a simple hash for a file path (similar to the old `quick_hash`)
+fn calculate_file_hash(path: &Path) -> u64 {
+    use std::collections::hash_map::DefaultHasher;
+    use std::hash::{Hash, Hasher};
+
+    let mut hasher = DefaultHasher::new();
+    if let Ok(canonical) = path.canonicalize() {
+        canonical.hash(&mut hasher);
+    } else {
+        path.hash(&mut hasher);
+    }
+    hasher.finish()
+}
+
+/// Get the module ID for a given source file
+fn get_module_id_for_file(
+    file_path: &Path,
+    context: &AssemblerContext,
+) -> Result<ModuleId, AssembleError> {
+    {
+        let registry = context.module_registry.read()?;
+
+        // Find module by path.
+        for module in registry.modules() {
+            if module.path == file_path {
+                return Ok(module.id);
+            }
+        }
+    }
+
+    Err(AssembleError::new_other_error(AssembleErrorKind::Io(
+        crate::error::IoError::new(
+            IoErrorKind::NotFound,
+            Some(format!(
+                "Module not found for file: {}",
+                file_path.display()
+            )),
+        ),
+    )))
+}
+
+/// Result of compilation. This is useless at present but compiles.
+#[derive(Debug)]
+pub struct CompileResult {
+    pub modules: Vec<ModuleId>,
+    pub tokens: HashMap<ModuleId, Vec<Token>>,
+}
+
+impl CompileResult {
+    /// Get tokens for a specific module
+    #[must_use]
+    pub fn get_tokens(&self, module_id: &ModuleId) -> Option<&Vec<Token>> {
+        self.tokens.get(module_id)
+    }
+
+    /// Get all module IDs
+    #[must_use]
+    pub fn module_ids(&self) -> &[ModuleId] {
+        &self.modules
+    }
+
+    /// Get total number of tokens across all modules
+    #[must_use]
+    pub fn total_tokens(&self) -> usize {
+        self.tokens.values().map(std::vec::Vec::len).sum()
+    }
+}

assembler/src/context.rs

@@ -0,0 +1,28 @@
+//! This module contains the global asembler context to be passed to functions that need
+//! it.
+
+use std::sync::RwLock;
+
+use crate::{model::module_registry::ModuleRegistry, symtab::SymbolTable};
+
+/// Global state to be passed around.
+pub struct AssemblerContext {
+    pub symbol_table: RwLock<SymbolTable>,
+    pub module_registry: RwLock<ModuleRegistry>,
+}
+
+impl Default for AssemblerContext {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl AssemblerContext {
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            symbol_table: RwLock::new(SymbolTable::new()),
+            module_registry: RwLock::new(ModuleRegistry::new()),
+        }
+    }
+}

assembler/src/error.rs

@@ -0,0 +1,275 @@
+//! This module contains code for various types of errors that may occur when assembling a
+//! set of source DSA files.
+
+use std::fmt::{Debug, Display};
+
+use crate::source::{source_info::SourceInfo, tokeniser::error::TokeniserError};
+
+/// An error that may occur during the assembly of a set of source files.
+#[derive(Debug)]
+pub struct AssembleError {
+    /// Display implementation can handle when the source code information is shown or
+    /// not.
+    source_info: Option<SourceInfo>,
+    /// The type of assembly error that occurred.
+    kind: AssembleErrorKind,
+    /// Whether context should be added to errors being printed. This might get changed
+    /// to Verbosity in the future.
+    display_quietly: bool,
+}
+
+impl AssembleError {
+    #[must_use]
+    pub const fn new_source_error(
+        source_info: SourceInfo,
+        kind: AssembleErrorKind,
+    ) -> Self {
+        Self {
+            source_info: Some(source_info),
+            kind,
+            display_quietly: false,
+        }
+    }
+
+    #[must_use]
+    pub const fn new_other_error(kind: AssembleErrorKind) -> Self {
+        Self {
+            source_info: None,
+            kind,
+            display_quietly: true,
+        }
+    }
+
+    /// Prints a parser error to the screen.
+    fn print_parser_error(
+        &self,
+        f: &mut std::fmt::Formatter<'_>,
+        parse_error: &ParserError,
+    ) -> std::fmt::Result {
+        let Some(source_info) = &self.source_info else {
+            write!(
+                f,
+                "parser error thrown with no source information. Error: {parse_error}"
+            )?;
+
+            return Ok(());
+        };
+
+        writeln!(f, "parser error of type `{parse_error}`.\n")?;
+
+        // Prints out the context for our error.
+        if !self.display_quietly {
+            source_info.print_context_with_underline().map_err(|e| {
+                _ = writeln!(f, "print context error: {e}");
+
+                std::fmt::Error {}
+            })?;
+        }
+
+        Ok(())
+    }
+
+    /// Prints a tokeniser error to the screen.
+    fn print_tokeniser_error(
+        &self,
+        f: &mut std::fmt::Formatter<'_>,
+        err: &TokeniserError,
+    ) -> std::fmt::Result {
+        let Some(source_info) = &self.source_info else {
+            write!(
+                f,
+                "Tokeniser error thrown with no source information. Error: {err}"
+            )?;
+
+            return Ok(());
+        };
+
+        writeln!(f, "tokeniser error of type `{err}`.\n")?;
+
+        // Prints out the context for our error.
+        source_info.print_context_with_underline().map_err(|e| {
+            _ = writeln!(f, "Print context error: {e}");
+
+            std::fmt::Error {}
+        })?;
+
+        Ok(())
+    }
+}
+
+impl Display for AssembleError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        if let Some(info) = &self.source_info {
+            write!(f, "At {info}, got ")?;
+
+            match &self.kind {
+                AssembleErrorKind::Parser(err) => self.print_parser_error(f, err)?,
+                AssembleErrorKind::Tokeniser(err) => {
+                    self.print_tokeniser_error(f, err)?;
+                }
+                _ => write!(f, "{}", self.kind)?,
+            }
+
+            writeln!(f)?;
+
+            return Ok(());
+        }
+
+        // Handle errors without SourceInfo.
+        write!(f, "{}", self.kind)?;
+
+        Ok(())
+    }
+}
+
+/// Marker trait.
+impl std::error::Error for AssembleError {}
+
+#[derive(Debug, Clone)]
+#[non_exhaustive]
+pub enum AssembleErrorKind {
+    /// Usually unexpected I/O errors. Not normally recoverable.
+    Io(IoError),
+    /// Errors emitted from the [`Tokeniser`].
+    Tokeniser(TokeniserError),
+    Parser(ParserError),
+    Symbol(SymbolError),
+    Codegen(CodegenError),
+    Threading(ThreadingError),
+    /// Returned for code where the functionality has not yet been implemented but we
+    /// don't want the program to panic.
+    Unimplemented(&'static str),
+}
+
+#[derive(Debug, Clone)]
+pub enum ParserError {
+    UnexpectedToken,
+    MissingOperand,
+    InvalidInstruction,
+    MissingLabel,
+    DuplicateLabel,
+}
+
+impl Display for ParserError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::UnexpectedToken => write!(f, "unexpected token"),
+            Self::MissingOperand => write!(f, "missing operand"),
+            Self::InvalidInstruction => write!(f, "invalid instruction"),
+            Self::MissingLabel => write!(f, "missing label"),
+            Self::DuplicateLabel => write!(f, "duplicate label"),
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub enum SymbolError {
+    Undefined,
+    Duplicate,
+    CircularDependency,
+    InvalidReference,
+}
+
+impl Display for SymbolError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Undefined => write!(f, "undefined symbol"),
+            Self::Duplicate => write!(f, "duplicate symbol"),
+            Self::CircularDependency => write!(f, "circular dependency"),
+            Self::InvalidReference => write!(f, "invalid reference"),
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub enum CodegenError {
+    InvalidOperand,
+    OutOfRange,
+    UnsupportedInstruction,
+}
+
+impl Display for CodegenError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::InvalidOperand => write!(f, "invalid operand"),
+            Self::OutOfRange => write!(f, "out of range"),
+            Self::UnsupportedInstruction => write!(f, "unsupported instruction"),
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub enum ThreadingError {
+    LockFailed,
+    ThreadPanic,
+}
+
+impl Display for ThreadingError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::LockFailed => write!(f, "lock failed"),
+            Self::ThreadPanic => write!(f, "thread panic"),
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct IoError {
+    msg: Option<String>,
+    kind: IoErrorKind,
+}
+
+impl IoError {
+    #[must_use]
+    pub const fn new(kind: IoErrorKind, msg: Option<String>) -> Self {
+        Self { msg, kind }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub enum IoErrorKind {
+    NotFound,
+    PermissionDenied,
+    InvalidData,
+    Other,
+}
+
+impl std::fmt::Display for IoErrorKind {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::NotFound => write!(f, "file not found"),
+            Self::PermissionDenied => write!(f, "permission denied"),
+            Self::InvalidData => write!(f, "invalid data"),
+            Self::Other => write!(f, "other I/O error"),
+        }
+    }
+}
+
+impl std::fmt::Display for IoError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.kind)?;
+
+        if let Some(msg) = &self.msg {
+            write!(f, ", \"{msg}\"")?;
+        }
+
+        Ok(())
+    }
+}
+
+impl Display for AssembleErrorKind {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Tokeniser(why) => write!(f, "tokeniser error: {why}"),
+            Self::Unimplemented(why) => write!(f, "used unimplemented feature: {why}"),
+            Self::Io(why) => write!(f, "problem occurred with I/O: {why}"),
+            #[allow(unreachable_patterns)]
+            _ => write!(
+                f,
+                "unhandled error type in Display implementation! See error.rs!"
+            ),
+        }
+    }
+}
+
+pub mod conversions;

assembler/src/error/conversions.rs

@@ -0,0 +1,67 @@
+use std::{
+    io::ErrorKind,
+    sync::{PoisonError, RwLockReadGuard, RwLockWriteGuard},
+};
+
+use crate::error::{AssembleError, IoError, IoErrorKind};
+
+use super::{AssembleErrorKind, ThreadingError};
+
+impl From<std::io::Error> for IoError {
+    fn from(err: std::io::Error) -> Self {
+        let kind = match err.kind() {
+            ErrorKind::NotFound => IoErrorKind::NotFound,
+            ErrorKind::PermissionDenied => IoErrorKind::PermissionDenied,
+            ErrorKind::InvalidData => IoErrorKind::InvalidData,
+            _ => IoErrorKind::Other,
+        };
+
+        let msg = err.to_string();
+
+        Self::new(kind, Some(msg))
+    }
+}
+
+impl From<std::io::Error> for AssembleError {
+    fn from(err: std::io::Error) -> Self {
+        Self::new_other_error(AssembleErrorKind::Io(err.into()))
+    }
+}
+
+// TODO: Maybe attempt recovery? To be honest we don't want any threads to panic at all,
+// or we want them all to panic spectacularly.
+impl<T> From<PoisonError<RwLockReadGuard<'_, T>>> for AssembleError {
+    fn from(err: PoisonError<RwLockReadGuard<'_, T>>) -> Self {
+        Self::new_other_error(AssembleErrorKind::Threading(err.into()))
+    }
+}
+
+impl<T> From<PoisonError<RwLockReadGuard<'_, T>>> for ThreadingError {
+    fn from(_err: PoisonError<RwLockReadGuard<'_, T>>) -> Self {
+        Self::LockFailed
+    }
+}
+
+impl<T> From<PoisonError<RwLockWriteGuard<'_, T>>> for AssembleError {
+    fn from(err: PoisonError<RwLockWriteGuard<'_, T>>) -> Self {
+        Self::new_other_error(AssembleErrorKind::Threading(err.into()))
+    }
+}
+
+impl<T> From<PoisonError<RwLockWriteGuard<'_, T>>> for ThreadingError {
+    fn from(_err: PoisonError<RwLockWriteGuard<'_, T>>) -> Self {
+        Self::LockFailed
+    }
+}
+
+impl From<std::fmt::Error> for AssembleError {
+    fn from(err: std::fmt::Error) -> Self {
+        IoError::new(IoErrorKind::Other, Some(err.to_string())).into()
+    }
+}
+
+impl From<IoError> for AssembleError {
+    fn from(err: IoError) -> Self {
+        Self::new_other_error(AssembleErrorKind::Io(err))
+    }
+}

assembler/src/lib.rs

@@ -0,0 +1,29 @@
+#![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 args;
+// pub mod tooling;
+pub mod compiler_engine;
+pub mod context;
+pub mod error;
+pub mod model;
+pub mod source;
+pub mod symtab;
+
+mod util;
+
+// pub mod prelude {}
+
+use num_cpus as _;
+use threadpool as _;

assembler/src/main.rs

@@ -0,0 +1,92 @@
+use std::sync::Arc;
+
+use assembler::{
+    error::{AssembleError, AssembleErrorKind, ParserError},
+    model::module::Module,
+    source::{source_info::SourceInfo, token::TokenType, tokeniser::Tokeniser},
+};
+use common as _;
+use num_cpus as _;
+use threadpool as _;
+
+// use clap::Parser;
+// use std::{fs, io::Write, path::PathBuf};
+
+fn main() -> Result<(), AssembleError> {
+    // // Parse command line arguments
+    // let args: Vec<String> = std::env::args().collect();
+    let contents = include_bytes!("../../resources/dsa/bf.dsa").to_vec();
+
+    let module = Arc::new(Module::new("resources/dsa/bf.dsa")?);
+    let tok = Tokeniser::from_data(contents, module.clone());
+
+    let ts = tok
+        .tokenise()?
+        .into_iter()
+        .filter(|t| !matches!(t.token_type, TokenType::Eof | TokenType::Newline));
+
+    for t in ts {
+        t.source_info.print_context_with_underline()?;
+    }
+
+    let test_error: AssembleError = AssembleError::new_source_error(
+        SourceInfo::new(45, module.clone(), 4..7),
+        AssembleErrorKind::Parser(ParserError::InvalidInstruction),
+    );
+
+    eprintln!("\n\n{test_error}");
+
+    Ok(())
+
+    // let _clap_args = assembler::args::Args::parse();
+
+    // 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/model.rs

@@ -0,0 +1,5 @@
+//! This module contains the underlying data models and enums used by the Assembler.
+
+pub mod module;
+pub mod module_registry;
+pub mod symbol;

assembler/src/model/module.rs

@@ -0,0 +1,110 @@
+//! This module contains the [`Module`] type and associated types. Each compilation unit
+//! (file) is represented by a module which is used to namespace "function" calls and
+//! accesses to global variables.
+//!
+//! They have unique identifiers in the form of UUIDs.
+
+use std::{
+    path::{Path, PathBuf},
+    sync::Arc,
+};
+
+use regex::Regex;
+use uuid::Uuid;
+
+use crate::{
+    error::{AssembleError, AssembleErrorKind, IoError, IoErrorKind},
+    model::module_registry::ModuleRegistry,
+};
+
+/// The ID for a module. A tuple struct for type safety.
+#[derive(Debug, Hash, PartialEq, Eq, Clone, Copy)]
+pub struct ModuleId(Uuid);
+
+impl ModuleId {
+    #[must_use]
+    pub fn new() -> Self {
+        Self(Uuid::new_v4())
+    }
+
+    #[must_use]
+    pub const fn from_module(module: &Module) -> Self {
+        module.id
+    }
+
+    /// Convenience method to get the [`Module`] from a [`ModuleId`].
+    #[must_use]
+    pub fn to_module<'m>(&self, registry: &'m ModuleRegistry) -> Option<&'m Arc<Module>> {
+        registry.get(self)
+    }
+
+    /// Convenience method to get the [`Module`] name from a [`ModuleId`].
+    #[must_use]
+    pub fn to_module_name(self, registry: &ModuleRegistry) -> Option<&str> {
+        self.to_module(registry).map(|module| module.name.as_str())
+    }
+}
+
+impl Default for ModuleId {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl std::fmt::Display for ModuleId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+/// A single source file or compilation unit. Stores its own symbol table.
+#[derive(Debug, Clone)]
+pub struct Module {
+    /// The name of the module. This is typically the name of the file, less the `.dsa`
+    /// extension.
+    pub name: String,
+    /// The file path to the module. This is an absolute path.
+    pub path: PathBuf,
+    /// A unique ID for this module.
+    pub id: ModuleId,
+}
+
+impl std::hash::Hash for Module {
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        self.id.0.hash(state);
+    }
+}
+
+impl Module {
+    pub fn new<P: AsRef<Path>>(p: P) -> Result<Self, AssembleError> {
+        let path = p.as_ref().to_path_buf();
+        let name = Self::extract_module_name(&path)?;
+        let id = ModuleId::new();
+
+        Ok(Self { name, path, id })
+    }
+
+    /// Gets the name for a module from the path.
+    fn extract_module_name<P: AsRef<Path>>(path: P) -> Result<String, AssembleError> {
+        let extensions_regex = Regex::new(".(dsa|S|asm)$")
+            .expect("For some reason the regular expression failed to compile!");
+        let module_name = path
+            .as_ref()
+            .file_name()
+            .map(|f| f.to_string_lossy())
+            .ok_or_else(|| {
+                AssembleError::new_other_error(AssembleErrorKind::Io(IoError::new(
+                    IoErrorKind::InvalidData,
+                    Some(
+                        "the filename couldn't be extracted, is it valid UTF-8?"
+                            .to_string(),
+                    ),
+                )))
+            })?;
+
+        // Strip any file extensions given. We don't care for now.
+        let out = extensions_regex.replace(&module_name, "");
+
+        Ok(out.to_string())
+    }
+}

assembler/src/model/module_registry.rs

@@ -0,0 +1,44 @@
+//! This module contains the code for the module registry. This is a singleton storing all
+//! the modules being assembled.
+
+use std::{collections::HashMap, sync::Arc};
+
+use super::module::{Module, ModuleId};
+
+/// Stores all the [`Module`]'s to be assembled.
+pub struct ModuleRegistry {
+    modules: HashMap<ModuleId, Arc<Module>>,
+}
+
+impl Default for ModuleRegistry {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl ModuleRegistry {
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            modules: HashMap::new(),
+        }
+    }
+
+    /// Gets a [`Module`] by ID.
+    #[must_use]
+    pub fn get(&self, module_id: &ModuleId) -> Option<&Arc<Module>> {
+        self.modules.get(module_id)
+    }
+
+    /// Adds a [`Module`] and returns its [`ModuleId`].
+    pub fn add(&mut self, module: Arc<Module>) -> ModuleId {
+        let id = module.id;
+        self.modules.insert(id, module);
+        id
+    }
+
+    /// Returns an iterator of modules.
+    pub fn modules(&self) -> impl Iterator<Item = &Arc<Module>> {
+        self.modules.values()
+    }
+}

assembler/src/model/symbol.rs

@@ -0,0 +1,165 @@
+//! This module contains the definitions for a Symbol.
+
+use std::collections::HashSet;
+
+use uuid::Uuid;
+
+use crate::{model::module::ModuleId, symtab::SymbolTable};
+
+/// Tuple struct for type safety. Has methods for fetching symbols by ID.
+#[derive(Debug, PartialEq, Eq, Hash, Copy, Clone)]
+pub struct SymbolId(Uuid);
+
+impl From<Symbol> for SymbolId {
+    fn from(sym: Symbol) -> Self {
+        sym.id
+    }
+}
+
+impl Default for SymbolId {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl SymbolId {
+    #[must_use]
+    pub fn new() -> Self {
+        Self(Uuid::new_v4())
+    }
+
+    /// Convenience method to get the [`Module`] from a [`ModuleId`].
+    #[must_use]
+    pub fn to_module<'s>(&self, registry: &'s SymbolTable) -> Option<&'s Symbol> {
+        registry.get(self)
+    }
+
+    /// Convenience method to get the [`Module`] name from a [`ModuleId`].
+    #[must_use]
+    pub fn to_module_name(self, registry: &SymbolTable) -> Option<&str> {
+        self.to_module(registry).map(|module| module.name.as_str())
+    }
+}
+
+/// A symbol is a named reference that may be resolved later to an address by a linker.
+#[derive(Debug)]
+pub struct Symbol {
+    /// Stored cheaply instead of the name. Shall be stored in the symbol table under
+    /// this key.
+    pub id: SymbolId,
+
+    /// The human-readable name for the symbol.
+    pub name: String,
+
+    pub visibility: Visibility,
+
+    pub symbol_type: SymbolType,
+
+    /// The id of the module the symbol is defined in. This will be different for symbols
+    /// in different objects.
+    pub module_id: ModuleId,
+
+    /// Whether or not the symbol requires relocating.
+    pub needs_relocation: bool,
+
+    /// A list of the symbol's dependencies.
+    ///
+    /// e.g.
+    ///
+    /// ```dsa
+    /// main:
+    ///   call another_func
+    ///
+    /// another_func:
+    ///   // Code goes here
+    ///   ret
+    /// ```
+    ///
+    /// Where `main` depends on `another_func`.
+    pub dependencies: HashSet<SymbolId>,
+
+    /// The address of the symbol.
+    pub address: Option<u32>,
+    /// The section the symbol is in.
+    /// TODO: Perhaps make this a proper type?
+    pub section: Option<String>,
+    pub size: Option<u32>,
+}
+
+impl Symbol {
+    #[must_use]
+    pub fn new(
+        name: String,
+        module_id: ModuleId,
+        visibility: Visibility,
+        symbol_type: SymbolType,
+    ) -> Self {
+        Self {
+            id: SymbolId::new(),
+            name,
+            module_id,
+            address: None,
+            section: None,
+            size: None,
+            visibility,
+            symbol_type,
+            needs_relocation: false,
+            dependencies: HashSet::new(),
+        }
+    }
+
+    /// Adds a dependency on another [`Symbol`].
+    pub fn add_dependency(&mut self, dep: SymbolId) {
+        if self.id == dep {
+            return;
+        }
+
+        // We can resolve a lot of addresses at assembly time, but not really foreign
+        // ones, since we aren't certain of their position.
+        //
+        /* TODO: Handle this for flat binary case i.e. no linker required. This may be
+         *       done using a similar method to before, such as just concatenating all
+         * of the files together and handling jumps and halts.
+         *
+         * > Ask Harry or read the initial code.
+         */
+        if self.dependencies.insert(dep) {
+            self.needs_relocation = true;
+        }
+    }
+
+    /// Returns whether a [`Symbol`] depends on `symbol_id`.
+    #[must_use]
+    pub fn depends_on(&self, symbol_id: &SymbolId) -> bool {
+        self.dependencies.contains(symbol_id)
+    }
+
+    /// Removes a [`Symbol`] from the dependency set.
+    pub fn remove_dependency(&mut self, symbol_id: &SymbolId) {
+        self.dependencies.remove(symbol_id);
+
+        if self.dependencies.is_empty() {
+            self.needs_relocation = false;
+        }
+    }
+}
+
+#[derive(Debug, Copy, Clone)]
+/// The visibility of the symbol in different object files.
+pub enum Visibility {
+    /// `STB_PUBLIC` under the ELF spec. Visible in all other object files. Shall be used
+    /// for labels. Remember labels are namespaced in different files so they won't clash
+    /// with one another.
+    Public,
+    /// Only visible within this object file. `STB_LOCAL` under ELF spec. Shall be used
+    /// for data definitions unless they are marked public.
+    Local,
+    /// `STB_WEAK` under the ELF spec. Potentially unused.
+    Weak,
+}
+
+#[derive(Debug)]
+pub enum SymbolType {
+    LabelOrFunction,
+    Variable,
+}

assembler/src/source.rs

@@ -0,0 +1,29 @@
+//! This module contains anything within the first stage of assembly, i.e. the
+//! tokenisation stage, or utility functions for reading input files.
+
+use std::{
+    io::{BufRead, Lines},
+    path::Path,
+};
+
+use crate::error::AssembleError;
+
+pub mod lines;
+pub mod opcode;
+pub mod source_info;
+pub mod token;
+pub mod token_info;
+pub mod tokeniser;
+
+/// Attempts to load and open a source file, returning a [`Vec<u8>`] or an
+/// [`AssembleError`].
+pub fn load_source_bytes<P: AsRef<Path>>(p: P) -> Result<Vec<u8>, AssembleError> {
+    let path = p.as_ref();
+
+    Ok(std::fs::read(path)?)
+}
+
+/// Get the lines from a [`BufReader`].
+pub fn reader_lines<R: BufRead>(rdr: R) -> Lines<R> {
+    rdr.lines()
+}

assembler/src/source/lines.rs

@@ -0,0 +1,76 @@
+//! Enhanced lines iterator that tracks line numbers and character positions.
+
+use std::io::{BufRead, BufReader, Cursor};
+
+use crate::error::AssembleError;
+
+/// Iterator that yields lines with their line numbers and character spans.
+pub struct LinesWithSpans<R: BufRead> {
+    reader: R,
+    line_number: usize,
+    total_chars: usize,
+    buffer: String,
+}
+
+#[derive(Debug, Clone)]
+pub struct LineSpan {
+    /// The line number.
+    pub line_number: usize,
+    /// The contents of the line.
+    pub content: String,
+    /// Character offset from start of file.
+    pub start_char: usize,
+    /// End character offset (exclusive).
+    pub end_char: usize,
+}
+
+impl<R: BufRead> LinesWithSpans<R> {
+    pub const fn new(reader: R) -> Self {
+        Self {
+            reader,
+            line_number: 0,
+            total_chars: 0,
+            buffer: String::new(),
+        }
+    }
+}
+
+impl<R: BufRead> Iterator for LinesWithSpans<R> {
+    type Item = Result<LineSpan, AssembleError>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        self.buffer.clear();
+
+        match self.reader.read_line(&mut self.buffer) {
+            Ok(0) => None, // EOF
+            Ok(bytes_read) => {
+                self.line_number += 1;
+                let start_char = self.total_chars;
+                self.total_chars += bytes_read;
+
+                // Remove trailing newline for cleaner processing
+                let content = if self.buffer.ends_with('\n') {
+                    self.buffer[..self.buffer.len() - 1].to_string()
+                } else {
+                    self.buffer.clone()
+                };
+
+                Some(Ok(LineSpan {
+                    line_number: self.line_number,
+                    content,
+                    start_char,
+                    end_char: self.total_chars,
+                }))
+            }
+            Err(e) => Some(Err(e.into())),
+        }
+    }
+}
+
+/// Helper function to create lines iterator from data.
+#[must_use]
+pub fn lines_with_spans(data: &[u8]) -> LinesWithSpans<BufReader<Cursor<&[u8]>>> {
+    let cursor = Cursor::new(data);
+    let reader = BufReader::new(cursor);
+    LinesWithSpans::new(reader)
+}

assembler/src/source/opcode.rs

@@ -0,0 +1,349 @@
+//! This module contains instructions for tokenisation.
+
+use std::{fmt, str::FromStr};
+
+use common::prelude::{ITypeArgs, Instruction, Interrupt, RTypeArgs};
+
+use crate::{
+    error::{AssembleError, AssembleErrorKind},
+    source::source_info::SourceInfo,
+};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Opcode {
+    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 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",
+    ];
+
+    pub fn to_instruction(
+        &self,
+        source_info: SourceInfo,
+    ) -> Result<Instruction, AssembleError> {
+        match self {
+            Self::Nop => Ok(Instruction::Nop),
+            Self::Mov => Ok(Instruction::Mov(RTypeArgs::default())),
+            Self::Movs => Ok(Instruction::MovSigned(RTypeArgs::default())),
+            Self::Ldb => Ok(Instruction::LoadByte(ITypeArgs::default())),
+            Self::Ldbs => Ok(Instruction::LoadByteSigned(ITypeArgs::default())),
+            Self::Ldh => Ok(Instruction::LoadHalfword(ITypeArgs::default())),
+            Self::Ldhs => Ok(Instruction::LoadHalfwordSigned(ITypeArgs::default())),
+            Self::Ldw => Ok(Instruction::LoadWord(ITypeArgs::default())),
+            Self::Stb => Ok(Instruction::StoreByte(ITypeArgs::default())),
+            Self::Sth => Ok(Instruction::StoreHalfword(ITypeArgs::default())),
+            Self::Stw => Ok(Instruction::StoreWord(ITypeArgs::default())),
+            Self::Lli => Ok(Instruction::LoadLowerImmediate(ITypeArgs::default())),
+            Self::Lui => Ok(Instruction::LoadUpperImmediate(ITypeArgs::default())),
+            Self::Jmp => Ok(Instruction::Jump(ITypeArgs::default())),
+            Self::Jeq => Ok(Instruction::JumpEq(ITypeArgs::default())),
+            Self::Jne => Ok(Instruction::JumpNeq(ITypeArgs::default())),
+            Self::Jgt => Ok(Instruction::JumpGt(ITypeArgs::default())),
+            Self::Jge => Ok(Instruction::JumpGe(ITypeArgs::default())),
+            Self::Jlt => Ok(Instruction::JumpLt(ITypeArgs::default())),
+            Self::Jle => Ok(Instruction::JumpLe(ITypeArgs::default())),
+            Self::Cmp => Ok(Instruction::Compare(RTypeArgs::default())),
+            Self::Inc => Ok(Instruction::Increment(RTypeArgs::default())),
+            Self::Dec => Ok(Instruction::Decrement(RTypeArgs::default())),
+            Self::Shl => Ok(Instruction::ShiftLeft(RTypeArgs::default())),
+            Self::Shr => Ok(Instruction::ShiftRight(RTypeArgs::default())),
+            Self::Add => Ok(Instruction::Add(RTypeArgs::default())),
+            Self::Sub => Ok(Instruction::Sub(RTypeArgs::default())),
+            Self::And => Ok(Instruction::And(RTypeArgs::default())),
+            Self::Or => Ok(Instruction::Or(RTypeArgs::default())),
+            Self::Not => Ok(Instruction::Not(RTypeArgs::default())),
+            Self::Xor => Ok(Instruction::Xor(RTypeArgs::default())),
+            Self::Nand => Ok(Instruction::Nand(RTypeArgs::default())),
+            Self::Nor => Ok(Instruction::Nor(RTypeArgs::default())),
+            Self::Xnor => Ok(Instruction::Xnor(RTypeArgs::default())),
+            Self::Int => Ok(Instruction::Interrupt(Interrupt::default())),
+            Self::Irt => Ok(Instruction::IntReturn),
+            Self::Hlt => Ok(Instruction::Halt),
+            Self::AddI => Ok(Instruction::AddImmediate(ITypeArgs::default())),
+            Self::SubI => Ok(Instruction::SubImmediate(ITypeArgs::default())),
+            Self::Segment => Ok(Instruction::Segment(0)),
+            _ => Err(AssembleError::new_source_error(
+                source_info,
+                AssembleErrorKind::Unimplemented(
+                    "Opcode::to_instruction called on an instruction that does not exist in common.",
+                ),
+            )),
+        }
+    }
+
+    #[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),
+            // TODO: Maybe recombine pseudos?
+            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
+        )
+    }
+}
+
+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 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]"),
+        }
+    }
+}

assembler/src/source/pseudo_opcode.rs

@@ -0,0 +1,4 @@
+//! This module contains code for handling pseudo opcodes.
+
+/// Pseudo instructions that cannot simply be lowered to ISA instructions.
+pub enum PseudoOpcode {}

assembler/src/source/source_info.rs

@@ -0,0 +1,104 @@
+//! This file contains information on where a [`Token`] or [`Node`] is within the source
+//! code for more informative errors.
+//!
+//! This will likely be attached to a [`Token`] which will in turn be attached to an AST
+//! [`Node`].
+
+use std::{
+    fmt::{Display, Write},
+    fs::File,
+    io::BufReader,
+    sync::Arc,
+};
+
+use crate::{
+    error::{AssembleError, AssembleErrorKind, IoError, IoErrorKind},
+    model::module::Module,
+    source::lines::LinesWithSpans,
+};
+
+///  Information on where the token is within the source.
+#[derive(Debug, Clone)]
+pub struct SourceInfo {
+    /// The line number within the source file underpinned by `module_id`.
+    pub line_number: usize,
+    /// The [`Module`] the source code is associated with.
+    pub module: Arc<Module>,
+    /// The indexes where this token may be found (line-local).
+    pub span: std::ops::Range<usize>,
+}
+
+impl Display for SourceInfo {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "{}:{}:{}",
+            self.module.path.display(),
+            self.line_number,
+            self.span.start + 1
+        )
+    }
+}
+
+impl SourceInfo {
+    #[must_use]
+    pub const fn new(
+        line_no: usize,
+        module: Arc<Module>,
+        span: std::ops::Range<usize>,
+    ) -> Self {
+        Self {
+            line_number: line_no,
+            module,
+            span,
+        }
+    }
+
+    /// Prints out where in the source code the error originated with an underline similar
+    /// to what rustc does.
+    pub fn print_context_with_underline(&self) -> Result<(), AssembleError> {
+        let f = File::open(&self.module.path)?;
+        let rdr = BufReader::new(f);
+
+        let mut lines = LinesWithSpans::new(rdr);
+
+        let Some(line_result) = lines.nth(self.line_number - 1) else {
+            // Handle a line not existing.
+            return Err(AssembleError::new_source_error(
+                self.clone(),
+                AssembleErrorKind::Io(IoError::new(
+                    IoErrorKind::Other,
+                    Some(format!(
+                        "the line {} does not exist in input file `{}` but source info suggested otherwise!.",
+                        self.line_number,
+                        self.module.path.display()
+                    )),
+                )),
+            ));
+        };
+
+        let line_span = line_result?;
+
+        // Print the line number and line content.
+        println!("{:>4} | {}", self.line_number, line_span.content);
+
+        let mut pad_left = String::new();
+        write!(pad_left, "{:>4}   ", "")?;
+
+        let mut underline = String::new();
+
+        for _ in 0..self.span.start {
+            pad_left.push(' ');
+        }
+
+        for _ in self.span.start..self.span.end.min(line_span.content.len()) {
+            underline.push('^');
+        }
+
+        // Print the underline in red and bold.
+        // TODO: Use a crate to make this extra portable.
+        println!("{pad_left}\x1b[1;31m{underline}\x1b[0m");
+
+        Ok(())
+    }
+}

assembler/src/source/token.rs

@@ -0,0 +1,91 @@
+//! Contains [`TokenType`] and [`Token`]'s. Adapted from Harry's old lexer since it was
+//! easier to build from scratch and edit his code than it would be to try and wrangle it
+//! into shape.
+
+use common::prelude::*;
+
+use crate::source::{
+    opcode::Opcode,
+    source_info::SourceInfo,
+    token_info::{DirectiveToken, LabelToken, RegisterToken, SymbolToken},
+};
+
+/// Represents the different types of tokens that can be produced by the tokeniser.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub enum TokenType {
+    /// Symbol reference (e.g., `loop_start`, `my_data`).
+    Symbol(SymbolToken),
+    /// CPU register (e.g., `r1`, `r2`, `sp`).
+    Register(RegisterToken),
+    /// Immediate value (e.g., `42`, `0xFF`).
+    Immediate(u32),
+    /// String literal (e.g., `"hello world"`).
+    String(String),
+    /// Intermediate token for multiline strings (filtered out in final output)
+    StringContinuation,
+    /// Assembly instruction (e.g., `add`, `jmp`, `nop`).
+    Instruction(Opcode),
+    /// Label definition (e.g., `loop_start:`).
+    Label(LabelToken),
+    /// Assembler directive (e.g., `.global`, `.section`, `.dw`).
+    Directive(DirectiveToken),
+    /// Comment (e.g., `// this is a comment`).
+    Comment,
+    /// Comma separator.
+    Comma,
+    /// End of line.
+    Newline,
+    /// End of file.
+    Eof,
+}
+
+#[derive(Debug)]
+pub struct Token {
+    /// The type of the token.
+    pub token_type: TokenType,
+    /// Where in the source code is this [`Token`]?
+    pub source_info: SourceInfo,
+}
+
+impl Token {
+    #[must_use]
+    pub const fn new(token_type: TokenType, source_info: SourceInfo) -> Self {
+        Self {
+            token_type,
+            source_info,
+        }
+    }
+
+    #[must_use]
+    pub const fn symbol(name: String, source_info: SourceInfo) -> Self {
+        Self::new(TokenType::Symbol(SymbolToken { name }), source_info)
+    }
+
+    #[must_use]
+    pub const fn label(name: String, source_info: SourceInfo) -> Self {
+        Self::new(TokenType::Label(LabelToken { name }), source_info)
+    }
+
+    #[must_use]
+    pub const fn instruction(op: Opcode, source_info: SourceInfo) -> Self {
+        Self::new(TokenType::Instruction(op), source_info)
+    }
+
+    #[must_use]
+    pub const fn register(reg: Register, source_info: SourceInfo) -> Self {
+        Self::new(TokenType::Register(RegisterToken { reg }), source_info)
+    }
+
+    #[must_use]
+    pub const fn immediate(value: u32, source_info: SourceInfo) -> Self {
+        Self::new(TokenType::Immediate(value), source_info)
+    }
+
+    #[must_use]
+    pub const fn directive(directive: String, source_info: SourceInfo) -> Self {
+        Self::new(
+            TokenType::Directive(DirectiveToken { directive }),
+            source_info,
+        )
+    }
+}

assembler/src/source/token_info.rs

@@ -0,0 +1,34 @@
+use common::prelude::Register;
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct SymbolToken {
+    pub name: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct LabelToken {
+    pub name: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct DirectiveToken {
+    pub directive: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct RegisterToken {
+    pub reg: Register,
+}
+
+impl RegisterToken {
+    #[must_use]
+    pub const fn new(reg: Register) -> Self {
+        Self { reg }
+    }
+
+    /// Returns the name of a valid [`Register`]
+    #[must_use]
+    pub fn name(&self) -> String {
+        self.reg.to_string()
+    }
+}

assembler/src/source/tokeniser.rs

@@ -0,0 +1,421 @@
+//! This file contains the [`Tokeniser`], which consumes a [`Vec`] of input bytes and
+//! outputs a [`Vec<Token>`].
+
+use std::{path::Path, str::FromStr, sync::Arc};
+
+use regex::Regex;
+
+use common::prelude::*;
+
+use crate::{
+    context::AssemblerContext,
+    error::{AssembleError, AssembleErrorKind},
+    model::module::Module,
+    source::{
+        lines::{LineSpan, lines_with_spans},
+        load_source_bytes,
+        opcode::Opcode,
+        source_info::SourceInfo,
+        token::{Token, TokenType},
+        token_info::{DirectiveToken, LabelToken, RegisterToken, SymbolToken},
+        tokeniser::error::TokeniserError,
+    },
+};
+
+pub mod error;
+#[cfg(test)]
+mod tests;
+
+/// Consumes a [`Vec<u8>`] and outputs a [`Vec`] of [Token]'s.
+pub struct Tokeniser {
+    /// The data in the file.
+    pub data: Vec<u8>,
+    /// A copy of the Module in which the file is situated.
+    pub module: Arc<Module>,
+
+    // Pre-compiled regex patterns
+    label_regex: Regex,
+    register_regex: Regex,
+    immediate_regex: Regex,
+    directive_regex: Regex,
+    instruction_regex: Regex,
+    symbol_regex: Regex,
+    comment_regex: Regex,
+
+    // String parsing state
+    in_string: bool,
+    string_buffer: String,
+    string_start_line: usize,
+    string_start_column: usize,
+}
+
+impl Tokeniser {
+    #[must_use]
+    pub fn from_data(data: Vec<u8>, module: Arc<Module>) -> Self {
+        Self {
+            data,
+            module,
+            label_regex: Regex::new(r"^([a-zA-Z_][a-zA-Z0-9_]*):")
+                .expect("Failed to compile label regex pattern"),
+            register_regex: Regex::new(
+                r"^(rg[0-9a-f]+|acc|spr|bpr|ret|idr|mmr|zero|noreg|pcx)\b",
+            )
+            .expect("Failed to compile register regex pattern"),
+            immediate_regex: Regex::new(
+                r"^(0x[0-9a-fA-F_]+|0b[0-1_]+|0o[0-7_]+|[0-9_]+)",
+            )
+            .expect("Failed to compile immediate regex pattern"),
+            directive_regex: Regex::new(r"^(res[bwh]|d[bwh]|include|section|global|local)\b")
+                .expect("Failed to compile directive regex pattern"),
+            instruction_regex: Regex::new(
+                r"^(nop|movs?|ld[bhw]s?|st[bhw]|l[lu]i|j(mp|[egl][qte])|cmp|[id]nc|sh[lr]|add[i]?|sub[i]?|x?n?or|and|not|i[rd]t|hlt|lhwmm|lidt|push[a]?|pop[a]?|lwi|return|call)\b",
+            )
+            .expect("Failed to compile instruction regex pattern"),
+            symbol_regex: Regex::new(r"^([a-zA-Z_][a-zA-Z0-9_]*)::{2}([a-zA-Z0-9_]*)|([a-zA-Z_][a-zA-Z0-9_]*)")
+                .expect("Failed to compile symbol regex pattern"),
+            comment_regex: Regex::new("^//.*")
+                .expect("Failed to compile comment regex pattern"),
+
+            // Initialize string parsing state
+            in_string: false,
+            string_buffer: String::new(),
+            string_start_line: 0,
+            string_start_column: 0,
+        }
+    }
+
+    /// Creates a [`Tokeniser`] from a file path. Also creates the underlying [`Module`]
+    /// for you.
+    pub fn new<P: AsRef<Path>>(
+        path: P,
+        ctx: &AssemblerContext,
+    ) -> Result<Self, AssembleError> {
+        let path = path.as_ref().to_path_buf();
+        let data = load_source_bytes(&path)?;
+        let module = Arc::new(Module::new(path)?);
+
+        {
+            let mut module_registry = ctx.module_registry.write()?;
+            module_registry.add(module.clone());
+        }
+
+        Ok(Self::from_data(data, module))
+    }
+
+    // Note that modules are tokenised in their own threads, possibly in parallel.
+    pub fn tokenise(mut self) -> Result<Vec<Token>, AssembleError> {
+        let mut token_stream = Vec::new();
+        let data = self.data.clone();
+        let lines = lines_with_spans(&data);
+
+        // Process each line
+        for line_result in lines {
+            let line_span = line_result?;
+            let trimmed = line_span.content.trim();
+
+            // Skip empty lines and add newline tokens
+            if trimmed.is_empty() {
+                token_stream.push(Token::new(
+                    TokenType::Newline,
+                    SourceInfo::new(line_span.line_number, self.module.clone(), 0..1),
+                ));
+                continue;
+            }
+
+            // Actually tokenise the line content
+            let line_tokens = self.tokenise_line(&line_span)?;
+            token_stream.extend(line_tokens);
+
+            // Add newline token at end of line
+            token_stream.push(Token::new(
+                TokenType::Newline,
+                SourceInfo::new(
+                    line_span.line_number,
+                    self.module.clone(),
+                    line_span.content.len()..line_span.content.len(),
+                ),
+            ));
+        }
+
+        // Add EOF token
+        token_stream.push(Token::new(
+            TokenType::Eof,
+            SourceInfo::new(0, self.module.clone(), 0..0),
+        ));
+
+        Ok(token_stream)
+    }
+
+    fn tokenise_line(
+        &mut self,
+        line_span: &LineSpan,
+    ) -> Result<Vec<Token>, AssembleError> {
+        let mut tokens = Vec::new();
+        let mut remaining = line_span.content.as_str();
+        let mut column = 0;
+
+        // Skip leading whitespace
+        let trimmed_start = remaining.trim_start();
+        column += remaining.len() - trimmed_start.len();
+        remaining = trimmed_start;
+
+        while !remaining.is_empty() {
+            let start_column = column;
+
+            // Try to match a token.
+            let (token_type, consumed) =
+                self.match_token(remaining, line_span.line_number, column)?;
+
+            // Filter out string continuation tokens and comments.
+            match token_type {
+                TokenType::StringContinuation => {
+                    // Don't add to token stream, just consume input
+                }
+                TokenType::Comment => {
+                    // Don't add to token stream, consume rest of line
+                    break;
+                }
+                _ => {
+                    tokens.push(Token::new(
+                        token_type,
+                        SourceInfo::new(
+                            line_span.line_number,
+                            self.module.clone(),
+                            start_column..start_column + consumed,
+                        ),
+                    ));
+                }
+            }
+
+            // Advance position.
+            remaining = &remaining[consumed..];
+            column += consumed;
+
+            // Skip whitespace.
+            let before_trim = remaining.len();
+            remaining = remaining.trim_start();
+            column += before_trim - remaining.len();
+        }
+
+        Ok(tokens)
+    }
+
+    fn try_match_comment(&self, input: &str) -> Option<(TokenType, usize)> {
+        let caps = self.comment_regex.captures(input)?;
+        let len = caps.get(0)?.len();
+
+        Some((TokenType::Comment, len))
+    }
+
+    fn try_match_label(&self, input: &str) -> Option<(TokenType, usize)> {
+        let caps = self.label_regex.captures(input)?;
+        let name = caps.get(1)?.as_str().to_string();
+        let len = caps.get(0)?.len();
+
+        Some((TokenType::Label(LabelToken { name }), len))
+    }
+
+    fn try_match_register(&self, input: &str) -> Option<(TokenType, usize)> {
+        let caps = self.register_regex.captures(input)?;
+
+        let captured_group = caps.get(1)?.as_str();
+        let len = caps.get(0)?.len();
+
+        let reg = Register::try_from(captured_group).ok()?;
+
+        Some((TokenType::Register(RegisterToken { reg }), len))
+    }
+
+    fn try_match_immediate(&self, input: &str) -> Option<(TokenType, usize)> {
+        let caps = self.immediate_regex.captures(input)?;
+        let value_str = caps.get(1)?.as_str();
+        let len = caps.get(0)?.len();
+
+        // Remove any underscores that were inserted for readability.
+        let value_str = value_str.replace('_', "");
+
+        let value = if let Some(hex_part) = value_str.strip_prefix("0x") {
+            u32::from_str_radix(hex_part, 16).ok()?
+        } else if let Some(bin_part) = value_str.strip_prefix("0b") {
+            u32::from_str_radix(bin_part, 2).ok()?
+        } else if let Some(oct_part) = value_str.strip_prefix("0o") {
+            u32::from_str_radix(oct_part, 8).ok()?
+        } else {
+            value_str.parse::<u32>().ok()?
+        };
+
+        Some((TokenType::Immediate(value), len))
+    }
+
+    fn try_match_directive(&self, input: &str) -> Option<(TokenType, usize)> {
+        let caps = self.directive_regex.captures(input)?;
+        let directive = caps.get(1)?.as_str().to_string();
+        let len = caps.get(0)?.len();
+
+        Some((TokenType::Directive(DirectiveToken { directive }), len))
+    }
+
+    fn try_match_instruction(&self, input: &str) -> Option<(TokenType, usize)> {
+        let caps = self.instruction_regex.captures(input)?;
+        let mnemonic = caps.get(1)?.as_str().to_string();
+        let len = caps.get(0)?.len();
+
+        let op = Opcode::from_str(&mnemonic).ok()?;
+
+        Some((TokenType::Instruction(op), len))
+    }
+
+    fn try_match_symbol(&self, input: &str) -> Option<(TokenType, usize)> {
+        let caps = self.symbol_regex.captures(input)?;
+        let len = caps.get(0)?.len();
+
+        // Check which capture group matched.
+        let name = if let Some(scoped_name) = caps.get(1) {
+            // Matched the scoped symbol pattern (name::scope).
+            format!("{}::{}", scoped_name.as_str(), caps.get(2)?.as_str())
+        } else if let Some(simple_name) = caps.get(3) {
+            simple_name.as_str().to_string()
+        } else {
+            return None;
+        };
+
+        Some((TokenType::Symbol(SymbolToken { name }), len))
+    }
+
+    fn try_match_string(
+        &mut self,
+        input: &str,
+        line_number: usize,
+        column: usize,
+    ) -> Option<(TokenType, usize)> {
+        if self.in_string {
+            // We're continuing a multiline string
+            Some(self.handle_string_continuation(input, line_number, column))
+        } else {
+            // Look for the start of a new string
+            self.handle_string_start(input, line_number, column)
+        }
+    }
+
+    fn handle_string_start(
+        &mut self,
+        input: &str,
+        line_number: usize,
+        column: usize,
+    ) -> Option<(TokenType, usize)> {
+        if !input.starts_with('"') {
+            return None;
+        }
+
+        // Find the closing quote on the same line
+        if let Some(end_pos) = input[1..].find('"') {
+            // Complete string on one line
+            let content = input[1..=end_pos].to_string();
+            let len = end_pos + 2; // +2 for both quotes
+            Some((TokenType::String(content), len))
+        } else {
+            // Start of multiline string
+            self.in_string = true;
+            self.string_start_line = line_number;
+            self.string_start_column = column;
+            self.string_buffer = input[1..].to_string(); // Everything after opening quote
+            self.string_buffer.push('\n'); // Add newline for multiline
+
+            // Consume the entire rest of the line
+            Some((TokenType::StringContinuation, input.len()))
+        }
+    }
+
+    fn handle_string_continuation(
+        &mut self,
+        input: &str,
+        _line_number: usize,
+        _column: usize,
+    ) -> (TokenType, usize) {
+        // Look for closing quote
+        if let Some(end_pos) = input.find('"') {
+            // End of multiline string found
+            self.string_buffer.push_str(&input[..end_pos]);
+            self.in_string = false;
+
+            let content = std::mem::take(&mut self.string_buffer);
+            let len = end_pos + 1; // +1 for the closing quote
+
+            (TokenType::String(content), len)
+        } else {
+            // Continue multiline string
+            self.string_buffer.push_str(input);
+            self.string_buffer.push('\n'); // Add newline
+
+            // Consume the entire line
+            (TokenType::StringContinuation, input.len())
+        }
+    }
+
+    #[expect(clippy::range_plus_one, reason = "RangeInclusive is a different type!")]
+    fn match_token(
+        &mut self,
+        input: &str,
+        line_number: usize,
+        column: usize,
+    ) -> Result<(TokenType, usize), AssembleError> {
+        if input.starts_with(',') {
+            return Ok((TokenType::Comma, 1));
+        }
+
+        // Check for string first (including multiline continuations).
+        if let Some(m) = self.try_match_string(input, line_number, column) {
+            return Ok(m);
+        }
+
+        if let Some(m) = self.try_match_directive(input) {
+            return Ok(m);
+        }
+
+        if let Some(m) = self.try_match_instruction(input) {
+            return Ok(m);
+        }
+
+        if let Some(m) = self.try_match_comment(input) {
+            return Ok(m);
+        }
+
+        if let Some(m) = self.try_match_label(input) {
+            return Ok(m);
+        }
+
+        if let Some(m) = self.try_match_register(input) {
+            return Ok(m);
+        }
+
+        if let Some(m) = self.try_match_immediate(input) {
+            return Ok(m);
+        }
+
+        if let Some(m) = self.try_match_symbol(input) {
+            return Ok(m);
+        }
+
+        let mut idx_iter = (column + 1)..;
+        let Some(idx) = idx_iter.next() else {
+            unreachable!()
+        };
+
+        let source = SourceInfo::new(line_number, self.module.clone(), idx..idx + 1);
+
+        // Handle miscellaneous characters.
+        if let Some(c) = input.chars().next() {
+            Err(AssembleError::new_source_error(
+                source,
+                AssembleErrorKind::Tokeniser(TokeniserError::UnexpectedChar(c)),
+            ))
+        } else {
+            Err(AssembleError::new_source_error(
+                source,
+                AssembleErrorKind::Tokeniser(TokeniserError::UnexpectedEndOfInput(
+                    input.len(),
+                )),
+            ))
+        }
+    }
+}

assembler/src/source/tokeniser/error.rs

@@ -0,0 +1,41 @@
+//! This module contains the error types for the tokeniser.
+
+#[derive(Debug, Clone, Copy)]
+/// Types of errors that may be returned during tokenisation.
+pub enum TokeniserError {
+    /// An unexpected character was found in the source code.
+    UnexpectedChar(char),
+    /// An unterminated string literal was found. [`SourceInfo`] will be attached if this
+    /// was returned.
+    UnterminatedString,
+    /// An invalid number format was encountered when parsing a literal value
+    /// ([`TokenType::Immediate`]).
+    InvalidNumber(&'static str),
+    /// An unrecognized token was encountered.
+    UnrecognisedToken,
+    /// Returned if the consumed count was lower than the length of the input file.
+    /// This is a sign you will need to debug some [`Tokeniser`] code to ensure that
+    /// [`Tokeniser::match_token`] is working as intended.
+    ///
+    /// First field is length of the line.
+    UnexpectedEndOfInput(usize),
+}
+
+impl TokeniserError {}
+
+impl std::fmt::Display for TokeniserError {
+    #[rustfmt::skip]
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::UnexpectedChar(c) => write!(f, "unexpected char '{c}' found in input")?,
+            Self::InvalidNumber(lit) => write!(f, "invalid integer literal \"{lit}\" found in input")?,
+            Self::UnrecognisedToken => write!(f, "unrecognised token found in input")?,
+            Self::UnterminatedString => write!(f, "unterminated string literal")?,
+            Self::UnexpectedEndOfInput(line_length) => write!(
+                f, "unexpected end of input, input length: {line_length}"
+            )?,
+        }
+
+        Ok(())
+    }
+}

assembler/src/source/tokeniser/tests.rs

@@ -0,0 +1,418 @@
+//! Unit tests for the tokenizer
+
+use common::prelude::Register;
+
+use crate::{
+    model::module::Module,
+    source::{
+        opcode::Opcode,
+        token::{Token, TokenType},
+        token_info::RegisterToken,
+        tokeniser::Tokeniser,
+    },
+};
+use std::{path::PathBuf, sync::Arc};
+
+/// Helper function to create a tokenizer from source text
+fn create_tokenizer_from_source(source: &str) -> Tokeniser {
+    let path = PathBuf::from("test.dsa");
+    let module = Module::new(path).expect("Cannot create module!");
+
+    Tokeniser::from_data(source.as_bytes().to_vec(), Arc::new(module))
+}
+
+/// Helper function to tokenize source and return tokens
+fn tokenize_source(source: &str) -> Result<Vec<Token>, crate::error::AssembleError> {
+    let tokenizer = create_tokenizer_from_source(source);
+
+    tokenizer.tokenise()
+}
+
+/// Helper function to extract token types from a token vector
+fn extract_token_types(tokens: &[Token]) -> Vec<&TokenType> {
+    tokens.iter().map(|t| &t.token_type).collect()
+}
+
+#[test]
+fn test_empty_source() {
+    let tokens = tokenize_source("").expect("Failed to tokenize empty source");
+
+    // Should have at least EOF token
+    assert!(!tokens.is_empty());
+    assert!(matches!(
+        tokens
+            .last()
+            .expect("Expected at least one token")
+            .token_type,
+        TokenType::Eof
+    ));
+}
+
+#[test]
+fn test_whitespace_only() {
+    let tokens = tokenize_source("   \n  \n  ").expect("Failed to tokenize whitespace");
+
+    // Should have newlines and EOF
+    let token_types = extract_token_types(&tokens);
+    assert!(token_types.iter().any(|t| matches!(t, TokenType::Newline)));
+    assert!(token_types.iter().any(|t| matches!(t, TokenType::Eof)));
+}
+
+#[test]
+fn test_single_instruction() {
+    let tokens = tokenize_source("add").expect("Failed to tokenize instruction");
+    let token_types = extract_token_types(&tokens);
+
+    // Should have instruction, newline, and EOF
+    assert!(
+        token_types
+            .iter()
+            .any(|t| matches!(t, TokenType::Instruction(_)))
+    );
+    if let TokenType::Instruction(instr) = &tokens[0].token_type {
+        assert_eq!(instr.to_string(), "add");
+    } else {
+        panic!("Expected instruction token");
+    }
+}
+
+#[test]
+fn test_all_instructions() {
+    let instructions = ["add", "sub", "jmp", "call", "return", "lli", "nop", "hlt"];
+
+    for instr in &instructions {
+        let tokens = tokenize_source(instr).expect("Failed to tokenize instruction");
+
+        if let TokenType::Instruction(parsed_instr) = &tokens[0].token_type {
+            assert_eq!(parsed_instr.to_string(), *instr);
+        } else {
+            panic!("Expected instruction token for {instr}");
+        }
+    }
+}
+
+#[test]
+fn test_registers() {
+    let test_cases = [("rg0", "rg0"), ("rgf", "rgf"), ("pcx", "pcx")];
+
+    for (input, expected) in &test_cases {
+        let tokens = tokenize_source(input).expect("Failed to tokenize register");
+
+        if let TokenType::Register(reg) = &tokens[0].token_type {
+            assert_eq!(reg.reg.to_string(), *expected);
+        } else {
+            panic!("Expected register token for {input}");
+        }
+    }
+}
+
+#[test]
+fn test_immediates() {
+    let test_cases = [
+        ("42", 42),
+        ("0", 0),
+        ("0xFF", 255),
+        ("0x1234", 0x1234),
+        ("0xDEADBEEF", 0xDEAD_BEEF),
+        ("0o12", 0o12),
+        ("0b101", 0b101),
+    ];
+
+    for (input, expected) in &test_cases {
+        let tokens = tokenize_source(input).expect("Failed to tokenize immediate");
+
+        if let TokenType::Immediate(value) = &tokens[0].token_type {
+            assert_eq!(*value, *expected);
+        } else {
+            panic!("Expected immediate token for {input}");
+        }
+    }
+}
+
+#[test]
+fn test_labels() {
+    let test_cases = [
+        ("loop_start:", "loop_start"),
+        ("main:", "main"),
+        ("_private_label:", "_private_label"),
+        ("Label123:", "Label123"),
+    ];
+
+    for (input, expected) in &test_cases {
+        let tokens = tokenize_source(input).expect("Failed to tokenize label");
+
+        if let TokenType::Label(label) = &tokens[0].token_type {
+            assert_eq!(label.name, *expected);
+        } else {
+            panic!("Expected label token for {input}");
+        }
+    }
+}
+
+#[test]
+fn test_directives() {
+    let test_cases = [
+        ("global", "global"),
+        ("section", "section"),
+        ("local", "local"),
+    ];
+
+    for (input, expected) in &test_cases {
+        let tokens = tokenize_source(input).expect("Failed to tokenize directive");
+
+        if let TokenType::Directive(directive) = &tokens[0].token_type {
+            assert_eq!(directive.directive, *expected);
+        } else {
+            panic!("Expected directive token for {input}");
+        }
+    }
+}
+
+#[test]
+fn test_symbols() {
+    let test_cases = [
+        ("my_symbol", "my_symbol"),
+        ("_private", "_private"),
+        ("Symbol123", "Symbol123"),
+        ("camelCase", "camelCase"),
+    ];
+
+    for (input, expected) in &test_cases {
+        let tokens = tokenize_source(input).expect("Failed to tokenize symbol");
+
+        if let TokenType::Symbol(symbol) = &tokens[0].token_type {
+            assert_eq!(symbol.name, *expected);
+        } else {
+            panic!("Expected symbol token for {input}");
+        }
+    }
+}
+
+#[test]
+fn test_complex_instruction_line() {
+    let source = "addi rg1, rg2, 0xFF";
+    let tokens = tokenize_source(source).expect("Failed to tokenise complex instruction");
+
+    // Should have: instruction, register, comma, register, comma, immediate, newline, EOF
+    assert!(tokens.len() >= 6);
+    assert!(matches!(tokens[0].token_type, TokenType::Instruction(_)));
+    assert!(matches!(tokens[1].token_type, TokenType::Register(_)));
+    assert!(matches!(tokens[2].token_type, TokenType::Comma));
+    assert!(matches!(tokens[3].token_type, TokenType::Register(_)));
+    assert!(matches!(tokens[4].token_type, TokenType::Comma));
+    assert!(matches!(tokens[5].token_type, TokenType::Immediate(_)));
+}
+
+#[test]
+fn test_multiline_with_comments() {
+    const EXPECTED_TOKEN_TYPES: [TokenType; 11] = [
+        TokenType::Instruction(Opcode::Add),
+        TokenType::Register(RegisterToken::new(Register::Rg0)),
+        TokenType::Comma,
+        TokenType::Register(RegisterToken::new(Register::Rg1)),
+        TokenType::Newline,
+        TokenType::Instruction(Opcode::SubI),
+        TokenType::Register(RegisterToken::new(Register::Rg2)),
+        TokenType::Comma,
+        TokenType::Immediate(10),
+        TokenType::Newline,
+        TokenType::Eof,
+    ];
+
+    const SOURCE: &str = r"add rg0, rg1 // Another comment
+        subi rg2, 10";
+
+    let tokens =
+        tokenize_source(SOURCE).expect("Failed to tokenise source with comments");
+    let token_types = extract_token_types(&tokens);
+
+    assert_eq!(
+        token_types.len(),
+        EXPECTED_TOKEN_TYPES.len(),
+        "{token_types:#?}"
+    );
+
+    for (expected, got) in EXPECTED_TOKEN_TYPES.iter().zip(token_types.iter()) {
+        assert!(!(expected != *got), "Expected {expected:?}, got {got:?}");
+    }
+}
+
+#[test]
+fn test_tokenise_brainf_interpreter() {
+    const SOURCE: &str = include_str!("../../../../resources/dsa/bf.dsa");
+
+    let tokens =
+        tokenize_source(SOURCE).expect("Failed to tokenise the brainfuck compiler!");
+
+    dbg!(tokens);
+}
+
+#[test]
+fn test_string_literals() {
+    let test_cases = [
+        (r#""hello world""#, "hello world"),
+        (
+            r#""++++++++++++++++++++++++++++++++++++++++++++""#,
+            "++++++++++++++++++++++++++++++++++++++++++++",
+        ),
+        (r#""Invalid Instruction!""#, "Invalid Instruction!"),
+        (r#""""#, ""),
+    ];
+
+    for (input, expected) in &test_cases {
+        let tokens = tokenize_source(input).expect("Failed to tokenize string literal");
+
+        if let TokenType::String(value) = &tokens[0].token_type {
+            assert_eq!(value, expected);
+        } else {
+            panic!("Expected string token for {input}");
+        }
+    }
+}
+
+#[test]
+fn test_data_directives() {
+    let test_cases = [("db", "db"), ("dw", "dw"), ("resb", "resb")];
+
+    for (input, expected) in &test_cases {
+        let tokens = tokenize_source(input).expect("Failed to tokenize data declaration");
+
+        if let TokenType::Directive(decl) = &tokens[0].token_type {
+            assert_eq!(decl.directive, *expected);
+        } else {
+            panic!("Expected data declaration token for {input}");
+        }
+    }
+}
+
+#[test]
+fn test_include_directive() {
+    let source = r#"include print "./lib/print.dsa""#;
+    let tokens = tokenize_source(source).expect("Failed to tokenize include directive");
+
+    assert!(tokens.len() >= 3);
+    assert!(matches!(tokens[0].token_type, TokenType::Directive(_)));
+    assert!(matches!(tokens[1].token_type, TokenType::Symbol(_)));
+    assert!(matches!(tokens[2].token_type, TokenType::String(_)));
+}
+
+#[test]
+fn test_hex_addresses() {
+    let test_cases = [("0x10000", 0x10000), ("0x30000", 0x30000)];
+
+    for (input, expected) in &test_cases {
+        let tokens = tokenize_source(input).expect("Failed to tokenize hex address");
+
+        if let TokenType::Immediate(value) = &tokens[0].token_type {
+            assert_eq!(*value, *expected);
+        } else {
+            panic!("Expected immediate token for {input}");
+        }
+    }
+}
+
+#[test]
+fn test_memory_operations() {
+    let source = "ldw rg1, rg2";
+    let tokens = tokenize_source(source).expect("Failed to tokenize memory operation");
+
+    assert!(tokens.len() >= 4);
+    assert!(matches!(tokens[0].token_type, TokenType::Instruction(_)));
+    assert!(matches!(tokens[1].token_type, TokenType::Register(_)));
+    assert!(matches!(tokens[2].token_type, TokenType::Comma));
+    assert!(matches!(tokens[3].token_type, TokenType::Register(_)));
+}
+
+#[test]
+fn test_function_calls() {
+    let source = "call print::print";
+    let tokens = tokenize_source(source).expect("Failed to tokenize function call");
+
+    assert!(tokens.len() >= 2);
+    assert!(matches!(tokens[0].token_type, TokenType::Instruction(_)));
+    // The symbol might be parsed differently depending on how :: is handled
+    // This test checks basic structure
+    assert!(
+        tokens
+            .iter()
+            .any(|t| matches!(t.token_type, TokenType::Symbol(_)))
+    );
+}
+
+#[test]
+fn test_comments_are_ignored() {
+    let source = "add rg0, rg1 // this is a comment\nsub rg2, rg3";
+    let tokens = tokenize_source(source).expect("Failed to tokenize with comments");
+
+    // Comments should be stripped, so we should only have instruction tokens
+    let instruction_count = tokens
+        .iter()
+        .filter(|t| matches!(t.token_type, TokenType::Instruction(_)))
+        .count();
+
+    assert_eq!(instruction_count, 2);
+}
+
+#[test]
+fn test_newline_always_present() {
+    // Test that even without explicit newline at end, one is added
+    let source = "add rg0, rg1"; // No newline at end
+    let tokens = tokenize_source(source).expect("Failed to tokenize without newline");
+
+    // Should have newline before EOF
+    let has_newline = tokens
+        .iter()
+        .any(|t| matches!(t.token_type, TokenType::Newline));
+
+    assert!(
+        has_newline,
+        "Expected newline to be added even when missing from input"
+    );
+
+    // EOF should be last.
+    assert!(matches!(
+        tokens
+            .last()
+            .expect("Expected at least one token")
+            .token_type,
+        TokenType::Eof
+    ));
+}
+
+#[test]
+fn test_complex_branching_code() {
+    let source = r"
+    cmp rg3, rg8
+    jeq increment
+    cmp rg3, rg9
+    jeq decrement";
+
+    let tokens = tokenize_source(source).expect("Failed to tokenize branching code");
+
+    let instruction_count = tokens
+        .iter()
+        .filter(|t| matches!(t.token_type, TokenType::Instruction(_)))
+        .count();
+
+    assert_eq!(instruction_count, 4);
+
+    let symbol_count = tokens
+        .iter()
+        .filter(|t| matches!(t.token_type, TokenType::Symbol(_)))
+        .count();
+
+    assert_eq!(symbol_count, 2); // increment and decrement labels
+}
+
+#[test]
+fn test_stack_operations() {
+    let source = "push rg2\npop zero\npusha 2\npopa 2";
+    let tokens = tokenize_source(source).expect("Failed to tokenize stack operations");
+
+    let instruction_count = tokens
+        .iter()
+        .filter(|t| matches!(t.token_type, TokenType::Instruction(_)))
+        .count();
+
+    assert_eq!(instruction_count, 4);
+}

assembler/src/symtab.rs

@@ -0,0 +1,122 @@
+//! This module contains the code for the Symbol Table, which can be written into object
+//! files to support deferred relocations when using ELF files.
+//!
+//! It is also required for detection of duplicate symbols, and resolution in the flat
+//! binary output type.
+
+use crate::{
+    error::AssembleError,
+    model::{
+        module::ModuleId,
+        symbol::{Symbol, SymbolId, Visibility},
+    },
+};
+use std::collections::HashMap;
+
+/// Global symbol table - single source of truth for all symbols.
+/// Much simpler than per-module tables.
+#[derive(Debug)]
+pub struct SymbolTable {
+    /// All symbols by their ID - O(1) lookup
+    symbols: HashMap<SymbolId, Symbol>,
+    /// Name to ID mapping for human-readable lookups - O(1) lookup
+    name_to_id: HashMap<String, SymbolId>,
+    /// Module to symbols mapping for module-specific queries
+    module_symbols: HashMap<ModuleId, Vec<SymbolId>>,
+}
+
+impl SymbolTable {
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            symbols: HashMap::new(),
+            name_to_id: HashMap::new(),
+            module_symbols: HashMap::new(),
+        }
+    }
+
+    /// Adds a symbol to the global table
+    pub fn add_symbol(&mut self, symbol: Symbol) -> Result<SymbolId, AssembleError> {
+        let id = symbol.id;
+        let module_id = symbol.module_id;
+        let name = symbol.name.clone();
+
+        // Check for duplicate names in the same module
+        if let Some(&existing_id) = self.name_to_id.get(&name)
+            && let Some(existing) = self.symbols.get(&existing_id)
+            && existing.module_id == module_id
+        {
+            return Err(std::io::Error::new(
+                std::io::ErrorKind::AlreadyExists,
+                format!("Symbol '{name}' already defined in module"),
+            )
+            .into());
+        }
+
+        // Add to all mappings
+        self.name_to_id.insert(name, id);
+        self.symbols.insert(id, symbol);
+        self.module_symbols.entry(module_id).or_default().push(id);
+
+        Ok(id)
+    }
+
+    /// Gets the [`Symbol`] by its [`SymbolId`].
+    #[must_use]
+    pub fn get(&self, id: &SymbolId) -> Option<&Symbol> {
+        self.symbols.get(id)
+    }
+
+    /// Gets the [`Symbol`] by its name.
+    #[must_use]
+    pub fn get_by_name(&self, name: &str) -> Option<&Symbol> {
+        self.name_to_id
+            .get(name)
+            .and_then(|id| self.symbols.get(id))
+    }
+
+    /// Gets all [`Symbol`]s in a module.
+    #[must_use]
+    pub fn get_module_symbols(&self, module_id: &ModuleId) -> Vec<&Symbol> {
+        self.module_symbols
+            .get(module_id)
+            .map(|ids| ids.iter().filter_map(|id| self.symbols.get(id)).collect())
+            .unwrap_or_default()
+    }
+
+    /// Gets all the public symbols.
+    #[must_use]
+    pub fn get_public_symbols(&self) -> Vec<&Symbol> {
+        self.symbols
+            .values()
+            .filter(|sym| matches!(sym.visibility, Visibility::Public))
+            .collect()
+    }
+
+    /// Updates symbol address (during resolution). Used for flat binaries or symbols with
+    /// no relocations.
+    pub fn update_symbol_address(
+        &mut self,
+        id: &SymbolId,
+        address: u32,
+    ) -> Result<(), AssembleError> {
+        if let Some(symbol) = self.symbols.get_mut(id) {
+            symbol.address = Some(address);
+            if symbol.dependencies.is_empty() {
+                symbol.needs_relocation = false;
+            }
+            Ok(())
+        } else {
+            Err(
+                std::io::Error::new(std::io::ErrorKind::NotFound, "Symbol not found")
+                    .into(),
+            )
+        }
+    }
+}
+
+impl Default for SymbolTable {
+    fn default() -> Self {
+        Self::new()
+    }
+}

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,109 @@
+#![allow(dead_code)]
+#![allow(unused)]
+use std::{fmt, sync::mpsc::Sender};
+
+#[derive(Debug, PartialEq, Eq)]
+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()
+}

book.toml

@@ -1,5 +0,0 @@
-[book]
-authors = ["zxq5", "nullndvoid"]
-language = "en"
-src = "src"
-title = "damn_simple_architecture"

common/Cargo.toml

@@ -0,0 +1,8 @@
+[package]
+name = "common"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+
+[dependencies]
+object = { version = "0.37.1", default-features = false, features = ["elf", "std", "read", "read_core", "write_std", "write", "alloc", "build"] }

common/README.md

@@ -0,0 +1,3 @@
+# Common types and methods for the DSA
+
+This library contains the instruction set, encoding and decoding routines, and ELF encoding and loading routines (WIP).

common/src/elf.rs

@@ -0,0 +1,8 @@
+//! ELF file creation and parsing routines.
+
+use object::{Endianness, build::elf::Builder};
+
+#[allow(clippy::missing_const_for_fn)]
+pub fn write() {
+    let _builder = Builder::new(Endianness::Little, false);
+}

common/src/instructions.rs

@@ -0,0 +1,516 @@
+use crate::{instructions::encode::Encode, prelude::*};
+
+#[derive(Copy, Clone, Debug, PartialEq, Eq, Default)]
+pub enum Interrupt {
+    Software(u8),
+    Breakpoint,
+    #[default]
+    HardFault,
+}
+
+pub type Address = u32;
+
+impl Interrupt {
+    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, Hash)]
+#[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,213 @@
+//! 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, Default)]
+/// 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, Default)]
+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,70 @@
+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::Interrupt(_) => todo!(),
+                Self::Data(data) => data,
+                Self::Segment(segment) => {
+                    let opcode = u32::from(self.opcode());
+                    let segment = segment as u8;
+                    (opcode << 26) | u32::from(segment)
+                }
+            ]
+        )
+    }
+}
+
+#[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,58 @@
+//! 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,23 @@
+#![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 elf;
+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,297 @@
+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()
+            && 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,234 @@
+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,
+                            );
+                        });
+                }
+                #[expect(unused_assignments)]
+                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);
+                    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);
+                    eprintln!("Could not decode instruction at {pcx:x}. Reason: {why}");
+                    continue;
+                }
+            };
+
+            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);
+    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 fn reg(&mut self, reg: Register) -> &mut u32 {
+        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,
+            _ => panic!("Invalid register."),
+        }
+    }
+
+    #[must_use]
+    pub fn get(&self, reg: Register) -> u32 {
+        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,
+            _ => panic!("Invalid register."),
+        }
+    }
+}

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

@@ -0,0 +1,478 @@
+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 dustbin: u32,
+}
+
+#[expect(dead_code)]
+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,
+            dustbin: 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))
+    }
+
+    fn fetch(&self) -> u32 {
+        self.get(Register::Pcx)
+    }
+
+    #[must_use]
+    pub fn get(&self, reg: Register) -> u32 {
+        self.registers.get(reg)
+    }
+
+    pub fn reg(&mut self, reg: Register) -> &mut u32 {
+        match reg {
+            Register::Zero => &mut self.dustbin,
+            _ => 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) |= flag as u32;
+        } else {
+            *self.reg(Register::Sts) &= !(flag as u32);
+        }
+    }
+
+    fn get_flag(&self, flag: Flag) -> bool {
+        self.get(Register::Sts) & (flag as u32) != 0
+    }
+
+    fn advance(&mut self) {
+        // increment PCX
+        *self.reg(Register::Pcx) += 4;
+    }
+
+    fn jump(&mut self, reg: Register, offset: u16) {
+        *self.reg(Register::Pcx) = self.get(reg) + u32::from(offset);
+    }
+
+    pub fn begin_interrupt(&mut self, _int: Interrupt) {
+        // first we get the address of the interrupt descriptor table.
+        todo!();
+    }
+
+    // TODO: remove this once implemented
+    #[allow(clippy::needless_pass_by_ref_mut)]
+    fn end_interrupt(&mut self) {
+        todo!();
+    }
+
+    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 regval = cpu.get(a.sr2);
+                let val = cpu.get(a.sr1);
+
+                *cpu.reg(a.sr1) =
+                    shl(val, if regval != 0 { regval as u8 } else { a.shamt });
+            }
+
+            // Right shifts the value in Reg by the given amount (either a register, or a
+            // literal value).
+            Self::ShiftRight(a) => {
+                let regval = cpu.get(a.sr2);
+                let val = cpu.get(a.sr1);
+
+                *cpu.reg(a.sr1) =
+                    shr(val, if regval != 0 { regval as u8 } else { a.shamt });
+            }
+
+            // Adds the value of Src2 to Src1 and writes the result to a.dr
+            Self::Add(a) => {
+                *cpu.reg(a.dr) = add(cpu.get(a.sr1), cpu.get(a.sr2));
+            }
+
+            // 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,595 @@
+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),
+        initial_state.get(Register::Rg0)
+    );
+    assert_eq!(
+        cpu.registers.get(Register::Acc),
+        initial_state.get(Register::Acc)
+    );
+}
+
+#[test]
+fn test_mov_instruction() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(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), 0x1234_5678);
+}
+
+#[test]
+fn test_mov_signed_instruction() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(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), 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) = 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), 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) = 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), 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) = 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), 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) = 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), 0x1234_5678);
+}
+
+#[test]
+fn test_store_byte_instruction() {
+    let mut cpu = create_test_processor();
+    let addr = 0x100;
+    *cpu.reg(Register::Rg1) = addr;
+    *cpu.reg(Register::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) = addr;
+    *cpu.reg(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) = 15;
+    *cpu.reg(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), 40);
+}
+
+#[test]
+fn test_sub_instruction() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(Register::Rg1) = 50;
+    *cpu.reg(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), 30);
+}
+
+#[test]
+fn test_and_instruction() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(Register::Rg1) = 0b1100;
+    *cpu.reg(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), 0b1000);
+}
+
+#[test]
+fn test_or_instruction() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(Register::Rg1) = 0b1100;
+    *cpu.reg(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), 0b1110);
+}
+
+#[test]
+fn test_xor_instruction() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(Register::Rg1) = 0b1100;
+    *cpu.reg(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), 0b0110);
+}
+
+#[test]
+fn test_not_instruction() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(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), 0xF0F0_F0F0);
+}
+
+#[test]
+fn test_compare_equal() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(Register::Rg1) = 42;
+    *cpu.reg(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));
+    assert!(!cpu.get_flag(Flag::GreaterThan));
+    assert!(!cpu.get_flag(Flag::LessThan));
+}
+
+#[test]
+fn test_compare_greater_than() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(Register::Rg1) = 50;
+    *cpu.reg(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));
+    assert!(cpu.get_flag(Flag::GreaterThan));
+    assert!(!cpu.get_flag(Flag::LessThan));
+}
+
+#[test]
+fn test_compare_less_than() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(Register::Rg1) = 20;
+    *cpu.reg(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));
+    assert!(!cpu.get_flag(Flag::GreaterThan));
+    assert!(cpu.get_flag(Flag::LessThan));
+}
+
+#[test]
+fn test_increment_instruction() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(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), 43);
+}
+
+#[test]
+fn test_decrement_instruction() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(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), 41);
+}
+
+#[test]
+fn test_shift_left_with_shamt() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(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), 0b10_1000);
+}
+
+#[test]
+fn test_shift_right_with_shamt() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(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), 0b1010);
+}
+
+#[test]
+fn test_shift_left_with_register() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(Register::Rg1) = 0b1010;
+    *cpu.reg(Register::Rg2) = 3;
+
+    let shl_instr = Instruction::ShiftLeft(RTypeArgs::new(
+        Some(Register::Rg1),
+        Some(Register::Rg2),
+        None,
+        None,
+    ));
+
+    shl_instr.execute(&mut cpu).expect(
+        "Emulator was slain by losing the game while attempting to execute instruction",
+    );
+    assert_eq!(cpu.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), 0x0000_1234);
+}
+
+#[test]
+fn test_load_upper_immediate() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(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), 0x1234_5678);
+}
+
+#[test]
+fn test_jump_unconditional() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(Register::Rg1) = 0x1000;
+    let initial_pc = cpu.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), 0x1100);
+    assert_ne!(cpu.get(Register::Pcx), initial_pc);
+}
+
+#[test]
+fn test_jump_equal_when_flag_set() {
+    let mut cpu = create_test_processor();
+    cpu.set_flag(Flag::Equal, true);
+    *cpu.reg(Register::Rg1) = 0x1000;
+
+    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), 0x1100);
+}
+
+#[test]
+fn test_jump_equal_when_flag_not_set() {
+    let mut cpu = create_test_processor();
+    cpu.set_flag(Flag::Equal, false);
+    *cpu.reg(Register::Rg1) = 0x1000;
+    let initial_pc = cpu.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), 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) = 0b1100;
+    *cpu.reg(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), !0b1000);
+}
+
+#[test]
+fn test_nor_instruction() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(Register::Rg1) = 0b1100;
+    *cpu.reg(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), !0b1110);
+}
+
+#[test]
+fn test_xnor_instruction() {
+    let mut cpu = create_test_processor();
+    *cpu.reg(Register::Rg1) = 0b1100;
+    *cpu.reg(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), !0b0110);
+}

emulator/src/emulator/ui/control_unit.rs

@@ -0,0 +1,189 @@
+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);
+            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))
+                .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,546 @@
+use std::fmt::Write;
+use std::{
+    ffi::OsStr,
+    fs,
+    path::{Path, PathBuf},
+};
+
+use assembler::compiler_engine::CompilerEngine;
+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) - 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/concept/assemblerconcept.md

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

resources/dsa/bf.dsa

@@ -0,0 +1,224 @@
+
+// a simple brainf##k interpreter,
+// because I already wrote a compiler lol.
+
+include print "./lib/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/fib.dsa

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

resources/dsa/lib/multiply.dsa

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

resources/dsa/lib/print.dsa

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

resources/dsa/test.dsa

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

resources/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/README.md

@@ -1 +0,0 @@
-# Introduction

src/SUMMARY.md

@@ -1,29 +0,0 @@
-# Summary
-
-[Introduction](README.md)
-
-- [DSA - Damn Simple Assembly](dsa.md)
-  - [Instructions](dsa/instructions.md)
-    - [Hardware Instructions](dsa/instructions/hardware.md)
-    - [Pseudo Instructions](dsa/instructions/pseudo.md)
-    - [Data Directives](dsa/instructions/directives.md)
-  - [Usable Registers](dsa/registers.md)
-  - [Imports](dsa/imports.md)
-  - [Calling Convention](dsa/cconv.md)
-  - [Examples](dsa/examples.md)
-  - [Tooling](dsa/tooling.md)
-    - [Assembler](dsa/tooling/assembler.md)
-    - [Syntax](dsa/tooling/syntax_tooling.md)
-- [DSA Emulator](emulator.md)
-  - [Building the Emulator](emulator/building.md)
-  - [Features](emulator/features.md)
-    - [Control Panel](emulator/features/control_panel.md)
-    - [Memory Inspector](emulator/features/memory_inspector.md)
-    - [Stack Inspector](emulator/features/stack_inspector.md)
-    - [Editor](emulator/features/editor.md)
-    - [Loader](emulator/features/loader.md)
-    - [Display](emulator/features/display.md)
-    - [Instruction History](emulator/features/instruction_history.md)
-- [DSC - Damn Simple Code](dsc.md)
-- [Other Language Support](misc_languages.md)
-  - [Brainf*](misc_languages/brainf.md)

src/dsa.md

@@ -1,12 +0,0 @@
-# DSA Assembly Language Instruction Reference
-
-## Overview
-
-This document provides a comprehensive reference for the DSA (Damn Simple Architecture) assembly language, including all hardware instructions and pseudo-instructions with their syntax variations and usage examples.
-
-## Table of Contents
-- [Instructions](instructions.md)
-- [Tooling](tooling.md)
-- [Imports](imports.md)
-- [Calling Convention](cconv.md)
-- [Examples](examples.md)