reformat SVP64 docstrings to vaguely resemble something useful in sphinx-doc
authorLuke Kenneth Casson Leighton <lkcl@lkcl.net>
Thu, 6 May 2021 13:36:45 +0000 (14:36 +0100)
committerLuke Kenneth Casson Leighton <lkcl@lkcl.net>
Thu, 6 May 2021 13:36:45 +0000 (14:36 +0100)
conf.py
src/openpower/test/alu/svp64_cases.py
src/openpower/test/logical/svp64_cases.py

diff --git a/conf.py b/conf.py
index 76f3c2297d11defda12efe701a675b4d19459684..40879253170bcb01a029b76b3a64669a5e59b4dd 100644 (file)
--- a/conf.py
+++ b/conf.py
@@ -43,7 +43,7 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
-    #'sphinx.ext.napoleon',
+    'sphinx.ext.napoleon',
     'sphinx.ext.coverage',
     'recommonmark',
     #'symbolator_sphinx',
index 7867ef153028655e88e5f48238c682bef1acd977..697ee2b883fcde0fc67417ad6716b960cd11928e 100644 (file)
@@ -9,9 +9,10 @@ class SVP64ALUTestCase(TestAccumulatorBase):
 
     def case_1_sv_add(self):
         """>>> lst = ['sv.add 1.v, 5.v, 9.v']
+
         adds:
-           1 = 5 + 9   => 0x5555 = 0x4321 + 0x1234
-           2 = 6 + 10  => 0x3334 = 0x2223 + 0x1111
+            * 1 = 5 + 9   => 0x5555 = 0x4321 + 0x1234
+            * 2 = 6 + 10  => 0x3334 = 0x2223 + 0x1111
         """
         isa = SVP64Asm(['sv.add 1.v, 5.v, 9.v'])
         lst = list(isa)
@@ -34,8 +35,9 @@ class SVP64ALUTestCase(TestAccumulatorBase):
 
     def case_2_sv_add_scalar(self):
         """>>> lst = ['sv.add 1, 5, 9']
+
         adds:
-           1 = 5 + 9   => 0x5555 = 0x4321 + 0x1234
+            * 1 = 5 + 9   => 0x5555 = 0x4321 + 0x1234
         """
         isa = SVP64Asm(['sv.add 1, 5, 9'])
         lst = list(isa)
@@ -56,8 +58,9 @@ class SVP64ALUTestCase(TestAccumulatorBase):
 
     def case_3_sv_check_extra(self):
         """>>> lst = ['sv.add 13.v, 10.v, 7.v']
+
         adds:
-            13 = 10 + 7   => 0x4242 = 0x1230 + 0x3012
+            13 = 10 + 7   => 0x4242 = 0x1230 + 0x3012
 
         This case helps checking the encoding of the Extra field
         It was built so the v3.0b registers are: 3, 2, 1
@@ -84,9 +87,10 @@ class SVP64ALUTestCase(TestAccumulatorBase):
 
     def case_4_sv_add_(self):
         """>>> lst = ['sv.add. 1.v, 5.v, 9.v']
+
         adds when Rc=1:                               TODO CRs higher up
