1.. SPDX-License-Identifier: GPL-2.0 2 3Debugging Kernel Shutdown Hangs with pstore 4+++++++++++++++++++++++++++++++++++++++++++ 5 6Overview 7======== 8If the system hangs while shutting down, the kernel logs may need to be 9retrieved to debug the issue. 10 11On systems that have a UART available, it is best to configure the kernel to use 12this UART for kernel console output. 13 14If a UART isn't available, the ``pstore`` subsystem provides a mechanism to 15persist this data across a system reset, allowing it to be retrieved on the next 16boot. 17 18Kernel Configuration 19==================== 20To enable ``pstore`` and enable saving kernel ring buffer logs, set the 21following kernel configuration options: 22 23* ``CONFIG_PSTORE=y`` 24* ``CONFIG_PSTORE_CONSOLE=y`` 25 26Additionally, enable a backend to store the data. Depending upon your platform 27some potential options include: 28 29* ``CONFIG_EFI_VARS_PSTORE=y`` 30* ``CONFIG_PSTORE_RAM=y`` 31* ``CONFIG_CHROMEOS_PSTORE=y`` 32* ``CONFIG_PSTORE_BLK=y`` 33 34Kernel Command-line Parameters 35============================== 36Add these parameters to your kernel command line: 37 38* ``printk.always_kmsg_dump=Y`` 39 * Forces the kernel to dump the entire message buffer to pstore during 40 shutdown 41* ``efi_pstore.pstore_disable=N`` 42 * For EFI-based systems, ensures the EFI backend is active 43 44Userspace Interaction and Log Retrieval 45======================================= 46On the next boot after a hang, pstore logs will be available in the pstore 47filesystem (``/sys/fs/pstore``) and can be retrieved by userspace. 48 49On systemd systems, the ``systemd-pstore`` service will help do the following: 50 51#. Locate pstore data in ``/sys/fs/pstore`` 52#. Read and save it to ``/var/lib/systemd/pstore`` 53#. Clear pstore data for the next event 54