MVP of LC3 VM in Rust

Cargo.toml

@@ -15,7 +15,8 @@ unwrap_used = "deny"
 expect_used = "deny"
 
 arithmetic_side_effects = "deny"
-overflow_check_conditional = "warn"
+panicking_overflow_checks = "warn"
 manual_saturating_arithmetic = "warn"
 
 [dependencies]
+termios = "0.3.3"

Makefile

@@ -0,0 +1,12 @@
+build:
+	cargo build
+run:
+	cargo run $(FILEPATH)
+test:
+	cargo test
+check:
+	cargo check
+lint:
+	cargo clippy -- -D warnings
+
+.PHONY: all run test check lint

README.md

@@ -2,6 +2,34 @@
 
 An implementation of the LC3 (Little Computer 3) Virtual Machine in Rust
 
+A VM is a program that acts like a computer. It simulates a CPU along with a few other hardware components, allowing it to perform arithmetic, read and write to memory, and interact with I/O devices, just like a physical computer. Most importantly, it can understand a machine language which you can use to program it.
+
 ## Reference
 
 This was made by following this guide: https://www.jmeiners.com/lc3-vm/
+
+## Installation
+
+1. Clone the repository
+```bash
+git clone https://github.com/tomip01/lc3-vm.git
+```
+2. Change to the directory:
+```bash
+cd lc3-vm
+```
+3. Build project:
+```bash
+make build
+```
+
+## Usage
+**Run object file**
+```bash
+make run FILEPATH=<path/to/file>
+```
+
+**Run example**
+```bash
+make run FILEPATH=./images/2048.obj
+```

src/lc3/bytes.rs

@@ -0,0 +1,52 @@
+use super::vm::VMError;
+
+pub fn sign_extend(mut value: u16, bit_count: u16) -> Result<u16, VMError> {
+    let last_bit_position = bit_count.checked_sub(1).ok_or(VMError::Overflow)?;
+    if (value >> (last_bit_position) & 1) == 1 {
+        value |= 0xFFFF << bit_count;
+    }
+    Ok(value)
+}
+
+pub fn concatenate_bytes(bytes: &[u8]) -> Result<u16, VMError> {
+    // maybe this check is redundant
+    if bytes.len() != 2 {
+        return Err(VMError::ConcatenatingBytes(String::from(
+            "Image file is not made from words of 16 bits",
+        )));
+    }
+    let first_byte: u8 = *bytes
+        .first()
+        .ok_or(VMError::ConcatenatingBytes(String::from(
+            "Non existing first byte",
+        )))?;
+    let second_byte: u8 = *bytes
+        .get(1)
+        .ok_or(VMError::ConcatenatingBytes(String::from(
+            "Non existing second byte",
+        )))?;
+    let res = u16::from_be_bytes([first_byte, second_byte]);
+    Ok(res)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn sign_extend_mantains_sign() -> Result<(), VMError> {
+        let x = 0b11111;
+        let y = 0b01111;
+        assert_eq!(sign_extend(x, 5)?, 0xFFFF);
+        assert_eq!(sign_extend(y, 5)?, 0x000F);
+        Ok(())
+    }
+
+    #[test]
+    fn concatenates_two_bytes() -> Result<(), VMError> {
+        let buffer: [u8; 2] = [0x12, 0x34];
+        let concatenated = concatenate_bytes(&buffer)?;
+        assert_eq!(concatenated, 0x1234);
+        Ok(())
+    }
+}

src/lc3/memory.rs

