| .. 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 |
