add shaddw to ls004

diff --git a/openpower/sv/rfc/ls004.mdwn b/openpower/sv/rfc/ls004.mdwn
index 9141006617ea6f2e932ed4ed4b0f20823807f61e..62831af1c8de2bd483c74de878b34c233767e2d8 100644 (file)
--- a/openpower/sv/rfc/ls004.mdwn
+++ b/openpower/sv/rfc/ls004.mdwn
@@ -34,6 +34,7 @@
 ```
     Instructions added
     shadd - Shift and Add
+    shaddw - Shift and Add Signed Word
     shadduw - Shift and Add Unsigned Word
 ```
 
@@ -44,7 +45,7 @@
 **Impact on processor**:
 
 ```
-    Addition of two new GPR-based instructions
+    Addition of three new GPR-based instructions
 ```
 
 **Impact on software**:
@@ -72,11 +73,14 @@ add shift-and-add.  Replaces a pair of explicit instructions in hot-loops.
 2. `shadduw` is intended for performing address offsets,
     as the second operand is constrained to lower 32-bits
     and zero-extended.
-3. Both are 2-in 1-out instructions.
+3. All three are 2-in 1-out instructions.
 4. shift-add operations are present in both x86 and aarch64,
     since they are useful for both general arithmetic and for
     computing addresses even when not immediately followed
     with a load/store.
+5. `shaddw` is often more useful than `shadduw` because C/C++ programmers like
+    to use `int` for array indexing. for additional details see
+    <https://bugs.libre-soc.org/show_bug.cgi?id=996>.
 
 TODO: signed 32-bit shift-and-add should be added, this needs to be addressed
 before submitting the RFC: <https://bugs.libre-soc.org/show_bug.cgi?id=996>
@@ -188,6 +192,43 @@ Examples:
     shadd r4, r1, r2, 3
 ```
 
+# Shift-and-Add Signed Word
+
+`shaddw RT, RA, RB`
+
+|  0-5  | 6-10 | 11-15 | 16-20 | 21-22 | 23-30 | 31 | Form     |
+|-------|------|-------|-------|-------|-------|----|----------|
+|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | Rc | Z23-Form |
+
+Pseudocode:
+
+```
+    shift <- sm + 1                  # Shift is between 1-4
+    n <- EXTS64((RB)[32:63])         # Only use lower 32-bits of RB
+    sum[0:63] <- (n << shift) + (RA) # Shift n, add RA
+    RT <- sum                        # Result stored in RT
+```
+
+When `sm` is zero, the lower word contents of register RB are multiplied by 2,
+added to the contents of register RA, and the result stored in RT.
+
+`sm` is a 2-bit bit-field, and allows multiplication of RB by 2, 4, 8, 16.
+
+Operands RA and RB, and the result RT are all 64-bit, signed integers.
+
+*Programmer's Note:
+The advantage of this instruction is doing address offsets. RA is the base 64-bit
+address. RB is the offset into data structure limited to 32-bit.*
+
+Examples:
+
+```
+#
+shaddw r4, r1, r2
+```
+
+[[!tag opf_rfc]]
+
 # Shift-and-Add Unsigned Word
 
 `shadduw RT, RA, RB`
@@ -235,4 +276,5 @@ shadduw r4, r1, r2
 | Form | Book | Page | Version | mnemonic | Description |
 |------|------|------|---------|----------|-------------|
 | Z23  | I    | #    | 3.0B    | shadd    | Shift-and-Add |
+| Z23  | I    | #    | 3.0B    | shaddw   | Shift-and-Add Signed Word |
 | Z23  | I    | #    | 3.0B    | shadduw  | Shift-and-Add Unsigned Word |