Skip to content

docs(linux): Power_Management: LPM documentation cleanups #102

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cshilwant merged 4 commits into from
Dec 14, 2024
Merged

docs(linux): Power_Management: LPM documentation cleanups #102

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8006bb1
docs(linux): Power_Management: Cleanup documentation
kwillis01 Dec 11, 2024
1948172
docs(linux): Power_Management: Put latency constraint in correct section
kwillis01 Dec 11, 2024
ebe7b88
docs(linux): Power_Management: Fix MCU GPIO wakeup pin
kwillis01 Dec 11, 2024
991b4ff
docs(linux): Power_Management: Update URL tags to 10.01
kwillis01 Dec 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion source/linux/Foundational_Components/Power_Management/pm_dfs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -332,9 +332,10 @@ table.
};

To disable any of the above OPP's one can simply add

.. code-block:: dts

status = "disabled";
status = "disabled";

to the corresponding DT Node.

Expand Down
8 changes: 4 additions & 4 deletions source/linux/Foundational_Components/Power_Management/pm_low_power_modes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ sources is found to be enabled, Partial I/O is entered instead of poweroff.

The following wakeup sources have been configured for Partial I/O:
mcu_uart0, mcu_mcan0, and mcu_mcan1. Partial I/O mode can only be tested
when `k3-am62x-sk-lpm-wkup-sources.dtso <https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/arch/arm64/boot/dts/ti/k3-am62x-sk-lpm-wkup-sources.dtso?h=10.00.07>`__
when `k3-am62x-sk-lpm-wkup-sources.dtso <https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/arch/arm64/boot/dts/ti/k3-am62x-sk-lpm-wkup-sources.dtso?h=10.01.10>`__
overlay is loaded. Please refer to :ref:`How to enable DT overlays<howto_dt_overlays>` for more details.

After Linux boots, the MCAN wakeup for Partial I/O is enabled using the
Expand Down Expand Up @@ -250,7 +250,7 @@ The benefits of using deep sleep in embedded devices:
reducing the amount of time that the processor is idle. This is because the processor can
be kept in a low-power state when it is not needed.

In order to enter deep sleep, use the following command:
In order to enter Deep Sleep, use the following command:

.. ifconfig:: CONFIG_part_variant in ('AM62X')

Expand Down Expand Up @@ -298,7 +298,7 @@ In order to enter deep sleep, use the following command:
[ 230.292413] psci: CPU2 killed (polled 4 ms)
[ 230.295457] psci: CPU3 killed (polled 0 ms)

This partially indicates that linux has finished it's deep sleep sequence.
This partially indicates that Linux has finished it's Deep Sleep suspend sequence.
For further confirmation, one can take a look at the PMIC_LPM_EN pin on the EVM
(after programming the PMCTRL_SYS register (0x43018080) to 0x15). Here, if the pin is 3.3V when active and
0V when in deep sleep.
Expand All @@ -320,7 +320,7 @@ Similar to Deep Sleep, with the major distinction being that the MCU core is kep
The benefits of using MCU Only mode:

#. Low power consumption: MCU Only mode can save a significant amount of power, especially in battery-powered
devices. This is because The rest of the SoC status is the same as Deep Sleep and DDR is in self-refresh.
devices. This is because the rest of the SoC status is the same as Deep Sleep and DDR is in self-refresh.
#. Run background tasks: This mode can be used to run background tasks that do not require the full power of the system.
For example, you could use the firmware on the MCU core to run a watchdog timer, a sensor polling loop,
or a network communication task.
Expand Down
34 changes: 17 additions & 17 deletions source/linux/Foundational_Components/Power_Management/pm_sw_arch.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,12 @@ Overview
TI AM62 family of devices support multiple Suspend-to-RAM modes, including Deep Sleep
and MCU Only as described in :ref:`Low Power Modes<lpm_modes>` section.
The SoC consumes very low power overall yet it is not completely shut off in these modes.
For example, During Deep Sleep, Certain IPs
For example, during Deep Sleep, certain IPs
(depending on the power domain to which then belong) will lose context on suspend.
S/W should save and restore the context as required across state transitions. DDR is in self-
refresh to allow context saving.

