.. 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 potential options include:

• CONFIG_EFI_VARS_PSTORE=y
• CONFIG_PSTORE_RAM=y
• CONFIG_CHROMEOS_PSTORE=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