From 0a57f55b8e4c34c07b8f1dcf55ec63625e2f113b Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Sat, 14 Feb 2026 01:56:07 +0200 Subject: [PATCH] Expanded and clarified virtual machine instructions documentation. --- doc/virtual machine.org | 782 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 719 insertions(+), 63 deletions(-) diff --git a/doc/virtual machine.org b/doc/virtual machine.org index 262c414..d10e704 100644 --- a/doc/virtual machine.org +++ b/doc/virtual machine.org @@ -22,94 +22,750 @@ CPU has following registers: - 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 | -- n | put immidiate number into datastack | -| 4 | jmp | -- | jump to specified code | -| 5 | call | | 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 | 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 | | | | -| 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 | | | | +| 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 -- 2.20.1