admin/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2025-12-07 20:06:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation: power: Add document on debugging shutdown hangs

Browse Source 
If the kernel hangs while shutting down, ideally a UART log should
be captured to debug the problem.  However if one isn't available,
users can use the pstore functionality to retrieve logs.

Add a document explaining how this works to make it more accessible
to users.

Tested-by: Harry Wentland <harry.wentland@amd.com>
Signed-off-by: Mario Limonciello (AMD) <superm1@kernel.org>
Link: https://patch.msgid.link/20251025004341.2386868-1-superm1@kernel.org
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
This commit is contained in:
Mario Limonciello (AMD)
2025-10-24 19:43:34 -05:00
committed by Rafael J. Wysocki
parent 1cf9c4f115
commit b1f02f005a
2 changed files with 54 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
Documentation/power/index.rst
View File

@@ -19,6 +19,7 @@ Power Management
power_supply_class power_supply_class
runtime_pm runtime_pm
s2ram s2ram
shutdown-debugging
suspend-and-cpuhotplug suspend-and-cpuhotplug
suspend-and-interrupts suspend-and-interrupts
swsusp-and-swap-files swsusp-and-swap-files

53
Documentation/power/shutdown-debugging.rst Normal file
View File

@@ -0,0 +1,53 @@
.. SPDX-License-Identifier: GPL-2.0
Debugging Kernel Shutdown Hangs with pstore
+++++++++++++++++++++++++++++++++++++++++++
Overview
========
If the system hangs while shutting down, the kernel logs may need to be
retrieved to debug the issue.
On systems that have a UART available, it is best to configure the kernel to use
this UART for kernel console output.
If a UART isn't available, the ``pstore`` subsystem provides a mechanism to
persist this data across a system reset, allowing it to be retrieved on the next
boot.
Kernel Configuration
====================
To enable ``pstore`` and enable saving kernel ring buffer logs, set the
following kernel configuration options:
* ``CONFIG_PSTORE=y``
* ``CONFIG_PSTORE_CONSOLE=y``
Additionally, enable a backend to store the data. Depending upon your platform
some options include:
* ``CONFIG_EFI_VARS_PSTORE=y``
* ``CONFIG_PSTORE_RAM=y``
* ``CONFIG_PSTORE_FIRMWARE=y``
* ``CONFIG_PSTORE_BLK=y``
Kernel Command-line Parameters
==============================
Add these parameters to your kernel command line:
* ``printk.always_kmsg_dump=Y``
* Forces the kernel to dump the entire message buffer to pstore during
shutdown
* ``efi_pstore.pstore_disable=N``
* For EFI-based systems, ensures the EFI backend is active
Userspace Interaction and Log Retrieval
=======================================
On the next boot after a hang, pstore logs will be available in the pstore
filesystem (``/sys/fs/pstore``) and can be retrieved by userspace.
On systemd systems, the ``systemd-pstore`` service will help do the following:
#. Locate pstore data in ``/sys/fs/pstore``
#. Read and save it to ``/var/lib/systemd/pstore``
#. Clear pstore data for the next event