From: Svjatoslav Agejenko <svjatoslav@svjatoslav.eu>
Date: Sun, 22 Feb 2026 02:38:03 +0000 (+0200)
Subject: Expand `shl` opcode documentation: detailed description, stack effect, corner cases... 
X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;h=d32706d505efeba1a882705772169a7130392950;p=fifth.git

Expand `shl` opcode documentation: detailed description, stack effect, corner cases, examples, and notes. Update virtual machine table entry for clarity.
---

diff --git a/doc/opcodes_30_39.org b/doc/opcodes_30_39.org
index 7e85502..ac4389e 100644
--- a/doc/opcodes_30_39.org
+++ b/doc/opcodes_30_39.org
@@ -132,18 +132,39 @@
 :CUSTOM_ID: ID-978d1b75-3a1d-476f-8cdb-d3a6ee40b3f5
 :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.
-- *Example:*
+- *Stack Effect:* =value count -- result=
+- *Description:* Shifts =value= left by =count= bit positions. Each bit
+  position shifted left multiplies the value by 2.
+- *Bits Shifted Out:* Bits that are shifted beyond the most
+  significant bit (bit 31) are **discarded**.
+- *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.
+
+*Examples:*
+  #+begin_example
+  1  \ Value to shift
+  2  \ Shift amount (count)
+  shl
+  #+end_example
+  Result: 4 (0b0001 << 2 = 0b0100).
+
   #+begin_example
-  2  ; Shift amount
-  1  ; Value to shift
+  FF    \ Value: 255 (0x000000FF)
+  4     \ Shift by 4
   shl
   #+end_example
-  After execution, stack contains 2 (1 << 2).
+  Result: FF0 (0x00000FF0 = 4080 decimal). The low 4 bits (F) were
+  shifted up, and the upper bits remain zero.
+  #+begin_example
 
 * 37: shr
 :PROPERTIES:
@@ -157,8 +178,8 @@
   the second item. Uses SHR instruction.
 - *Example:*
   #+begin_example
-  1  ; Shift amount
-  2  ; Value to shift
+  1  \ Shift amount
+  2  \ Value to shift
   shr
   #+end_example
   After execution, stack contains 1 (2 >> 1).
diff --git a/doc/virtual machine.org b/doc/virtual machine.org
index 0650773..da544a2 100644
--- a/doc/virtual machine.org	
+++ b/doc/virtual machine.org	
@@ -148,7 +148,7 @@ in FIFTH programming language):
 | 33 | [[id:cfa8550e-bf8b-4d44-a3d1-9ba8ad183147][cprt!]]    | byte port --          | Write byte to hardware I/O port                          |                                                                     |
 | 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 shift -- result | Left shift value by shift amount                         | TODO: Document example. What happens to bits that are shifted away? |
+| 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                        |                                                                     |
 | 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               |                                                                     |