1 # Code for the first few disk sectors that all programs in this directory need:
   2 #   - load sectors past the first (using BIOS primitives) since only the first is available by default
   3 #     - if this fails, print 'D' at top-left of screen and halt
   4 #   - initialize a minimal graphics mode
   5 #   - switch to 32-bit mode (giving up access to BIOS primitives)
   6 #   - set up a handler for keyboard events
   7 #   - jump to start of program
   8 
   9 # Code in this file needs to be more deliberate about the SubX facilities it
  10 # uses:
  11 #   - sigils only support 32-bit general-purpose registers, so don't work with segment registers or 16-bit or 8-bit registers
  12 #   - metadata like rm32 and r32 can sometimes misleadingly refer to only the bottom 16 bits of the register; pay attention to the register name
  13 #
  14 # While most of Mu is thoroughly tested, this file is not. I don't yet
  15 # understand hardware interfaces well enough to explain to others.
  16 
  17 # Memory map of a Mu computer:
  18 #   code:         [0x00007c00, 0x0007de00)
  19 #   system font:  [0x00100000, 0x00f00000)
  20 #   stack:        (0x02000000, 0x01000000]
  21 #   heap:         [0x02000000, 0x80000000)
  22 #     see 120allocate.subx; Qemu initializes with 128MB RAM by default; simulating 2GB RAM is known to work
  23 # Consult https://wiki.osdev.org/Memory_Map_(x86) before modifying any of
  24 # this. And don't forget to keep *stack-debug.subx in sync.
  25 
  26 == code
  27 
  28 ## 16-bit entry point: 0x7c00
  29 
  30 # Upon reset, the IBM PC:
  31 #   - loads the first sector (512 bytes)
  32 #     from some bootable image (look for the boot-sector-marker further down this file)
  33 #     to the address range [0x7c00, 0x7e00)
  34 #   - starts executing code at address 0x7c00
  35 
  36   fa/disable-interrupts
  37 
  38   # initialize segment registers
  39   b8/copy-to-ax 0/imm16
  40   8e/->seg 3/mod/direct 0/rm32/ax 3/r32/ds
  41   8e/->seg 3/mod/direct 0/rm32/ax 0/r32/es
  42   8e/->seg 3/mod/direct 0/rm32/ax 4/r32/fs
  43   8e/->seg 3/mod/direct 0/rm32/ax 5/r32/gs
  44 
  45   # Temporarily initialize stack to 0x00070000 in real mode.
  46   # We don't read or write the stack before we get to 32-bit mode, but BIOS
  47   # calls do. We need to move the stack in case BIOS initializes it to some
  48   # low address that we want to write code into.
  49   b8/copy-to-ax 0x7000/imm16
  50   8e/->seg 3/mod/direct 0/rm32/ax 2/r32/ss
  51   bc/copy-to-esp 0/imm16
  52 
  53   # undo the A20 hack: https://en.wikipedia.org/wiki/A20_line
  54   # this is from https://github.com/mit-pdos/xv6-public/blob/master/bootasm.S
  55   {
  56     e4/read-port-into-al 0x64/imm8
  57     a8/test-bits-in-al 0x02/imm8  # set zf if bit 1 (second-least significant) is not set
  58     75/jump-if-!zero loop/disp8
  59     b0/copy-to-al 0xd1/imm8
  60     e6/write-al-into-port 0x64/imm8
  61   }
  62   {
  63     e4/read-port-into-al 0x64/imm8
  64     a8/test-bits-in-al 0x02/imm8  # set zf if bit 1 (second-least significant) is not set
  65     75/jump-if-!zero loop/disp8
  66     b0/copy-to-al 0xdf/imm8
  67     e6/write-al-into-port 0x64/imm8
  68   }
  69 
  70   # load remaining sectors from first two tracks of disk into addresses [0x7e00, 0x17800)
  71   b4/copy-to-ah 2/imm8/read-drive
  72   # dl comes conveniently initialized at boot time with the index of the device being booted
  73   b5/copy-to-ch 0/imm8/cylinder
  74   b6/copy-to-dh 0/imm8/head                   # <====
  75   b1/copy-to-cl 2/imm8/sector  # 1-based
  76   b0/copy-to-al 0x7d/imm8/num-sectors  # 2*63 - 1 = 125
  77   # address to write sectors to = es:bx = 0x7e00, contiguous with boot segment
  78   bb/copy-to-bx 0/imm16
  79   8e/->seg 3/mod/direct 3/rm32/bx 0/r32/es
  80   bb/copy-to-bx 0x7e00/imm16                  # <====
  81   cd/syscall 0x13/imm8/bios-disk-services
  82   0f 82/jump-if-carry disk_error/disp16
  83 
  84   # load two more tracks of disk into addresses [0x17800, 0x27400)
  85   b4/copy-to-ah 2/imm8/read-drive
  86   # dl comes conveniently initialized at boot time with the index of the device being booted
  87   b5/copy-to-ch 0/imm8/cylinder
  88   b6/copy-to-dh 2/imm8/head                   # <====
  89   b1/copy-to-cl 1/imm8/sector  # 1-based
  90   b0/copy-to-al 0x7e/imm8/num-sectors  # 2*63 = 126
  91   # address to write sectors to = es:bx = 0x17800, contiguous with boot segment
  92   bb/copy-to-bx 0x1780/imm16                  # <====
  93   8e/->seg 3/mod/direct 3/rm32/bx 0/r32/es
  94   bb/copy-to-bx 0/imm16
  95   cd/syscall 0x13/imm8/bios-disk-services
  96   0f 82/jump-if-carry disk_error/disp16
  97 
  98   # load two more tracks of disk into addresses [0x27400, 0x37000)
  99   b4/copy-to-ah 2/imm8/read-drive
 100   # dl comes conveniently initialized at boot time with the index of the device being booted
 101   b5/copy-to-ch 0/imm8/cylinder
 102   b6/copy-to-dh 4/imm8/head                   # <====
 103   b1/copy-to-cl 1/imm8/sector  # 1-based
 104   b0/copy-to-al 0x7e/imm8/num-sectors  # 2*63 = 126
 105   # address to write sectors to = es:bx = 0x27400, contiguous with boot segment
 106   bb/copy-to-bx 0x2740/imm16                  # <====
 107   8e/->seg 3/mod/direct 3/rm32/bx 0/r32/es
 108   bb/copy-to-bx 0/imm16
 109   cd/syscall 0x13/imm8/bios-disk-services
 110   0f 82/jump-if-carry disk_error/disp16
 111 
 112   # load two more tracks of disk into addresses [0x37000, 0x46c00)
 113   b4/copy-to-ah 2/imm8/read-drive
 114   # dl comes conveniently initialized at boot time with the index of the device being booted
 115   b5/copy-to-ch 0/imm8/cylinder
 116   b6/copy-to-dh 6/imm8/head                   # <====
 117   b1/copy-to-cl 1/imm8/sector  # 1-based
 118   b0/copy-to-al 0x7e/imm8/num-sectors  # 2*63 = 126
 119   # address to write sectors to = es:bx = 0x37000, contiguous with boot segment
 120   bb/copy-to-bx 0x3700/imm16                  # <====
 121   8e/->seg 3/mod/direct 3/rm32/bx 0/r32/es
 122   bb/copy-to-bx 0/imm16
 123   cd/syscall 0x13/imm8/bios-disk-services
 124   0f 82/jump-if-carry disk_error/disp16
 125 
 126   # load two more tracks of disk into addresses [0x46c00, 0x56800)
 127   b4/copy-to-ah 2/imm8/read-drive
 128   # dl comes conveniently initialized at boot time with the index of the device being booted
 129   b5/copy-to-ch 0/imm8/cylinder
 130   b6/copy-to-dh 8/imm8/head                   # <====
 131   b1/copy-to-cl 1/imm8/sector  # 1-based
 132   b0/copy-to-al 0x7e/imm8/num-sectors  # 2*63 = 126
 133   # address to write sectors to = es:bx = 0x46c00, contiguous with boot segment
 134   bb/copy-to-bx 0x46c0/imm16                  # <====
 135   8e/->seg 3/mod/direct 3/rm32/bx 0/r32/es
 136   bb/copy-to-bx 0/imm16
 137   cd/syscall 0x13/imm8/bios-disk-services
 138   0f 82/jump-if-carry disk_error/disp16
 139 
 140   # load two more tracks of disk into addresses [0x56800, 0x66400)
 141   b4/copy-to-ah 2/imm8/read-drive
 142   # dl comes conveniently initialized at boot time with the index of the device being booted
 143   b5/copy-to-ch 0/imm8/cylinder
 144   b6/copy-to-dh 0xa/imm8/head                 # <====
 145   b1/copy-to-cl 1/imm8/sector  # 1-based
 146   b0/copy-to-al 0x7e/imm8/num-sectors  # 2*63 = 126
 147   # address to write sectors to = es:bx = 0x56800, contiguous with boot segment
 148   bb/copy-to-bx 0x5680/imm16                  # <====
 149   8e/->seg 3/mod/direct 3/rm32/bx 0/r32/es
 150   bb/copy-to-bx 0/imm16
 151   cd/syscall 0x13/imm8/bios-disk-services
 152   0f 82/jump-if-carry disk_error/disp16
 153 
 154   # load two more tracks of disk into addresses [0x66400, 0x76000)
 155   b4/copy-to-ah 2/imm8/read-drive
 156   # dl comes conveniently initialized at boot time with the index of the device being booted
 157   b5/copy-to-ch 0/imm8/cylinder
 158   b6/copy-to-dh 0xc/imm8/head                 # <====
 159   b1/copy-to-cl 1/imm8/sector  # 1-based
 160   b0/copy-to-al 0x7e/imm8/num-sectors  # 2*63 = 126
 161   # address to write sectors to = es:bx = 0x56800, contiguous with boot segment
 162   bb/copy-to-bx 0x6640/imm16                  # <====
 163   8e/->seg 3/mod/direct 3/rm32/bx 0/r32/es
 164   bb/copy-to-bx 0/imm16
 165   cd/syscall 0x13/imm8/bios-disk-services
 166   0f 82/jump-if-carry disk_error/disp16
 167 
 168   # load one final track of disk into addresses [0x76000, 0x7de00)
 169   b4/copy-to-ah 2/imm8/read-drive
 170   # dl comes conveniently initialized at boot time with the index of the device being booted
 171   b5/copy-to-ch 0/imm8/cylinder
 172   b6/copy-to-dh 0xe/imm8/head                 # <====
 173   b1/copy-to-cl 1/imm8/sector  # 1-based
 174   b0/copy-to-al 0x3f/imm8/num-sectors=63
 175   # address to write sectors to = es:bx = 0x56800, contiguous with boot segment
 176   bb/copy-to-bx 0x7600/imm16                  # <====
 177   8e/->seg 3/mod/direct 3/rm32/bx 0/r32/es
 178   bb/copy-to-bx 0/imm16
 179   cd/syscall 0x13/imm8/bios-disk-services
 180   0f 82/jump-if-carry disk_error/disp16
 181 
 182   ### Loading more code tracks would clobber BIOS; we need a new compilation strategy.
 183 
 184   # reset es
 185   bb/copy-to-bx 0/imm16
 186   8e/->seg 3/mod/direct 3/rm32/bx 0/r32/es
 187 
 188   # adjust video mode
 189   b4/copy-to-ah 0x4f/imm8  # VBE commands
 190   b0/copy-to-al 2/imm8  # set video mode
 191   bb/copy-to-bx 0x4105/imm16  # 0x0105 | 0x4000
 192                               # 0x0105 = graphics mode 1024x768x256
 193                               #  (alternative candidate: 0x0101 for 640x480x256)
 194                               # 0x4000 bit = configure linear frame buffer in Bochs emulator; hopefully this doesn't hurt anything when running natively
 195   cd/syscall 0x10/imm8/bios-video-services
 196 
 197   # load information for the (hopefully) current video mode
 198   # mostly just for the address to the linear frame buffer
 199   b4/copy-to-ah 0x4f/imm8  # VBE commands
 200   b0/copy-to-al 1/imm8  # get video mode info
 201   b9/copy-to-cx 0x0105/imm16  # mode we requested
 202   bf/copy-to-di Video-mode-info/imm16
 203   cd/syscall 0x10/imm8/bios-video-services
 204 
 205   ## switch to 32-bit mode
 206   # load global descriptor table
 207   # We can't refer to the label directly because SubX doesn't do the right
 208   # thing for lgdt, so rather than make errors worse in most places we instead
 209   # pin gdt_descriptor below.
 210   0f 01 2/subop/lgdt 0/mod/indirect 6/rm32/use-disp16 0x7de0/disp16/gdt_descriptor
 211   # enable paging
 212   0f 20/<-cr 3/mod/direct 0/rm32/eax 0/r32/cr0
 213   66 83 1/subop/or 3/mod/direct 0/rm32/eax 1/imm8  # eax <- or 0x1
 214   0f 22/->cr 3/mod/direct 0/rm32/eax 0/r32/cr0
 215   # far jump to initialize_32bit_mode that sets cs to offset 8 in the gdt in the process
 216   # We can't refer to the label directly because SubX doesn't have syntax for
 217   # segment selectors. So we instead pin initialize_32bit_mode below.
 218   ea/jump-far-absolute 0x00087e00/disp32  # address 0x7e00 in offset 8 of the gdt
 219 
 220 disk_error:
 221   # print 'D' to top-left of screen to indicate disk error
 222   # *0xb8000 <- 0x0f44
 223   bb/copy-to-bx 0xb800/imm16
 224   8e/->seg 3/mod/direct 3/rm32/bx 3/r32/ds
 225   b0/copy-to-al 0x44/imm8/D
 226   b4/copy-to-ah 0x0f/imm8/white-on-black
 227   bb/copy-to-bx 0/imm16
 228   89/<- 0/mod/indirect 7/rm32/bx 0/r32/ax  # *ds:bx <- ax
 229   # loop forever
 230   {
 231     eb/jump loop/disp8
 232   }
 233 
 234 ## GDT: 3 records of 8 bytes each
 235 == data 0x7de0
 236 gdt_descriptor:
 237   0x17/imm16  # final index of gdt = size of gdt - 1
 238   gdt_start/imm32/start
 239 
 240 gdt_start:
 241 # offset 0: gdt_null:  mandatory null descriptor
 242   00 00 00 00 00 00 00 00
 243 # offset 8: gdt_code
 244   ff ff  # limit[0:16]
 245   00 00 00  # base[0:24]
 246   9a  # 1/present 00/privilege 1/descriptor type = 1001b
 247       # 1/code 0/conforming 1/readable 0/accessed =draw-code-point`
