## SubX
SubX is a notation for a subset of x86 machine code. [The Mu translator](http://akkartik.github.io/mu/html/apps/mu.subx.html)
is implemented in SubX and also emits SubX code.
Here's an example program in SubX that adds 1 and 1 and returns the result to
the parent shell process:
```sh
== code
Entry:
# ebx = 1
bb/copy-to-ebx 1/imm32
# increment ebx
43/increment-ebx
# exit(ebx)
e8/call syscall_exit/disp32
```
## The syntax of SubX instructions
Just like in regular machine code, SubX programs consist mostly of instructions,
which are basically sequences of numbers (always in hex). Instructions consist
of words separated by whitespace. Words may be _opcodes_ (defining the
operation being performed) or _arguments_ (specifying the data the operation
acts on). Any word can have extra _metadata_ attached to it after `/`. Some
metadata is required (like the `/imm32` and `/imm8` above), but unrecognized
metadata is silently skipped so you can attach comments to words (like the
instruction name `/copy-to-eax` above, or the `/exit` argument).
What do all these numbers mean? SubX supports a small subset of the 32-bit x86
instruction set that likely runs on your computer. (Think of the name as short
for "sub-x86".) The instruction set contains instructions like `89/copy`,
`01/add`, `3d/compare` and `51/push-ecx` which modify registers and a byte-addressable
memory. For a complete list of supported instructions, run `bootstrap help
opcodes`.
The registers instructions operate on are as follows:
- Six general-purpose 32-bit registers: `0/eax`, `1/ebx`, `2/ecx`, `3/edx`,
`6/esi` and `7/edi`.
- Two additional 32-bit registers: `4/esp` and `5/ebp`. (I suggest you only
use these to manage the call stack.)
(SubX doesn't support floating-point registers yet. Intel processors support
an 8-bit mode, 16-bit mode and 64-bit mode. SubX will never support them.
There are also _many_ more instructions that SubX will never support.)
While//: jump to 8-bit offset
//:: jump
:(before "End Initialize Op Names")
put_new(Name, "eb", "jump disp8 bytes away (jmp)");
:(code)
void test_jump_disp8() {
run(
"== code 0x1\n"
// op ModR/M SIB displacement immediate
" eb 05 \n" // skip 1 instruction
" 05 00 00 00 01 \n"
" 05 00 00 00 02 \n"
);
CHECK_TRACE_CONTENTS(
"run: 0x00000001 opcode: eb\n"
"run: jump 5\n"
"run: 0x00000008 opcode: 05\n"
);
CHECK_TRACE_DOESNT_CONTAIN("run: 0x00000003 opcode: 05");
}
:(before "End Single-Byte Opcodes")
case 0xeb: { // jump disp8
int8_t offset = static_cast<int>(next());
trace(Callstack_depth+1, "run") << "jump " << NUM(offset) << end();
EIP += offset;
break;
}
//:: jump if equal/zero
:(before "End Initialize Op Names")
put_new(Name, "74", "jump disp8 bytes away if equal, if ZF is set (jcc/jz/je)");
:(code)
void test_je_disp8_success() {
ZF = true;
run(
"== code 0x1\n"
// op ModR/M SIB displacement immediate
" 74 05 \n" // skip 1 instruction
" 05 00 00 00 01 \n"
" 05 00 00 00 02 \n"
);
CHECK_TRACE_CONTENTS(
"run: 0x00000001 opcode: 74\n"
"run: jump 5\n"
"run: 0x00000008 opcode: 05\n"
);
CHECK_TRACE_DOESNT_CONTAIN("run: 0x00000003 opcode: 05");
}
:(before "End Single-Byte Opcodes")
case 0x74: { // jump disp8 if ZF
const int8_t offset = static_cast<int>(next());
if (ZF) {
trace(Callstack_depth+1, "run") << "jump " << NUM(offset) << end();
EIP += offset;
}
break;
}
:(code)
void test_je_disp8_fail() {
ZF = false;
run(
"== code 0x1\n"
// op ModR/M SIB displacement immediate
" 74 05 \n" // skip 1 instruction
" 05 00 00 00 01 \n"
" 05 00 00 00 02 \n"
);
CHECK_TRACE_CONTENTS(
"run: 0x00000001 opcode: 74\n"
"run: 0x00000003 opcode: 05\n"
"run: 0x00000008 opcode: 05\n"
);
CHECK_TRACE_DOESNT_CONTAIN("run: jump 5");
}
//:: jump if not equal/not zero
:(before "End Initialize Op Names")
put_new(Name, "75", "jump disp8 bytes away if not equal, if ZF is not set (jcc/jnz/jne)");
:(code)
void test_jne_disp8_success() {
ZF = false;
run(
"== code 0x1\n"
// op ModR/M SIB displacement immediate
" 75 05 \n" // skip 1 instruction
" 05 00 00 00 01 \n"
" 05 00 00 00 02 \n"
);
CHECK_TRACE_CONTENTS(
"run: 0x00000001 opcode: 75\n"
"run: jump 5\n"
"run: 0x00000008 opcode: 05\n"
);
CHECK_TRACE_DOESNT_CONTAIN("run: 0x00000003 opcode: 05");
}
:(before "End Single-Byte Opcodes")
case 0x75: { // jump disp8 if !ZF
const int8_t offset = static_cast<int>(next());
if (!ZF) {
trace(Callstack_depth+1, "run") << "jump " << NUM(offset) << end();
EIP += offset;
}
break;
}
:(code)
void test_jne_disp8_fail() {
ZF = true;
run(
"== code 0x1\n"
// op ModR/M SIB displacement immediate
" 75 05 \n" // skip 1 instruction
" 05 00 00 00 01 \n"
" 05 00 00 00 02 \n"
);
CHECK_TRACE_CONTENTS(
"run: 0x00000001 opcode: 75\n"
"run: 0x00000003 opcode: 05\n"
"run: 0x00000008 opcode: 05\n"
);
CHECK_TRACE_DOESNT_CONTAIN("run: jump 5");
}
//:: jump if greater
:(before "End Initialize Op Names")
put_new(Name, "7f", "jump disp8 bytes away if greater (signed), if ZF is unset and SF == OF (jcc/jg/jnle)");
put_new(Name, "77", "jump disp8 bytes away if greater (unsigned), if ZF is unset and CF is unset (jcc/ja/jnbe)");
:(code)
void test_jg_disp8_success() {
ZF = false;
SF = false;
OF = false;
run(
"== code 0x1\n"
// op ModR/M SIB displacement immediate
" 7f 05 \n" // skip 1 instruction
" 05 00 00 00 01 \n"
" 05 00 00 00 02 \n"
);
CHECK_TRACE_CONTENTS(
"run: 0x00000001 opcode: 7f\n"
"run: jump 5\n"
"run: 0x00000008 opcode: 05\n"
);
CHECK_TRACE_DOESNT_CONTAIN("run: 0x00000003 opcode: 05");
}
:(before "End Single-Byte Opcodes")
case 0x7f: { // jump disp8 if SF == OF and !ZF
const int8_t offset = static_cast<int>(next());
if (SF == OF && !ZF) {
trace(Callstack_depth+1, "run") << "jump " << NUM(offset) << end();
EIP += offset;
}
break;
}
case 0x77: { // jump disp8 if !CF and !ZF
const int8_t offset = static_cast<int>(next());
if (!CF && !ZF) {
trace(Callstack_depth+1, "run") << "jump " << NUM(offset) << end();
EIP += offset;
}
break;
}
:(code)
void test_jg_disp8_fail() {
ZF = false;
SF = true;
OF = false;
run(
"== code 0x1\n"
// op ModR/M SIB displacement immediate
" 7f 05 \n" // skip 1 instruction
" 05 00 00 00 01 \n"
" 05 00 00 00 02 \n"
);
CHECK_TRACE_CONTENTS(
"run: 0x00000001 opcode: 7f\n"
"run: 0x00000003 opcode: 05\n"
"run: 0x00000008 opcode: 05\n"
);
CHECK_TRACE_DOESNT_CONTAIN("run: jump 5");
}
//:: jump if greater or equal
:(before "End Initialize Op Names")
put_new(Name, "7d", "jump disp8 bytes away if greater or equal (signed), if SF == OF (jcc/jge/jnl)");
put_new(Name, "73", "jump disp8 bytes away if greater or equal (unsigned), if CF is unset (jcc/jae/jnb)");
:(code)
void test_jge_disp8_success() {
SF = false;
OF = false;
run(
"== code 0x1\n"
// op ModR/M SIB displacement immediate
" 7d 05 \n" // skip 1 instruction
" 05 00 00 00 01 \n"
" 05 00 00 00 02 \n"
);
CHECK_TRACE_CONTENTS(
"run: 0x00000001 opcode: 7d\n"
"run: jump 5\n"
"run: 0x00000008 opcode: 05\n"
);
CHECK_TRACE_DOESNT_CONTAIN("run: 0x00000003 opcode: 05");
}
:(before "End Single-Byte Opcodes")
case 0x7d: { // jump disp8 if SF == OF
const int8_t offset = static_cast<int>(next());
if (SF == OF) {
trace(Callstack_depth+1, "run") << "jump " << NUM(offset) << end();
EIP += offset;
}
break;
}
case 0x73: { // jump disp8 if !CF
const int8_t offset = static_cast<int>(next());
if (!CF) {
trace(Callstack_depth+1, "run") << "jump " << NUM(offset) << end();
EIP += offset;
}
break;
}
:(code)
void test_jge_disp8_fail() {
SF = true;
OF = false;
run(
"== code 0x1\n"
// op ModR/M SIB displacement immediate
" 7d 05 \n" // skip 1 instruction
" 05 00 00 00 01 \n"
" 05 00 00 00 02 \n"
);
CHECK_TRACE_CONTENTS(
"run: 0x00000001 opcode: 7d\n"
"run: 0x00000003 opcode: 05\n"
"run: 0x00000008 opcode: 05\n"
);
CHECK_TRACE_DOESNT_CONTAIN("run: jump 5");
}
//:: jump if lesser
:(before "End Initialize Op Names")
put_new(Name, "7c", "jump disp8 bytes away if lesser (signed), if SF != OF (jcc/jl/jnge)");
put_new(Name, "72", "jump disp8 bytes away if lesser (unsigned), if CF is set (jcc/jb/jnae)");
:(code)
void test_jl_disp8_success() {
ZF = false;
SF = true;
OF = false;
run(
"== code 0x1\n"
// op ModR/M SIB displacement immediate
" 7c 05 \n" // skip 1 instruction
" 05 00 00 00 01 \n"
" 05 00 00 00 02 \n"
);
CHECK_TRACE_CONTENTS(
"run: 0x00000001 opcode: 7c\n"
"run: jump 5\n"
"run: 0x00000008 opcode: 05\n"
);
CHECK_TRACE_DOESNT_CONTAIN("run: 0x00000003 opcode: 05");
}
:(before "End Single-Byte Opcodes")
case 0x7c: { // jump disp8 if SF != OF
const int8_t offset = static_cast<int>(next());
if (SF != OF) {
trace(Callstack_depth+1, "run") << "jump " << NUM(offset) << end();
EIP += offset;
}
break;
}
case 0x72: { // jump disp8 if CF
const int8_t offset = static_cast<int>(next());
if (CF) {
trace(Callstack_depth+1, "run") << "jump " << NUM(offset) << end();
EIP += offset;
}
break;
}
:(code)
void test_jl_disp8_fail() {
ZF = false;
SF = false;
OF = false;
run(
"== code 0x1\n"
// op ModR/M SIB displacement immediate
" 7c 05 \n" // skip 1 instruction
" 05 00 00 00 01 \n"
" 05 00 00 00 02 \n"
);
CHECK_TRACE_CONTENTS(
"run: 0x00000001 opcode: 7c\n"
"run: 0x00000003 opcode: 05\n"
"run: 0x00000008 opcode: 05\n"
);
CHECK_TRACE_DOESNT_CONTAIN("run: jump 5");
}
//:: jump if lesser or equal
:(before "End Initialize Op Names")
put_new(Name, "7e", "jump disp8 bytes away if lesser or equal (signed), if ZF is set or SF != OF (jcc/jle/jng)");
put_new(Name, "76", "jump disp8 bytes away if lesser or equal (unsigned), if ZF is set or CF is set (jcc/jbe/jna)");
:(code)
void test_jle_disp8_equal() {
ZF = true;
SF = false;
OF = false;
run(
"== code 0x1\n"
// op ModR/M SIB displacement immediate
" 7e 05 \n" // skip 1 instruction
" 05 00 00 00 01 \n"
" 05 00 00 00 02 \n"
);
CHECK_TRACE_CONTENTS(
"run: 0x00000001 opcode: 7e\n"
"run: jump 5\n"
"run: 0x00000008 opcode: 05\n"
);
CHECK_TRACE_DOESNT_CONTAIN("run: 0x00000003 opcode: 05");
}
:(code)
void test_jle_disp8_lesser() {
ZF = false;
SF = true;
OF = false;
run(
"== code 0x1\n"
// op ModR/M SIB displacement immediate
" 7e 05 \n" // skip 1 instruction
" 05 00 00 00 01 \n"
" 05 00 00 00 02 \n"
);
CHECK_TRACE_CONTENTS(
"run: 0x00000001 opcode: 7e\n"
"run: jump 5\n"
"run: 0x00000008 opcode: 05\n"
);
CHECK_TRACE_DOESNT_CONTAIN("run: 0x00000003 opcode: 05");
}
:(before "End Single-Byte Opcodes")
case 0x7e: { // jump disp8 if ZF or SF != OF
const int8_t offset = static_cast<int>(next());
if (ZF || SF != OF) {
trace(Callstack_depth+1, "run") << "jump " << NUM(offset) << end();
EIP += offset;
}
break;
}
case 0x76: { // jump disp8 if ZF or CF
const int8_t offset = static_cast<int>(next());
if (ZF || CF) {
trace(Callstack_depth+1, "run") << "jump " << NUM(offset) << end();
EIP += offset;
}
break;
}
:(code)
void test_jle_disp8_greater() {
ZF = false;
SF = false;
OF = false;
run(
"== code 0x1\n"
// op ModR/M SIB displacement immediate
" 7e 05 \n" // skip 1 instruction
" 05 00 00 00 01 \n"
" 05 00 00 00 02 \n"
);
CHECK_TRACE_CONTENTS(
"run: 0x00000001 opcode: 7e\n"
"run: 0x00000003 opcode: 05\n"
"run: 0x00000008 opcode: 05\n"
);
CHECK_TRACE_DOESNT_CONTAIN("run: jump 5");
}