diff options
Diffstat (limited to 'subx')
| -rw-r--r-- | subx/Readme.md | 78 |
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) +* [“Creating tiny ELF executables”](https://www.muppetlabs.com/~breadbox/software/tiny/teensy.html) +* [“Bootstrapping a compiler from nothing”](http://web.archive.org/web/20061108010907/http://www.rano.org/bcompiler.html) |