- `clear-screen`

- `draw-text-rightward`: draws a single line of text, stopping when it reaches
  either the provided bound or the right screen margin.
- `draw-stream-rightward`
- `draw-text-rightward-over-full-screen`: does not provide a bound.
- `draw-text-wrapping-right-then-down`: draws multiple lines of text on screen
  with simplistic word-wrap (no hyphenation) within (x, y) bounds.
- `draw-stream-wrapping-right-then-down`
- `draw-text-wrapping-right-then-down-over-full-screen`
- `draw-int32-hex-wrapping-right-then-down`
- `draw-int32-hex-wrapping-right-then-down-over-full-screen`
- `draw-int32-decimal-wrapping-right-then-down`
- `draw-int32-decimal-wrapping-right-then-down-over-full-screen`

Similar primitives for writing text top-to-bottom, left-to-right.

- `draw-text-downward`
- `draw-stream-downward`
- `draw-text-wrapping-down-then-right`
- `draw-stream-wrapping-down-then-right`
- `draw-text-wrapping-down-then-right-over-full-screen`
- `draw-int32-hex-wrapping-down-then-right`
- `draw-int32-hex-wrapping-down-then-right-over-full-screen`
- `draw-int32-decimal-wrapping-down-then-right`
- `draw-int32-decimal-wrapping-down-then-right-over-full-screen`

