From: Alain D D Williams <addw@phcomp.co.uk>
Date: Tue, 30 Mar 2021 17:26:25 +0000 (+0100)
Subject: Add comments to the markdown
X-Git-Tag: DRAFT_SVP64_0_1~1088
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=48229602bed6f07211378f04ea3fe90ed6b39813;p=libreriscv.git

Add comments to the markdown
Some more work is needed
---

diff --git a/openpower/isa/bcd.mdwn b/openpower/isa/bcd.mdwn
index c34561f26..30bb16190 100644
--- a/openpower/isa/bcd.mdwn
+++ b/openpower/isa/bcd.mdwn
@@ -1,3 +1,12 @@
+<!-- Instructions here described in PowerISA Version 3.0 B Book 1 -->
+
+<!-- Section 3.3.15 Binary Coded Decimal (BCD) Assist Instructions. Page 111 -->
+
+<!-- The Binary Coded Decimal Assist instructions operate on Binary Coded Decimal -->
+<!-- operands (cbcdtd and addg6s) and Decimal Floating-Point operands (cdtbcd) -->
+<!-- See Chapter 5. for additional information. -->
+
+
 # Convert Declets To Binary Coded Decimal
 
 X-Form
@@ -54,3 +63,4 @@ Special Registers Altered:
 
     None
 
+<!-- Checked March 2021 -->
diff --git a/openpower/isa/branch.mdwn b/openpower/isa/branch.mdwn
index ff09f6a5e..5867ea872 100644
--- a/openpower/isa/branch.mdwn
+++ b/openpower/isa/branch.mdwn
@@ -1,3 +1,25 @@
+<!-- Instructions here described in PowerISA Version 3.0 B Book 1 -->
+
+<!-- Section 2.4 Branch Instructions. Pages 33 - 39 -->
+
+<!-- The sequence of instruction execution can be changed by the Branch -->
+<!-- instructions. Because all instructions are on word boundaries, bits 62 and 63 -->
+<!-- of the generated branch target address are ignored by the processor in -->
+<!-- performing the branch. -->
+
+<!-- target_addr specifies the branch target address. -->
+
+<!-- If AA=0 then the branch target address is the sum of LI || 0b00 sign-extended -->
+<!-- and the address of this instruction, with the high-order 32 bits of the branch -->
+<!-- target address set to 0 in 32-bit mode. -->
+
+<!-- If AA=1 then the branch target address is the value LI || 0b00 sign-extended, -->
+<!-- with the high-order 32 bits of the branch target address set to 0 in 32-bit -->
+<!-- mode. -->
+
+<!-- If LK=1 then the effective address of the instruction following the Branch -->
+<!-- instruction is placed into the Link Register. -->
+
 # Branch
 
 I-Form
@@ -103,3 +125,6 @@ Special Registers Altered:
 
     CTR                    (if BO2=0)
     LR                       (if LK=1)
+
+
+<!-- Checked March 2021 -->
diff --git a/openpower/isa/comparefixed.mdwn b/openpower/isa/comparefixed.mdwn
index ffa1b58b3..e1a365f2a 100644
--- a/openpower/isa/comparefixed.mdwn
+++ b/openpower/isa/comparefixed.mdwn
@@ -1,3 +1,12 @@
+<!-- Instructions here described in PowerISA Version 3.0 B Book 1 -->
+
+<!-- Section 3.3.10 Fixed-Point Compare Instructions Pages 84 - 88 -->
+
+<!-- The fixed-point Compare instructions compare the contents of register RA with -->
+<!-- (1) the sign-extended value of the SI field, (2) the zero-extended value of the -->
+<!-- UI field, or (3) the contents of register RB. The comparison is signed for cmpi -->
+<!-- and cmp, and unsigned for cmpli and cmpl. -->
+
 # Compare Immediate
 
 D-Form
@@ -136,3 +145,4 @@ Special Registers Altered:
 
     CR field BF
 
