Skip to content

Commit 7203e8c

Browse files
akashdeep-tiakashdeep-ti
committed
feat(Power_Management): Add LPM failure debugging guide for AM62L
Add detailed documentation for debugging low power mode failures on AM62LX platform. The guide provides step-by-step instructions for enabling SYSFW trace logs and troubleshooting suspend/resume issues. Signed-off-by: Akashdeep Kaur <[email protected]>
1 parent 8056b30 commit 7203e8c

File tree

3 files changed

+213
-0
lines changed

3 files changed

+213
-0
lines changed

‎configs/AM62LX/AM62LX_linux_toc.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@ linux/Foundational_Components/Power_Management/pm_overview
7777
linux/Foundational_Components/Power_Management/pm_cpuidle
7878
linux/Foundational_Components/Power_Management/pm_am62lx_low_power_modes
7979
linux/Foundational_Components/Power_Management/pm_wakeup_sources
80+
linux/Foundational_Components/Power_Management/pm_am62lx_debug
8081

8182
linux/Foundational_Components/System_Security/Security_overview
8283
#linux/Foundational_Components/System_Security/SELinux

‎source/linux/Foundational_Components/Power_Management/pm_am62lx_debug.rst‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
.. _pm_debug:
2+
3+
#################
4+
Debug Information
5+
#################
6+
7+
***************
8+
Low Power Modes
9+
***************
10+
11+
Overview
12+
========
13+
14+
Implementing Low Power Modes requires synchronization between multiple
15+
software components. Debugging a LPM issue requires finding out which
16+
component (Linux, TF-A or TIFS) might be at fault.
17+
18+
The comprehensive way of debugging LPM starts by looking at all
19+
the commands that have been executed by the TIFS and TF-A firmware.
20+
21+
The TIFS and TF-A firmware will trace the low power mode sequence and dump a series of
22+
representative hex values. These hex values are not in human-readable form, so the SYSFW Trace
23+
Parser Script :doc:`/linux/How_to_Guides/Host/SYSFW_Trace_Parser` helps translate the hex values into a readable format.
24+
25+
These transactions can be found on the WKUP UART port (``/dev/ttyUSB2``).
26+
27+
Prerequisites
28+
=============
29+
30+
Before using the parser, the following steps are required to enable the SYSFW trace to include
31+
Low Power Mode sequencing:
32+
33+
1. Enable low power logs in the board configuration file
34+
2. Remove isolation from I/Os and enable appropriate log level in TF-A
35+
36+
Step 1: Enable Low Power Logs in Board Configuration
37+
=====================================================
38+
39+
Apply the following patch in the U-Boot source code to enable trace logs.
40+
41+
File location:
42+
43+
.. code-block:: text
44+
45+
<SDK Install Directory>/board-support/ti-u-boot-<version>/board/ti/am62lx/board-cfg.yaml
46+
47+
Patch to apply:
48+
49+
.. code-block:: diff
50+
51+
diff --git a/board/ti/am62lx/board-cfg.yaml b/board/ti/am62lx/board-cfg.yaml
52+
index a0297c284a6..a535a73734d 100644
53+
--- a/board/ti/am62lx/board-cfg.yaml
54+
+++ b/board/ti/am62lx/board-cfg.yaml
55+
@@ -28,5 +28,5 @@ board-cfg:
56+
subhdr:
57+
magic: 0x020C
58+
size: 8
59+
- trace_dst_enables: 0x00
60+
- trace_src_enables: 0x00
61+
+ trace_dst_enables: 0x0D
62+
+ trace_src_enables: 0x7F
63+
64+
After applying the patch, re-build U-Boot following the instructions in :ref:`u-boot-build-guide-build-k3`.
65+
66+
Make sure to copy the target images to your boot media.
67+
68+
Step 2: Remove I/O Isolation and Enable Logging in TF-A
69+
========================================================
70+
71+
Apply the following patch in the TF-A (Arm Trusted Firmware) source code to disable I/O isolation
72+
and enable debug logging.
73+
74+
File location:
75+
76+
.. code-block:: text
77+
78+
<SDK Install Directory>/board-support/arm-trusted-firmware-<version>/plat/ti/k3/common/am62l_psci.c
79+
80+
Patch to apply:
81+
82+
.. code-block:: diff
83+
84+
diff --git a/plat/ti/k3/common/am62l_psci.c b/plat/ti/k3/common/am62l_psci.c
85+
index 3df4986e5..bd20c8413 100644
86+
--- a/plat/ti/k3/common/am62l_psci.c
87+
+++ b/plat/ti/k3/common/am62l_psci.c
88+
@@ -329,7 +329,7 @@ static void am62l_pwr_domain_suspend(const psci_power_state_t *target_state)
89+
if ((mode == 0) || (mode == 6)) {
90+
INFO("Started Suspend Sequence in ATF\n");
91+
/* Isolate the I/Os to allow I/O Daisy chain wakeup */
92+
- k3_lpm_set_io_isolation(true);
93+
+ // k3_lpm_set_io_isolation(true);
94+
k3_lpm_config_magic_words(mode);
95+
ti_sci_prepare_sleep(mode, context_save_addr, 0);
96+
INFO("sent prepare message\n");
97+
98+
.. important::
99+
100+
Modifying the I/O isolation code will impact the functionality of any wake-up source that uses
101+
I/O Daisy Chain, such as Main Domain UART. Refer to the `TRM <https://www.ti.com/lit/ug/sprujb4a/sprujb4a.pdf>`__
102+
section 6.2.3.11 I/O Power Management and Daisy Chaining for more information.
103+
104+
After applying the patch, re-compile TF-A with ``LOG_LEVEL=20`` (LOG_LEVEL_INFO). Follow the
105+
instructions in :ref:`foundational-components-atf` for building TF-A.
106+
107+
Make sure to copy the new ``bl31.bin`` image to your boot media.
108+
109+
Generating Logs & Running the Parser Script
110+
============================================
111+
112+
Boot the device with the new changes made. To isolate the low power mode related logs, start
113+
running the parser script right before entering low power mode.
114+
115+
Step 1: Prepare the EVM Terminal
116+
---------------------------------
117+
118+
On the EVM terminal, get it ready to enter low power mode:
119+
120+
.. code-block:: console
121+
122+
root@am62lxx-evm:~# echo mem > /sys/power/state
123+
124+
Step 2: Setup the Parser Script on Host
125+
----------------------------------------
126+
127+
On the Host terminal, setup the script:
128+
129+
.. code-block:: console
130+
131+
HOST:~$ cd <SDK Install Directory>/bin
132+
HOST:~$ python3 sysfw_trace_parser.py -d /dev/ttyUSB2 -o <output file> -Tv <version>
133+
134+
For example, using version ``0x03007``:
135+
136+
.. code-block:: console
137+
138+
HOST:~$ python3 sysfw_trace_parser.py -d /dev/ttyUSB2 -o am62lx_lpm_trace.txt -Tv 0x03007
139+
140+
Step 3: Execute and Capture Logs
141+
---------------------------------
142+
143+
Once both terminals are ready:
144+
145+
1. Run the Parser Script on the host terminal
146+
2. Execute the low power command on the EVM terminal
147+
3. Send a keyboard interrupt (``Ctrl + C``) to the parser script once the device wakes up
148+
149+
The human-readable logs will be saved in the designated output file.
150+
151+
Alternative: Direct Terminal Output
152+
------------------------------------
153+
154+
Alternatively, the parser script can write the log output directly to the terminal instead of
155+
a file:
156+
157+
.. code-block:: console
158+
159+
HOST:~$ python3 sysfw_trace_parser.py -d /dev/ttyUSB2 -O -Tv 0x03007
160+
161+
Troubleshooting: Parser Errors
162+
===============================
163+
164+
Sometimes the parser results in an error:
165+
166+
.. code-block:: text
167+
168+
invalid literal for int() with base 16: '0x6C001700H0x6C001820'
169+
170+
**Workaround:** Copy the logs directly from ``/dev/ttyUSB2`` and save it as an input file.
171+
The error is caused by the hex values not creating a new line.
172+
173+
When using the workaround with a saved log file, run the parser script as follows:
174+
175+
.. code-block:: console
176+
177+
HOST:~$ python3 sysfw_trace_parser.py -l <input hex log file> -o <output file> -Tv 0x03007
178+
179+
Or for direct terminal output:
180+
181+
.. code-block:: console
182+
183+
HOST:~$ python3 sysfw_trace_parser.py -l <input hex log file> -O -Tv 0x03007
184+
185+
Interpreting the Logs
186+
======================
187+
188+
The generated logs contain detailed information about the low power mode sequence execution.
189+
190+
.. note::
191+
192+
For detailed information on interpreting the logs, refer to the `low power mode sequence documentation <https://software-dl.ti.com/tisci/esd/latest/4_trace/trace.html#low-power-mode-sequence-id>`__.
193+
194+
The logs will show:
195+
196+
- Security management action IDs and their status
197+
- Sequence of operations during suspend and resume
198+
- Any errors or warnings during the low power mode transition
199+
200+
Additional information: Decoding Drivers Failure during suspend
201+
===============================================================
202+
203+
Sometimes the suspend does not go through. In that case, the console suspend can be delayed to get the logs at
204+
low power mode suspend time using the below command:
205+
206+
.. code-block:: console
207+
208+
root@am62lxx-evm:~# echo N | sudo tee /sys/module/printk/parameters/console_suspend
209+
root@am62lxx-evm:~# echo mem > /sys/power/state
210+
211+
This can be used to debug whether any drivers in linux failed to enter suspend.

‎source/linux/Foundational_Components_Power_Management.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,4 @@ Power Management
1616
Foundational_Components/Power_Management/pm_wakeup_sources
1717
Foundational_Components/Power_Management/pm_sw_arch
1818
Foundational_Components/Power_Management/pm_debug
19+
Foundational_Components/Power_Management/pm_am62lx_debug

0 commit comments

Comments
 (0)