-            1 = 5 + 9   => 0 = -1+1                 CR0=0b100
-            2 = 6 + 10  => 0x3334 = 0x2223+0x1111   CR1=0b010
+            1 = 5 + 9   => 0 = -1+1                 CR0=0b100
+            2 = 6 + 10  => 0x3334 = 0x2223+0x1111   CR1=0b010
         """
         isa = SVP64Asm(['sv.add. 1.v, 5.v, 9.v'])
         lst = list(isa)
@@ -113,8 +117,9 @@ class SVP64ALUTestCase(TestAccumulatorBase):
             'sv.add 13.v, 10.v, 7.v',  # skipped, because VL == 0
             'add 1, 5, 9'
         ]
+
         adds:
-            1 = 5 + 9   => 0x5555 = 0x4321 + 0x1234
+            1 = 5 + 9   => 0x5555 = 0x4321 + 0x1234
         """
         isa = SVP64Asm([
             'sv.add 13.v, 10.v, 7.v',  # skipped, because VL == 0
@@ -144,13 +149,14 @@ class SVP64ALUTestCase(TestAccumulatorBase):
             'sv.add 1.v, 5.v, 9.v',
             'sv.add 13.v, 10.v, 7.v'
         ]
+
         adds:
-            1 = 5 + 9   => 0x5555 = 0x4321 + 0x1234
-            2 = 6 + 10  => 0x3334 = 0x2223 + 0x1111
-            3 = 7 + 11  => 0x4242 = 0x3012 + 0x1230
-            13 = 10 + 7  => 0x2341 = 0x1111 + 0x1230
-            14 = 11 + 8  => 0x3012 = 0x3012 + 0x0000
-            15 = 12 + 9  => 0x1234 = 0x0000 + 0x1234
+            1 = 5 + 9   => 0x5555 = 0x4321 + 0x1234
+            2 = 6 + 10  => 0x3334 = 0x2223 + 0x1111
+            3 = 7 + 11  => 0x4242 = 0x3012 + 0x1230
+            13 = 10 + 7  => 0x2341 = 0x1111 + 0x1230
+            14 = 11 + 8  => 0x3012 = 0x3012 + 0x0000
+            15 = 12 + 9  => 0x1234 = 0x0000 + 0x1234
         """
         isa = SVP64Asm([
             'sv.add 1.v, 5.v, 9.v',
@@ -178,8 +184,9 @@ class SVP64ALUTestCase(TestAccumulatorBase):
 
     def case_7_sv_add_2(self):
         """>>> lst = ['sv.add 1, 5.v, 9.v']
+
         adds:
-            1 = 5 + 9   => 0x5555 = 0x4321 + 0x1234
+            1 = 5 + 9   => 0x5555 = 0x4321 + 0x1234
         """
         #       r1 is scalar so ENDS EARLY
         isa = SVP64Asm(['sv.add 1, 5.v, 9.v'])
@@ -204,8 +211,8 @@ class SVP64ALUTestCase(TestAccumulatorBase):
         """>>> lst = ['sv.add 1.v, 5, 9.v']
 
         adds:
-            1 = 5 + 9   => 0x5555 = 0x4321+0x1234
-            2 = 5 + 10  => 0x5432 = 0x4321+0x1111
+            1 = 5 + 9   => 0x5555 = 0x4321+0x1234
+            2 = 5 + 10  => 0x5432 = 0x4321+0x1111
         """
         isa = SVP64Asm(['sv.add 1.v, 5, 9.v'])
         lst = list(isa)
@@ -237,14 +244,14 @@ class SVP64ALUTestCase(TestAccumulatorBase):
         mask was set up as part of a parallel If-Then-Else)
 
         first add:
-            1 = 5 + 9   => 0x5555 = 0x4321 + 0x1234
-            2 = 0 (skipped)
-            3 = 7 + 11  => 0x4242 = 0x3012 + 0x1230
+            1 = 5 + 9   => 0x5555 = 0x4321 + 0x1234
+            2 = 0 (skipped)
+            3 = 7 + 11  => 0x4242 = 0x3012 + 0x1230
 
         second add:
-           13 = 0 (skipped)
-           14 = 11 + 8  => 0xB063 = 0x3012 + 0x8051
-           15 = 0 (skipped)
+           13 = 0 (skipped)
+           14 = 11 + 8  => 0xB063 = 0x3012 + 0x8051
+           15 = 0 (skipped)
         """
         isa = SVP64Asm([
             'sv.add/m=r30 1.v, 5.v, 9.v',
@@ -284,14 +291,14 @@ class SVP64ALUTestCase(TestAccumulatorBase):
         Vector operations with a fully-zero mask.
 
         first add:
-            1 = 0 (skipped)
-            2 = 0 (skipped)
-            3 = 0 (skipped)
+            1 = 0 (skipped)
+            2 = 0 (skipped)
+            3 = 0 (skipped)
 
         second add:
-           13 = 10 + 7  => 0x2341 = 0x1111 + 0x1230
-           14 = 11 + 8  => 0xB063 = 0x3012 + 0x8051
-           15 = 12 + 9  => 0x7736 = 0x6502 + 0x1234
+            * 13 = 10 + 7  => 0x2341 = 0x1111 + 0x1230
+            * 14 = 11 + 8  => 0xB063 = 0x3012 + 0x8051
+            * 15 = 12 + 9  => 0x7736 = 0x6502 + 0x1234
         """
         isa = SVP64Asm([
             'sv.add/m=r30 1.v, 5.v, 9.v',
@@ -324,12 +331,12 @@ class SVP64ALUTestCase(TestAccumulatorBase):
         """>>> lst = ['sv.add/m=ne 1.v, 5.v, 9.v']
 
         adds, CR predicated mask CR4.eq = 1, CR5.eq = 0, invert (ne)
-            1 = 5 + 9   => not to be touched (skipped)
-            2 = 6 + 10  => 0x3334 = 0x2223+0x1111
+            1 = 5 + 9   => not to be touched (skipped)
+            2 = 6 + 10  => 0x3334 = 0x2223+0x1111
 
         expected results:
-        r1 = 0xbeef skipped since CR4 is 1 and test is inverted
-        r2 = 0x3334 CR5 is 0, so this is used
+            * r1 = 0xbeef skipped since CR4 is 1 and test is inverted
+            * r2 = 0x3334 CR5 is 0, so this is used
         """
         isa = SVP64Asm(['sv.add/m=ne 1.v, 5.v, 9.v'])
         lst = list(isa)
index d604472438c64a7ef2b5ac019bf0ab0c8e3c4b30..0c4591daf173b4638a4bed3e70a30146df51efdf 100644 (file)
@@ -12,28 +12,30 @@ class SVP64LogicalTestCase(TestAccumulatorBase):
 
         extsb, integer twin-pred mask: source is ~r3 (0b01), dest r3 (0b10)
         works as follows, where any zeros indicate "skip element"
-        - sources are 9 and 10
-        - dests are 5 and 6
-        - source mask says "pick first element from source (5)
-        - dest mask says "pick *second* element from dest (10)
 
-        therefore the operation that's carried out is:
+            * sources are 9 and 10
+            * dests are 5 and 6
+            * source mask says "pick first element from source (5)
+            * dest mask says "pick *second* element from dest (10)
+
+        therefore the operation that's carried out is::
+
              GPR(10) = extsb(GPR(5))
 
         this is a type of back-to-back VREDUCE and VEXPAND but it applies
         to *operations*, not just MVs like in traditional Vector ISAs
-        ascii graphic:
+        ascii graphic::
 
-           reg num                 0 1 2 3 4 5 6 7 8 9 10
-           predicate src ~r3=0b01                    Y N
-                                                     |
-                                               +-----+
-                                               |
-           predicate dest r3=0b10            N Y
+            reg num                 0 1 2 3 4 5 6 7 8 9 10
+            predicate src ~r3=0b01                    Y N
+                                                      |
+                                                +-----+
+                                                |
+            predicate dest r3=0b10            N Y
 
         expected results:
-        r5 = 0x0                   dest r3 is 0b10: skip
-        r6 = 0xffff_ffff_ffff_ff91 2nd bit of r3 is 1
+            * r5 = 0x0                   dest r3 is 0b10: skip
+            * r6 = 0xffff_ffff_ffff_ff91 2nd bit of r3 is 1
         """
         isa = SVP64Asm(['sv.extsb/sm=~r3/dm=r3 5.v, 9.v'])
         lst = list(isa)
@@ -56,18 +58,20 @@ class SVP64LogicalTestCase(TestAccumulatorBase):
     def case_10_intpred_vcompress(self):
         """>>> lst = ['sv.extsb/sm=r3 5.v, 9.v']
 
-           reg num                 0 1 2 3 4 5 6 7 8 9 10 11
-           predicate src r3=0b101                     Y  N  Y
-                                                     |     |
-                                             +-------+     |
-                                             | +-----------+
-                                             | |
-           predicate dest always             Y Y Y
+        ascii graphic::
+
+            reg num                 0 1 2 3 4 5 6 7 8 9 10 11
+            predicate src r3=0b101                    Y  N  Y
+                                                      |     |
+                                              +-------+     |
+                                              | +-----------+
+                                              | |
+            predicate dest always             Y Y Y
 
         expected results:
-        r5 = 0xffff_ffff_ffff_ff90 (from r9)
-        r6 = 0xffff_ffff_ffff_ff92 (from r11)
-        r7 = 0x0 (VL loop runs out before we can use it)
+            * r5 = 0xffff_ffff_ffff_ff90 (from r9)
+            * r6 = 0xffff_ffff_ffff_ff92 (from r11)
+            * r7 = 0x0 (VL loop runs out before we can use it)
         """
         isa = SVP64Asm(['sv.extsb/sm=r3 5.v, 9.v'])
         lst = list(isa)
@@ -91,18 +95,20 @@ class SVP64LogicalTestCase(TestAccumulatorBase):
     def case_11_intpred_vexpand(self):
         """>>> lst = ['sv.extsb/dm=r3 5.v, 9.v']
 
-        reg num                  0 1 2 3 4 5 6 7 8 9 10 11
-        predicate src always                       Y  Y  Y
-                                                   |  |
-                                           +-------+  |
-                                           |   +------+
-                                           |   |
-        predicate dest r3=0b101            Y N Y
+        ascii graphic::
+
+            reg num                  0 1 2 3 4 5 6 7 8 9 10 11
+            predicate src always                       Y  Y  Y
+                                                       |  |
+                                               +-------+  |
+                                               |   +------+
+                                               |   |
+            predicate dest r3=0b101            Y N Y
 
         expected results:
-        r5 = 0xffff_ffff_ffff_ff90 1st bit of r3 is 1
-        r6 = 0x0                   skip
-        r7 = 0xffff_ffff_ffff_ff91 3nd bit of r3 is 1
+            * r5 = 0xffff_ffff_ffff_ff90 1st bit of r3 is 1
+            * r6 = 0x0                   skip
+            * r7 = 0xffff_ffff_ffff_ff91 3nd bit of r3 is 1
         """
         isa = SVP64Asm(['sv.extsb/dm=r3 5.v, 9.v'])
         lst = list(isa)
@@ -126,17 +132,19 @@ class SVP64LogicalTestCase(TestAccumulatorBase):
     def case_12_sv_twinpred(self):
         """>>> lst = ['sv.extsb/sm=r3/dm=~r3 5.v, 9.v']
 
-        reg num        0 1 2 3 4 5 6 7 8 9 10 11
-        predicate src r3=0b101                     Y  N  Y
-                                                   |
-                                             +-----+
-                                             |
-        predicate dest ~r3=0b010           N Y N
+        ascii graphic::
+
+            reg num        0 1 2 3 4 5 6 7 8 9 10 11
+            predicate src r3=0b101                     Y  N  Y
+                                                       |
+                                                 +-----+
+                                                 |
+            predicate dest ~r3=0b010           N Y N
 
         expected results:
-        r5 = 0x0                   dest ~r3 is 0b010: skip
-        r6 = 0xffff_ffff_ffff_ff90 2nd bit of ~r3 is 1
-        r7 = 0x0                   dest ~r3 is 0b010: skip
+            * r5 = 0x0                   dest ~r3 is 0b010: skip
+            * r6 = 0xffff_ffff_ffff_ff90 2nd bit of ~r3 is 1
+            * r7 = 0x0                   dest ~r3 is 0b010: skip
         """
         isa = SVP64Asm(['sv.extsb/sm=r3/dm=~r3 5.v, 9.v'])
         lst = list(isa)
@@ -170,21 +178,23 @@ class SVP64LogicalTestCase(TestAccumulatorBase):
         make sure to skip mask bits before the initial step,
         to save clock cycles. or not. your choice.
 
-        reg num        0 1 2 3 4 5 6 7 8 9 10 11 12
-        srcstep=1                           v
-        src r3=0b0101                    Y  N  Y  N
-                                         :     |
-                                   + - - +     |
-                                   :   +-------+
-                                   :   |
-        dest ~r3=0b1010          N Y N Y
-        dststep=2                    ^
+        ascii graphic::
+
+            reg num        0 1 2 3 4 5 6 7 8 9 10 11 12
+            srcstep=1                           v
+            src r3=0b0101                    Y  N  Y  N
+                                             :     |
+                                       + - - +     |
+                                       :   +-------+
+                                       :   |
+            dest ~r3=0b1010          N Y N Y
+            dststep=2                    ^
 
         expected results:
-        r5 = 0x0  # skip
-        r6 = 0x0  # dststep starts at 3, so this gets skipped
-        r7 = 0x0  # skip
-        r8 = 0xffff_ffff_ffff_ff92  # this will be used
+            * r5 = 0x0  # skip
+            * r6 = 0x0  # dststep starts at 3, so this gets skipped
+            * r7 = 0x0  # skip
+            * r8 = 0xffff_ffff_ffff_ff92  # this will be used
         """
         isa = SVP64Asm(['sv.extsb/sm=r3/dm=~r3 5.v, 9.v'])
         lst = list(isa)
@@ -217,17 +227,19 @@ class SVP64LogicalTestCase(TestAccumulatorBase):
         lots of opportunity for hardware optimisation, it effectively
         allows dynamic indexing of the register file
 
-        reg num        0 1 2 3 4 5 6 7 8 9 10 11
-        src r30=0b100                    N  N  Y
-                                               |
-                                   +-----------+
-                                   |
-        dest r3=1: 1<<r3=0b010   N Y N
+        ascii graphic::
+
+            reg num        0 1 2 3 4 5 6 7 8 9 10 11
+            src r30=0b100                    N  N  Y
+                                                   |
+                                       +-----------+
+                                       |
+            dest r3=1: 1<<r3=0b010   N Y N
 
         expected results:
-        r5 = 0x0                    skipped
-        r6 = 0xffff_ffff_ffff_ff92  r3 is 1, so this is used
-        r7 = 0x0                    skipped
+            * r5 = 0x0                    skipped
+            * r6 = 0xffff_ffff_ffff_ff92  r3 is 1, so this is used
+            * r7 = 0x0                    skipped
         """
         isa = SVP64Asm(['sv.extsb/dm=1<<r3/sm=r30 5.v, 9.v'])
         lst = list(isa)
@@ -252,17 +264,19 @@ class SVP64LogicalTestCase(TestAccumulatorBase):
     def case_17_shift_one_by_r3_source(self):
         """>>> lst = ['sv.extsb/sm=1<<r3/dm=r30 5.v, 9.v']
 
-        reg num        0 1 2 3 4 5 6 7 8 9 10 11
-        src r3=2: 1<<r3=0b100            N  N  Y
-                                               |
-                                   +-----------+
-                                   |
-        dest r30=0b010           N Y N
+        ascii graphic::
+
+            reg num        0 1 2 3 4 5 6 7 8 9 10 11
+            src r3=2: 1<<r3=0b100            N  N  Y
+                                                   |
+                                       +-----------+
+                                       |
+            dest r30=0b010           N Y N
 
         expected results:
-        r5 = 0x0                    skipped
-        r6 = 0xffff_ffff_ffff_ff92  2nd bit of r30 is 1
-        r7 = 0x0                    skipped
+            * r5 = 0x0                    skipped
+            * r6 = 0xffff_ffff_ffff_ff92  2nd bit of r30 is 1
+            * r7 = 0x0                    skipped
         """
         isa = SVP64Asm(['sv.extsb/sm=1<<r3/dm=r30 5.v, 9.v'])
         lst = list(isa)
@@ -290,24 +304,27 @@ class SVP64LogicalTestCase(TestAccumulatorBase):
         checks reentrant CR predication.  note that the source CR-mask
         and destination CR-mask use *different bits* of the CR fields,
         despite both predicates starting from the same CR field number.
-        cr4.lt is zero, cr7.lt is zero AND
-        cr5.eq is zero, cr6.eq is zero.
-
-        reg num        0 1 2 3 4 5 6 7 8 9 10 11 12
-        srcstep=1                           v
-        src cr4.eq=1                     Y  N  Y  N
-            cr6.eq=1                     :     |
-                                   + - - +     |
-                                   :   +-------+
-        dest cr5.lt=1              :   |
-             cr7.lt=1            N Y N Y
-        dststep=2                    ^
+
+            * cr4.lt is zero, cr7.lt is zero AND
+            * cr5.eq is zero, cr6.eq is zero.
+
+        ascii graphic::
+
+            reg num        0 1 2 3 4 5 6 7 8 9 10 11 12
+            srcstep=1                           v
+            src cr4.eq=1                     Y  N  Y  N
+                cr6.eq=1                     :     |
+                                       + - - +     |
+                                       :   +-------+
+            dest cr5.lt=1              :   |
+                 cr7.lt=1            N Y N Y
+            dststep=2                    ^
 
         expected results:
-        r5 = 0x0  skip
-        r6 = 0x0  dststep starts at 3, so this gets skipped
-        r7 = 0x0  skip
-        r8 = 0xffff_ffff_ffff_ff92  this will be used
+            * r5 = 0x0  skip
+            * r6 = 0x0  dststep starts at 3, so this gets skipped
+            * r7 = 0x0  skip
+            * r8 = 0xffff_ffff_ffff_ff92  this will be used
         """
         isa = SVP64Asm(['sv.extsb/sm=eq/dm=lt 5.v, 9.v'])
         lst = list(isa)