This section explains the high-level Software Flow of low power modes in AM62 family of devices.
This section explains the high-level software flow of low power modes in AM62 family of devices.
It also introduces the LPM constraints framework that enables seamless management of
multiple Suspend-to-RAM modes.

Expand All @@ -27,34 +27,34 @@ System diagram and components
.. Image:: /images/AM62x_Deep_Sleep_Flow.png


Above diagram has software sequence for how deep sleep (ie. Suspend to RAM) works on
Above diagram has software sequence for how Deep Sleep (ie. Suspend to RAM) works on
SK-AM62 ( Read more on the Starter Kit `here <https://www.ti.com/tool/SK-AM62>`__ ).

Deep Sleep Entry
================

#. The user first instructs the System to Suspend. This triggers a suspend
sequence from linux side (which runs on the A53 cluster of the SoC).
#. The user first instructs the system to suspend. This triggers a suspend
sequence from Linux side (which runs on the A53 cluster of the SoC).

#. As part of the TI_SCI driver's suspend hook, I/O isolation is invoked which
isolates all the pads from their respective pinmuxed controllers. Refer to
:ref:`Wakeup sources Documentation<pm_wakeup_sources>` to understand more on this.

#. Linux then suspends all the drivers in the order that they are probed.
After ensuring that there were no faults in suspending the drivers, linux
After ensuring that there were no faults in suspending the drivers, Linux
then issues core system suspend which ultimately is a PSCI system
suspend call. Read more about PSCI `here <https://developer.arm.com/Architectures/Power%20State%20Coordination%20Interface>`__

#. At this point only ATF is running on A53 cores and it does the job of
sending a TISCI Message to the TIFS Core telling it to enter deep sleep
sending a TISCI Message to the TIFS Core telling it to enter Deep Sleep
and then it puts A53 into standby.

#. The TIFS Core then encrypts and writes the contents of it's own SRAM to DDR.

#. Further it stops tick timer, disables interrupts that are not needed, and suspends local drivers.
After the above steps it sends TISCI To DM for Suspend Finish and enters WFI.

#. The DM (Device Manager) is the final entity in this entire deep sleep sequence. It does the following:
#. The DM (Device Manager) is the final entity in this entire Deep Sleep sequence. It does the following:

a. Saves own context to DDR
b. Disables Security IP LPSCs, such as LPSC_SAUL.
Expand Down Expand Up @@ -151,8 +151,8 @@ Specifically, checking of constraints is done at two levels:

The code enabling the constraints framework can be found in:

#. TISCI PM Domain driver: https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/drivers/pmdomain/ti/ti_sci_pm_domains.c?h=10.00.07
#. TISCI driver: https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/drivers/pmdomain/ti/ti_sci_pm_domains.c?h=10.00.07
#. TISCI PM Domain driver: https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/drivers/pmdomain/ti/ti_sci_pm_domains.c?h=10.01.10
#. TISCI driver: https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/drivers/firmware/ti_sci.c?h=10.01.10

Examples of adding constraints from the remote core side are being implemented and will
be enabled in future release.
Expand All @@ -174,11 +174,6 @@ are required.
Some devices may disable the wakeup property by default. These can be enabled via
the sysfs interface (e.g., :file:`/sys/bus/platform/devices/\*/power/wakeup`)

If a device wants to put a constraint to be not powered-off, it can use the Linux
QoS framework and set the DEV_PM_QOS_RESUME_LATENCY equal to 0.
An example is shown in the following RemoteProc driver:
https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/drivers/remoteproc/ti_k3_r5_remoteproc.c?h=10.00.07#n535

Resume Latency Constraint
-------------------------

Expand All @@ -200,6 +195,11 @@ Default constraint is "no constraint", but it can be changed as shown in the exa
Setting a resume latency constraint impacts the deepest low power mode system can enter.
The various modes and their latencies are documented here: https://downloads.ti.com/tisci/esd/latest/2_tisci_msgs/pm/lpm.html#tisci-msg-lpm-set-latency-constraint

If a device wants to put a constraint to not be powered-off, it can use the Linux
QoS framework and set the ``DEV_PM_QOS_RESUME_LATENCY`` equal to 0.
An example is shown in the following RemoteProc driver:
https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/drivers/remoteproc/ti_k3_r5_remoteproc.c?h=10.01.10#n523

