Skip to content

Commit

Permalink
Merge pull request #439 from Silabs-ArjanB/ArjanB_docm
Browse files Browse the repository at this point in the history 
Fixing mtvec and mtvt alignment requirements. Better links for spec v…
  • Loading branch information
@silabs-oysteink
silabs-oysteink authored Feb 16, 2022
2 parents b6214af + 2b0d849 commit 380b9fd
Show file tree
Hide file tree
Showing 4 changed files with 52 additions and 36 deletions.
52 changes: 30 additions & 22 deletions docs/user_manual/source/control_status_registers.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -446,7 +446,7 @@ Machine ISA (``misa``)

CSR Address: 0x301

Reset Value: defined (based on ``A_EXT``, ``M_EXT``, ``X_EXT``, ``X_MISA``)
Reset Value: defined (based on ``RV32``, ``A_EXT``, ``M_EXT``, ``X_EXT``, ``X_MISA``)

Detailed:

Expand Down Expand Up @@ -599,18 +599,17 @@ Detailed:
+---------+------------------+---------------------------------------------------------------------------------------------------------------+
| Bit # | R/W | Description |
+=========+==================+===============================================================================================================+
| 31:12 | RW | **BASE[31:12]**: Trap-handler base address, always aligned to 4096 bytes. |
| 31:7 | RW | **BASE[31:7]**: Trap-handler base address, always aligned to 128 bytes. |
+---------+------------------+---------------------------------------------------------------------------------------------------------------+
| 11:2 | WARL (0x0) | **BASE[11:2]**: Trap-handler base address, always aligned to 4096 bytes. ``mtvec[11:2]`` is hardwired to 0x0. |
| 6:2 | WARL (0x0) | **BASE[6:2]**: Trap-handler base address, always aligned to 128 bytes. ``mtvec[6:2]`` is hardwired to 0x0. |
+---------+------------------+---------------------------------------------------------------------------------------------------------------+
| 1:0 | WARL (0x0*, 0x1) | **MODE[0]**: Interrupt handling mode. 0x0 = non-vectored basic mode, 0x1 = vectored basic mode. |
+---------+------------------+---------------------------------------------------------------------------------------------------------------+

The initial value of ``mtvec`` is equal to {**mtvec_addr_i[31:12]**, 10'b0, 2'b01}.
The initial value of ``mtvec`` is equal to {**mtvec_addr_i[31:7]**, 5'b0, 2'b01}.

When an exception or an interrupt is encountered, the core jumps to the corresponding
handler using the content of the ``mtvec[31:8]`` as base address. Only
8-byte aligned addresses are allowed. Both direct mode and vectored mode
handler using the content of the ``mtvec[31:7]`` as base address. Both direct mode and vectored mode
are supported.

.. _csr-mtvec-smclic:
Expand All @@ -627,14 +626,14 @@ Detailed:
+---------+------------------+---------------------------------------------------------------------------------------------------------------+
| Bit # | R/W | Description |
+=========+==================+===============================================================================================================+
| 31:12 | RW | **BASE[31:12]**: Trap-handler base address, always aligned to 4096 bytes. |
| 31:7 | RW | **BASE[31:7]**: Trap-handler base address, always aligned to 128 bytes. |
+---------+------------------+---------------------------------------------------------------------------------------------------------------+
| 11:2 | WARL (0x0) | **BASE[11:2]**: Trap-handler base address, always aligned to 4096 bytes. ``mtvec[11:2]`` is hardwired to 0x0. |
| 6:2 | WARL (0x0) | **BASE[6:2]**: Trap-handler base address, always aligned to 128 bytes. ``mtvec[6:2]`` is hardwired to 0x0. |
+---------+------------------+---------------------------------------------------------------------------------------------------------------+
| 1:0 | WARL (0x3) | **MODE**: Interrupt handling mode. Always CLIC mode. |
+---------+------------------+---------------------------------------------------------------------------------------------------------------+

