feedback on ls004

https://bugs.libre-soc.org/show_bug.cgi?id=1091
* change field name "sm" to "SH"
* change instruction name to "sadd" not "shadd"
* add Formats/Fields for 1.6 and 1.7

diff --git a/openpower/sv/rfc/ls004.mdwn b/openpower/sv/rfc/ls004.mdwn
index 7d006d089b2309ef2b150cb0e5d5c4b51bb99c68..7830020c33cec90a045b45b9c7c6ecb0ca8a6086 100644 (file)
--- a/openpower/sv/rfc/ls004.mdwn
+++ b/openpower/sv/rfc/ls004.mdwn
@@ -9,7 +9,7 @@
 **Changes**:
 
 * initial shift-and-add <https://bugs.libre-soc.org/show_bug.cgi?id=968>
-* add shaddw: <https://bugs.libre-soc.org/show_bug.cgi?id=996>
+* add saddw: <https://bugs.libre-soc.org/show_bug.cgi?id=996>
 * consider LD/ST-Shifted  <https://bugs.libre-soc.org/show_bug.cgi?id=1055>
 
 **Severity**: Major
@@ -36,9 +36,9 @@
 
 ```
     Instructions added
-    shadd - Shift and Add
-    shaddw - Shift and Add Signed Word
-    shadduw - Shift and Add Unsigned Word
+    sadd - Shift and Add
+    saddw - Shift and Add Signed Word
+    sadduw - Shift and Add Unsigned Word
     Also under consideration LD/ST-Indexed-Shifted
 ```
 