@@ -0,0 +1,117 @@
+use std::{fs, io::Read};
+
+use super::{bytes::concatenate_bytes, vm::VMError};
+
+const MEMORY_MAX: usize = 1 << 16;
+// Keyboard status register
+const MR_KBSR: usize = 0xFE00;
+// Keyboard data register
+const MR_KBDR: usize = 0xFE02;
+
+pub struct Memory {
+    memory: [u16; MEMORY_MAX],
+}
+
+impl Memory {
+    pub fn new() -> Memory {
+        Memory {
+            memory: [0; MEMORY_MAX],
+        }
+    }
+
+    pub fn read_image(&mut self, image_path: &str) -> Result<(), VMError> {
+        let content = &fs::read(image_path).map_err(|e| {
+            VMError::ReadingFile(format!("Failed to read file {}: {}", image_path, e))
+        })?;
+        self.read_image_bytes(content)?;
+        Ok(())
+    }
+
+    fn read_image_bytes(&mut self, bytes: &[u8]) -> Result<(), VMError> {
+        let mut collected: Vec<u16> = Vec::new();
+        let mut chunks_of_two_bytes = bytes.chunks_exact(2);
+        let origin: usize = concatenate_bytes(chunks_of_two_bytes.next().ok_or(
+            VMError::ConcatenatingBytes(String::from("No valid origin position from image")),
+        )?)?
+        .into();
+        for chunk in chunks_of_two_bytes {
+            let concatenated = concatenate_bytes(chunk)?;
+            collected.push(concatenated);
+        }
+
+        for (i, word) in collected.iter().enumerate() {
+            let index = i
+                .checked_add(origin)
+                .ok_or(VMError::MemoryIndex(String::from(
+                    "Invalid index to access memory on loading",
+                )))?;
+            self.mem_write(*word, index)?;
+        }
+
+        Ok(())
+    }
+
+    pub fn mem_read(&mut self, index: usize) -> Result<u16, VMError> {
+        if index == MR_KBSR {
+            self.check_key()?;
+        }
+        let value = self
+            .memory
+            .get(index)
+            .ok_or(VMError::MemoryIndex(String::from(
+                "Invalid out of bounds when reading from memory",
+            )))?;
+        Ok(*value)
+    }
+
+    pub fn mem_write(&mut self, value: u16, index: usize) -> Result<(), VMError> {
+        let cell = self
+            .memory
+            .get_mut(index)
+            .ok_or(VMError::MemoryIndex(String::from(
+                "Index out of bound when writing memory",
+            )))?;
+        *cell = value;
+        Ok(())
+    }
+
+    fn check_key(&mut self) -> Result<(), VMError> {
+        let mut buffer: [u8; 1] = [0];
+        std::io::stdin()
+            .read_exact(&mut buffer)
+            .map_err(|e| VMError::StandardIO(format!("Cannot read from Standard Input: {}", e)))?;
+
+        if buffer[0] != 0 {
+            self.mem_write(1 << 15, MR_KBSR)?;
+            self.mem_write(buffer[0].into(), MR_KBDR)?;
+        } else {
+            self.mem_write(0, MR_KBSR)?;
+        }
+
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn read_and_write() -> Result<(), VMError> {
+        let mut mem = Memory::new();
+        mem.mem_write(0x4242, 0x2424)?;
+        assert_eq!(0x4242, mem.mem_read(0x2424)?);
+        Ok(())
+    }
+
+    #[test]
+    fn correct_image_read() -> Result<(), VMError> {
+        let mut mem = Memory::new();
+        // file containing 0x00 0x30 0xf2 0xf3 0xf4 0xf5 0xf6 0xf7
+        mem.read_image("images/test-image-load-big-endian")?;
+        assert_eq!(mem.mem_read(0x3000)?, 0xf3f2);
+        assert_eq!(mem.mem_read(0x3001)?, 0xf5f4);
+        assert_eq!(mem.mem_read(0x3002)?, 0xf7f6);
+        Ok(())
+    }
+}

src/lc3/mod.rs

@@ -0,0 +1,5 @@
+pub mod bytes;
+pub mod memory;
+pub mod opcode;
+pub mod trap;
+pub mod vm;

src/lc3/opcode.rs

@@ -0,0 +1,47 @@
+use std::convert::TryFrom;
+
+use super::vm::VMError;
+pub enum Opcode {
+    BR = 0, /* branch */
+    Add,    /* add  */
+    LD,     /* load */
+    ST,     /* store */
+    Jsr,    /* jump register */
+    And,    /* bitwise and */
+    Ldr,    /* load register */
+    Str,    /* store register */
+    Rti,    /* unused */
+    Not,    /* bitwise not */
+    Ldi,    /* load indirect */
+    Sti,    /* store indirect */
+    Jmp,    /* jump */
+    Res,    /* reserved (unused) */
+    Lea,    /* load effective address */
+    Trap,   /* execute trap */
+}
+
+impl TryFrom<u16> for Opcode {
+    type Error = VMError;
+
+    fn try_from(value: u16) -> Result<Self, Self::Error> {
+        match value {
+            0b0000 => Ok(Opcode::BR),
+            0b0001 => Ok(Opcode::Add),
+            0b0010 => Ok(Opcode::LD),
+            0b0011 => Ok(Opcode::ST),
+            0b0100 => Ok(Opcode::Jsr),
+            0b0101 => Ok(Opcode::And),
+            0b0110 => Ok(Opcode::Ldr),
+            0b0111 => Ok(Opcode::Str),
+            0b1000 => Ok(Opcode::Rti),
+            0b1001 => Ok(Opcode::Not),
+            0b1010 => Ok(Opcode::Ldi),
+            0b1011 => Ok(Opcode::Sti),
+            0b1100 => Ok(Opcode::Jmp),
+            0b1101 => Ok(Opcode::Res),
+            0b1110 => Ok(Opcode::Lea),
+            0b1111 => Ok(Opcode::Trap),
+            _ => Err(VMError::InvalidOpcode),
+        }
+    }
+}

src/lc3/trap.rs

@@ -0,0 +1,27 @@
+use super::vm::VMError;
+
+pub enum TrapCode {
+    Getc,
+    Out,
+    Puts,
+    IN,
+    Putsp,
+    Halt,
+}
+
+impl TryFrom<u16> for TrapCode {
+    type Error = VMError;
+
+    fn try_from(value: u16) -> Result<Self, Self::Error> {
+        let trap = match value {
+            0x20 => TrapCode::Getc,
+            0x21 => TrapCode::Out,
+            0x22 => TrapCode::Puts,
+            0x23 => TrapCode::IN,
+            0x24 => TrapCode::Putsp,
+            0x25 => TrapCode::Halt,
+            _ => return Err(VMError::InvalidTrapCode),
+        };
+        Ok(trap)
+    }
+}