From 4650c8188ff8c134187836ccc81d0bd14a3afb47 Mon Sep 17 00:00:00 2001 From: Kartik Agaram Date: Wed, 28 Nov 2018 14:16:27 -0800 Subject: 4793 Experimenting with putting code examples higher up in the Readme. Thanks Pelle Hjek for the feedback: http://arclanguage.org/item?id=20875. --- subx/Readme.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 46 insertions(+), 9 deletions(-) diff --git a/subx/Readme.md b/subx/Readme.md index 39952d2d..1aba8c57 100644 --- a/subx/Readme.md +++ b/subx/Readme.md @@ -6,9 +6,50 @@ SubX is a minimalist assembly language designed: * to be easy to implement in itself, and * to help learn and teach the x86 instruction set. +``` +$ git clone https://github.com/akkartik/mu +$ cd mu/subx +$ ./subx # print out a help message +``` + +[![Build Status](https://api.travis-ci.org/akkartik/mu.svg)](https://travis-ci.org/akkartik/mu) + Expanding on the first bullet, it hopes to support more comprehensive tests by: +0. Running generated binaries in _emulated mode_. It's slower, but there's + more sanity checking, and more descriptive error messages for common + low-level problems. + + ``` + $ ./subx translate examples/ex1.subx -o examples/ex1 + $ ./examples/ex1 # only on Linux + $ echo $? + 42 + $ ./subx run examples/ex1 # on Linux or BSD or OS X + $ echo $? + 42 + ``` + + The assembly syntax is designed so the assembler (`subx translate`) has + very little to do, making it feasible to reimplement in itself. Programmers + have to explicitly specify all opcodes and operands. + + ``` + # exit(42) + bb/copy-to-EBX 0x2a/imm32 # 42 in hex + b8/copy-to-EAX 1/imm32/exit + cd/syscall 0x80/imm8 + ``` + + To keep code readable you can add _metadata_ to any word after a `/`. + Metadata can be just comments for readers, and they'll be ignored. They can + also trigger checks. Here, tagging operands with the `imm32` type allows + SubX to check that instructions have precisely the operand types they + should. x86 instructions have 14 types of operands, and missing one causes + all future instructions to go out off the rails, interpreting operands as + opcodes and vice versa. So this is a useful check. + 1. Designing testable wrappers for operating system interfaces. For example, it can `read()` from or `write()` to fake in-memory files in tests. We'll gradually port ideas for other syscalls from [the old Mu VM in the parent @@ -96,8 +137,6 @@ useful to catch such errors early. Try running this example now: ``` -$ git clone https://github.com/akkartik/mu -$ cd mu/subx $ ./subx translate examples/ex3.subx -o examples/ex3 $ ./subx run examples/ex3 $ echo $? @@ -112,8 +151,6 @@ $ echo $? 55 ``` -[![Build Status](https://api.travis-ci.org/akkartik/mu.svg)](https://travis-ci.org/akkartik/mu) - The rest of this Readme elaborates on the syntax for SubX programs, starting with a few prerequisites about the x86 instruction set. @@ -259,11 +296,11 @@ Within the code segment, each line contains a comment, label or instruction. Comments start with a `#` and are ignored. Labels should always be the first word on a line, and they end with a `:`. -Instructions consist of a sequence of opcode bytes and their operands. Each -opcode and operand can contain _metadata_ after a `/`. Metadata can be either -for SubX or act as a comment for the reader; SubX silently ignores unrecognized -metadata. A single word can contain multiple pieces of metadata, each starting -with a `/`. +Instructions consist of a sequence of opcode bytes and their operands. As +mentioned above, each opcode and operand can contain _metadata_ after a `/`. +Metadata can be either for SubX or act as a comment for the reader; SubX +silently ignores unrecognized metadata. A single word can contain multiple +pieces of metadata, each starting with a `/`. SubX uses metadata to express instruction encoding and get decent error messages. You must tag each instruction operand with the appropriate operand -- cgit 1.4.1-2-gfad0