+<!-- Checked March 2021 -->
diff --git a/openpower/isa/condition.mdwn b/openpower/isa/condition.mdwn
index 6dd831d42..5cef0675a 100644
--- a/openpower/isa/condition.mdwn
+++ b/openpower/isa/condition.mdwn
@@ -1,3 +1,15 @@
+<!-- Instructions here described in PowerISA Version 3.0 B Book 1 -->
+
+<!-- Section 2.5.1 Condition Register Logical Instructions Pages 40 - 41 -->
+
+<!-- The Condition Register Logical instructions have preferred forms; see Section -->
+<!-- 1.9.1. -->
+
+<!-- In the preferred forms, the BT and BB fields satisfy the following rule: -->
+
+<!-- * The bit specified by BT is in the same Condition Register field as the bit -->
+<!-- specified by BB. -->
+
 # Condition Register AND
 
 XL-Form
@@ -124,3 +136,4 @@ Special Registers Altered:
 
     CR field BF
 
+<!-- Checked March 2021 -->
diff --git a/openpower/isa/fixedarith.mdwn b/openpower/isa/fixedarith.mdwn
index 9fd56d5db..470a833ca 100644
--- a/openpower/isa/fixedarith.mdwn
+++ b/openpower/isa/fixedarith.mdwn
@@ -1,3 +1,7 @@
+<!-- X Instructions here described in PowerISA Version 3.0 B Book 1 -->
+
+<!-- Section 3.3.9 Fixed-point arithmetic instructions. Pages 67 - 83 -->
+
 # Add Immediate
 
 D-Form
@@ -812,3 +816,4 @@ Special Registers Altered:
 
     None
 
+<!-- Checked March 2021 -->
diff --git a/openpower/isa/fixedldstcache.mdwn b/openpower/isa/fixedldstcache.mdwn
index 0a34d582b..8215ec144 100644
--- a/openpower/isa/fixedldstcache.mdwn
+++ b/openpower/isa/fixedldstcache.mdwn
@@ -1,3 +1,14 @@
+<!-- Instructions here described in PowerISA Version 3.0 B Book 1 -->
+
+<!-- Section 4.4.1 Fixed-Point Load and Store Caching Inhibited Instructions. Pages 965 - 967 -->
+
+<!-- The storage accesses caused by the instructions described in this section are -->
+<!-- performed as though the specified storage location is Caching Inhibited and -->
+<!-- Guarded. The instructions can be executed only in hypervisor state. Software -->
+<!-- must ensure that the specified storage location is not in the caches. If the -->
+<!-- specified storage location is in a cache, the results are undefined. -->
+
+
 # Load Byte and Zero Caching Inhibited Indexed
 
 X-Form
@@ -126,3 +137,4 @@ Special Registers Altered:
 
     None
 
+<!-- Checked March 2021 -->
diff --git a/openpower/isa/fixedload.mdwn b/openpower/isa/fixedload.mdwn
index 214149c1f..5a64265a8 100644
--- a/openpower/isa/fixedload.mdwn
+++ b/openpower/isa/fixedload.mdwn
@@ -1,3 +1,31 @@
+<!-- This defines instructions described in PowerISA Version 3.0 B Book 1 -->
+
+<!-- This defines instructions that load from RAM to a register -->
+
+<!-- Note that these pages also define equivalent store instructions, -->
+<!-- these are described in fixedstore.mdwn -->
+
+<!-- Section 3.3.2 This defines the Fixed-Point Load Instructions pages 47 - 53 -->
+<!-- Section 3.3.3 Fixed-Point Store Instructions pages 54 - 56 -->
+<!-- Section 3.3.3.1 64-bit Fixed-Point Store Instructions pages 57 -->
+<!-- Section 3.3.4 Fixed Point Load and Store Quadword Instructions pages 58 - 59 -->
+<!-- Section 3.3.5 Fixed-Point Load and Store with Byte Reversal Instructions page 60 -->
+<!-- Section 3.3.5.1 64-Bit Load and Store with Byte Reversal Instructions page 61 -->
+<!-- Section 3.3.6 Fixed-Point Load and Store Multiple Instructions page 62 -->
+
+
+
+<!-- Section 3.3.2 This defines the Fixed-Point Load Instructions pages 47 - 53 -->
+
+<!-- The byte, halfword, word, or doubleword in storage addressed by EA is loaded -->
+<!-- into register RT. -->
+
+<!-- Many of the Load instructions have an “update” form, in which register RA is -->
+<!-- updated with the effective address. For these forms, if RA!=0 and RA!=RT, the -->
+<!-- effective address is placed into register RA and the storage element (byte, -->
+<!-- halfword, word, or doubleword) addressed by EA is loaded into RT. -->
+
+
 # Load Byte and Zero
 
 D-Form
