Traps_Interrupts_Exceptions.rst: update chapter

docs/01_cva6_user/Traps_Interrupts_Exceptions.rst

@@ -1,25 +1,134 @@
-..
-   Copyright (c) 2023 OpenHW Group
-   Copyright (c) 2023 Thales DIS design services SAS
-
-   SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1
-
-.. Level 1
-   =======
-
-   Level 2
-   -------
-
-   Level 3
-   ~~~~~~~
-
-   Level 4
-   ^^^^^^^
-
-.. _cva6_traps_interrupts_exceptions:
-
-Traps, Interrupts, Exceptions
-=============================
-Gap for step1 verification. Reuse DVplan from E4? Jean-Roch will check with André. Mike will reach out to some people who could help.
-We expect this section to be 1 page.
-
+..
+   Copyright (c) 2023 OpenHW Group
+   Copyright (c) 2023 Thales DIS SAS
+
+   SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1
+
+.. Level 1
+   =======
+
+   Level 2
+   -------
+
+   Level 3
+   ~~~~~~~
+
+   Level 4
+   ^^^^^^^
+
+.. _cva6_traps_interrupts_exceptions:
+
+Traps, Interrupts, Exceptions
+=============================
+Traps are composed of interrupts and exceptions.
+Interrupts are asynchronous events whereas exceptions are synchronous ones.
+On one hand, interrupts are occuring independently of the instructions
+(mainly raised by peripherals or debug module).
+On the other hand, an instruction may raise exceptions synchronously.
+
+Raising Traps
+=============
+When a trap is raised, the behaviour of the CVA6 core depends on
+several CSRs and some CSRs are modified. The CSR description is available
+in :doc:`CV32A6_Control_Status_Registers.rst`.
+
+Configuration CSRs
+------------------
+CSRs having an effect on the core behaviour when a trap occurs are:
+
+* ``mstatus`` and ``sstatus``: several fields control the core behaviour like interrupt enable (``MIE``, ``SIE``)
+* ``mtvec`` and ``stvec``: specifies the address of trap handler.
+* ``medeleg``: specifies which exceptions can be handled by a lower privileged mode (S-mode)
+* ``mideleg``: specifies which interrupts can be handled by a lower privileged mode (S-mode)
+
+Modified CSRs
+-------------
+CSRs (or fields) updated by the core when a trap occurs are:
+
+* ``mstatus`` or ``sstatus``: several fields are updated like previous privilege mode (``MPP``, ``SPP``), previous interrupt enabled (``MPIE``, SPIE``)
+* ``mepc`` or ``sepc``: updated with the virtual address of the interrupted instruction or the instruction raising the exception.
+* ``mcause`` or ``scause``: updated with a code indicating the event causing the trap.
+* ``mtval`` or ``stval``: updated with exception specific information like the faulting virtual address
+
+Supported exceptions
+--------------------
+The following exceptions are supported by the CVA6:
+
+* instruction address misaligned
+
+  * control flow instruction with misaligned target
+
+* instruction access fault
+
+  * access to PMP region without execute permissions
+
+* illegal instruction:
+
+  * unimplemented CSRs
+  * unsupported extensions
+
+* breakpoint (``EBREAK``)
+* load address misaligned:
+
+  * ``LH`` at 2n+1 address
+  * ``LW`` at 4n+1, 4n+2, 4n+3 address
+
+* load access fault
+
+  * access to PMP region without read permissions
+
+* store/AMO address misaligned
+
+  * ``SH`` at 2n+1 address
+  * ``SW`` at 4n+1, 4n+2, 4n+3 address
+
+* store/AMO access fault
+
+  * access to PMP region without write permissions
+
+* environment call (``ECALL``) from U-mode
+* environment call (``ECALL``) from S-mode
+* environment call (``ECALL``) from M-mode
+* instruction page fault
+* load page fault
+
+  * access to effective address without read permissions
+
+* store/AMO page fault
+
+  * access to effective address without write permissions
+
+* debug request (custom) via debug interface
+
+Note: all exceptions are supported except the ones linked to the hypervisor extension
+
+Trap return
+===========
+Trap handler ends with trap return instruction (``MRET``, ``SRET``). The behaviour of the CVA6 core depends on several CSRs.
+
+Configuration CSRs
+------------------
+CSRs having an effect on the core behaviour when returning from a trap are:
+
+* ``mstatus``: several fields control the core behaviour like previous privilege mode (``MPP``, ``SPP``), previous interrupt enabled (``MPIE``, ``SPIE``)
+
+Modified CSRs
+-------------
+CSRs (or fields) updated by the core when returning from a trap are:
+
+* ``mstatus``: several fields are updated like interrupt enable (``MIE``, ``SIE``), modify privilege (``MPRV``)
+
+Interrupts
+==========
+* external interrupt: ``irq_i`` signal
+* software interrupt (inter-processor interrupt): ``ipi_i`` signal
+* timer interrupt: ``time_irq_i`` signal
+* debug interrupt: ``debug_req_i`` signal
+
+These signals are level sensitive. It means the interrupt is raised until it is cleared.
+
+The exception code field (``mcause`` CSR) depends on the interrupt source.
+
+Wait for Interrupt
+==================
+* CVA6 implementation: ``WFI`` stalls the core. The instruction is not available in U-mode (raise illegal instruction exception). Such exception is also raised when ``TW=1`` in ``mstatus``.