doc/virtual machine.org

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