.. _plic:

PLIC Unit Introduction
======================

PLIC Overview
-------------

For the Linux capable applications or symmetric multi-processor (SMP)
applications, Nuclei processor core have been equipped with a
`Platform-Level Interrupt Controller (PLIC)`_, which is part of RISC-V
standard privileged architecture specification (riscv-privileged-v1.10.pdf),
user can easily get the original copy (riscv-privileged-v1.10.pdf)
from |nuclei_user_center| or from other public channels.

.. note::

   -  The PLIC unit arbitrates the interrupt sources to the processor core
      (as the interrupt target) by a line as shown in :ref:`figure_eclic_plic_conn_2`.
   
   -  The PLIC need to be enabled by setting the LSB bits of CSR registers
      mtvec as CLINT mode. Please refer to :ref:`interrupt_set_clint_or_clic_mode` for the details.
   
   -  The PLIC is functionally exclusive to ECLIC. The ECLIC and PLIC
      connection diagrams are as described in :ref:`eclic_plic_conn`.

.. _plic_registers:

PLIC Registers
--------------

The RISC-V standard privileged architecture specification does not
specify the exact register offset for PLIC. The Nuclei processor core
implements PLIC as a memory-mapped unit:

-  The base address of the PLIC unit, please refer to the specific
   datasheet of the Nuclei processor core.

-  Registers and the corresponding offset in the PLIC unit are shown in
   :ref:`table_plic_1`.

.. _table_plic_1:

.. table:: The address offset of registers in the PLIC unit
   :widths: auto

   +-------------+----------+-------------+-------------+-------------+
   |    Offset   |    Width |             |             |    Default  |
   |             |          |  Permission | Description |    Value    |
   +=============+==========+=============+=============+=============+
   | 0x00_0000   |          |             | Reserved    |             |
   |             |          |             | (source 0   |             |
   |             |          |             | does not    |             |
   |             |          |             | exist)      |             |
   +-------------+----------+-------------+-------------+-------------+
   | 0x00_0004   | 4B       | RW          | Source 1    | 0x0         |
   |             |          |             | priority    |             |
   +-------------+----------+-------------+-------------+-------------+
   | 0x00_0008   | 4B       | RW          | Source 2    | 0x0         |
   |             |          |             | priority    |             |
   +-------------+----------+-------------+-------------+-------------+
   | ……          |          | ……          | ……          | ……          |
   +-------------+----------+-------------+-------------+-------------+
   | 0x00_0FFC   | 4B       | RW          | Source 1023 | 0x0         |
   |             |          |             | priority    |             |
   +-------------+----------+-------------+-------------+-------------+
   | ……          |          | ……          | ……          | ……          |
   +-------------+----------+-------------+-------------+-------------+
   | 0x00_1000   | 4B       | R           | Start of    | 0x0         |
   |             |          |             | pending     |             |
   |             |          |             | array       |             |
   |             |          |             |             |             |
   |             |          |             | (bit 0-31)  |             |
   +-------------+----------+-------------+-------------+-------------+
   | ……          |          | ……          | ……          | ……          |
   +-------------+----------+-------------+-------------+-------------+
   | 0x00_107C   | 4B       | R           | Last word   | 0x0         |
   |             |          |             | of pending  |             |
   |             |          |             | array       |             |
   |             |          |             |             |             |
   |             |          |             | (bit        |             |
   |             |          |             | 992-1023)   |             |
   +-------------+----------+-------------+-------------+-------------+
   | ……          |          | ……          | ……          | ……          |
   +-------------+----------+-------------+-------------+-------------+
   | 0x00_2000   | 4B       | RW          | Start of    | 0x0         |
   |             |          |             | Hart 0      |             |
   |             |          |             | M-mode      |             |
   |             |          |             | interrupt   |             |
   |             |          |             | enables     |             |
   |             |          |             |             |             |
   |             |          |             | (source     |             |
   |             |          |             | 0-31)       |             |
   +-------------+----------+-------------+-------------+-------------+
   | ……          |          | ……          | ……          | ……          |
   +-------------+----------+-------------+-------------+-------------+
   | 0x00_207C   | 4B       | RW          | Last word   |             |
   |             |          |             | of Hart 0   |             |
   |             |          |             | M-mode      |             |
   |             |          |             | interrupt   |             |
   |             |          |             | enables     |             |
   |             |          |             |             |             |
   |             |          |             | (source     |             |
   |             |          |             | 992-1023)   |             |
   +-------------+----------+-------------+-------------+-------------+
   | 0x00_2080   | 4B       | RW          | Start of    |             |
   |             |          |             | Hart 0      |             |
   |             |          |             | S-mode      |             |
   |             |          |             | interrupt   |             |
   |             |          |             | enables     |             |
   |             |          |             |             |             |
   |             |          |             | (source     |             |
   |             |          |             | 0-31)       |             |
   +-------------+----------+-------------+-------------+-------------+
   | ……          |          | ……          | ……          |             |
   +-------------+----------+-------------+-------------+-------------+
   | 0x00_20FC   | 4B       | RW          | Last word   |             |
   |             |          |             | of Hart 0   |             |
   |             |          |             | S-mode      |             |
   |             |          |             | interrupt   |             |
   |             |          |             | enables     |             |
   |             |          |             |             |             |
   |             |          |             | (source     |             |
   |             |          |             | 992-1023)   |             |
   +-------------+----------+-------------+-------------+-------------+
   | 0x20_0000   | 4B       | RW          | Hart 0      | 0x0         |
   |             |          |             | M-mode      |             |
   |             |          |             | Priority    |             |
   |             |          |             | threshold   |             |
   +-------------+----------+-------------+-------------+-------------+
   | 0x20_0004   | 4B       | RW          | Hart 0      | 0x0         |
   |             |          |             | M-mode      |             |
   |             |          |             | Cla\        |             |
   |             |          |             | im/Complete |             |
   +-------------+----------+-------------+-------------+-------------+
   | ……          |          |             | Reserved    |             |
   +-------------+----------+-------------+-------------+-------------+
   | 0x20_1000   | 4B       | RW          | Hart 0      | 0x0         |
   |             |          |             | S-mode      |             |
   |             |          |             | Priority    |             |
   |             |          |             | threshold   |             |
   +-------------+----------+-------------+-------------+-------------+
   | 0x20_1004   | 4B       | RW          | Hart 0      | 0x0         |
   |             |          |             | S-mode      |             |
   |             |          |             | Cla\        |             |
   |             |          |             | im/Complete |             |
   +-------------+----------+-------------+-------------+-------------+

.. note::                                                          
    
    -  PLIC registers only support aligned access which is the size of word.
    -  The above ``R`` means read-only, and any write to this read-only register will be ignored without generating bus error.
    -  The PLIC unit may not be configured to support 1024 interrupt sources. If an interrupt is not present in the hardware,
       the corresponding registers of memory locations appear hardwired to zero.
    -  The PLIC unit has M-mode and S-mode dedicated registers, which can be configured to trigger M-mode interrupt or S-mode interrupt,
       by default, both M-mode and S-mode interrupts are all handled in M-mode, when **mideleg** is configured,
       S-mode interrupts will be delegated to be handled in S-mode, but the M-mode interrupts will still be
       handled in M-mode regardless of the **mideleg**.
    -  The PLIC unit is memory mapped and needs to be protected by PMP if different access permissions are needed for different sources.


.. _Platform-Level Interrupt Controller (PLIC): https://github.com/riscv/riscv-plic-spec/blob/master/riscv-plic.adoc