[doc] Document the newly added performance counters

Author: SamuelRiedel

doc/01_overview/compliance.rst

@@ -43,6 +43,10 @@ In addition, the following instruction set extensions are available.
      - 2.0
      - always enabled
 
+   * - **"Zicntr" and "Zihpm": Extensions for Counters and Performance Monitoring**
+     - 2.0
+     - always enabled
+
    * - **Zifencei**: Instruction-Fetch Fence
      - 2.0
      - always enabled

doc/03_reference/performance_counters.rst

@@ -3,10 +3,13 @@
 Performance Counters
 ====================
 
-Ibex implements performance counters according to the RISC-V Privileged Specification, version 1.11 (see Hardware Performance Monitor, Section 3.1.11).
+Ibex implements performance counters according to the RISC-V Privileged Specification, version 1.11 (see Hardware Performance Monitor, Section 3.1.11) and supports the **Zihpm** (Hardware Performance Counters) extension.
 The performance counters are placed inside the Control and Status Registers (CSRs) and can be accessed with the ``CSRRW(I)`` and ``CSRRS/C(I)`` instructions.
 
-Ibex implements the clock cycle counter ``mcycle(h)``, the retired instruction counter ``minstret(h)``, as well as the 29 event counters ``mhpmcounter3(h)`` - ``mhpmcounter31(h)`` and the corresponding event selector CSRs ``mhpmevent3`` - ``mhpmevent31``, and the ``mcountinhibit`` CSR to individually enable/disable the counters.
+Ibex implements the machine-mode clock cycle counter ``mcycle(h)``, the retired instruction counter ``minstret(h)``, as well as the 29 event counters ``mhpmcounter3(h)`` - ``mhpmcounter31(h)`` and the corresponding event selector CSRs ``mhpmevent3`` - ``mhpmevent31``, and the ``mcountinhibit`` CSR to individually enable/disable the counters.
+
+Additionally, Ibex implements the Zicntr and Zihpm extensions which provide User-mode (U-mode) aliases for these performance counters: ``cycle(h)``, ``instret(h)``, and ``hpmcounter3(h)`` - ``hpmcounter31(h)``. These aliases provide read-only access to the exact same underlying hardware counters configured in M-mode.
+
 ``mcycle(h)`` and ``minstret(h)`` are always available and 64 bit wide.
 The ``mhpmcounter`` performance counters are optional (unavailable by default) and parametrizable in width.
 
@@ -60,6 +63,19 @@ In particular, to enable/disable ``mcycle(h)``, bit 0 must be written. For ``min
 The lower 32 bits of all counters can be accessed through the base register, whereas the upper 32 bits are accessed through the ``h``-register.
 Reads to all these registers are non-destructive.
 
+User-Mode Counter Access (mcounteren)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Access to the U-mode counter aliases (``cycle(h)``, ``instret(h)``, and ``hpmcounterX(h)``) is controlled via the Machine Counter-Enable CSR (``mcounteren``). This register can gate access to the counters from less privileged modes to prevent benchmarking the core if desired.
+
+* **Bit 0** controls access to ``cycle(h)``.
+* **Bit 2** controls access to ``instret(h)``.
+* **Bit X** controls access to ``hpmcounterX(h)``.
+
+When a bit in ``mcounteren`` is clear (0), any attempt to read the corresponding counter alias from U-mode will trigger an illegal instruction exception.
+
+To secure this mechanism, the ``mcounteren`` register can be locked against software modifications using a MUBI input signal called ``mcounteren_writeable``. When this signal disables writes, any attempt by software to modify the contents of ``mcounteren`` is ignored.
+
 Parametrization at synthesis time
 ---------------------------------