@@ -366,6 +394,31 @@ Special Registers Altered:
 
     None
 
+<!-- Section 3.3.3 Fixed-Point Store Instructions pages 54 - 56 -->
+
+<!-- The contents of register RS are stored into the byte, halfword, word, or -->
+<!-- doubleword in storage addressed by EA. -->
+
+<!-- Many of the Store instructions have an “update” form, in which register RA is -->
+<!-- updated with the effective address. For these forms, the following rules apply. -->
+
+<!-- If RA!=0, the effective address is placed into register RA. -->
+
+<!-- If RS=RA, the contents of register RS are copied to the target storage element -->
+<!-- and then EA is placed into RA (RS). -->
+
+<!-- Section 3.3.3.1 64-bit Fixed-Point Store Instructions pages 57 -->
+
+<!-- Section 3.3.4 Fixed Point Load and Store Quadword Instructions pages 58 - 59 -->
+
+<!-- For lq, the quadword in storage addressed by EA is loaded into an even-odd pair -->
+<!-- of GPRs as follows. In Big-Endian mode, the even-numbered GPR is loaded with -->
+<!-- the doubleword from storage addressed by EA and the odd-numbered GPR is loaded -->
+<!-- with the doubleword addressed by EA+8. In Little-Endian mode, the even-numbered -->
+<!-- GPR is loaded with the byte-reversed doubleword from storage addressed by EA+8 -->
+<!-- and the odd-numbered GPR is loaded with the byte-reversed doubleword addressed -->
+<!-- by EA. -->
+
 # Load Quadword
 
 DQ-Form
@@ -382,6 +435,10 @@ Special Registers Altered:
 
     None
 
+<!-- MISSING stq -->
+
+<!-- Section 3.3.5 Fixed-Point Load and Store with Byte Reversal Instructions page 60 -->
+
 # Load Halfword Byte-Reverse Indexed
 
 X-Form
@@ -399,6 +456,8 @@ Special Registers Altered:
 
     None
 
+<!-- MISSING sthbrx -->
+
 # Load Word Byte-Reverse Indexed
 
 X-Form
@@ -417,6 +476,11 @@ Special Registers Altered:
 
     None
 
+<!-- MISSING stwbrx -->
+
+
+<!-- Section 3.3.5.1 64-Bit Load and Store with Byte Reversal Instructions page 61 -->
+
 # Load Doubleword Byte-Reverse Indexed
 
 X-Form
@@ -437,6 +501,10 @@ Special Registers Altered:
 
     None
 
+<!-- MISSING stdbrx -->
+
+<!-- Section 3.3.6 Fixed-Point Load and Store Multiple Instructions page 62 -->
+
 # Load Multiple Word
 
 DQ-Form
@@ -456,3 +524,7 @@ Pseudo-code:
 Special Registers Altered:
 
     None
+
+<!-- MISSING stmw -->
+
+
diff --git a/openpower/isa/fixedlogical.mdwn b/openpower/isa/fixedlogical.mdwn
index 13fdf8d39..99d550566 100644
--- a/openpower/isa/fixedlogical.mdwn
+++ b/openpower/isa/fixedlogical.mdwn
@@ -1,3 +1,15 @@
+<!-- This defines instructions described in PowerISA Version 3.0 B Book 1 -->
+
+<!-- Section 3.3.13 Fixed-Point Logical Instructions page 92 - 100 -->
+
+<!-- The Logical instructions perform bit-parallel operations on 64-bit operands. -->
+
+<!-- The X-form Logical instructions with Rc=1, and the D-form Logical instructions -->
+<!-- andi. and andis., set the first three bits of CR Field 0 as described in -->
+<!-- Section 3.3.8, “Other Fixed-Point Instructions” on page 66. The Logical -->
+<!-- instructions do not change the SO, OV, OV32, CA, and CA32 bits in the XER. -->
+
+
 # AND Immediate
 
 D-Form
