From 9799b991bc33ac5227f51353e03c84ebc4a46b28 Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Sun, 22 Feb 2026 04:46:51 +0200 Subject: [PATCH] Expand `shr` opcode documentation: detailed description, stack effect, corner cases, examples, and notes. Update virtual machine table entry for consistency. --- doc/opcodes_30_39.org | 77 +++++++++++++++++++++++++++-------------- doc/virtual machine.org | 2 +- 2 files changed, 52 insertions(+), 27 deletions(-) diff --git a/doc/opcodes_30_39.org b/doc/opcodes_30_39.org index ac4389e..bff88cc 100644 --- a/doc/opcodes_30_39.org +++ b/doc/opcodes_30_39.org @@ -132,6 +132,7 @@ :CUSTOM_ID: ID-978d1b75-3a1d-476f-8cdb-d3a6ee40b3f5 :ID: 978d1b75-3a1d-476f-8cdb-d3a6ee40b3f5 :END: + - *Stack Effect:* =value count -- result= - *Description:* Shifts =value= left by =count= bit positions. Each bit position shifted left multiplies the value by 2. @@ -150,39 +151,63 @@ - =value = 0=: Result is always 0 regardless of count. *Examples:* - #+begin_example - 1 \ Value to shift - 2 \ Shift amount (count) - shl - #+end_example - Result: 4 (0b0001 << 2 = 0b0100). - #+begin_example - FF \ Value: 255 (0x000000FF) - 4 \ Shift by 4 - shl - #+end_example - Result: FF0 (0x00000FF0 = 4080 decimal). The low 4 bits (F) were - shifted up, and the upper bits remain zero. - #+begin_example +#+begin_example +1 \ Value to shift +2 \ Shift amount (count) +shl +#+end_example +Result: 4 (0b0001 << 2 = 0b0100). + +#+begin_example +FF \ Value: 255 (0x000000FF) +4 \ Shift by 4 +shl +#+end_example +Result: FF0 (0x00000FF0 = 4080 decimal). The low 4 bits (F) were +shifted up, and the upper bits remain zero. +#+begin_example * 37: shr :PROPERTIES: :CUSTOM_ID: ID-9dbfcd07-6c34-41b7-b5dc-a33f0773e7cd :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. -- *Example:* - #+begin_example - 1 \ Shift amount - 2 \ Value to shift - shr - #+end_example - After execution, stack contains 1 (2 >> 1). + +- *Stack Effect:* =value count -- result= +- *Description:* Shifts =value= right by =count= bit positions. Each bit + position shifted right divides the value by 2 (integer division). +- *Bits Shifted Out:* Bits that are shifted beyond the least significant + bit (bit 0) are **discarded**. +- *Zero Fill:* This is a **logical shift right** (unsigned). Zeros are + shifted in from the left (MSB side). This differs from an arithmetic + shift right which would preserve the sign bit. +- *Count Masking:* Only the low byte of =count= is used. On x86 + processors, the actual shift amount is further masked to 5 bits + (=count & 0x1F=), meaning the effective shift is always 0-31. + +*Corner Cases:* +- =count = 0=: Value unchanged. +- =count >= 32=: Due to 5-bit masking, the effective shift is + =count mod 32=. For example, shift by 32 results in no change, + shift by 33 shifts by 1. +- =value = 0=: Result is always 0 regardless of count. +- Shifting by 31 always results in 0 (all bits shifted out). + +*Examples:* +#+begin_example +8 \ Value to shift +2 \ Shift amount (count) +shr +#+end_example +Result: 2 (0b1000 >> 2 = 0b0010). + +#+begin_example +1 \ Value: only bit 0 set +1 \ Shift by 1 +shr +#+end_example +Result: 0. The single bit was shifted out and discarded. * 38: or :PROPERTIES: diff --git a/doc/virtual machine.org b/doc/virtual machine.org index da544a2..d1e3633 100644 --- a/doc/virtual machine.org +++ b/doc/virtual machine.org @@ -149,7 +149,7 @@ in FIFTH programming language): | 34 | [[id:c3758859-c82e-40c1-9e92-87e5ef410cd2][i2]] | -- n | Push second item from return stack to data stack | | | 35 | [[id:304cadf7-9725-4e2d-8634-2e67b5ad49f3][i3]] | -- n | Push third item from return stack to data stack | | | 36 | [[id:978d1b75-3a1d-476f-8cdb-d3a6ee40b3f5][shl]] | value count -- result | Left shift value by count bits; shifted-out bits discarded | -| 37 | [[id:9dbfcd07-6c34-41b7-b5dc-a33f0773e7cd][shr]] | value shift -- result | Right shift value by shift amount | | +| 37 | [[id:9dbfcd07-6c34-41b7-b5dc-a33f0773e7cd][shr]] | value count -- result | Logical right shift; zeros shifted in, shifted-out bits discarded | | 38 | [[id:b38b971f-3a5f-4b16-9536-4193d2c5ae6b][or]] | n1 n2 -- result | Bitwise OR of top two items on data stack | | | 39 | [[id:e87a0d6d-89b0-4791-9500-654d60d99318][xor]] | n1 n2 -- result | Bitwise XOR of top two items on data stack | | | 40 | [[id:fe47ff6d-768f-4b05-9f8c-f52352c106f4][vidmap]] | addr -- | Copy memory to video memory | | -- 2.20.1