Commit b1f02f00 authored by Mario Limonciello (AMD)'s avatar Mario Limonciello (AMD) Committed by Rafael J. Wysocki
Browse files

Documentation: power: Add document on debugging shutdown hangs 



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: default avatarHarry Wentland <harry.wentland@amd.com>
Signed-off-by: default avatarMario Limonciello (AMD) <superm1@kernel.org>
Link: https://patch.msgid.link/20251025004341.2386868-1-superm1@kernel.org


Signed-off-by: default avatarRafael J. Wysocki <rafael.j.wysocki@intel.com>
parent 1cf9c4f1

Documentation/power/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -19,6 +19,7 @@ Power Management 
    power_supply_class

    runtime_pm

    s2ram

    shutdown-debugging

    suspend-and-cpuhotplug

    suspend-and-interrupts

    swsusp-and-swap-files

Documentation/power/shutdown-debugging.rst

0 → 100644
+53 −0
Original line number Diff line number Diff line 
.. 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