ls004: Added initial draft.

diff --git a/openpower/sv/rfc/ls004.mdwn b/openpower/sv/rfc/ls004.mdwn
new file mode 100644 (file)
index 0000000..60c14d4
--- /dev/null
+++ b/openpower/sv/rfc/ls004.mdwn
@@ -0,0 +1,154 @@
+# RFC ls004  Shift-And-Add
+
+**URLs**:
+
+* <https://libre-soc.org/openpower/sv/biginteger/analysis/>
+* <https://libre-soc.org/openpower/sv/rfc/ls004/>
+* <https://bugs.libre-soc.org/show_bug.cgi?id=960>
+* <https://git.openpower.foundation/isa/PowerISA/issues/91>
+* shift-and-add <https://bugs.libre-soc.org/show_bug.cgi?id=968>
+
+**Severity**: Major
+
+**Status**: New
+
+**Date**: 31 Oct 2022
+
+**Target**: v3.2B
+
+**Source**: v3.0B
+
+**Books and Section affected**:
+
+```
+    Book I Fixed-Point Shift Instructions 3.3.14.2
+    Appendix E Power ISA sorted by opcode
+    Appendix F Power ISA sorted by version
+    Appendix G Power ISA sorted by Compliancy Subset
+    Appendix H Power ISA sorted by mnemonic
+```
+
+**Summary**
+
+```
+    Instructions added
+    shadd - Shift and Add
+    shadduw - Shift and Add Unsigned Word 
+```
+
+**Submitter**: Luke Leighton (Libre-SOC)
+
+**Requester**: Libre-SOC
+
+**Impact on processor**:
+
+```
+    Addition of two new GPR-based instructions
+```
+
+**Impact on software**:
+
+```
+    Requires support for new instructions in assembler, debuggers,
+    and related tools.
+```
+
+**Keywords**:
+
+```
+    GPR, Big-manip, Shift, Arithmetic
+```
+
+**Motivation**
+
+Power ISA is missing LD/ST with shift, which is present in both ARM and x86.
+Adding more LD/ST is too complex, a compromise is to add shift-and-add.
+Replaces a pair of explicit instructions in hot-loops.
+
+**Notes and Observations**:
+
+1. `shadd` and `shadduw` operate on unsigned integers.
+2. `shadduw` masks the upper 32-bits of the operand to-be-shifted.
+3. These are both 2-in 1-out instructions.
+
+**Changes**
+
+Add the following entries to:
+
+* the Appendices of Book I
+* Instructions of Book I added to Section 3.3.14.2
+
+----------------
+
+\newpage{}
+
+# Shift-and-Add
+
+`shadd 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
+    sum[0:63] <- ((RB) << shift) + (RA) # Shift RB, add RA
+    RT <- sum                                      # Result stored in RT
+
+`shift` is determined by the 2-bit bitfield `sm`+1.
+The minimum shift as 1, maximum 4.
+The result is shifted (RB) + (RA), and is stored in register RT.
+
+Operands RA and RB, and the result RT are all 64-bit, unsigned integers.
+
+**NEED EXAMPLES (not sure how to embedd sm)!!!**
+Examples:
+```
+# 
+shadd r4, r1, r2
+```
+
+# Shift-and-Add Upper Word
+
+`shadd 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 <- shift + 1                         # Shift is between 1-4
+    n <- (RB)[XLEN/2:XLEN-1]               # Limit RB to upper word (32-bits)
+    sum[0:63] <- (n << shift) + (RA)    # Shift n, add RA
+    RT <- sum                                      # Result stored in RT
+
+`shift` is determined by the 2-bit bitfield `sm`+1.
+Mask (RB) to only use the upper word (32-bits).
+The minimum shift as 1, maximum 4.
+The result is shifted `n` + (RA), and is stored in register RT.
+
+Operands RA and RB, and the result RT are all 64-bit, unsigned integers.
+
+Examples:
+```
+# 
+shadduw r4, r1, r2
+```
+
+
+[[!tag opf_rfc]]
+
+# Appendices
+
+    Appendix E Power ISA sorted by opcode
+    Appendix F Power ISA sorted by version
+    Appendix G Power ISA sorted by Compliancy Subset
+    Appendix H Power ISA sorted by mnemonic
+
+| Form | Book | Page | Version | mnemonic | Description |
+|------|------|------|---------|----------|-------------|
+| Z23  | I    | #    | 3.0B    | shadd    | Shift-and-Add |
+| Z23  | I    | #    | 3.0B    | shadduw  | Shift-and-Add Unsigned Word |
+