From a5b5f19101b8a436620dc62f4e1423768ab70d1e Mon Sep 17 00:00:00 2001
From: wuzhenghui <wuzhenghui@espressif.com>
Date: Thu, 30 Oct 2025 17:12:35 +0800
Subject: [PATCH] docs(esp_pm): add PM lock debugging and profiling
 documentation

---
 .../api-reference/system/power_management.rst   | 17 +++++++++++++++++
 .../api-reference/system/power_management.rst   | 17 +++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/docs/en/api-reference/system/power_management.rst b/docs/en/api-reference/system/power_management.rst
index 7d96d7f8d9b..3813e086cdf 100644
--- a/docs/en/api-reference/system/power_management.rst
+++ b/docs/en/api-reference/system/power_management.rst
@@ -92,6 +92,23 @@ Light-sleep duration is chosen to wake up the chip before the nearest event (tas
 
 To skip unnecessary wake-up, you can consider initializing an ``esp_timer`` with the ``skip_unhandled_events`` option as ``true``. Timers with this flag will not wake up the system and it helps to reduce consumption.
 
+Debugging and Profiling
+-----------------------
+
+The power management subsystem provides several functions to help debug and profile power management lock usage in applications:
+
+- :cpp:func:`esp_pm_dump_locks` - Dumps a list of all currently created locks to a specified stream, showing their types, names, and current acquisition status.
+- :cpp:func:`esp_pm_get_lock_stats_all` - Retrieves statistics for all PM lock types, including the number of locks created and the number currently acquired.
+- :cpp:func:`esp_pm_lock_get_stats` - Gets detailed statistics for a specific lock instance, including acquisition count and (if profiling is enabled) the number of times taken and total time held.
+
+These functions are particularly useful for:
+
+1. Identifying leaks where locks are acquired but never released
+2. Understanding which components are preventing power savings
+3. Optimizing power consumption by analyzing lock usage patterns
+4. Debugging issues related to lock management in applications
+
+To enable profiling features (timing information for individual locks), enable the :ref:`CONFIG_PM_PROFILING` option in menuconfig.
 
 Dynamic Frequency Scaling and Peripheral Drivers
 ------------------------------------------------
diff --git a/docs/zh_CN/api-reference/system/power_management.rst b/docs/zh_CN/api-reference/system/power_management.rst
index 32efa15b41a..c6c0eb26b1f 100644
--- a/docs/zh_CN/api-reference/system/power_management.rst
+++ b/docs/zh_CN/api-reference/system/power_management.rst
@@ -92,6 +92,23 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求，
 
 为了跳过不必要的唤醒，可以将 ``skip_unhandled_events`` 选项设置为 ``true`` 来初始化 ``esp_timer``。带有此标志的定时器不会唤醒系统，有助于减少功耗。
 
+调试和性能分析
+-----------------------
+
+电源管理子系统提供了几个函数来帮助调试和分析应用程序中的电源管理锁使用情况：
+
+- :cpp:func:`esp_pm_dump_locks` - 将所有当前创建的锁列表转储到指定流，显示其类型、名称和当前获取状态。
+- :cpp:func:`esp_pm_get_lock_stats_all` - 获取所有 PM 锁类型的统计信息，包括创建的锁数量和当前持有数。
+- :cpp:func:`esp_pm_lock_get_stats` - 获取特定锁实例的详细统计信息，包括获取计数（如果启用性能分析）和总占用时间。
+
+这些函数特别适用于：
+
+1. 识别获取但从未释放的锁导致的泄漏
+2. 了解哪些组件阻止了节能
+3. 通过分析锁使用模式来优化功耗
+4. 调试与应用程序中锁管理相关的问题
+
+要启用性能分析功能（单个锁的计时信息），请在 menuconfig 中启用 :ref:`CONFIG_PM_PROFILING` 选项。
 
 动态调频和外设驱动
 ------------------------------------------------