Update README.md

README.md

@@ -1,34 +1,61 @@
 5150 stuff
 ==========
 
-The binary programs here use multiple conventions (more Fun!):
+## Layout of a bootable polOS floppy disk
-- .asm files use NASM syntax and are built with `nasm xx.asm`
-- .s files use GAS syntax, they are built with `ia16-elf-gcc`
 
-The reason is uh, because you see, I did things.
+The floppy disk is FAT12 formatted. It must contain at least the following items:
 
-The .asm came first and was copy pasta from the internet.
+* _fat12boot.bin_: the boot sector. It loads _polio.com_ from a FAT12-formatted
-The .s files came from the output of `ia16-elf-gcc -S` when I couldn't be bothered to write programs in assembly but still needed to make them compatible with BASIC's *CALL* instruction.
+    drive 0 to address _0x0600_ and jumps to it.
+* _polio.com_: the basic OS functions. It serves all interrupt 0x80 functions
+    (see below) and loads _polmon.com_ to address _0x1200_, then jumps to it.
+* _polmon.com_: a barebones memory utility. See below for all it can do.
 
-Also the wozmon binary contains special care to make it into a boot sector (0xaa55 magic).
+## polOS int 0x80
 
-Anyway, just type
+* function in AH
-```
+* optional argument in AL
-make binaries
+* other arguments on the stack
-```
+* return value in AX
 
-and stop whining.
+| AH | AL | stack arguments | return | description |
+|-------------|--------------|-----------------|-------------|
+| _0x01_ | | _addr_, _c_, _h_, _s_ | error code in AH | __readsector__: reads 1 floppy sector at _c/h/s_ into _0000:addr_ |
+| _0x02_ | | _addr_, _c_, _h_, _s_ | error code in AH | __writesector__: writes 1 floppy sector at _c/h/s_ from _0000:addr_ |
+| 0x03 | | _c_, _h_ | error code in AH | __formattrack__: formats 1 track at c/h |
+| 0x04 | | _fname_, _addr_ | non-zero if error | __readfile__: reads file with name at _ds:fname_ into _ds:addr_ |
+| 0x05 | | _addr_, _size_ | bytes received, < 0 if error | __recvpara__: receive at most _size_ bytes  from parallel port into _ds:addr_ |
+| 0x06 | | _addr_, _size_ | bytes sent, < 0 if error | __sendpara__: send at most _size_ bytes to parallel port from _ds:addr_ |
+| 0x07 | _until-idle_ | | 0 if idle | __runpara__: run a round of parallel comms if _AL=0_, keep going until idle if _AL!=0_ |
+| 0x08 | | _fname_, _addr_, _size_ | error code in AH | __writefile__: writes _size_ bytes from _ds:addr_ into file with name at _ds:fname_ |
 
-You can also type
-```
-make floppy
-```
 
-then 
+## polmon commands
-```
+
-bochs
+Commands are a single letter followed by an optional space and arguments, with optional spaces between them.
-```
+A command can be prefixed with up to 4 hex digits, which will then change the current address.
-to launch the simulator. You'll need to `c` it in the console for it to start.
+
+* (no command): dumps 16 bytes at the current address. If no address is given, also increments the current address by 16.
+* _w [u8]*_: writes bytes in hex to the current address.
+* _k src:u16 size:u16_: copy _size_ bytes of memory from _cur-seg_:_src_ to _cur-seg:cur-addr_
+* _s seg:u16_: changes the current segment
+* _j_: calls a function at the current address. ABI calling conventions below.
+* _l file:str_: loads a program with given name into the current segment, address _0x0100_.
+* _r [u16]*_: runs the program in the current segment with arguments.
+* _i ax:u16_: call an int 0x80 function with AX register specified. See section above.
+
+The _r_, _j_ and _i_ commands display the value of the AX register after returning to polmon.
+
+### ABI convention for (j)umping to functions
+
+* AX, BX, CX, DX are caller-saved, all others are callee-saved
+* first 3 arguments passed in AX, DX and CX, others are pushed in reverse order (former argument in lower memory)
+* return value in AX
+
+
+### ABI for programs
+
+See example in _hello.com_
 
 
 ## Useful stuff