@@ -73,8 +73,8 @@ 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` is intended for performing address offsets,
+1. `sadd` and `sadduw` operate on unsigned integers.
+2. `sadduw` is intended for performing address offsets,
     as the second operand is constrained to lower 32-bits
     and zero-extended.
 3. All three are 2-in 1-out instructions.
@@ -82,11 +82,11 @@ add shift-and-add.  Replaces a pair of explicit instructions in hot-loops.
     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
+5. `saddw` is often more useful than `sadduw` 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>.
 6. Even Motorola 68000 has LD/ST-Indexed-Shifted <https://tack.sourceforge.net/olddocs/m68020.html#2.2.2.%20Extra%20MC68020%20addressing%20modes>
-7.  should average-add also be included? what about CA?
+7.  should average-shift-add also be included? what about CA-in / CA-out?
 
 **Changes**
 
@@ -129,67 +129,67 @@ in EXT2xx.
 
 |  0-5  | 6-10 | 11-15 | 16-20 | 21-22 | 23-31 | Instruction          |
 |-------|------|-------|-------|-------|-------|----------------------|
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | lbzsx RT,RA,RB,sm    |
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | lhzsx RT,RA,RB,sm    |
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | lhasx RT,RA,RB,sm    |
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | lwzsx RT,RA,RB,sm    |
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | lwasx RT,RA,RB,sm    |
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | ldsx RT,RA,RB,sm     |
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | lhbrsx RT,RA,RB,sm   |
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | lwbrsx RT,RA,RB,sm   |
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | ldbrsx RT,RA,RB,sm   |
-|  PO   | RS   |  RA   |  RB   |  sm   |  XO   | stbsx RS,RA,RB,sm    |
-|  PO   | RS   |  RA   |  RB   |  sm   |  XO   | sthsx RS,RA,RB,sm    |
-|  PO   | RS   |  RA   |  RB   |  sm   |  XO   | stwsx RS,RA,RB,sm    |
-|  PO   | RS   |  RA   |  RB   |  sm   |  XO   | stdsx RS,RA,RB,sm    |
-|  PO   | RS   |  RA   |  RB   |  sm   |  XO   | sthbrsx RS,RA,RB,sm  |
-|  PO   | RS   |  RA   |  RB   |  sm   |  XO   | stwbrsx RS,RA,RB,sm  |
-|  PO   | RS   |  RA   |  RB   |  sm   |  XO   | stdbrsx RS,RA,RB,sm  |
-|  PO   | FRT  |  RA   |  RB   |  sm   |  XO   | lfsxs FRT,RA,RB,sm   |
-|  PO   | FRT  |  RA   |  RB   |  sm   |  XO   | lfdxs FRT,RA,RB,sm   |
-|  PO   | FRT  |  RA   |  RB   |  sm   |  XO   | lfiwaxs FRT,RA,RB,sm |
-|  PO   | FRT  |  RA   |  RB   |  sm   |  XO   | lfiwzxs FRT,RA,RB,sm |
-|  PO   | FRS  |  RA   |  RB   |  sm   |  XO   | stfsxs FRS,RA,RB,sm  |
-|  PO   | FRS  |  RA   |  RB   |  sm   |  XO   | stfdxs FRS,RA,RB,sm  |
-|  PO   | FRS  |  RA   |  RB   |  sm   |  XO   | stfiwxs FRS,RA,RB,sm |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | lbzsx RT,RA,RB,SH    |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | lhzsx RT,RA,RB,SH    |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | lhasx RT,RA,RB,SH    |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | lwzsx RT,RA,RB,SH    |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | lwasx RT,RA,RB,SH    |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | ldsx RT,RA,RB,SH     |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | lhbrsx RT,RA,RB,SH   |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | lwbrsx RT,RA,RB,SH   |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | ldbrsx RT,RA,RB,SH   |
+|  PO   | RS   |  RA   |  RB   |  SH   |  XO   | stbsx RS,RA,RB,SH    |
+|  PO   | RS   |  RA   |  RB   |  SH   |  XO   | sthsx RS,RA,RB,SH    |
+|  PO   | RS   |  RA   |  RB   |  SH   |  XO   | stwsx RS,RA,RB,SH    |
+|  PO   | RS   |  RA   |  RB   |  SH   |  XO   | stdsx RS,RA,RB,SH    |
+|  PO   | RS   |  RA   |  RB   |  SH   |  XO   | sthbrsx RS,RA,RB,SH  |
+|  PO   | RS   |  RA   |  RB   |  SH   |  XO   | stwbrsx RS,RA,RB,SH  |
+|  PO   | RS   |  RA   |  RB   |  SH   |  XO   | stdbrsx RS,RA,RB,SH  |
+|  PO   | FRT  |  RA   |  RB   |  SH   |  XO   | lfsxs FRT,RA,RB,SH   |
+|  PO   | FRT  |  RA   |  RB   |  SH   |  XO   | lfdxs FRT,RA,RB,SH   |
+|  PO   | FRT  |  RA   |  RB   |  SH   |  XO   | lfiwaxs FRT,RA,RB,SH |
+|  PO   | FRT  |  RA   |  RB   |  SH   |  XO   | lfiwzxs FRT,RA,RB,SH |
+|  PO   | FRS  |  RA   |  RB   |  SH   |  XO   | stfsxs FRS,RA,RB,SH  |
+|  PO   | FRS  |  RA   |  RB   |  SH   |  XO   | stfdxs FRS,RA,RB,SH  |
+|  PO   | FRS  |  RA   |  RB   |  SH   |  XO   | stfiwxs FRS,RA,RB,SH |
 
 **LD/ST-Shifted-Update**
 
 |  0-5  | 6-10 | 11-15 | 16-20 | 21-22 | 23-31 | Instruction          |
 |-------|------|-------|-------|-------|-------|----------------------|
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | lbzusx RT,RA,RB,sm   |
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | lhzusx RT,RA,RB,sm   |
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | lhausx RT,RA,RB,sm   |
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | lwzusx RT,RA,RB,sm   |
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | lwausx RT,RA,RB,sm   |
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | ldusx RT,RA,RB,sm    |
-|  PO   | RS   |  RA   |  RB   |  sm   |  XO   | stbusx RS,RA,RB,sm   |
-|  PO   | RS   |  RA   |  RB   |  sm   |  XO   | sthusx RS,RA,RB,sm   |
-|  PO   | RS   |  RA   |  RB   |  sm   |  XO   | stwusx RS,RA,RB,sm   |
-|  PO   | RS   |  RA   |  RB   |  sm   |  XO   | stdusx RS,RA,RB,sm   |
-|  PO   | FRT  |  RA   |  RB   |  sm   |  XO   | lfsuxs FRT,RA,RB,sm  |
-|  PO   | FRT  |  RA   |  RB   |  sm   |  XO   | lfduxs FRT,RA,RB,sm  |
-|  PO   | FRS  |  RA   |  RB   |  sm   |  XO   | stfsuxs FRS,RA,RB,sm |
-|  PO   | FRS  |  RA   |  RB   |  sm   |  XO   | stfduxs FRS,RA,RB,sm |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | lbzusx RT,RA,RB,SH   |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | lhzusx RT,RA,RB,SH   |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | lhausx RT,RA,RB,SH   |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | lwzusx RT,RA,RB,SH   |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | lwausx RT,RA,RB,SH   |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | ldusx RT,RA,RB,SH    |
+|  PO   | RS   |  RA   |  RB   |  SH   |  XO   | stbusx RS,RA,RB,SH   |
+|  PO   | RS   |  RA   |  RB   |  SH   |  XO   | sthusx RS,RA,RB,SH   |
+|  PO   | RS   |  RA   |  RB   |  SH   |  XO   | stwusx RS,RA,RB,SH   |
+|  PO   | RS   |  RA   |  RB   |  SH   |  XO   | stdusx RS,RA,RB,SH   |
+|  PO   | FRT  |  RA   |  RB   |  SH   |  XO   | lfsuxs FRT,RA,RB,SH  |
+|  PO   | FRT  |  RA   |  RB   |  SH   |  XO   | lfduxs FRT,RA,RB,SH  |
+|  PO   | FRS  |  RA   |  RB   |  SH   |  XO   | stfsuxs FRS,RA,RB,SH |
+|  PO   | FRS  |  RA   |  RB   |  SH   |  XO   | stfduxs FRS,RA,RB,SH |
 
 **Post-Increment-Update LD/ST-Shifted**
 
 |  0-5  | 6-10 | 11-15 | 16-20 | 21-22 | 23-31 | Instruction          |
 |-------|------|-------|-------|-------|-------|----------------------|
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | lbzuspx RT,RA,RB,sm   |
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | lhzuspx RT,RA,RB,sm   |
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | lhauspx RT,RA,RB,sm   |
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | lwzuspx RT,RA,RB,sm   |
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | lwauspx RT,RA,RB,sm   |
-|  PO   | RS   |  RA   |  RB   |  sm   |  XO   | stbuspx RS,RA,RB,sm   |
-|  PO   | RS   |  RA   |  RB   |  sm   |  XO   | sthuspx RS,RA,RB,sm   |
-|  PO   | RS   |  RA   |  RB   |  sm   |  XO   | stwuspx RS,RA,RB,sm   |
-|  PO   | RS   |  RA   |  RB   |  sm   |  XO   | stduspx RS,RA,RB,sm   |
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | lduspx RT,RA,RB,sm   |
-|  PO   | FRT  |  RA   |  RB   |  sm   |  XO   | lfdupxs FRT,RA,RB,sm  |
-|  PO   | FRT  |  RA   |  RB   |  sm   |  XO   | lfsupxs FRT,RA,RB,sm  |
-|  PO   | FRS  |  RA   |  RB   |  sm   |  XO   | stfdupxs FRS,RA,RB,sm |
-|  PO   | FRS  |  RA   |  RB   |  sm   |  XO   | stfsupxs FRS,RA,RB,sm |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | lbzuspx RT,RA,RB,SH   |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | lhzuspx RT,RA,RB,SH   |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | lhauspx RT,RA,RB,SH   |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | lwzuspx RT,RA,RB,SH   |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | lwauspx RT,RA,RB,SH   |
+|  PO   | RS   |  RA   |  RB   |  SH   |  XO   | stbuspx RS,RA,RB,SH   |
+|  PO   | RS   |  RA   |  RB   |  SH   |  XO   | sthuspx RS,RA,RB,SH   |
+|  PO   | RS   |  RA   |  RB   |  SH   |  XO   | stwuspx RS,RA,RB,SH   |
+|  PO   | RS   |  RA   |  RB   |  SH   |  XO   | stduspx RS,RA,RB,SH   |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | lduspx RT,RA,RB,SH   |
+|  PO   | FRT  |  RA   |  RB   |  SH   |  XO   | lfdupxs FRT,RA,RB,SH  |
+|  PO   | FRT  |  RA   |  RB   |  SH   |  XO   | lfsupxs FRT,RA,RB,SH  |
+|  PO   | FRS  |  RA   |  RB   |  SH   |  XO   | stfdupxs FRS,RA,RB,SH |
+|  PO   | FRS  |  RA   |  RB   |  SH   |  XO   | stfsupxs FRS,RA,RB,SH |
 
 ----------------
 
@@ -197,56 +197,56 @@ in EXT2xx.
 
 # Shift-and-Add
 
-`shadd RT, RA, RB, sm`
+`sadd RT, RA, RB, SH`
 
 |  0-5  | 6-10 | 11-15 | 16-20 | 21-22 | 23-30 | 31 | Form     |
 |-------|------|-------|-------|-------|-------|----|----------|
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | Rc | Z23-Form |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | Rc | Z23-Form |
 
 Pseudocode:
 
 ```
