--- /dev/null
+:PROPERTIES:
+:ID: 9b251eb9-aff6-4025-94bf-25e89e26d54a
+:END:
+
+#+TITLE: Fifth - virtual machine
+#+AUTHOR: Svjatoslav Agejenko
+#+LANGUAGE: en
+
+Current emulator emulates:
+- 1 CPU.
+- It has 2 stacks
+- ~50 instructions
+- 4GB flat address space (theoretically).
+
+
+While I tried to keep instruction set simple, I was forced to put in
+some complex instructions to make performance acceptable on
+emulator.
+
+CPU has following registers:
+- IP :: instruction pointer
+- DSP :: data stack pointer
+- RSP :: return stack pointer
+
+* Instructions overview
+Virtual CPU, commands (most of them are avaiable as ordinary commands
+in programming language):
+
+
+| # | name | stack footprint | description |
+|----+--------------+--------------------------------------+-------------------------------------------------------------|
+| 0 | nop | -- | does nothing |
+| 1 | halt | -- | halt CPU ( return to DOS on emulator ) |
+| 2 | [[id:820b1b90-4f4c-4ab1-b49f-9b4a52ea2528][kbd@]] | -- c | read scancode of pressed or released key |
+| 3 | num <dword> | -- n | put immidiate number into datastack |
+| 4 | jmp <dword> | -- | jump to specified code |
+| 5 | call <dword> | | jump to specified code, save return address to return stack |
+| 6 | 1+ | n -- n+1 | |
+| 7 | 1- | n -- n-1 | |
+| 8 | dup | n -- n n | duplicate top of data stack |
+| 9 | drop | n -- | drop last element in data stack |
+| 10 | if <dword> | n -- | jump to addr if top element was 0 |
+| 11 | ret | | jump to code, specified in return stack. |
+| 12 | c@ | addr -- n | read byte from memory at specified address |
+| 13 | c! | n addr -- | store byte to specified memory |
+| 14 | push | DSTK -> RSTK | move top of datastack to returnstack |
+| 15 | pop | RSTK -> DSTK | move top of returnstack to datastack |
+| 16 | <unused> | | |
+| 17 | rot | n1 n2 n3 -- n2 n3 n1 | rotate stack elements |
+| 18 | disk@ | FromDiskSect ToMem -- | read 1KB from disk into RAM |
+| 19 | disk! | FromMem ToDiskSect -- | write 1KB to disk |
+| 20 | @ | addr -- n | read 32 bit number from memory |
+| 21 | ! | n addr -- | store 32 bit number to memory |
+| 22 | over | n1 n2 -- n1 n2 n1 | |
+| 23 | swap | n1 n2 -- n2 n1 | |
+| 24 | + | n1 n2 -- n1+n2 | |
+| 25 | - | n1 n2 -- n1-n2 | |
+| 26 | * | n1 n2 -- n1*n2 | |
+| 27 | / | n1 n2 -- n1/n2 | |
+| 28 | > | n1 n2 -- result | is true when n1 > n2 |
+| 29 | < | n1 n2 -- result | is true when n1 < n2 |
+| 30 | not | n1 -- not_n1 | logical not |
+| 31 | i | -- n | copies top of return stack into datastack |
+| 32 | cprt@ | addr -- n | read one byte from hardware port |
+| 33 | cprt! | n addr -- | store one byte to hardware port |
+| 34 | i2 | -- n | like "i" but takes second top stack element |
+| 35 | i3 | -- n | like "i" but takes third top stack element. |
+| 36 | shl | n amount -- n | left bit shift |
+| 37 | shr | n amount -- n | right bit shift |
+| 38 | or | n1 n2 -- n | logical or |
+| 39 | xor | n1 n2 -- n | exclusive logical or |
+| 40 | vidmap | addr -- | copy memory from "addr" to video memory. |
+| 41 | mouse@ | -- x y button | read mouse coordinates & buttons |
+| 42 | [[id:238e8b03-57b6-424d-bfee-b6bb652cefbc][vidput]] | addr1 addr2 x y -- | put image1 into image2, at location x, y |
+| 43 | [[id:79e1916f-4103-42cc-ac10-bb1ee776ed50][cmove]] | addr1 addr2 amount | move memory from addr1 to addr2 |
+| 44 | cfill | c addr amount -- | fill memory starting at "addr" with "c" bytes. |
+| 45 | [[id:ab45247c-44c3-464d-9e2a-337f483b4616][tvidput]] | addr1 addr2 x y -- | put image with transparency support |
+| 46 | depth | -- depth | returns current depth of data stack. |
+| 47 | [[id:4bb479cf-aae0-4128-9868-f016c286a162][charput]] | colorfg colorbg addrsrc addrdest x y | draw text character |
+
+** kbd@ - read scancode of pressed or released key
+:PROPERTIES:
+:ID: 820b1b90-4f4c-4ab1-b49f-9b4a52ea2528
+:END:
+Returns 0 if no data available.
+** vidput - put image1 into image2, at location x, y
+:PROPERTIES:
+:ID: 238e8b03-57b6-424d-bfee-b6bb652cefbc
+:END:
+Does clipping, so part of a big image can be mapped into smaller one.
+** cmove - copy memory array
+:PROPERTIES:
+:ID: 79e1916f-4103-42cc-ac10-bb1ee776ed50
+:END:
+Move memory from addr1 to addr2. If addr1 is greater than addr2 then
+count address foward while moving, elseway starts from end and counts
+backwards, so no data loss occurs when memory regions partially
+overlap.
+** tvidput - put image with transparency support
+:PROPERTIES:
+:ID: ab45247c-44c3-464d-9e2a-337f483b4616
+:END:
+Stack footprint
+: addr1 addr2 x y --
+
+Put image1 into image2, at location x, y with transparency support
+
+Color 255 in source image is treated as transparent.
+** charput - draw text character
+:PROPERTIES:
+:ID: 4bb479cf-aae0-4128-9868-f016c286a162
+:END:
+Draw character to image buffer located at "addrdest" to specified x &
+y location. Decodes 8 bytes from source to bits, used to draw
+character.