Screens remember the current cursor position.

- `cursor-position`
- `set-cursor-position`
- `draw-grapheme-at-cursor`
- `draw-code-point-at-cursor`
- `draw-cursor`: highlights the current position of the cursor. Programs must
  pass in the grapheme to draw at the cursor position, and are responsible for
  clearing the highlight when the cursor moves.
- `move-cursor-left`, `move-cursor-right`, `move-cursor-up`, `move-cursor-down`.
  These primitives always silently fail if the desired movement would go out
  of screen bounds.
- `move-cursor-to-left-margin-of-next-line`
- `move-cursor-rightward-and-downward`: move cursor one grapheme to the right

- `draw-text-rightward-from-cursor`
- `draw-text-wrapping-right-then-down-from-cursor`
- `draw-text-wrapping-right-then-down-from-cursor-over-full-screen`
- `draw-int32-hex-wrapping-right-then-down-from-cursor`
- `draw-int32-hex-wrapping-right-then-down-from-cursor-over-full-screen`
- `draw-int32-decimal-wrapping-right-then-down-from-cursor`
- `draw-int32-decimal-wrapping-right-then-down-from-cursor-over-full-screen`

- `draw-text-wrapping-down-then-right-from-cursor`
- `draw-text-wrapping-down-then-right-from-cursor-over-full-screen`