-    shift <- sm + 1                     # Shift is between 1-4
+    shift <- SH + 1                     # Shift is between 1-4
     sum[0:63] <- ((RB) << shift) + (RA) # Shift RB, add RA
     RT <- sum                           # Result stored in RT
 ```
 
-When `sm` is zero, the contents of register RB are multiplied by 2,
+When `SH` is zero, the 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.
+`SH` 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, unsigned integers.
 
-**NEED EXAMPLES (not sure how to embed sm)!!!**
+**NEED EXAMPLES (not sure how to embed SH)!!!**
 Examples:
 
 ```
     # adds r1 to (r2*8)
-    shadd r4, r1, r2, 3
+    sadd r4, r1, r2, 3
 ```
 
 # Shift-and-Add Signed Word
 
-`shaddw RT, RA, RB, sm`
+`saddw RT, RA, RB, SH`
 
 |  0-5  | 6-10 | 11-15 | 16-20 | 21-22 | 23-30 | 31 | Form     |
 |-------|------|-------|-------|-------|-------|----|----------|
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | Rc | Z23-Form |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | Rc | Z23-Form |
 
 Pseudocode:
 
 ```
-    shift <- sm + 1                  # Shift is between 1-4
+    shift <- SH + 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,
+When `SH` 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.
+`SH` 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.
 
