4345

1 files changed, 57 insertions, 21 deletions

diff --git a/subx/Readme.md b/subx/Readme.md
index b7741350..bdf93a71 100644
--- a/subx/Readme.md
+++ b/subx/Readme.md
@@ -1,6 +1,56 @@
-## The SubX VM
+## What is this? 
 
-Bytecode interpreter for a subset of the 32-bit x86 ISA.
+A suite of tools for directly programming in (32-bit x86) machine code without
+a compiler. The generated ELF binaries require just a Unix-like kernel to run.
+(It isn't self-hosted yet, so generating the binaries requires a C compiler
+and libc.)
+
+## Why in the world?
+
+1. It seems wrong-headed that our computers look polished but are plagued by
+   foundational problems of security and reliability. I'd like to learn to
+   walk before I try to run, use the computer only to check my program for
+   errors and not hide low-level details. That may simplify the hard problems.
+   It adds to the burden of the programmer, but computers have been failing to
+   relieve the programmer entirely. Our abstractions so far leak at
+   inopportune times.
+
+2. The software in our computers has grown incomprehensible. Nobody
+   understands it all, not even experts. Even simple programs written by a
+   single author require lots of time for others to comprehend. Compilers are
+   a prime example, growing so complex that programmers have to choose to
+   either program them or use them. I'd like to explore how much of a HLL I
+   can build without an optimizing compiler, and see if the result is more
+   comprehensible by others. ([More details.](http://akkartik.name/about))
+
+3. I want to learn about the internals of the infrastructure we all rely on in
+   our lives.
+
+## Running
+
+```
+$ git clone https://github.com/akkartik/mu
+$ cd mu/subx
+$ ./subx
+```
+
+Running `subx` will transparently compile it as necessary.
+
+## Usage
+
+`subx` currently has the following sub-commands:
+
+* `subx test`: runs all automated tests.
+
+* `subx translate <input file> <output ELF binary>`: translates a text file
+  containing hex bytes and macros into an executable ELF binary.
+
+* `subx run <ELF binary>`: simulates running the ELF binaries emitted by `subx
+  translate`. Useful for debugging, and also enables more thorough testing of
+  `translate`.
+
+I'm not building general infrastructure here for all of the x86 ISA and ELF
+format. SubX is about programming with a small, regular subset of 32-bit x86:
 
 * Only instructions that operate on the 32-bit E\*X registers. (No
   floating-point yet.)
@@ -11,24 +61,10 @@ Bytecode interpreter for a subset of the 32-bit x86 ISA.
   on unsigned integers)
 * Only relative jump instructions (with 8-bit or 16-bit offsets).
 
-These rules yield a clean instruction set. We don't care about running
-arbitrary binaries, just those generated by our forthcoming Mu compiler.
-
-Targeting a VM enables more comprehensive tests for the compiler, without
-requiring access to processor/memory state without getting bogged down in
-details of the ELF format, ABI, STABS debugging format, etc., etc.
-
-Having the VM implement a real (and ubiquitous) instruction set makes it easy
-to generate native binaries outside of tests.
-
-Just unit tests so far:
-
-  ```
-  ./subx test
-  ```
-
-x86 instruction set resources used in building this:
+## Resources
 
+* [Single-page cheatsheet for the x86 ISA](https://net.cs.uni-bonn.de/fileadmin/user_upload/plohmann/x86_opcode_structure_and_instruction_overview.pdf) (pdf)
+* [Concise reference for the x86 ISA](https://c9x.me/x86)
 * [Intel programming manual](http://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-instruction-set-reference-manual-325383.pdf) (pdf)
-* [Concise instruction reference](https://c9x.me/x86)
-* [Single-page cheatsheet](https://net.cs.uni-bonn.de/fileadmin/user_upload/plohmann/x86_opcode_structure_and_instruction_overview.pdf) (pdf)
+* [&ldquo;Creating tiny ELF executables&rdquo;](https://www.muppetlabs.com/~breadbox/software/tiny/teensy.html)
+* [&ldquo;Bootstrapping a compiler from nothing&rdquo;](http://web.archive.org/web/20061108010907/http://www.rano.org/bcompiler.html)