Assertions for tests:

- `check-screen-row`: compare a screen from the left margin of a given row
  index with a string. The row index counts downward from 0 at the top of the
  screen. String can be smaller or larger than a single row, and defines the
  region of interest. Strings longer than a row wrap around to the left margin
  of the next screen row. Currently assumes text is printed left-to-right on
  the screen.
- `check-screen-row-from`: compare a fragment of a screen (left to write, top
  to bottom) starting from a given (x, y) coordinate with an expected string.
  Currently assumes text is printed left-to-right and top-to-bottom on the
  screen.
- `check-screen-row-in-color`: like `check-screen-row` but:
  - also compares foreground color
  - ignores screen locations where the expected string contains spaces
- `check-screen-row-in-color-from`
- `check-screen-row-in-background-color`
- `check-screen-row-in-background-color-from`
- `check-background-color-in-screen-row`: unlike previous functions, this
  doesn't check screen contents, only background color. Ignores background
  color where expected string contains spaces, and compares background color
  where expected string does not contain spaces. Never compares the character
  at any screen location.
- `check-background-color-in-screen-row-from`

#### events

`read-key` reads a single key from the keyboard and returns it if it exists.
Returns 0 if no key has been pressed.

`read-mouse-event` returns a recent change in x and y coordinate.

Mu doesn't currently support interrupt-based mouse events.

#### persistent storage

`load-sector` synchronously reads a single _sector_ from a _disk_ of persistent
storage. The disk must follow the ATA specification with a 28-bit sector
address. Each sector is 512 bytes. Therefore, Mu currently supports ATA hard
disks of up to 128GB capacity.

Similarly, `store-sector` synchronously writes a single sector to disk.

Mu doesn't currently support asynchronous transfers to or from a disk.