- DSP :: data stack pointer
- RSP :: return stack pointer
-* Instructions overview
+* Implemented instructions
+
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 |
+| # | name | stack footprint | description |
+|----+----------+--------------------------------------+-------------------------------------------------------------|
+| 0 | [[id:4f0dee8a-647e-4d91-a252-aaf4782b5edc][nop]] | -- | No operation |
+| 1 | [[#halt][halt]] | -- | Halt CPU (exit emulator) |
+| 2 | [[id:820b1b90-4f4c-4ab1-b49f-9b4a52ea2528][kbd@]] | -- c | Read scancode of pressed or released key |
+| 3 | [[id:8721dc8c-b237-4e9a-a509-0ded1c02329b][num]] | -- n | Put immidiate number into datastack |
+| 4 | [[#jmp][jmp]] | -- | Jump to specified code |
+| 5 | [[#call][call]] | | Jump to specified code, save return address to return stack |
+| 6 | [[#section][1+]] | n -- n+1 | |
+| 7 | [[#section-1][1-]] | n -- n-1 | |
+| 8 | [[#dup][dup]] | n -- n n | Duplicate top of data stack |
+| 9 | [[#drop][drop]] | n -- | Drop last element in data stack |
+| 10 | [[#if][if]] | n -- | Jump to addr if top element was 0 |
+| 11 | [[#ret][ret]] | | Jump to code, specified in return stack. |
+| 12 | [[#c][c@]] | addr -- n | Read byte from memory at specified address |
+| 13 | [[#c-1][c!]] | n addr -- | Store byte to specified memory |
+| 14 | [[#push][push]] | DSTK -> RSTK | Move top of datastack to returnstack |
+| 15 | [[id:21871d09-4d58-440f-8c94-231105aa4e3f][pop]] | RSTK -> DSTK | Move top of returnstack to datastack |
+| 16 | <unused> | | |
+| 17 | [[#rot][rot]] | n1 n2 n3 -- n2 n3 n1 | Rotate stack elements |
+| 18 | [[#disk][disk@]] | FromDiskSect ToMem -- | Read 1KB from disk into RAM |
+| 19 | [[#disk-1][disk!]] | FromMem ToDiskSect -- | Write 1KB to disk |
+| 20 | [[#section-2][@]] | addr -- n | Read 32 bit number from memory |
+| 21 | [[#section-3][!]] | n addr -- | Store 32 bit number to memory |
+| 22 | [[#over][over]] | n1 n2 -- n1 n2 n1 | |
+| 23 | [[#swap][swap]] | n1 n2 -- n2 n1 | |
+| 24 | [[#section-4][+]] | n1 n2 -- n1+n2 | |
+| 25 | [[#section-5][-]] | n1 n2 -- n1-n2 | |
+| 26 | [[#section-6][*]] | n1 n2 -- n1*n2 | |
+| 27 | [[#section-7][/]] | n1 n2 -- n1/n2 | |
+| 28 | [[#section-8][>]] | n1 n2 -- result | Is true when n1 > n2 |
+| 29 | [[#section-9][<]] | n1 n2 -- result | Is true when n1 < n2 |
+| 30 | [[#not][not]] | n1 -- not_n1 | Logical not |
+| 31 | [[#i][i]] | -- n | Copies top of return stack into datastack |
+| 32 | [[#cprt][cprt@]] | addr -- n | Read one byte from hardware port |
+| 33 | [[#cprt-1][cprt!]] | n addr -- | Store one byte to hardware port |
+| 34 | [[#i2][i2]] | -- n | Like "i" but takes second top stack element |
+| 35 | [[#i3][i3]] | -- n | Like "i" but takes third top stack element |
+| 36 | [[#shl][shl]] | n amount -- n | Left bit shift |
+| 37 | [[#shr][shr]] | n amount -- n | Right bit shift |
+| 38 | [[#or][or]] | n1 n2 -- n | Logical or |
+| 39 | [[#xor][xor]] | n1 n2 -- n | Exclusive logical or |
+| 40 | [[#vidmap][vidmap]] | addr -- | Copy memory from "addr" to video memory |
+| 41 | [[#mouse][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][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 | [[id:77fa76d3-9cd0-49c1-882c-f30383347352][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 |
+
+** nop
+:PROPERTIES:
+:ID: 4f0dee8a-647e-4d91-a252-aaf4782b5edc
+:END:
+
+- *Stack Effect:* =--=
+- *Description:* No operation. The VM simply proceeds to the next
+ instruction without modifying any state. This is a placeholder
+ instruction that has no effect on registers or stacks.
+- *Notes:* Implemented by jumping back to the main instruction fetch
+ loop (=emu= label), effectively doing nothing.
+
+** halt
+:PROPERTIES:
+:CUSTOM_ID: halt
+:ID: 7c8841d3-2335-4ee9-b6b9-518d05354841
+:END:
+- *Stack Effect:* =--=
+- *Description:* Terminates the emulator process. Restores the original
+ text mode, closes the virtual disk file, restores the keyboard driver,
+ and exits to DOS.
+- *Notes:* This is the only way to cleanly exit the emulator. No stack
+ items are consumed.
** kbd@ - read scancode of pressed or released key
:PROPERTIES:
:ID: 820b1b90-4f4c-4ab1-b49f-9b4a52ea2528
:END:
-Returns 0 if no data available.
+- *Stack Effect:* =-- scancode=
+- *Description:* Reads the next keyboard scan code from the keyboard
+ buffer. Returns 0 if no keys are pressed. Non-blocking operation.
+
+** num
+:PROPERTIES:
+:ID: 8721dc8c-b237-4e9a-a509-0ded1c02329b
+:END:
+- *Stack Effect:* =-- n=
+- *Description:* Pushes a 32-bit immediate value onto the data stack.
+ The value is encoded in the instruction stream immediately after the
+ opcode.
+- *Notes:* The value is loaded from =[es:esi]=, then =esi= is
+ incremented by 4 to skip over the immediate data.
+
+** jmp
+:PROPERTIES:
+:CUSTOM_ID: jmp
+:ID: a5c53b60-ffe9-4ba4-ab87-30c2ccc51a45
+:END:
+- *Stack Effect:* =--=
+- *Description:* Unconditionally jumps to the absolute address specified
+ by the next 32-bit value in the instruction stream.
+- *Notes:* The target address is added to =xms_addr= to convert from
+ virtual to physical memory address before jumping.
+
+** call
+:PROPERTIES:
+:CUSTOM_ID: call
+:ID: 66efbd35-c2b6-4657-ba0f-ff00a3a2c312
+:END:
+- *Stack Effect:* =--=
+- *Description:* Calls a subroutine at the specified address. Saves the
+ return address (current instruction pointer + 4) onto the return stack
+ before jumping.
+- *Notes:* The return address is pushed to the return stack before the
+ jump occurs.
+
+** 1+
+:PROPERTIES:
+:CUSTOM_ID: section
+:ID: 76fe1c8f-756d-406e-9e8a-4ecc8f1d7369
+:END:
+- *Stack Effect:* =n -- n+1=
+- *Description:* Increments the top value on the data stack by 1.
+- *Notes:* Directly increments the dword at the data stack pointer.
+
+** 1-
+:PROPERTIES:
+:CUSTOM_ID: section-1
+:ID: 523f93a3-359e-4a6d-b296-df25008db403
+:END:
+- *Stack Effect:* =n -- n-1=
+- *Description:* Decrements the top value on the data stack by 1.
+- *Notes:* Directly decrements the dword at the data stack pointer.
+
+** dup
+:PROPERTIES:
+:CUSTOM_ID: dup
+:ID: 2a6a449a-fc76-421c-a81c-c2024a15fc78
+:END:
+- *Stack Effect:* =n -- n n=
+- *Description:* Duplicates the top value on the data stack.
+- *Notes:* Creates a copy of the top item and pushes it onto the stack.
+
+** drop
+:PROPERTIES:
+:CUSTOM_ID: drop
+:ID: 4600dbeb-1833-4e7d-af7e-f6cc6c98d022
+:END:
+- *Stack Effect:* =n --=
+- *Description:* Removes the top value from the data stack.
+- *Notes:* Simply increments the data stack pointer by 4 bytes.
+
+** if
+:PROPERTIES:
+:CUSTOM_ID: if
+:ID: d6f834b6-9a37-4414-91b3-62b3e1d920c1
+:END:
+- *Stack Effect:* =n --=
+- *Description:* Pops the top value from the data stack. If the value is
+ zero, jumps to the address specified by the next 32-bit value.
+ Otherwise, skips the address.
+- *Notes:* Used for conditional branching. The address is added to
+ =xms_addr= for physical address conversion.
+
+** ret
+:PROPERTIES:
+:CUSTOM_ID: ret
+:ID: 6e683977-a985-4bb8-9d2c-c860d30e1df6
+:END:
+- *Stack Effect:* =--=
+- *Description:* Returns from a subroutine by popping the return address
+ from the return stack and jumping to it.
+- *Notes:* The return stack pointer is incremented after the jump.
+
+** c@
+:PROPERTIES:
+:CUSTOM_ID: c
+:ID: a2ce44f7-b661-44e0-909b-644ff52aa38e
+:END:
+- *Stack Effect:* =addr -- byte=
+- *Description:* Reads a single byte from the specified memory address.
+ Replaces the address on the stack with the byte value.
+- *Notes:* The address is adjusted by =xms_addr= to convert to physical
+ memory before reading.
+
+** c!
+:PROPERTIES:
+:CUSTOM_ID: c-1
+:ID: f129ef87-a31a-40fe-b8d3-984da2db90e2
+:END:
+- *Stack Effect:* =n addr --=
+- *Description:* Stores a byte value to the specified memory address.
+- *Notes:* Takes two values from the stack: the byte to store and the
+ address. The address is adjusted by =xms_addr= before writing.
+
+** push
+:PROPERTIES:
+:CUSTOM_ID: push
+:ID: e4bcbaf1-7724-4051-b19c-1aa7cd06eae6
+:END:
+- *Stack Effect:* =DSTK -> RSTK=
+- *Description:* Moves the top value from the data stack to the return
+ stack.
+- *Notes:* Used for transferring values between the two stacks without
+ modifying the value.
+
+** pop
+:PROPERTIES:
+:ID: 21871d09-4d58-440f-8c94-231105aa4e3f
+:END:
+- *Stack Effect:* =RSTK -> DSTK=
+- *Description:* Moves the top value from the return stack to the data
+ stack.
+- *Notes:* Used for transferring values between the two stacks without
+ modifying the value.
+
+** rot
+:PROPERTIES:
+:CUSTOM_ID: rot
+:ID: 4cee73f7-c105-4b96-9380-ff89bd7fedad
+:END:
+- *Stack Effect:* =n1 n2 n3 -- n2 n3 n1=
+- *Description:* Rotates the top three values on the data stack. The
+ third item becomes the top, the top becomes the second, and the second
+ becomes the third.
+- *Notes:* Useful for reordering stack items without temporary storage.
+
+** disk@
+:PROPERTIES:
+:CUSTOM_ID: disk
+:ID: bed1aa27-66ac-4c73-bbb9-e49ff2aa67c5
+:END:
+- *Stack Effect:* =sector addr --=
+- *Description:* Reads 1KB of data from the virtual disk at the
+ specified sector into the specified memory address.
+- *Notes:* The sector number is the top of the stack, followed by the
+ destination address. The disk is accessed via DOS interrupt calls.
+
+** disk!
+:PROPERTIES:
+:CUSTOM_ID: disk-1
+:ID: 02eda775-e483-4057-b809-de36d586579b
+:END:
+- *Stack Effect:* =addr sector --=
+- *Description:* Writes 1KB of data from the specified memory address to
+ the virtual disk at the specified sector.
+- *Notes:* The destination address is on top of the stack, followed by
+ the sector number. Data is first copied to a temporary buffer before
+ writing.
+
+** @
+:PROPERTIES:
+:CUSTOM_ID: section-2
+:ID: 0a54f24b-e62a-4244-85e1-855a0007c81e
+:END:
+- *Stack Effect:* =addr -- value=
+- *Description:* Reads a 32-bit value from the specified memory address.
+ Replaces the address on the stack with the value.
+- *Notes:* The address is adjusted by =xms_addr= before reading. This is
+ the 32-bit equivalent of =c@=.
+
+** !
+:PROPERTIES:
+:CUSTOM_ID: section-3
+:ID: 50e0c841-d678-41b4-be5a-1bab792f367d
+:END:
+- *Stack Effect:* =value addr --=
+- *Description:* Stores a 32-bit value to the specified memory address.
+- *Notes:* Takes two values: the value to store and the address. The
+ address is adjusted by =xms_addr= before writing.
+
+** over
+:PROPERTIES:
+:CUSTOM_ID: over
+:ID: 29828b20-b14d-41ff-9705-ca576c352fb4
+:END:
+- *Stack Effect:* =n1 n2 -- n1 n2 n1=
+- *Description:* Duplicates the second item on the data stack, placing
+ it on top.
+- *Notes:* Commonly used to access the second item without popping the
+ top item.
+
+** swap
+:PROPERTIES:
+:CUSTOM_ID: swap
+:ID: 905894ae-d687-47cd-add0-f1904179a8a0
+:END:
+- *Stack Effect:* =n1 n2 -- n2 n1=
+- *Description:* Swaps the top two values on the data stack.
+- *Notes:* Essential for reordering stack items during complex
+ operations.
+
+** +
+:PROPERTIES:
+:CUSTOM_ID: section-4
+:ID: bf4434bb-91a5-40c1-93de-90a0e05a50ec
+:END:
+- *Stack Effect:* =n1 n2 -- n1+n2=
+- *Description:* Adds the top two values on the data stack. The result
+ replaces both values.
+- *Notes:* Performs unsigned 32-bit addition. The top value (n1) is
+ added to the second value (n2).
+
+** -
+:PROPERTIES:
+:CUSTOM_ID: section-5
+:ID: 9afc77fc-ecee-4a69-b1d2-f511e64a0d72
+:END:
+- *Stack Effect:* =n1 n2 -- n2-n1=
+- *Description:* Subtracts the top value from the second value on the
+ data stack. The result replaces both values.
+- *Notes:* Performs unsigned 32-bit subtraction. The second value (n2)
+ minus the top value (n1).
+
+** *
+:PROPERTIES:
+:CUSTOM_ID: section-6
+:ID: 85833e5c-e3ae-41a7-ad3d-6e9f0ecc9cdb
+:END:
+- *Stack Effect:* =n1 n2 -- n1*n2=
+- *Description:* Multiplies the top two values on the data stack. The
+ result replaces both values.
+- *Notes:* Uses 32-bit signed multiplication (IMUL). The top value (n1)
+ is multiplied by the second value (n2).
+
+** /
+:PROPERTIES:
+:CUSTOM_ID: section-7
+:ID: e5ff13c7-a9e6-4035-8efd-220d05381bf1
+:END:
+- *Stack Effect:* =n1 n2 -- n2/n1=
+- *Description:* Divides the second value by the top value on the data
+ stack. The quotient replaces both values.
+- *Notes:* Uses signed integer division (IDIV). The second value (n2) is
+ divided by the top value (n1).
+
+** >
+:PROPERTIES:
+:CUSTOM_ID: section-8
+:ID: abcc14d3-6cbf-46c3-8a93-ee7180f350d4
+:END:
+- *Stack Effect:* =n1 n2 -- result=
+- *Description:* Compares the second value with the top value. Returns
+ -1 (true) if n1 > n2, otherwise 0.
+- *Notes:* The comparison is between the second item (n1) and top item
+ (n2) on the stack.
+
+** <
+:PROPERTIES:
+:CUSTOM_ID: section-9
+:ID: 68362f38-c9e4-43f8-809c-8e15725a58c8
+:END:
+- *Stack Effect:* =n1 n2 -- result=
+- *Description:* Compares the second value with the top value. Returns
+ -1 (true) if n1 < n2, otherwise 0.
+- *Notes:* The comparison is between the second item (n1) and top item
+ (n2) on the stack.
+
+** not
+:PROPERTIES:
+:CUSTOM_ID: not
+:ID: 21994321-a1c6-42f6-9682-d5a3fbabb88a
+:END:
+- *Stack Effect:* =n -- ~n=
+- *Description:* Performs a bitwise NOT operation on the top value of
+ the data stack.
+- *Notes:* Inverts all bits of the dword at the top of the stack.
+
+** i
+:PROPERTIES:
+:CUSTOM_ID: i
+:ID: 61fbdd36-4384-44a6-b162-b4e998c4c191
+:END:
+- *Stack Effect:* =-- r=
+- *Description:* Pushes the top value from the return stack onto the
+ data stack.
+- *Notes:* Commonly used to access loop counters or subroutine
+ parameters.
+
+** cprt@
+:PROPERTIES:
+:CUSTOM_ID: cprt
+:ID: 78c1ac50-9c26-4132-8e02-8311331f2a1c
+:END:
+- *Stack Effect:* =port -- byte=
+- *Description:* Reads a byte from the specified hardware I/O port.
+- *Notes:* Uses IN instruction to read from the port. Replaces the port
+ address with the read byte.
+
+** cprt!
+:PROPERTIES:
+:CUSTOM_ID: cprt-1
+:ID: cfa8550e-bf8b-4d44-a3d1-9ba8ad183147
+:END:
+- *Stack Effect:* =byte port --=
+- *Description:* Writes a byte to the specified hardware I/O port.
+- *Notes:* Uses OUT instruction to write to the port. Consumes both the
+ byte and port address.
+
+** i2
+:PROPERTIES:
+:CUSTOM_ID: i2
+:ID: c3758859-c82e-40c1-9e92-87e5ef410cd2
+:END:
+- *Stack Effect:* =-- r2=
+- *Description:* Pushes the second value from the return stack onto the
+ data stack.
+- *Notes:* Useful for accessing deeper items in the return stack without
+ popping.
+
+** i3
+:PROPERTIES:
+:CUSTOM_ID: i3
+:ID: 304cadf7-9725-4e2d-8634-2e67b5ad49f3
+:END:
+- *Stack Effect:* =-- r3=
+- *Description:* Pushes the third value from the return stack onto the
+ data stack.
+- *Notes:* Allows access to the third item in the return stack for
+ deeper subroutine contexts.
+
+** shl
+:PROPERTIES:
+:CUSTOM_ID: shl
+:ID: 978d1b75-3a1d-476f-8cdb-d3a6ee40b3f5
+:END:
+- *Stack Effect:* =value shift -- result=
+- *Description:* Shifts the top value left by the specified number of
+ bits.
+- *Notes:* The shift amount is the top item, and the value to shift is
+ the second item. Uses SHL instruction.
+
+** shr
+:PROPERTIES:
+:CUSTOM_ID: shr
+:ID: 9dbfcd07-6c34-41b7-b5dc-a33f0773e7cd
+:END:
+- *Stack Effect:* =value shift -- result=
+- *Description:* Shifts the top value right by the specified number of
+ bits.
+- *Notes:* The shift amount is the top item, and the value to shift is
+ the second item. Uses SHR instruction.
+
+** or
+:PROPERTIES:
+:CUSTOM_ID: or
+:ID: b38b971f-3a5f-4b16-9536-4193d2c5ae6b
+:END:
+- *Stack Effect:* =n1 n2 -- n1|n2=
+- *Description:* Performs a bitwise OR operation on the top two values.
+- *Notes:* The top value (n1) is ORed with the second value (n2).
+
+** xor
+:PROPERTIES:
+:CUSTOM_ID: xor
+:ID: e87a0d6d-89b0-4791-9500-654d60d99318
+:END:
+- *Stack Effect:* =n1 n2 -- n1^n2=
+- *Description:* Performs a bitwise XOR operation on the top two values.
+- *Notes:* The top value (n1) is XORed with the second value (n2).
+
+** vidmap
+:PROPERTIES:
+:CUSTOM_ID: vidmap
+:ID: fe47ff6d-768f-4b05-9f8c-f52352c106f4
+:END:
+Stack Footprint
+: addr --
+
+Copies memory from the specified address to the video memory (VGA or
+VESA mode). Used for displaying images directly on the screen.
+
+Parameters:
+- *addr* (32-bit): Source memory address containing the image data to
+ copy to video memory.
+
+*** Detailed Operation
+:PROPERTIES:
+:CUSTOM_ID: detailed-operation-4
+:END:
+1. *Video Memory Setup*:
+ - Set video memory segment to =0xA000= (VGA standard segment for
+ graphics mode).
+ - Initialize VESA-related variables (e.g., =gra= for page number).
+2. *VESA Page Mapping*:
+ - For each VESA page (up to 19 pages for 640x480x8 mode):
+ - Set VESA page using interrupt =0x10= with =AX = 0x4F05=.
+ - The page number is stored in =gra=.
+3. *Memory Copying*:
+ - For each page:
+ - Copy 4096 bytes (4KB) from source address to video memory.
+ - Use =STOSD= to write 32-bit words for efficiency.
+ - The source address is incremented by 4KB after each page.
+4. *Final Cleanup*:
+ - Restore original segments and clean up stack.
+
+*** Example
+:PROPERTIES:
+:CUSTOM_ID: example-4
+:END:
+Copy a 640x480x8 image (307,200 bytes) from memory at =0x10000= to video
+memory:
+
+1. *Stack Operation*:
+
+ #+begin_example
+ 0x10000
+ vidmap
+ #+end_example
+
+2. *Result*:
+
+ - The image data is copied to video memory.
+ - For 640x480x8 mode, 307,200 bytes are copied across multiple VESA
+ pages.
+
+*** Notes
+
+- The operation assumes the video mode is set to VESA 640x480x8 (mode
+ =0x101=).
+- The exact number of pages copied depends on the video mode (19 pages
+ for 640x480x8).
+- Requires VESA BIOS support and proper initialization via
+ =set_vesa_mode=.
+** mouse@
+:PROPERTIES:
+:CUSTOM_ID: mouse
+:ID: b4bce653-d38f-45ed-82ec-13ca78c9860b
+:END:
+Stack Footprint:
+: -- x y buttons
+
+*** Description
+
+Reads the current mouse position and button states from the mouse
+driver. Returns three values on the stack:
+- X-coordinate,
+- Y-coordinate,
+- button states.
+
+*** Parameters
+
+- *Returns*:
+ - *x* (32-bit): Current X-coordinate of the mouse cursor (0-based).
+ - *y* (32-bit): Current Y-coordinate of the mouse cursor (0-based).
+ - *buttons* (32-bit): Bitmask of button states:
+ - Bit 0: Left button (1 = pressed)
+ - Bit 1: Right button (1 = pressed)
+ - Bit 2: Middle button (1 = pressed)
+
** 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.
+Stack Footprint:
+: addr1 addr2 x y --=
+
+Copies a portion of image1 to image2 at the specified (x, y)
+coordinates with clipping. Unlike =tvidput=, there is no transparency
+support - every pixel is copied regardless of value.
+
+*** Parameters
+
+- *addr1* (32-bit): Address of the source image structure (width,
+ height, data address).
+- *addr2* (32-bit): Address of the destination image structure (width,
+ height, data address).
+- *x* (32-bit): X-coordinate in the destination image where the copy
+ starts.
+- *y* (32-bit): Y-coordinate in the destination image where the copy
+ starts.
+
+*** Image Structure Format
+
+Identical to =tvidput=:
+- *Offset 0*: Image width (32-bit)
+- *Offset 4*: Image height (32-bit)
+- *Offset 8*: Base address of image data (32-bit pointer)
+
+*** Example
+Same as =tvidput= example but without transparency handling. Copying a
+100x100 image from =0x1000= to =0x2000= at (50, 50) would copy all
+pixels (including those with value 255).
+
** 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.
+
+- *Stack Effect:*
+: addr1 addr2 len --
+
+Copies =len= bytes from =addr1= to =addr2=. Handles overlapping memory
+regions correctly.
+
+- *Notes:* If =addr1 > addr2=, copies backwards to avoid data
+ corruption; otherwise copies forwards.
+
+** cfill
+:PROPERTIES:
+:CUSTOM_ID: cfill
+:ID: fecb9438-d9d2-4224-a017-cc87dba9209e
+:END:
+- *Stack Effect:* =byte addr len --=
+- *Description:* Fills =len= bytes of memory starting at =addr= with the
+ specified byte value.
+- *Notes:* Simple byte-by-byte filling operation. Used for initializing
+ memory regions.
+
** tvidput - put image with transparency support
:PROPERTIES:
:ID: ab45247c-44c3-464d-9e2a-337f483b4616
:END:
-Stack footprint
+Stack Footprint:
: addr1 addr2 x y --
-Put image1 into image2, at location x, y with transparency support
+Copies a portion of image1 to image2 at the specified (x, y)
+coordinates with transparency support. Pixels in image1 with value 255
+(0xFF) are treated as transparent and are not copied to the
+destination.
+
+*** Parameters
+
+- *addr1* (32-bit): Address of the source image structure (contains
+ width, height, and data address).
+- *addr2* (32-bit): Address of the destination image structure (contains
+ width, height, and data address).
+- *x* (32-bit): X-coordinate in the destination image where the copy
+ starts.
+- *y* (32-bit): Y-coordinate in the destination image where the copy
+ starts.
+
+*** Image Structure Format
+
+Each image structure is stored in memory as follows:
+- *Offset 0*: Image width (32-bit integer)
+- *Offset 4*: Image height (32-bit integer)
+- *Offset 8*: Base address of image data (32-bit pointer)
+
+*** Example
+
+Copy a 100x100 image from source structure at =0x1000= to destination
+structure at =0x2000=, starting at (50, 50):
+
+1. *Source Structure (0x1000)*:
+
+ - Width: 100
+ - Height: 100
+ - Data Address: =0x3000=
+
+2. *Destination Structure (0x2000)*:
+
+ - Width: 640
+ - Height: 480
+ - Data Address: =0x5000=
+
+3. *Stack Operations*:
+
+ #+begin_example
+ 50 ; y
+ 50 ; x
+ 0x2000 ; addr2 (destination structure)
+ 0x1000 ; addr1 (source structure)
+ tvidput
+ #+end_example
+
+4. *Result*:
+
+ - Only the overlapping region (100x100) is copied.
+ - Any pixel in the source image with value 255 is skipped
+ (transparent).
+ - The copied image starts at (50, 50) in the destination buffer.
+
+*** Notes
+
+- Transparency is fixed at value 255 (0xFF).
+- The operation handles clipping automatically to ensure the copy stays
+ within destination bounds.
+- Source and destination image structures must be properly formatted.
+
+** depth
+:PROPERTIES:
+:ID: 77fa76d3-9cd0-49c1-882c-f30383347352
+:END:
+- *Stack Effect:* =-- depth=
+- *Description:* Pushes the current depth (number of items) on the data
+ stack onto the stack.
+- *Notes:* Calculated by comparing the data stack pointer to the base
+ address of the stack.
-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.
+
+Stack Footprint:
+=colorfg colorbg addrsrc addrdest x y --=
+
+
+Draws an 8x8 character from a source memory buffer to a destination
+image buffer at the specified (x, y) coordinates. Each byte in the
+source buffer represents one row of the character (8 bits per row),
+where each bit determines whether to use the foreground or background
+color for that pixel.
+
+*** Parameters
+
+- *colorfg* (1 byte): Foreground color value (0-255). Typically a
+ grayscale value where 0 is black and 255 is white.
+- *colorbg* (1 byte): Background color value (0-255).
+- *addrsrc* (32-bit): Memory address pointing to 8 bytes of character
+ data. Each byte represents one row of the character (8 bits per row).
+- *addrdest* (32-bit): Base address of the destination image buffer in
+ memory.
+- *x* (32-bit): X-coordinate (0-based) where the character's left edge
+ starts.
+- *y* (32-bit): Y-coordinate (0-based) where the character's top edge
+ starts.
+
+*** Example
+
+To draw the letter 'A' (ASCII 65) at position (10, 20) in a 640x480
+VGA image buffer starting at address =0x5000=, with white foreground
+(0xFF) and black background (0x00):
+
+
+Character data for 'A' (8 rows):
+#+begin_example
+0x00, 0x18, 0x24, 0x24, 0x24, 0x3C, 0x24, 0x24
+#+end_example
+
+- Each byte represents a row:
+ - Row 0: =0x00= → all pixels black
+ - Row 1: =0x18= → bits 3-4 set (binary =00011000=)
+ - Row 2: =0x24= → bits 2 and 5 set (binary =00100100=)
+ - Row 3: =0x24= → same as row 2
+ - Row 4: =0x24= → same as row 2
+ - Row 5: =0x3C= → bits 2-5 set (binary =00111100=)
+ - Row 6: =0x24= → same as row 2
+ - Row 7: =0x24= → same as row 2
projects / fifth.git / commitdiff