Documentation: power: Add document on debugging shutdown hangs
PATCH 1/1 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 <[email protected]>
Signed-off-by Mario Limonciello (AMD) <[email protected]>
--- Documentation/power/index.rst | 1 + Documentation/power/shutdown-debugging.rst | 53 ++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 Documentation/power/shutdown-debugging.rst
Documentation/power/index.rst +1 -0
@@ -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 new file +53 -0
53 lines not on this page · raw message
Signature · 1 line
2.43.0
Quoted 76 lines · Mario Limonciello (AMD)
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 <[email protected]>Signed-off-by Mario Limonciello (AMD) <[email protected]>--- Documentation/power/index.rst | 1 + Documentation/power/shutdown-debugging.rst | 53 ++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 Documentation/power/shutdown-debugging.rstDocumentation/power/index.rst +1
-0@@ -19,6 +19,7 @@ Power Management power_supply_class runtime_pm s2ram + shutdown-debugging suspend-and-cpuhotplug suspend-and-interrupts swsusp-and-swap-filesDocumentation/power/shutdown-debugging.rst new file +44
-0@@ -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
Documentation/power/shutdown-debugging.rst
Quoted 10 lines
Documentation/power/shutdown-debugging.rst new file +9
-1+======================================= +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 --
Applied as 6.19 material, thanks!