@@ -466,3 +478,4 @@ Special Registers Altered:
 
     None
 
+<!-- Checked March 2021 -->
diff --git a/openpower/isa/fixedshift.mdwn b/openpower/isa/fixedshift.mdwn
index d35b7d1f6..58d3ea70b 100644
--- a/openpower/isa/fixedshift.mdwn
+++ b/openpower/isa/fixedshift.mdwn
@@ -1,3 +1,15 @@
+<!-- This defines instructions described in PowerISA Version 3.0 B Book 1 -->
+
+<!-- Section 3.3.14 Fixed-Point Rotate and Shift Instructions pages 101 - 110 -->
+<!-- Section 3.3.14.1 Fixed-Point Rotate Instructions pages 101 - 106 -->
+<!-- Section 3.3.14.2 Fixed-Point Shift Instructions pages 107 - 110 -->
+
+<!-- The Fixed-Point Facility performs rotation operations on data from a GPR and -->
+<!-- returns the result, or a portion of the result, to a GPR. -->
+
+
+<!-- Section 3.3.14.1 Fixed-Point Rotate Instructions pages 101 - 106 -->
+
 # Rotate Left Word Immediate then AND with Mask
 
 M-Form
@@ -167,6 +179,8 @@ Special Registers Altered:
     CR0                    (if Rc=1)
 
 
+<!-- Section 3.3.14.2 Fixed-Point Shift Instructions pages 107 - 110 -->
+
 # Shift Left Word
 
 X-Form
@@ -361,3 +375,4 @@ Special Registers Altered:
 
     CR0                     (if Rc=1)
 
+<!-- Checked March 2021 -->
diff --git a/openpower/isa/fixedstore.mdwn b/openpower/isa/fixedstore.mdwn
index 1a8fe1152..ce64d4b91 100644
--- a/openpower/isa/fixedstore.mdwn
+++ b/openpower/isa/fixedstore.mdwn
@@ -1,3 +1,28 @@
+<!-- This defines instructions described in PowerISA Version 3.0 B Book 1 -->
+
+<!-- This defines instructions that store from a register to RAM -->
+
+<!-- Note that these pages also define equivalent load instructions, -->
+<!-- these are described in fixedload.mdwn -->
+
+<!-- Section 3.3.3 Fixed-Point Store Instructions pages 54 - 57 -->
+<!-- Section 3.3.3.1 64-bit Fixed-Point Store Instructions page 57 -->
+<!-- Section 3.3.4 Fixed Point Load and Store Quadword Instructions pages 58 - 59 -->
+<!-- Section 3.3.5 Fixed-Point Load and Store with Byte Reversal Instructions page 60 -->
+<!-- Section 3.3.5.1 64-Bit Load and Store with Byte Reversal Instructions page 61 -->
+<!-- Section 3.3.6 Fixed-Point Load and Store Multiple Instructions page 62 -->
+
+<!-- MISSING stbh -->
+<!-- MISSING stbhx -->
+<!-- MISSING stbhu -->
+<!-- MISSING stbhux -->
+<!-- MISSING stbw -->
+<!-- MISSING stbwx -->
+<!-- MISSING stbwu -->
+<!-- MISSING stbwux -->
+
+<!-- Section 3.3.3 Fixed-Point Store Instructions pages 54 - 57 -->
+
 # Store Byte
 
 D-Form
@@ -190,6 +215,10 @@ Special Registers Altered:
 
     None
 
+
+
+<!-- Section 3.3.3.1 64-bit Fixed-Point Store Instructions page 57 -->
+
 # Store Doubleword
 
 DS-Form