.. note::

The constraints need to be set before each system suspend as DM firmware clears all
Expand All @@ -217,15 +217,15 @@ Otherwise, the mode selection is done as described below:

Above diagram shows the mode selection if constraints are set on MCU_WAKEUP devgroup devices.
As shown, if the constraints are set on WAKEUP Domain devices or Always ON MCU domain devices,
deep sleep mode will be selected. Otherwise, MCU Only mode will be selected.
Deep Sleep mode will be selected. Otherwise, MCU Only mode will be selected.

If constraint is put on MAIN devgroup devices, then no low power mode is possible.

.. important::

USB devices are an exception in MAIN devgroup as there is extra hardware logic preventing
reset of USB devices in Deep Sleep and MCU Only mode.
If constraints are set on USB devices, deep sleep mode will be selected even though it's
If constraints are set on USB devices, Deep Sleep mode will be selected even though it's
technically part of MAIN devgroup.

.. ifconfig:: CONFIG_part_variant in ('AM62X')
Expand Down
56 changes: 28 additions & 28 deletions source/linux/Foundational_Components/Power_Management/pm_wakeup_sources.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -274,10 +274,10 @@ MCU GPIO

One of the most common ways to wakeup a system is by using some I/O activity. MCU GPIOs allow us to do this
by configuring the MCU GPIO controller as a wakeup source.
In ideal scenarios, The firmware running on MCU core is responsible for configuring MCU GPIO's as a wakeup source.
In ideal scenarios, the firmware running on MCU core is responsible for configuring MCU GPIO's as a wakeup source.
However, if the application design doesn't rely too much on the MCU firmware then
linux can be used to configure the MCU GPIOs as a wakeup source. You can refer to the mcu_gpio_key node in
`k3-am62x-sk-lpm-wkup-sources.dtso <https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/arch/arm64/boot/dts/ti/k3-am62x-sk-lpm-wkup-sources.dtso?h=10.00.07>`__
Linux can be used to configure the MCU GPIOs as a wakeup source. You can refer to the mcu_gpio_key node in
`k3-am62x-sk-lpm-wkup-sources.dtso <https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/arch/arm64/boot/dts/ti/k3-am62x-sk-lpm-wkup-sources.dtso?h=10.01.10>`__
and use it as a template to configure the MCU GPIO of your choice as a wakeup capable GPIO.

A brief guide to configuring an MCU GPIO as wakeup:
Expand All @@ -302,7 +302,7 @@ Setup the interrupt parent and interrupt as MCU_GPIO0,
.. code-block:: dts

interrupt-parent = <&mcu_gpio0>;
interrupts = <16 IRQ_TYPE_EDGE_RISING>;
interrupts = <4 IRQ_TYPE_EDGE_RISING>;

Now, under the switch node we add the following:

Expand All @@ -311,16 +311,16 @@ Now, under the switch node we add the following:
switch {
label = "MCUGPIO";
linux,code = <143>;
gpios = <&mcu_gpio0 16 GPIO_ACTIVE_LOW>;
gpios = <&mcu_gpio0 4 GPIO_ACTIVE_LOW>;
wakeup-source;
};

#. The label is the descriptive name of the key. The string will reflect under /proc/interrupts as:

.. code-block:: console

root@<machine>:~# cat /proc/interrupts | grep "MCUGPIO"
262: 0 0 0 0 GPIO 16 Edge -davinci_gpio MCUGPIO
root@<machine>:~# cat /proc/interrupts | grep "MCUGPIO"
273: 0 0 0 0 GPIO 4 Edge -davinci_gpio MCUGPIO

#. linux,code: Keycode to emit.
#. gpios: the gpio required to be used as the gpio-key.
Expand All @@ -336,12 +336,12 @@ source and send a wakeup interrupt to the Device Manager. To understand the role
please refer to :ref:`S/W Architecture of System Suspend<pm_sw_arch>`

