subx_bare.md

   1 [The SubX documentation](subx.md) describes SubX notation with some details
   2 hidden behind _syntax sugar_ -- local rewrite rules that make programming in
   3 SubX less error-prone. However, much low-level SubX (before the syntax sugar
   4 is implemented) is written without syntax sugar. This document describes some
   5 details of the syntax sugar: how the reg/mem operand is translated into
   6 arguments.
   7
   8 ## How x86 instructions compute operands
   9
  10 The [Intel processor 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)
  11 is the final source of truth on the x86 instruction set, but it can be
  12 forbidding to make sense of, so here's a quick orientation. You will need
  13 familiarity with binary numbers, and maybe a few other things. Email [me](mailto:mu@akkartik.com)
  14 any time if something isn't clear. I love explaining this stuff for as long as
  15 it takes. The bad news is that it takes some getting used to. The good news is
  16 that internalizing the next 500 words will give you a significantly deeper
  17 understanding of your computer.
  18
  19 The reg/mem operand can be specified by 1-7 arguments, each ranging in size
  20 from 2 bits to 4 bytes. The key argument that's always present for reg/mem
  21 operands is `/mod`, the _addressing mode_. This is a 2-bit argument that can
  22 take 4 possible values, and it determines what other arguments are required,
  23 and how to interpret them.
  24
  25 - If `/mod` is `3`: the operand is in the register described by the 3-bit
  26   `/rm32` argument.
  27
  28 - If `/mod` is `0`: the operand is in the address provided in the register
  29   described by `/rm32`. That's `*rm32` in C syntax.
  30
  31 - If `/mod` is `1`: the operand is in the address provided by adding the
  32   register in `/rm32` with the (1-byte) displacement. That's `*(rm32 + /disp8)`
  33   in C syntax.
  34
  35 - If `/mod` is `2`: the operand is in the address provided by adding the
  36   register in `/rm32` with the (4-byte) displacement. That's `*(/rm32 +
  37   /disp32)` in C syntax.
  38
  39 In the last three cases, one exception occurs when the `/rm32` argument
  40 contains `4`. Rather than encoding register `esp`, it means the address is
  41 provided by three _whole new_ arguments (`/base`, `/index` and `/scale`) in a
  42 _totally_ different way (where `<<` is the left-shift operator):
  43
  44 ```
  45 reg/mem = *(base + (index << scale))
  46 ```
  47
  48 (There are a couple more exceptions ☹; see [Table 2-2](modrm.pdf) and [Table 2-3](sib.pdf)
  49 of the Intel manual for the complete story.)
  50
  51 Phew, that was a lot to take in. Some examples to work through as you reread
  52 and digest it:
  53
  54 1. To read directly from the `eax` register, `/mod` must be `3` (direct mode),
  55    and `/rm32` must be `0`. There must be no `/base`, `/index` or `/scale`
  56    arguments.
  57
  58 2. To read from `*eax` (in C syntax), `/mod` must be `0` (indirect mode), and
  59    the `/rm32` argument must be `0`. There must be no `/base`, `/index` or
  60    `/scale` arguments (Intel calls the trio the 'SIB byte'.).
  61
  62 3. To read from `*(eax+4)`, `/mod` must be `1` (indirect + disp8 mode),
  63    `/rm32` must be `0`, there must be no SIB byte, and there must be a single
  64    displacement byte containing `4`.
  65
  66 4. To read from `*(eax+ecx+4)`, one approach would be to set `/mod` to `1` as
  67    above, `/rm32` to `4` (SIB byte next), `/base` to `0`, `/index` to `1`
  68    (`ecx`) and a single displacement byte to `4`. (What should the `scale` bits
  69    be? Can you think of another approach?)
  70
  71 5. To read from `*(eax+ecx+1000)`, one approach would be:
  72    - `/mod`: `2` (indirect + disp32)
  73    - `/rm32`: `4` (`/base`, `/index` and `/scale` arguments required)
  74    - `/base`: `0` (eax)
  75    - `/index`: `1` (ecx)
  76    - `/disp32`: 4 bytes containing `1000`
  77
  78 ## Putting it all together
  79
  80 Here's an example showing these arguments at work:
  81
  82 <img alt='linux/ex3.subx' src='html/ex3.png'>
  83
  84 This program sums the first 10 natural numbers. By convention I use horizontal
  85 tabstops to help read instructions, dots to help follow the long lines,
  86 comments before groups of instructions to describe their high-level purpose,
  87 and comments at the end of complex instructions to state the low-level
  88 operation they perform. Numbers are always in hexadecimal (base 16) and must
  89 start with a digit ('0'..'9'); use the '0x' prefix when a number starts with a
  90 letter ('a'..'f'). I tend to also include it as a reminder when numbers look
  91 like decimal numbers.
  92
  93 ---
  94
  95 I recommend you order arguments consistently in your programs. SubX allows
  96 arguments in any order, but only because that's simplest to explain/implement.
  97 Switching order from instruction to instruction is likely to add to the
  98 reader's burden. Here's the order I've been using after opcodes:
  99
 100 ```
 101         |<--------- reg/mem --------->|        |<- reg/mem? ->|
 102 /subop  /mod /rm32  /base /index /scale  /r32   /displacement   /immediate
 103 ```
 104
 105 ---
 106
 107 Try running this example now:
 108
 109 ```sh
 110 $ cd linux
 111 $ bootstrap/bootstrap translate 000init.subx ex3.subx -o ex3
 112 $ bootstrap/bootstrap run ex3
 113 $ echo $?
 114 55
 115 ```
 116
 117 If you're on Linux you can also run it natively:
 118
 119 ```sh
 120 $ chmod +x ex3
 121 $ ./ex3
 122 $ echo $?
 123 55
 124 ```
 125
 126 These details should now be enough information for reading and modifying
 127 low-level SubX programs.
 128
 129 ## Translating SubX programs
 130
 131 This repo includes two translators for bare SubX. The first is [the bootstrap
 132 translator](bootstrap/bootstrap.md) implemented in C++. In addition, you can
 133 use SubX to translate itself. For example, running natively on Linux:
 134
 135 ```sh
 136 # generate translator phases using the C++ translator
 137 $ cd linux
 138 $ bootstrap/bootstrap translate [01]*.subx subx-params.subx hex.subx      -o hex
 139 $ bootstrap/bootstrap translate [01]*.subx subx-params.subx survey_elf.subx -o survey_elf
 140 $ bootstrap/bootstrap translate [01]*.subx subx-params.subx pack.subx     -o pack
 141 $ bootstrap/bootstrap translate [01]*.subx subx-params.subx assort.subx   -o assort
 142 $ bootstrap/bootstrap translate [01]*.subx subx-params.subx dquotes.subx  -o dquotes
 143 $ bootstrap/bootstrap translate [01]*.subx subx-params.subx tests.subx    -o tests
 144 $ chmod +x hex survey_elf pack assort dquotes tests
 145
 146 # use the generated translator phases to translate SubX programs
 147 $ cat 000init.subx ex1.subx |./tests |./dquotes |./assort |./pack |./survey_elf |./hex > a.elf
 148 $ chmod +x a.elf
 149 $ ./a.elf
 150 $ echo $?
 151 42
 152
 153 # or, automating the above steps
 154 $ cd linux
 155 $ ./translate_subx 000init.linux ex1.subx
 156 $ ./a.elf
 157 $ echo $?
 158 42
 159 ```
 160
 161 Or, running in a VM on other platforms (much slower):
 162
 163 ```sh
 164 $ ./translate_subx_emulated init.linux linux/ex1.subx  # generates identical a.elf to above
 165 $ bootstrap/bootstrap run a.elf
 166 $ echo $?
 167 42
 168 ```
 169
 170 ## Resources
 171
 172 - [Single-page cheatsheet for the x86 ISA](https://net.cs.uni-bonn.de/fileadmin/user_upload/plohmann/x86_opcode_structure_and_instruction_overview.pdf)
 173   (pdf; [cached local copy](https://github.com/akkartik/mu/blob/main/cheatsheet.pdf))
 174 - [Concise reference for the x86 ISA](https://c9x.me/x86)
 175 - [Concise reference for the x86 ISA #2](http://ref.x86asm.net/coder32.html)
 176 - [Intel processor 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)