Add synopsis and description for Zacas (Atomic CAS) extension (#516) (#518)

* Add synopses and descriptions for Zacas instructions

* Add synopses and descriptions for Zacas instructions

* Add synopses and descriptions for Zacas instruction

* Add synopses and descriptions for Zacas instructions.

* Add synopses and descriptions for Zacas instructions

---------

Co-authored-by: Derek Hower <134728312+dhower-qc@users.noreply.github.com>

Author: syedowaisalishah

arch/inst/Zacas/amocas.d.yaml

@@ -1,26 +1,82 @@
+---
 # yaml-language-server: $schema=../../../schemas/inst_schema.json
 
 $schema: "inst_schema.json#"
 kind: instruction
 name: amocas.d
-long_name: No synopsis available.
+long_name: Atomic Compare-and-Swap Doubleword
 description: |
-  No description available.
+  For RV32, AMOCAS.D atomically loads 64-bits of a data value from address in
+  rs1, compares the loaded value to a 64-bit value held in a register pair
+  consisting of rd and rd+1, and if the comparison is bitwise equal, then
+  stores the 64-bit value held in the register pair rs2 and rs2+1 to the
+  original address in rs1. The value loaded from memory is placed into the
+  register pair rd and rd+1. The instruction requires the first register in
+  the pair to be even numbered; encodings with odd-numbered registers
+  specified in rs2 and rd are reserved. When the first register of a source
+  register pair is x0, then both halves of the pair read as zero. When the
+  first register of a destination register pair is x0, then the entire
+  register result is discarded and neither destination register is written.
+
+  For RV64, AMOCAS.D atomically loads 64-bits of a data value from address in
+  rs1, compares the loaded value to a 64-bit value held in rd, and if the
+  comparison is bitwise equal, then stores the 64-bit value held in rs2 to the
+  original address in rs1. The value loaded from memory is placed into
+  register rd.
+
+  Just as for AMOs in the A extension, AMOCAS.D requires that the address held
+  in rs1 be naturally aligned to the size of the operand (i.e., eight-byte
+  aligned for doublewords). And the same exception options apply if the
+  address is not naturally aligned.
+
+  Just as for AMOs in the A extension, the AMOCAS.D optionally provides release
+  consistency semantics, using the aq and rl bits, to help implement
+  multiprocessor synchronization. The memory operation performed by an
+  AMOCAS.D, when successful, has acquire semantics if aq bit is 1 and has
+  release semantics if rl bit is 1. The memory operation performed by an
+  AMOCAS.W/D/Q, when not successful, has acquire semantics if aq bit is 1 but
+  does not have release semantics, regardless of rl.
+
+  A FENCE instruction may be used to order the memory read access and, if
+  produced, the memory write access by an AMOCAS.D instruction.
+
+  [Note] An unsuccessful AMOCAS.D may either not perform a memory write or may
+  write back the old value loaded from memory. The memory write, if produced,
+  does not have release semantics, regardless of rl.
+
+  An AMOCAS.D instruction always requires write permissions.
+
 definedBy: Zacas
 assembly: xd, xs1, xs2, aq, rl
 encoding:
-  match: 00101------------011-----0101111
-  variables:
-    - name: aq
-      location: 26-26
-    - name: rl
-      location: 25-25
-    - name: rs2
-      location: 24-20
-    - name: rs1
-      location: 19-15
-    - name: rd
-      location: 11-7
+  RV32:
+    match: 00101------------011-----0101111
+    variables:
+      - name: aq
+        location: 26-26
+      - name: rl
+        location: 25-25
+      - name: rs2
+        location: 24-20
+        not: [1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, 25, 27, 29, 31]
+      - name: rs1
+        location: 19-15
+      - name: rd
+        location: 11-7
+        not: [1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, 25, 27, 29, 31]
+  RV64:
+    match: 00101------------011-----0101111
+    variables:
+      - name: aq
+        location: 26-26
+      - name: rl
+        location: 25-25
+      - name: rs2
+        location: 24-20
+      - name: rs1
+        location: 19-15
+      - name: rd
+        location: 11-7
 access:
   s: always
   u: always

arch/inst/Zacas/amocas.q.yaml

@@ -1,11 +1,45 @@
+---
 # yaml-language-server: $schema=../../../schemas/inst_schema.json
 
 $schema: "inst_schema.json#"
 kind: instruction
 name: amocas.q
-long_name: No synopsis available.
+long_name: Atomic Compare-and-Swap Quadword
 description: |
-  No description available.
+  For RV64, AMOCAS.Q atomically loads 128-bits of a data value from address
+  in rs1, compares the loaded value to a 128-bit value held in a register
+  pair consisting of rd and rd+1, and if the comparison is bitwise equal,
+  then stores the 128-bit value held in the register pair rs2 and rs2+1 to
+  the original address in rs1. The value loaded from memory is placed into
+  the register pair rd and rd+1. The instruction requires the first register
+  in the pair to be even numbered; encodings with odd-numbered registers
+  specified in rs2 and rd are reserved. When the first register of a source
+  register pair is x0, then both halves of the pair read as zero. When the
+  first register of a destination register pair is x0, then the entire
+  register result is discarded and neither destination register is written.
+
+  Just as for AMOs in the A extension, AMOCAS.Q requires that the address held
+  in rs1 be naturally aligned to the size of the operand (i.e., sixteen-byte
+  aligned for quadwords). And the same exception options apply if the
+  address is not naturally aligned.
+
+  Just as for AMOs in the A extension, the AMOCAS.Q optionally provides release
+  consistency semantics, using the aq and rl bits, to help implement
+  multiprocessor synchronization. The memory operation performed by an
+  AMOCAS.Q, when successful, has acquire semantics if aq bit is 1 and has
+  release semantics if rl bit is 1. The memory operation performed by an
+  AMOCAS.W/D/Q, when not successful, has acquire semantics if aq bit is 1 but
+  does not have release semantics, regardless of rl.
+
+  A FENCE instruction may be used to order the memory read access and, if
+  produced, the memory write access by an AMOCAS.Q instruction.
+
+  [Note] An unsuccessful AMOCAS.Q may either not perform a memory write or
+  may write back the old value loaded from memory. The memory write, if
+  produced, does not have release semantics, regardless of rl.
+
+  An AMOCAS.Q instruction always requires write permissions.
+
 definedBy: Zacas
 base: 64
 assembly: xd, xs1, xs2, aq, rl
@@ -18,10 +52,12 @@ encoding:
       location: 25-25
     - name: rs2
       location: 24-20
+      not: [1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, 25, 27, 29, 31]
     - name: rs1
       location: 19-15
     - name: rd
       location: 11-7
+      not: [1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, 25, 27, 29, 31]
 access:
   s: always
   u: always

arch/inst/Zacas/amocas.w.yaml

@@ -1,11 +1,45 @@
+---
 # yaml-language-server: $schema=../../../schemas/inst_schema.json
 
 $schema: "inst_schema.json#"
 kind: instruction
 name: amocas.w
-long_name: No synopsis available.
+long_name: Atomic Compare-and-Swap Word
 description: |
-  No description available.
+  For RV32, AMOCAS.W atomically loads a 32-bit data value from address in rs1,
+  compares the loaded value to the 32-bit value held in rd, and if the
+  comparison is bitwise equal, then stores the 32-bit value held in rs2 to the
+  original address in rs1. The value loaded from memory is placed into
+  register rd.
+
+  For RV64, AMOCAS.W atomically loads a 32-bit data value from address in rs1,
+  compares the loaded value to the lower 32 bits of the value held in rd, and
+  if the comparison is bitwise equal, then stores the lower 32 bits of the
+  value held in rs2 to the original address in rs1. The 32-bit value loaded
+  from memory is sign-extended and is placed into register rd.
+
+  Just as for AMOs in the A extension, AMOCAS.W requires that the address held
+  in rs1 be naturally aligned to the size of the operand (i.e., four-byte
+  aligned for words). And the same exception options apply if the address is
+  not naturally aligned.
+
+  Just as for AMOs in the A extension, the AMOCAS.W optionally provides release
+  consistency semantics, using the aq and rl bits, to help implement
+  multiprocessor synchronization. The memory operation performed by an
+  AMOCAS.W, when successful, has acquire semantics if aq bit is 1 and has
+  release semantics if rl bit is 1. The memory operation performed by an
+  AMOCAS.W/D/Q, when not successful, has acquire semantics if aq bit is 1 but
+  does not have release semantics, regardless of rl.
+
+  A FENCE instruction may be used to order the memory read access and, if
+  produced, the memory write access by an AMOCAS.W instruction.
+
+  [Note] An unsuccessful AMOCAS.W may either not perform a memory write or may
+  write back the old value loaded from memory. The memory write, if produced,
+  does not have release semantics, regardless of rl.
+
+  An AMOCAS.W instruction always requires write permissions.
+
 definedBy: Zacas
 assembly: xd, xs1, xs2, aq, rl
 encoding: