From 9ada099d70d96635430cac4bdbfb50152e6d76bb Mon Sep 17 00:00:00 2001
From: Marco Thomas <github@marcothms.de>
Date: Tue, 8 Jul 2025 11:08:22 +0900
Subject: [PATCH] chore: update readme

---
 README.md | 45 +++++++++++++++++++++++++++++++++++++++------
 1 file changed, 39 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 0f19b89..e74121d 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,15 @@
 # 8086-rs
 
-8086-rs is a Rust-based toolchain for analyzing and interpreting 16-bit 8086 binaries, made with the intention of interpreting binaries compiled for MINIX 1.x.
+8086-rs is a Rust-based toolchain for analyzing and interpreting binaries, compiled for the Intel 16-bit 8086-type family, made with the intention of interpreting binaries compiled for MINIX 1.x.
 
-It includes:
-- a.out Parser to parse legacy MINIX 1.x executables.
-- 8086 disassembler to parse the 16-bit instructions into an IR and prints them in a `objdump(1)`-style fashion.
-- 8086 interpreter which interprets the instructions with MINIX 1.x conventions (e.g. interrupts, memory layout, ...) in mind and obeys segment register indirection, which enables the usage of the **entire 20-bit memory bus**.
+Features:
+- A parser for the `a.out` format, to parse legacy MINIX 1.x executables
+- A disassembler to parse the 16-bit instructions into an IR
+- Disassembly output in a `objdump(1)`-style fashion
+- Interpretation of instructions
+- MINIX 1.x interrupts and memory layout
+- Obeying of segment register indirection (`CS`, `SS`, `DS`, `ES`)
+- Full 20-bit memory bus
 
 ## Usage
 
@@ -19,11 +23,13 @@ Or run it directly:
 cargo run -- --help
 ```
 
-Run with debug output:
+Run with output:
 ```
 RUST_LOG=debug cargo run -- interpret -p ./a.out 2>&1 | less
 ```
 
+`info` will show things, such as register state and call to interrupts, `debug` will additionally show disassmbly and interpretation internals.
+
 CLI Options:
 ```
 $ cargo run -- --help
@@ -46,6 +52,25 @@ Options:
   -V, --version      Print version
 ```
 
+## Example
+```
+$ cat 1.c
+main() {
+    write(1, "hello\n", 6);
+}
+
+$ ./target/release/i8086-rs interpret -p ./a.out
+hello                                                                 
+
+$ RUST_LOG=info ./target/release/i8086-rs interpret -p ./a.out
+INFO: Initializing stack...                                                                    
+INFO: Initializing static data...                                                              
+INFO: (0000) xor %bp, %bp                     0000 0000 0000 0000 ffb4 0000 0000 0000 ---------
+INFO: (0002) mov %bx, %sp                     0000 0000 0000 0000 ffb4 0000 0000 0000 -----Z---
+INFO: (0004) mov %ax, [%bx]                   0000 ffb4 0000 0000 ffb4 0000 0000 0000 -----Z---
+...
+```
+
 ## Status
 
 This project is under active development and primarily used by me to explore some Intel disassembly and learn some more Rust.
@@ -75,6 +100,14 @@ For the implementation of the disassembly, I used the Intel "8086 16-BIT HMOS MI
 
 For the implementation of the interpreter, I used the Intel "Intel® 64 and IA-32 Architectures Software Developer’s Manual Volume 2 (2A, 2B, 2C & 2D): Instruction Set Reference, A-Z" Spec.
 
+## TODOs
+
+- Map instructions into actual memory for interpretation
+- Implement all Minix Interrupts
+- Allow execution of 'raw' instructions, not only `a.out`
+- Don't hardcode Minix
+- Implement BIOS Interrupts
+
 
 ## FAQ