Expand `shr` opcode documentation: detailed description, stack effect, corner cases...

diff --git a/doc/opcodes_30_39.org b/doc/opcodes_30_39.org
index ac4389e..bff88cc 100644 (file)
--- 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 (file)
--- 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                              |                                                                     |