@@ -254,6 +283,18 @@ Special Registers Altered:
 
     None
 
+
+<!-- Section 3.3.4 Fixed Point Load and Store Quadword Instructions pages 58 - 59 -->
+
+<!-- For stq, the contents of an even-odd pair of GPRs is stored into the quadword -->
+<!-- in storage addressed by EA as follows. In Big-Endian mode, the even-numbered -->
+<!-- GPR is stored into the doubleword in storage addressed by EA and the -->
+<!-- odd-numbered GPR is stored into the doubleword addressed by EA+8. In -->
+<!-- Little-Endian mode, the even-numbered GPR is stored byte-reversed into the -->
+<!-- doubleword in storage addressed by EA+8 and the odd-numbered GPR is stored -->
+<!-- byte-reversed into the doubleword addressed by EA. -->
+
+
 # Store Quadword
 
 DS-Form
@@ -270,6 +311,8 @@ Special Registers Altered:
 
     None
 
+<!-- Section 3.3.5 Fixed-Point Load and Store with Byte Reversal Instructions page 60 -->
+
 # Store Halfword Byte-Reverse Indexed
 
 X-Form
@@ -303,6 +346,8 @@ Special Registers Altered:
 
     None
 
+<!-- Section 3.3.5.1 64-Bit Load and Store with Byte Reversal Instructions page 61 -->
+
 # Store Doubleword Byte-Reverse Indexed
 
 X-Form
@@ -322,6 +367,9 @@ Special Registers Altered:
 
     None
 
+
+<!-- Section 3.3.6 Fixed-Point Load and Store Multiple Instructions page 62 -->
+
 # Store Multiple Word
 
 D-Form
@@ -342,3 +390,4 @@ Special Registers Altered:
 
     None
 
+<!-- Checked March 2021 -->
diff --git a/openpower/isa/fixedtrap.mdwn b/openpower/isa/fixedtrap.mdwn
index fe1e97a83..34a0184ce 100644
--- a/openpower/isa/fixedtrap.mdwn
+++ b/openpower/isa/fixedtrap.mdwn
@@ -1,3 +1,12 @@
+<!-- This defines instructions described in PowerISA Version 3.0 B Book 1 -->
+
+<!-- Section 3.3.11 Fixed-Point Trap Instructions pages 89 - 91 -->
+
+<!-- The Trap instructions are provided to test for a specified set of conditions. -->
+<!-- If any of the conditions tested by a Trap instruction are met, the system trap -->
+<!-- handler is invoked. If none of the tested conditions are met, instruction -->
+<!-- execution continues normally. -->
+
 # Trap Word Immediate
 
 D-Form
@@ -92,3 +101,4 @@ Special Registers Altered:
 
     None
 
+<!-- Checked March 2021 -->
diff --git a/openpower/isa/simplev.mdwn b/openpower/isa/simplev.mdwn
index 350a2e89f..e2482b374 100644
--- a/openpower/isa/simplev.mdwn
+++ b/openpower/isa/simplev.mdwn
@@ -1,3 +1,7 @@
+<!-- This defines instructions described in PowerISA Version 3.0 B Book 1 -->
+
+<!-- These are not described in book 1 -->
+
 # setvl
 
 SVL-Form
