Skip to content

Commit f044977

Browse files
akashdeep-ticshilwant
akashdeep-ti
authored and
cshilwant
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 bad3adf commit f044977

File tree

4 files changed

+206
-0
lines changed

4 files changed

+206
-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/common/Tools/_SYSFW_Trace_Parser.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _sysfw-trace-parser:
2+
13
Enabling and Parsing SYSFW Trace
24
================================
35

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

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