MCU GPIO wakeup can only be tested when
`k3-am62x-sk-lpm-wkup-sources.dtso <https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/arch/arm64/boot/dts/ti/k3-am62x-sk-lpm-wkup-sources.dtso?h=10.00.07>`__
`k3-am62x-sk-lpm-wkup-sources.dtso <https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/arch/arm64/boot/dts/ti/k3-am62x-sk-lpm-wkup-sources.dtso?h=10.01.10>`__
overlay is loaded. Please refer to :ref:`How to enable DT overlays<howto_dt_overlays>` for more details.

Once the system has entered Deep Sleep or MCU Only mode as shown in the
:ref:`LPM section<lpm_modes>`, wakeup from MCU GPIO0_16 can be triggered
by grounding Pin 11 on J8 MCU Header.
:ref:`LPM section<lpm_modes>`, wakeup from MCU_SPI0_D1 can be triggered
by grounding Pin 4 on J8 MCU Header.

********************
Main I/O Daisy Chain
Expand All @@ -352,16 +352,16 @@ Main UART, GPIO, I2C, etc. The question then arises how to wakeup the SoC from p
to these controllers (for example main UART)? Here's where the role of I/O Daisy Chaining comes in.
At the hardware level, all the pads in an SoC have to be pinmuxed to dedicated controllers like UART or GPIO.

For example, If a key press on Main UART (which is used for linux console logs)
were to wakeup the system from deep sleep then simply configuring the Main UART controller as a
For example, If a key press on Main UART (which is used for Linux console logs)
were to wakeup the system from Deep Sleep then simply configuring the Main UART controller as a
wakeup source wouldn't suffice. This is because the UART controller is powered off and wouldn't be able to
register any key press as such. However, at the "pad" level we are still connected, and the pads have
a specific way to be configured as wakeup sources.

For detailed information and sequence please refer to
I/O Power Management and Daisy Chaining section in the TRM. To briefly explain,
Setting the 29th Bit in the desired padconfig register, allows the pad to act as a wakeup source by
triggering a wake irq to the DM R5 in deep sleep states.
setting the 29th bit in the desired padconfig register, allows the pad to act as a wakeup source by
triggering a wake irq to the DM R5 in Deep Sleep states.

.. note::
|__PART_FAMILY_DEVICE_NAMES__| supports the ability to wakeup using pad based wake event ONLY in Deep Sleep or MCU Only Mode.
Expand All @@ -371,15 +371,15 @@ triggering a wake irq to the DM R5 in deep sleep states.

To demonstrate I/O daisy chain wakeup as part of |__PART_FAMILY_DEVICE_NAMES__| offering, two reference examples are provided:

#. main_uart0 is used where a key press on the linux console can wakeup the system.
#. main_uart0 is used where a key press on the Linux console can wakeup the system.
#. main_gpio is used where activity on configured GPIO pin can wakeup the system.


Main UART
=========

The way to configure UART as an I/O daisy chain wakeup, refer to the
main_uart0 node in `k3-am62x-sk-common.dtsi <https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/arch/arm64/boot/dts/ti/k3-am62x-sk-common.dtsi?h=10.00.07>`_
main_uart0 node in `k3-am62x-sk-common.dtsi <https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/arch/arm64/boot/dts/ti/k3-am62x-sk-common.dtsi?h=10.01.10>`_

.. code-block:: dts

Expand All @@ -388,7 +388,7 @@ main_uart0 node in `k3-am62x-sk-common.dtsi <https://git.ti.com/cgit/ti-linux-ke
interrupt-names = "irq", "wakeup";

Here, we chain the IRQ to the pinctrl driver using the second interrupts-extended entry.
The wake IRQ framework in linux works in such a way that the second entry gets marked as a
The wake IRQ framework in Linux works in such a way that the second entry gets marked as a
wakeup source, and then the pinctrl driver is informed that the pad 0x1c8 in this case is to
be configured as a wakeup pad when system enters deep sleep.

Expand Down Expand Up @@ -427,7 +427,7 @@ Then, run this script:


This will configure UART to act as deep sleep wakeup source, and
then a *key press* on same terminal should trigger a wakeup from deep sleep.
then a *key press* on same terminal should trigger a wakeup from Deep Sleep.

Any other pad can be chosen as per application requirements depending on which pad is required
to wakeup the system.
Expand All @@ -442,10 +442,10 @@ configuration and working of these frameworks have been covered under
the MCU GPIO and Main UART sections.

The reference configuration for Main GPIO wakeup can be found under
gpio_key node in `k3-am62x-sk-lpm-wkup-sources.dtso <https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/arch/arm64/boot/dts/ti/k3-am62x-sk-lpm-wkup-sources.dtso?h=10.00.07#n21>`__
gpio_key node in `k3-am62x-sk-lpm-wkup-sources.dtso <https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/arch/arm64/boot/dts/ti/k3-am62x-sk-lpm-wkup-sources.dtso?h=10.01.10#n21>`__