@@ -258,7 +258,7 @@ Examples:
 
 ```
 # r4 = r1 + (r2*16)
-shaddw r4, r1, r2, 3
+saddw r4, r1, r2, 3
 ```
 
 ----------------
@@ -268,25 +268,25 @@ shaddw r4, r1, r2, 3
 
 # Shift-and-Add Unsigned Word
 
-`shadduw RT, RA, RB, sm`
+`sadduw RT, RA, RB, SH`
 
 |  0-5  | 6-10 | 11-15 | 16-20 | 21-22 | 23-30 | 31 | Form     |
 |-------|------|-------|-------|-------|-------|----|----------|
-|  PO   | RT   |  RA   |  RB   |  sm   |  XO   | Rc | Z23-Form |
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | Rc | Z23-Form |
 
 Pseudocode:
 
 ```
-    shift <- sm + 1                  # Shift is between 1-4
+    shift <- SH + 1                  # Shift is between 1-4
     n <- (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,
+When `SH` 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.
+`SH` 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, unsigned integers.
 
@@ -298,7 +298,31 @@ Examples:
 
 ```
 #
-shadduw r4, r1, r2, 2
+sadduw r4, r1, r2, 2
+```
+
+# Instruction Formats
+
+**Add the following to Book I 1.6.1**
+
+Z23-Form:
+
+```
+|  0-5  | 6-10 | 11-15 | 16-20 | 21-22 | 23-30 | 31 | Form     |
+|-------|------|-------|-------|-------|-------|----|----------|
+|  PO   | RT   |  RA   |  RB   |  SH   |  XO   | Rc | Z23-Form |
+```
+
+# Instruction Fields
+
+Add Z23 to the following Formats in Book I 1.6.2: `RT RA RB XO Rc`
+
+Add the following new fields:
+
+```
+    SH (21:22)
+        Field used to specify a shift amount.
+        Formats: Z23
 ```
 
 # Appendices
@@ -310,9 +334,9 @@ shadduw r4, r1, r2, 2
 
 | 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 |
+| Z23  | I    | #    | 3.0B    | sadd    | Shift-and-Add |
+| Z23  | I    | #    | 3.0B    | saddw   | Shift-and-Add Signed Word |
+| Z23  | I    | #    | 3.0B    | sadduw  | Shift-and-Add Unsigned Word |
 
 [[!tag opf_rfc]]