.. _lowpower:

WFI/WFE Low-Power Mechanism
===========================

The Nuclei processor core can support sleep mode for lower power
consumption.

.. _lowpower_enter_sleep_mode:

Enter the Sleep Mode
--------------------

The Nuclei processor core can enter sleep mode by executing the WFI
instruction. When the core executes the WFI instruction, it will perform
following operations:

-  Stop executing the current instruction stream immediately.

-  Waiting for the core to complete any outstanding transactions, such
   as fetching instructions, load or store operations, to ensure that
   all the transactions sent to the bus are completed.

   .. note::

      If a memory access error exception occurs while waiting for
      a bus operation to complete, the core will enter the exception
      handling mode rather than sleep mode.

-  When all of the outstanding transactions are completed, the core
   safely enters an idle state, which is called the sleep mode.

-  When entered the sleep mode:

   -  The clocks of the main units inside the core will be gated off to
      save dynamic power consumption.

   -  The output signal *core_wfi_mode* of the core will be asserted to
      indicate that this core is in the sleep mode after executing the
      WFI instruction.

   -  The output signal *core_sleep_value* of the core will output the
      value of the CSR register sleepvalue (**Note:** this signal is valid
      only when the core_wfi_mode is asserted; if the signal
      *core_wfi_mode* is 0, then the value of *core_sleep_value* must be
      0). The software can indicate different sleep modes (0 as shallow sleep
      or 1 as deep sleep) by set the CSR register |csr_sleepvalue| in advance.

      .. note::

         - The Nuclei processor core behaves exactly the same for
           different sleep modes. These sleep modes only provide different
           output value (via output signal *core_sleep_value*) for
           different controlling scheme to the Power Management Unit (PMU)
           at the SoC system level.
         - When entering to the deep sleep mode, the processor core will no
           longer be able to be debugged by JTAG interface.

.. _lowpower_wfi:

Wait for Interrupt
-------------------

The Wait for Interrupt mechanism refers to make the core enter the sleep
mode, and the core keeps waiting for an interrupt to wake up.

As described in :ref:`lowpower_enter_sleep_mode`, the **Wait for Interrupt**
mechanism can be implemented by executing the WFI instruction with setting
the value of CSR |csr_wfe|.WFE to 0.

.. _lowpower_wfe:

Wait for Event
---------------

The **Wait for Event** mechanism refers to make the core enter the sleep
mode, and the core keeps waiting for an event to wake up. When the core
wakes up by the event, it continues to execute the previously
interrupted instruction stream.

As mentioned in :ref:`lowpower_enter_sleep_mode`, the **Wait for Event**
mechanism can be implemented by executing the WFI instruction combined
with the following sequence of instructions:

- First step: set the value of |csr_wfe|.WFE to 1.

- Second step: execute the WFI instruction. The core will stay in the
  sleep mode until an event or NMI wakes it up.

- Third step: restore the value of |csr_wfe|.WFE to 0.

.. _lowpower_exit_sleep_mode:

Exit the Sleep Mode
-------------------

The key points of the Nuclei processor core exiting the sleep mode are
as follows:

-  The output signal *core_wfi_mode* of the core is cleared to 0.

-  The core can be woken up in four ways:

   -  NMI

   -  Interrupt

   -  Event

   -  Debug request

These will be described in detail next.

.. _lowpower_wakeup_nmi:

Wake Up by NMI
~~~~~~~~~~~~~~

NMI can always wake up the core. When the core detects a rising edge of
the input signal nmi, the core is woken up and jumps to the NMI service
routine.

.. _lowpower_wakeup_interrupt:

Wake Up by Interrupt
~~~~~~~~~~~~~~~~~~~~

Interrupts can wake up the core as well:

-  If the value of |csr_wfe|.WFE is set to 0, t he core will be waited for the
   interrupt to wake up. In this case, the behavior of WFI wake up is
   just following the RISC-V standard architecture. This document will
   not repeat its content here, please refer to RISC-V standard
   privileged architecture specification for more details.

-  If the value of |csr_wfe|.WFE is set to 1, the core will be waited for an
   event to wake up. Please see the detailed description in the next
   section.

.. _lowpower_wakeup_event:

Wake Up by Event
~~~~~~~~~~~~~~~~

Event can wake up the processor core when the following conditions are
met:

-  If the value of |csr_wfe|.WFE is set to 1, then:

   -  When the core detects that the input signal *rx_evt* (called the
      event signal) is asserted, the core will be woken up and continue
      to execute the previously interrupted instruction stream. Please
      refer to the specific datasheet of the Nuclei processor core for
      details about the signal *rx_evt*.

.. _lowpower_wakeup_debug:

Wake Up by Debug Request
~~~~~~~~~~~~~~~~~~~~~~~~

Debug requests can always wake up the core. If the debugger is
connected, it will also wake up the core and enter the debug mode.