From b1f02f005a2e01287cdb627e1c03c3deb73c5163 Mon Sep 17 00:00:00 2001 From: "Mario Limonciello (AMD)" Date: Fri, 24 Oct 2025 19:43:34 -0500 Subject: [PATCH] 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: Harry Wentland Signed-off-by: Mario Limonciello (AMD) Link: https://patch.msgid.link/20251025004341.2386868-1-superm1@kernel.org Signed-off-by: Rafael J. Wysocki --- Documentation/power/index.rst | 1 + Documentation/power/shutdown-debugging.rst | 53 ++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 Documentation/power/shutdown-debugging.rst diff --git a/Documentation/power/index.rst b/Documentation/power/index.rst index a0f5244fb4279..ea70633d9ce6c 100644 --- a/Documentation/power/index.rst +++ b/Documentation/power/index.rst @@ -19,6 +19,7 @@ Power Management power_supply_class runtime_pm s2ram + shutdown-debugging suspend-and-cpuhotplug suspend-and-interrupts swsusp-and-swap-files diff --git a/Documentation/power/shutdown-debugging.rst b/Documentation/power/shutdown-debugging.rst new file mode 100644 index 0000000000000..cdfa2cd90e5c6 --- /dev/null +++ b/Documentation/power/shutdown-debugging.rst @@ -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 -- 2.47.3