diff --git a/openpower/isa/sprset.mdwn b/openpower/isa/sprset.mdwn
index 4048641a5..ab1ace714 100644
--- a/openpower/isa/sprset.mdwn
+++ b/openpower/isa/sprset.mdwn
@@ -1,3 +1,32 @@
+<!-- This defines instructions described in PowerISA Version 3.0 B Book 1 -->
+
+<!-- Section 4.4.4 Move To/From System Register Instructions pages 970 - 1038 -->
+
+<!-- Section 4.4.4 Move To/From System Register Instructions pages 970 - 1038 -->
+<!-- Section 3.3.17 Move To/From System Register Instructions Page 120 -->
+<!-- Section 4.3.2 Data Cache Instructions Page 850 -->
+
+<!-- This needs checking again -->
+
+<!-- The Move To Special Purpose Register and Move From Special Purpose Register -->
+<!-- instructions are described in Book I, but only at the level available to an -->
+<!-- application programmer. For example, no mention is made there of registers that -->
+<!-- can be accessed only in privileged state. The descriptions of these instructions -->
+<!-- given below extend the descriptions given in Book I, but do not list Special -->
+<!-- Purpose Registers that are implementation-dependent. In the descriptions of -->
+<!-- these instructions given in below, the “defined” SPR numbers are the SPR -->
+<!-- numbers shown in the Figure 18 for the instruction and the -->
+<!-- implementation-specific SPR numbers that are implemented, and similarly for -->
+<!-- “defined” registers. All other SPR numbers are undefined for the instruction. -->
+<!-- (Implementation-specific SPR numbers that are not implemented are considered to -->
+<!-- be undefined.) When an SPR is defined for mtspr and undefined for mfspr, or -->
+<!-- vice versa, a hyphen appears in the column for the instruction for which the -->
+<!-- SPR number is undefined. -->
+
+
+
+<!-- Page 974 -->
+
 # Move To Special Purpose Register
 
 XFX-Form
@@ -20,6 +49,8 @@ Special Registers Altered:
 
     See spec 3.3.17
 
+<!-- Page 975 -->
+
 # Move From Special Purpose Register
 
 XFX-Form
@@ -42,6 +73,8 @@ Special Registers Altered:
 
     None
 
+<!-- Section 3.3.17 Move To/From System Register Instructions Page 120 -->
+
 # Move to CR from XER Extended
 
 X-Form
@@ -142,6 +175,8 @@ Special Registers Altered:
 
     None
 
+<!-- Out of order from the PDF. Page 977 -->
+
 # Move To Machine State Register
 
 X-Form
@@ -210,6 +245,8 @@ Special Registers Altered:
 
     None
 
+<!-- Section 4.3.2 Data Cache Instructions Page 850 -->
+
 # Data Cache Block set to Zero
 
 X-Form
@@ -226,6 +263,8 @@ Special Registers Altered:
 
     None
 
+<!-- Section 5.9.3.3 TLB Management Instructions Page 1033 -->
+
 # TLB Invalidate Entry
 
 X-Form
@@ -240,3 +279,5 @@ Special Registers Altered:
 
     None
 
+<!-- MISSING tlbiel page 1038 -->
+<!-- MISSING tlbsync page 1042 -->
diff --git a/openpower/isa/stringldst.mdwn b/openpower/isa/stringldst.mdwn
index 04723e2e1..6357c4e10 100644
--- a/openpower/isa/stringldst.mdwn
+++ b/openpower/isa/stringldst.mdwn
@@ -1,3 +1,13 @@
+<!-- Instructions here described in PowerISA Version 3.0 B Book 1 -->
+
+<!-- Section 3.3.7 Fixed-Point Move Assist Instructions [Phased Out] pages 63 - 65 -->
+
+<!-- The Move Assist instructions allow movement of an arbitrary sequence of bytes -->
+<!-- from storage to registers or from registers to storage without concern for -->
+<!-- alignment. These instructions can be used for a short move between arbitrary -->
+<!-- storage locations or to initiate a long move between unaligned storage fields. -->
+
+
 # Load String Word Immediate
 
 X-Form
@@ -103,3 +113,4 @@ Special Registers Altered:
 
     None
 
+<!-- Checked March 2021 -->
diff --git a/openpower/isa/system.mdwn b/openpower/isa/system.mdwn
index df853c143..74f06c50b 100644
--- a/openpower/isa/system.mdwn
+++ b/openpower/isa/system.mdwn
@@ -1,3 +1,9 @@
+<!-- Instructions here described in PowerISA Version 3.0 B Book 1 -->
+
+<!-- 3.3.1 System Linkage Instructions Page 952 - 956 -->
+
+<!-- These instructions provide the means by which a program can call upon the system to perform a service. -->
+
 # System Call
 
 SC-Form
@@ -118,3 +124,4 @@ Special Registers Altered:
 
     MSR
 
+<!-- Checked March 2021 -->