The initial value of ``mtvec`` is equal to {**mtvec_addr_i[31:12]**, 10'b0, 2'b11}.
The initial value of ``mtvec`` is equal to {**mtvec_addr_i[31:7]**, 5'b0, 2'b11}.

.. _csr-mtvt:

Expand All @@ -652,13 +651,18 @@ Detailed:
+-------------+------------+-----------------------------------------------------------------------+
| Bit # | R/W | Description |
+=============+============+=======================================================================+
| 31:6 | RW | **BASE**: Trap-handler vector table base address, 64 byte aligned. |
| 31:8 | WARL | **BASE[31:8]**: Trap-handler vector table base address. |
| | | See note below for alignment restrictions. |
+-------------+------------+-----------------------------------------------------------------------+
| 5:0 | R (0x0) | Reserved. Hardwired to 0. |
| 7:6 | WARL (0x0) | **BASE[7:6]**: Trap-handler vector table base address. |
+-------------+------------+-----------------------------------------------------------------------+
| 5:0 | R (0x0) | Reserved. Hardwired to 0. |
+-------------+------------+-----------------------------------------------------------------------+

The ``mtvt`` CSR holds the base address of the trap vector table, aligned on a 64-byte or greater
power-of-two boundary.
.. note::
The ``mtvt`` CSR holds the base address of the trap vector table, aligned on a ``2^(2+SMCLIC_ID_WIDTH)`` bytes or greater
power-of-two boundary. For example if ``SMCLIC_ID_WIDTH`` = 8, then 256 CLIC interrupts are supported and the trap vector table
is aligned to 1024 bytes, and therefore **BASE[9:8]** will be WARL (0x0).

