[Docs] Add Zcmp Instructions in CVA6 user guide and requirement speci…

…fications (#1927)

docs/01_cva6_user/Programmer_View.rst

@@ -44,6 +44,7 @@ Some of them are optional and are enabled through parameters in the SystemVerilo
    "Zb* - Bit-Manipulation",                                            "Yes", "✔", "✔", "Note 1"
    "C - Compressed Instructions ",                                      "Yes", "✔", "✔", "Note 1"
    "Zcb - Code Size Reduction",                                         "Yes", "✔", "✔", "Note 1"
+   "Zcmp - Code Size Reduction",                                        "Yes", "✔", "✔", "Note 1"
    "D - Double precision floating-point",                               "Yes", "",  "✔", "Note 1"
    "F - Single precision floating-point",                               "Yes", "✔", "✔", "Note 1"
    "M - Integer Multiply/Divide",                                       "No",  "✔", "✔", "Note 1"

docs/01_cva6_user/RISCV_Instructions.rst

@@ -36,12 +36,13 @@ In the next pages, the ISA (Instruction Set Architecture) for various CVA6 confi
 * RVZbc        - Standard Extension for Bit Manipulation: Carry-less multiplication (RV32 and RV64)
 * RVZbs        - Standard Extension for Bit Manipulation: Single-bit instructions (RV32 and RV64)
 * RV32Zcb      – Standard Extension for Code Size Reduction
+* RVZcmp       – Standard Extension for Code Size Reduction (RV32 and RV64)
 * RVZicsr      – Standard Extension for CSR Instructions
 * RVZifencei   – Standard Extension for Instruction-Fetch Fence
 * RVZicond     – Standard Extension for Integer Conditional Operations
 
 The base RISC-V ISA (RV32I or RV64I) has fixed-length 32-bit instructions or 16-bit instructions, so that must be naturally aligned on 2-byte boundary.
-If 16-bit instructions are not implemented (RVC, RVZcb), then instructions must be naturally aligned on 4-byte boundary.
+If 16-bit instructions are not implemented (RVC, RVZcb, RVZcmp), then instructions must be naturally aligned on 4-byte boundary.
 
 All CVA6 configurations support:
 

docs/01_cva6_user/RISCV_Instructions_RVZcmp.rst

@@ -0,0 +1,169 @@
+..
+   Copyright (c) 2023 OpenHW Group
+   Copyright (c) 2023 Thales
+
+   SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1
+
+.. Level 1
+   =======
+
+   Level 2
+   -------
+
+   Level 3
+   ~~~~~~~
+
+   Level 4
+   ^^^^^^^
+
+.. _cva6_riscv_instructions_RVZcmp:
+
+*Applicability of this chapter to configurations:*
+
+.. csv-table::
+   :widths: auto
+   :align: left
+   :header: "Configuration", "Implementation"
+
+   "CV32A60AX", "Implemented extension"
+   "CV32A60X", "Implemented extension"
+
+**Note**: Zcmp is primarily targeted at embedded class CPUs due to implementation complexity. Additionally, it is not compatible with architecture class profiles.  
+
+RVZcmp Code Size Reduction Instructions
+---------------------------------------
+
+Zcmp belongs to group of extensions called RISC-V Code Size Reduction Extension (Zc*). Zc* has become the superset of Standard C extension adding more 16-bit instructions to the ISA.
+Zcmp includes 16-bit macro instructions, PUSH/POP and double move, which reuse the encoding for c.fsdsp instruction.
+All the Zcmp instructions require at least standard C extension support as pre-requisite, along with Zca extension.
+
+- **CM.PUSH**: Compressed Push
+
+    **Format**: cm.push {reg_list}, -stack_adj
+
+    **Description**: This instruction pushes (stores) the registers in reg_list to the memory below the stack pointer, and then creates the stack frame by decrementing the stack pointer by stack_adj, including any additional stack space requested by the value of spimm.
+
+    **Pseudocode**: if (XLEN==32) bytes=4; else bytes=8;
+                    addr=sp-bytes;
+                    for(i in 27,26,25,24,23,22,21,20,19,18,9,8,1) {
+                        if (xreg_list[i]) {
+                            switch(bytes) {
+                                4: asm("sw x[i], 0(addr)");
+                                8: asm("sd x[i], 0(addr)");
+                            }
+                            addr-=bytes;
+                        }
+                    }
+                    sp-=stack_adj;
+
+    **Invalid values**: reg_list not in [ {ra}, {ra, s0}, {ra, s0-s1}, {ra, s0-s2}, ..., {ra, s0-s8}, {ra, s0-s9}, {ra, s0-s11} ], stack_adj not in [ 16, 32, 48, 64, 80, 96, 112 ] and [ 16, 32, 48, 64, 80, 96, 112, 128, 144, 160 ] for RV32 and RV64 respectively.
+
+    **Exception raised**: NONE
+
+- **CM.POP**: Compressed Pop
+
+    **Format**: cm.pop {reg_list}, stack_abj
+
+    **Description**: Destroy stack frame: load ra and 0 to 12 saved registers from the stack frame, deallocate the stack frame.
+
+    **Pseudocode**: if (XLEN==32) bytes=4; else bytes=8;
+                    addr=sp+stack_adj-bytes;
+                    for(i in 27,26,25,24,23,22,21,20,19,18,9,8,1) {
+                        if (xreg_list[i]) {
+                            switch(bytes) {
+                                4: asm("lw x[i], 0(addr)");
+                                8: asm("ld x[i], 0(addr)");
+                            }
+                            addr-=bytes;
+                        }
+                    }
+                    sp+=stack_adj;
+
+    **Invalid values**: reg_list not in [ {ra}, {ra, s0}, {ra, s0-s1}, {ra, s0-s2}, ..., {ra, s0-s8}, {ra, s0-s9}, {ra, s0-s11} ], stack_adj not in [ 16, 32, 48, 64, 80, 96, 112 ] and [ 16, 32, 48, 64, 80, 96, 112, 128, 144, 160 ] for RV32 and RV64 respectively.
+
+    **Exception raised**: NONE
+
+- **CM.POPRETZ**: Compressed Pop return zero
+
+    **Format**: cm.popretz {reg_list}, stack_adj
+
+    **Description**: Destroy stack frame: load ra and 0 to 12 saved registers from the stack frame, deallocate the stack frame, move zero into a0, return to ra.
+
+    **Pseudocode**: if (XLEN==32) bytes=4; else bytes=8;
+                    addr=sp+stack_adj-bytes;
+                    for(i in 27,26,25,24,23,22,21,20,19,18,9,8,1) {
+                        if (xreg_list[i]) {
+                            switch(bytes) {
+                                4: asm("lw x[i], 0(addr)");
+                                8: asm("ld x[i], 0(addr)");
+                            }
+                            addr-=bytes;
+                        }
+                    }
+                    asm("li a0, 0");
+                    sp+=stack_adj;
+                    asm("ret");
+
+    **Invalid values**: reg_list not in [ {ra}, {ra, s0}, {ra, s0-s1}, {ra, s0-s2}, ..., {ra, s0-s8}, {ra, s0-s9}, {ra, s0-s11} ], stack_adj not in [ 16, 32, 48, 64, 80, 96, 112 ] and [ 16, 32, 48, 64, 80, 96, 112, 128, 144, 160 ] for RV32 and RV64 respectively.
+
+    **Exception raised**: NONE
+
+- **CM.POPRET**: Compressed Pop return
+
+    **Format**: cm.popret {reg_list}, stack_adj
+
+    **Description**: Destroy stack frame: load ra and 0 to 12 saved registers from the stack frame, deallocate the stack frame, return to ra.
+
+    **Pseudocode**: if (XLEN==32) bytes=4; else bytes=8;
+                    addr=sp+stack_adj-bytes;
+                    for(i in 27,26,25,24,23,22,21,20,19,18,9,8,1) {
+                        if (xreg_list[i]) {
+                            switch(bytes) {
+                                4: asm("lw x[i], 0(addr)");
+                                8: asm("ld x[i], 0(addr)");
+                            }
+                            addr-=bytes;
+                        }
+                    }
+                    sp+=stack_adj;
+                    asm("ret");
+
+    **Invalid values**: reg_list not in [ {ra}, {ra, s0}, {ra, s0-s1}, {ra, s0-s2}, ..., {ra, s0-s8}, {ra, s0-s9}, {ra, s0-s11} ], stack_adj not in [ 16, 32, 48, 64, 80, 96, 112 ] and [ 16, 32, 48, 64, 80, 96, 112, 128, 144, 160 ] for RV32 and RV64 respectively.
+
+    **Exception raised**: NONE
+
+- **CM.MVSA01**: Compressed move argument registers into save registers
+
+    **Format**: cm.mvsa01 r1s', r2s'
+
+    **Description**: This instruction moves a0 into r1s' and a1 into r2s'. r1s' and r2s' must be different. The execution is atomic, so it is not possible to observe state where only one of r1s' or r2s' has been updated.
+
+    **Pseudocode**: if (RV32E && (r1sc>1 || r2sc>1)) {
+                        reserved();
+                    }
+                    xreg1 = {r1sc[2:1]>0,r1sc[2:1]==0,r1sc[2:0]};
+                    xreg2 = {r2sc[2:1]>0,r2sc[2:1]==0,r2sc[2:0]};
+                    X[xreg1] = X[10];
+                    X[xreg2] = X[11];
+
+    **Invalid values**: r1s' = r2s'
+
+    **Exception raised**: NONE
+
+- **CM.MVA01S**: Compressed move save registers into argument registers
+
+    **Format**: cm.mva01s r1s', r2s'
+
+    **Description**: This instruction moves r1s' into a0 and r2s' into a1. The execution is atomic, so it is not possible to observe state where only one of a0 or a1 have been updated.
+
+    **Pseudocode**: if (RV32E && (r1sc>1 || r2sc>1)) {
+                        reserved();
+                    }
+                    xreg1 = {r1sc[2:1]>0,r1sc[2:1]==0,r1sc[2:0]};
+                    xreg2 = {r2sc[2:1]>0,r2sc[2:1]==0,r2sc[2:0]};
+                    X[10] = X[xreg1];
+                    X[11] = X[xreg2];
+
+    **Invalid values**: NONE
+
+    **Exception raised**: NONE

docs/02_cva6_requirements/cva6_requirements_specification.rst

@@ -317,6 +317,10 @@ independent requirements.
 |                                   | **option** the **Zcb**            |
 |                                   | extension version 1.0.            |
 +-----------------------------------+-----------------------------------+
+| ISA-150                           | CVA6 should support as an         |
+|                                   | **option** the **Zcmp**           |
+|                                   | extension version 1.0.            |
++-----------------------------------+-----------------------------------+
 
 
 Note to ISA-60 and ISA-70: CV64A6 cannot support the D extension with