Skip to content

Commit

Permalink
Merge pull request #135 from silabs-oysteink/silabs-oysteink_doc-merge2
Browse files Browse the repository at this point in the history 
40X to 40S doc merge
  • Loading branch information
@Silabs-ArjanB
Silabs-ArjanB authored Feb 16, 2022
2 parents 91ea955 + fd76d36 commit 4c5440b
Show file tree
Hide file tree
Showing 5 changed files with 62 additions and 29 deletions.
13 changes: 13 additions & 0 deletions .github/release.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# .github/release.yml

changelog:
exclude:
labels:
- ignore-for-release
categories:
- title: Documentation Changes
labels:
- Component:Doc
- title: RTL Changes
labels:
- Component:RTL
49 changes: 29 additions & 20 deletions docs/user_manual/source/control_status_registers.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -464,7 +464,7 @@ Machine ISA (``misa``)

CSR Address: 0x301

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

Detailed:

Expand Down Expand Up @@ -612,18 +612,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 @@ -640,14 +639,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 @@ -665,13 +664,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 @@ -771,7 +775,7 @@ CSR Address: 0x320

Reset Value: 0x0000_0005

The performance counter inhibit control register. The default value is to inihibit counters out of reset.
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 @@ -851,14 +855,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 @@ -887,11 +891,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 Expand Up @@ -1267,7 +1276,7 @@ Detailed:
| 31:0 | RW | **DATA** |
+-------+------+------------------------------------------------------------------+

Accessible in Debug Mode or M-Mode, depending on **TDATA1.dmode**.
Accessible in Debug Mode or M-Mode, depending on **TDATA1.DMODE**.
This register stores the instruction address to match against for a breakpoint trigger or the currently selected exception codes for an exception trigger.

Trigger Data Register 3 (``tdata3``)
Expand Down
4 changes: 3 additions & 1 deletion docs/user_manual/source/exceptions_interrupts.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,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
17 changes: 13 additions & 4 deletions docs/user_manual/source/integration.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,8 @@ Instantiation Template
.PMP_MSECCFG_RV ( PMP_MSECCFG_RV ),
.PMA_NUM_REGIONS ( 0 ),
.PMA_CFG ( PMA_CFG[] ),
.SMCLIC ( 0 )
.SMCLIC ( 0 ),
.SMCLIC_ID_WIDTH ( 0 )
) u_core (
// Clock and reset
.clk_i (),
Expand Down Expand Up @@ -90,6 +91,7 @@ Instantiation Template
.data_err_i (),
.data_rchk_i (),
.mcycle_o (),
// Interrupt interface
.irq_i (),
Expand Down Expand Up @@ -169,6 +171,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 @@ -193,9 +200,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 Expand Up @@ -225,6 +232,8 @@ Interfaces
+-------------------------+----------------------------------------------------------------------------+
| ``data_*`` | Load-store unit interface, see :ref:`load-store-unit` |
+-------------------------+----------------------------------------------------------------------------+
| ``mcycle_o`` | Cycle Counter Output |
+-------------------------+----------------------------------------------------------------------------+
| ``irq_*`` | Interrupt inputs, see :ref:`exceptions-interrupts` |
+-------------------------+----------------------------------------------------------------------------+
| ``clic_*`` | CLIC interface, see :ref:`exceptions-interrupts` |
Expand Down
8 changes: 4 additions & 4 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 Down

0 comments on commit 4c5440b

Please sign in to comment.