Main GPIO wakeup can only be tested when
`k3-am62x-sk-lpm-wkup-sources.dtso <https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/arch/arm64/boot/dts/ti/k3-am62x-sk-lpm-wkup-sources.dtso?h=10.00.07>`__
`k3-am62x-sk-lpm-wkup-sources.dtso <https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/arch/arm64/boot/dts/ti/k3-am62x-sk-lpm-wkup-sources.dtso?h=10.01.10>`__
overlay is loaded. Please refer to :ref:`How to enable DT overlays<howto_dt_overlays>` for more details.

To use main_gpio as a wakeup source, ensure gpio is a wake-irq in /proc/interrupts:
Expand All @@ -469,7 +469,7 @@ Sleep and MCU Only modes.
In order to use WKUP UART as a wakeup source, it needs to be configured
in a generic way using the ti-sysc interconnect target module driver.
The reference configuration can be found under target-module in
`k3-am62-wakeup.dtsi <https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/arch/arm64/boot/dts/ti/k3-am62-wakeup.dtsi?h=10.00.07#n36>`__
`k3-am62-wakeup.dtsi <https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/arch/arm64/boot/dts/ti/k3-am62-wakeup.dtsi?h=10.01.10#n36>`__

WKUP UART is generally available on the third serial port
(/dev/ttyUSB2) and by default it only shows output from DM R5.
Expand Down Expand Up @@ -516,7 +516,7 @@ Plug in a USB device to one of the port on the board and check that the device i
Follow the steps described in :ref:`LPM section<lpm_modes>` to put the system in Low Power Mode via Deep Sleep or MCU only method.

Once the system is suspended, disconnect the USB device from the board and this should wakeup the system.
And device would not show up in list of USB enumerated devices. This can be verified by executing
The device will not show up in list of USB enumerated devices. This can be verified by executing

.. code-block:: console

Expand All @@ -541,13 +541,13 @@ It should show "suspended", indicating that the keyboard has entered into suspen

.. code-block:: console

# cat /sys/bus/usb/devices/1-1/power/runtime_status
# cat /sys/bus/usb/devices/1-1/power/runtime_status

Now press a key on the keyboard and check the runtime power status and it would come back to "active".

.. code-block:: console

# cat /sys/bus/usb/devices/1-1/power/runtime_status
# cat /sys/bus/usb/devices/1-1/power/runtime_status

Follow the steps described in :ref:`LPM section<lpm_modes>` to put the system in Low Power Mode via Deep Sleep or MCU only method.

Expand All @@ -556,7 +556,7 @@ And USB keyboard would still be present in the system's list of USB enumerated d

.. code-block:: console

# lsusb -t
# lsusb -t

Device Mode Wakeup Events
=========================
Expand All @@ -568,17 +568,17 @@ Load a USB gadget driver such as g_zero

.. code-block:: console

# modprobe g_zero
# modprobe g_zero

Follow the steps described in :ref:`LPM section<lpm_modes>` to put the system in Low Power Mode via Deep Sleep or MCU only method.

Once the system has entered the suspend state, plug a cable from a different Host system to the board's USB DRP port.
This should wakeup the system and gadget would be enumerated on the Host. Enumeration of the gadget on the Host system can be verified by executing the
This should wakeup the system and gadget will be enumerated on the Host. Enumeration of the gadget on the Host system can be verified by executing the
below command on the Host system

.. code-block:: console

HOST:~$ > lsusb -t
HOST:~$ lsusb -t


********************
Expand Down
Loading