$ subx
Welcome to SubX, a better way to program in machine code.
SubX uses a subset of the x86 instruction set. SubX programs will run without modification on Linux computers.
It provides a better experience and better error messages than programming directly in machine code, but you have to stick to the instructions it supports.
== Ways to invoke subx
- Run tests:
subx test
- See this message:
subx --help
- Convert a textual SubX program into a standard ELF binary that you can run on your computer:
subx translate <input 'source' file> <output ELF binary>
- Run a SubX binary using SubX itself (for better error messages):
subx run <ELF binary>
To start learning how to write SubX programs, run:
subx help
$ subx help
help on what?
Available top-level topics:
usage
registers
syntax
opcodes
$ subx help registers
SubX currently supports eight 32-bit integer registers: R0 to R7.
R4 contains the top of the stack.
There's also a register for the address of the currently executing instruction. It is modified by jumps.
Various instructions modify one or more of three 1-bit 'flag' registers, as a side-effect:
- the sign flag (SF): usually set if an arithmetic result is negative, or reset if not.
- the zero flag (ZF): usually set if a result is zero, or reset if not.
- the overflow flag (OF): usually set if an arithmetic result overflows.
The flag bits are read by conditional jumps.
We don't support non-integer (floating-point) registers yet.
$ subx help syntax
SubX programs consist of segments, each segment in turn consisting of lines.
Line-endings are significant; each line should contain a single instruction, macro or directive.
Comments start with the '#' character. It should be at the start of a word (start of line, or following a space).
Each segment starts with a header line: a '==' delimiter followed by the starting address for the segment.
The starting address for a segment has some finicky requirements. But just start with a round number, and `subx` will try to guide you to a valid configuration.
A good rule of thumb is to try to start the first segment at the default address of 0x08048000, and to start each subsequent segment at least 0x1000 (most common page size) bytes after the last.
If a segment occupies than 0x1000 bytes you'll need to push subsequent segments further down.
Currently only the first segment contains executable code (because it gets annoying to have to change addresses in later segments every time an earlier one changes length; one of those finicky requirements).
Check out some examples in this directory (ex*.subx)
Programming in machine code can be annoying, but let's see if we can make it nice enough to be able to write a compiler in it.
$ subx help opcodes
Opcodes currently supported by SubX:
01: add r32 to rm32
03: add rm32 to r32
05: add imm32 to R0 (EAX)
09: rm32 = bitwise OR of r32 with rm32
0b: r32 = bitwise OR of r32 with rm32
0d: R0 = bitwise OR of imm32 with R0 (EAX)
21: rm32 = bitwise AND of r32 with rm32
23: r32 = bitwise AND of r32 with rm32
25: R0 = bitwise AND of imm32 with R0 (EAX)
29: subtract r32 from rm32
2b: subtract rm32 from r32
2d: subtract imm32 from R0 (EAX)
31: rm32 = bitwise XOR of r32 with rm32
33: r32 = bitwise XOR of r32 with rm32
35: R0 = bitwise XOR of imm32 with R0 (EAX)
39: set SF if rm32 < r32
3b: set SF if rm32 > r32
3d: subtract imm32 from R0 (EAX)
50: push R0 (EAX) to stack
51: push R1 (ECX) to stack
52: push R2 (EDX) to stack
53: push R3 (EBX) to stack
54: push R4 (ESP) to stack
55: push R5 (EBP) to stack
56: push R6 (ESI) to stack
57: push R7 (EDI) to stack
58: pop top of stack to R0 (EAX)
59: pop top of stack to R1 (ECX)
5a: pop top of stack to R2 (EDX)
5b: pop top of stack to R3 (EBX)
5c: pop top of stack to R4 (ESP)
5d: pop top of stack to R5 (EBP)
5e: pop top of stack to R6 (ESI)
5f: pop top of stack to R7 (EDI)
68: push imm32 to stack
74: jump disp8 bytes away if ZF is set
75: jump disp8 bytes away if ZF is not set
7c: jump disp8 bytes away if lesser (SF != OF)
7d: jump disp8 bytes away if greater or equal (SF == OF)
7e: jump disp8 bytes away if lesser or equal (ZF is set or SF != OF)
7f: jump disp8 bytes away if greater (ZF is unset, SF == OF)
81: combine rm32 with imm32 based on subop
87: swap the contents of r32 and rm32
89: copy r32 to rm32
8b: copy rm32 to r32
8f: pop top of stack to rm32
b8: copy imm32 to R0 (EAX)
b9: copy imm32 to R1 (ECX)
ba: copy imm32 to R2 (EDX)
bb: copy imm32 to R3 (EBX)
bc: copy imm32 to R4 (ESP)
bd: copy imm32 to R5 (EBP)
be: copy imm32 to R6 (ESI)
bf: copy imm32 to R7 (EDI)
c3: return from most recent unfinished call
c7: copy imm32 to rm32
cd: software interrupt (0x80 only)
e8: call disp32
e9: jump disp16 bytes away
eb: jump disp8 bytes away
f4: halt
f7: bitwise complement of rm32
ff: jump/push/call rm32 based on subop
Coming soon: `subx help operands` for details on words like 'r32' and 'disp8'.