Machine Status (``mstatush``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -756,11 +760,10 @@ Machine Counter-Inhibit Register (``mcountinhibit``)

CSR Address: 0x320

Reset Value: 0x0000_000D
Reset Value: Defined

The performance counter inhibit control register. The default value is to inihibit counters out of reset.
The bit returns a read value of 0 for non implemented counters. This reset value
shows the result using the default number of performance counters to be 1.
The performance counter inhibit control register. The default value is to inihibit all implemented counters out of reset.
The bit returns a read value of 0 for non implemented counters.

Detailed:

Expand Down Expand Up @@ -845,14 +848,14 @@ Reset Value: 0x0000_0000
+=============+============+==================================================================================+
| 31 | RW | **INTERRUPT:** This bit is set when the exception was triggered by an interrupt. |
+-------------+------------+----------------------------------------------------------------------------------+
| 30:10 | WLRL (0x0) | **EXCCODE[30:10]**. Hardwired to 0. |
| 30:11 | WLRL (0x0) | **EXCCODE[30:11]**. Hardwired to 0. |
+-------------+------------+----------------------------------------------------------------------------------+
| 9:0 | WLRL | **EXCCODE[30:10]** (See note below) |
| 10:0 | WLRL | **EXCCODE[10:0]**. See note below. |
+-------------+------------+----------------------------------------------------------------------------------+

.. note::

Software accesses to `mcause[7:0]` must be sensitive to the WLRL field specification of this CSR. For example,
Software accesses to `mcause[10:0]` must be sensitive to the WLRL field specification of this CSR. For example,
when `mcause[31]` is set, writing 0x1 to `mcause[1]` (Supervisor software interrupt) will result in UNDEFINED behavior.

Machine Cause (``mcause``) - ``SMCLIC`` == 1
Expand Down Expand Up @@ -880,11 +883,16 @@ Reset Value: 0x0000_0000
+-------------+------------+----------------------------------------------------------------------------------+
| 15:12 | WARL (0x0) | Reserved. Hardwired to 0. |
+-------------+------------+----------------------------------------------------------------------------------+
| 11:10 | WLRL (0x0) | **EXCCODE[11:10]** |
| 11 | WLRL (0x0) | **EXCCODE[11]** |
+-------------+------------+----------------------------------------------------------------------------------+
| 9:0 | WLRL | **EXCCODE[9:0]** |
| 10:0 | WLRL | **EXCCODE[10:0]** |
+-------------+------------+----------------------------------------------------------------------------------+

.. note::

``mcause.MPP`` and ``mstatus.MPP`` mirror each other. ``mcause.MPIE`` and ``mstatus.MPIE`` mirror each other. Reading or writing the
fields ``MPP``/``MPIE`` in ``mcause`` is equivalent to reading or writing the homonymous field in ``mstatus``.

Machine Trap Value (``mtval``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down
12 changes: 7 additions & 5 deletions docs/user_manual/source/exceptions_interrupts.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,8 +62,8 @@ If multiple interrupts are pending, they are handled in the fixed priority order
The highest priority is given to the interrupt with the highest ID, except for the Machine Timer Interrupt, which has the lowest priority. So from high to low priority the interrupts are
ordered as follows:

* ``store bus fault NMI (1021)``
* ``load bus fault NMI (1020)``
* ``store bus fault NMI (1025)``
* ``load bus fault NMI (1024)``
* ``irq_i[31]``
* ``irq_i[30]``
* ...
Expand All @@ -90,9 +90,9 @@ In Debug Mode, all interrupts are ignored independent of ``mstatus.MIE`` and the
+----------------+----------------+-------------------------------------------------+-----------------------------------------------------------------+
| 1 | 31-16 | Machine Fast Interrupts | ``irq_i[31]``-``irq_i[16]`` |
+----------------+----------------+-------------------------------------------------+-----------------------------------------------------------------+
| 1 | 1020 | Load bus fault NMI (imprecise) | ``data_err_i`` = 1 and ``data_rvalid_i`` = 1 for load |
| 1 | 1024 | Load bus fault NMI (imprecise) | ``data_err_i`` = 1 and ``data_rvalid_i`` = 1 for load |
+----------------+----------------+-------------------------------------------------+-----------------------------------------------------------------+
| 1 | 1021 | Store bus fault NMI (imprecise) | ``data_err_i`` = 1 and ``data_rvalid_i`` = 1 for store |
| 1 | 1025 | Store bus fault NMI (imprecise) | ``data_err_i`` = 1 and ``data_rvalid_i`` = 1 for store |
+----------------+----------------+-------------------------------------------------+-----------------------------------------------------------------+

.. note::
Expand All @@ -109,7 +109,9 @@ CLIC interrupt handling mode can be used and the ``irq_i[31:0]`` pins are ignore
Interrupts - ``SMCLIC`` == 1
----------------------------

Although the [RISC-V-SMCLIC] specification supports up to 4096 interrupts, |corev| itself is limited to supporting 1024 interrupts (of which interrupts 1020-1023 are reserved for NMIs).
Although the [RISC-V-SMCLIC]_ specification supports up to 4096 interrupts, |corev| itself supports at most 1024 interrupts. The
maximum number of supported CLIC interrupts is equal to ``2^SMCLIC_ID_WIDTH``, which can range from 64 to 1024. The ``SMCLIC_ID_WIDTH`` parameter
also dictates the minimum alignment requirement for the trap vector table to ``2^(2+SMCLIC_ID_WIDTH)`` byte boundaries, see :ref:`csr-mtvt`.

Non Maskable Interrupts
-----------------------
Expand Down
14 changes: 10 additions & 4 deletions docs/user_manual/source/integration.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,8 @@ Instantiation Template
.NUM_MHPMCOUNTERS ( 1 ),
.PMA_NUM_REGIONS ( 1 ),
.PMA_CFG ( PMA_CFG[] ),
.SMCLIC ( 0 )
.SMCLIC ( 0 ),
.SMCLIC_ID_WIDTH ( 0 )
) u_core (
// Clock and reset
.clk_i (),
Expand Down Expand Up @@ -174,6 +175,11 @@ Parameters
+------------------------------+----------------+---------------+--------------------------------------------------------------------+
| ``SMCLIC`` | int (0..1 ) | 0 | Is Smclic supported? |
+------------------------------+----------------+---------------+--------------------------------------------------------------------+
| ``SMCLIC_ID_WIDTH`` | int (6..10 ) | 6 | Width of ``clic_irq_id_i`` and ``clic_irq_id_o``. The maximum |
| | | | number of supported interrupts in CLIC mode is |
| | | | ``2^SMCLIC_ID_WIDTH``. Trap vector table alignment is restricted |
| | | | to at least ``2^(2+SMCLIC_ID_WIDTH)``, see :ref:`csr-mtvt`. |
+------------------------------+----------------+---------------+--------------------------------------------------------------------+


Interfaces
Expand All @@ -199,9 +205,9 @@ Interfaces
| | | | core via ``fetch_enable_i`` |
+-------------------------+-------------------------+-----+--------------------------------------------+
| ``mtvec_addr_i`` | 32 | in | ``mtvec`` address. Initial value for the |
| | | | address part of :ref:`csr-mtvec`. |
| | | | Must be 4096-byte aligned |
| | | | (i.e. ``mtvec_addr_i[11:0]`` = 0). |
| | | | address part of :ref:`csr-mtvec `. |
| | | | Must be 128-byte aligned |
| | | | (i.e. ``mtvec_addr_i[6:0]`` = 0). |
| | | | Do not change after enabling core |
| | | | via ``fetch_enable_i`` |
+-------------------------+-------------------------+-----+--------------------------------------------+
Expand Down
10 changes: 5 additions & 5 deletions docs/user_manual/source/intro.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,11 +39,11 @@ It follows these specifications:
.. [RISC-V-PRIV] RISC-V Instruction Set Manual, Volume II: Privileged Architecture, Document Version 20211105-signoff (November 5, 2021),
https://github.com/riscv/riscv-isa-manual/releases/download/draft-20211105-c30284b/riscv-privileged.pdf
.. [RISC-V-DEBUG] RISC-V External Debug Support, version 1.0.0, 2021-10-07,
https://github.com/riscv/riscv-debug-spec/blob/master/riscv-debug-stable.pdf
.. [RISC-V-DEBUG] RISC-V Debug Support, version 1.0.0-STABLE, fe3d1e65efed4b56574c50867830c3c499f9b18c,
https://github.com/riscv/riscv-debug-spec/blob/b659d7dc7f578e1a2a76f9e62a5eec0f2d80045c/riscv-debug-stable.pdf
.. [RISC-V-SMCLIC] "Smclic" Core-Local Interrupt Controller (CLIC) RISC-V Privileged Architecture Extension, version 0.9-draft, 12/21/2021,
https://github.com/riscv/riscv-fast-interrupt/blob/master/clic.pdf
.. [RISC-V-SMCLIC] "Smclic" Core-Local Interrupt Controller (CLIC) RISC-V Privileged Architecture Extension, version 0.9-draft, 2/15/2022,
https://raw.githubusercontent.com/riscv/riscv-fast-interrupt/0b0083ee0af0cd88d59cdcf81e89cd3f9859e9ad/clic.pdf
.. [RISC-V-ZBA_ZBB_ZBC_ZBS] RISC-V Bit Manipulation ISA-extensions, Version 1.0.0-38-g865e7a7, 2021-06-28,
https://github.com/riscv/riscv-bitmanip/releases/download/1.0.0/bitmanip-1.0.0-38-g865e7a7.pdf
Expand All @@ -57,7 +57,7 @@ It follows these specifications:
.. [OPENHW-OBI] OpenHW Open Bus Interface (OBI) protocol, version 1.2,
https://github.com/openhwgroup/core-v-docs/blob/master/cores/obi/OBI-v1.2.pdf
.. [OPENHW-XIF] OpenHW eXtension Interface, revision fa77b73e,
.. [OPENHW-XIF] OpenHW eXtension Interface, revision 458c8a73,
https://docs.openhwgroup.org/projects/openhw-group-core-v-xif/
.. [SYMBIOTIC-RVFI] Symbiotic EDA RISC-V Formal Interface
Expand Down

0 comments on commit 380b9fd

Please sign in to comment.