doc/usage/pstore.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2
   3 pstore command
   4 ==============
   5
   6 Synopsis
   7 --------
   8
   9 ::
  10
  11     pstore set <addr> <len> [record-size] [console-size] [ftrace-size] [pmsg_size] [ecc-size]
  12     pstore display [record-type] [nb]
  13     pstore save <interface> <dev[:part]> <directory-path>
  14
  15 Design
  16 ------
  17
  18 Linux PStore and Ramoops modules (Linux config options PSTORE and PSTORE_RAM)
  19 allow to use memory to pass data from the dying breath of a crashing kernel to
  20 its successor. This command allows to read those records from U-Boot command
  21 line.
  22
  23 Ramoops is an oops/panic logger that writes its logs to RAM before the system
  24 crashes. It works by logging oopses and panics in a circular buffer. Ramoops
  25 needs a system with persistent RAM so that the content of that area can survive
  26 after a restart.
  27
  28 Ramoops uses a predefined memory area to store the dump.
  29
  30 Ramoops parameters can be passed as kernel parameters or through Device Tree,
  31 i.e.::
  32
  33     ramoops.mem_address=0x30000000 ramoops.mem_size=0x100000 ramoops.record_size=0x2000 ramoops.console_size=0x2000 memmap=0x100000$0x30000000
  34
  35 The same values should be set in U-Boot to be able to retrieve the records.
  36 This values can be set at build time in U-Boot configuration file, or at runtime.
  37 U-Boot automatically patches the Device Tree to pass the Ramoops parameters to
  38 the kernel.
  39
  40 The PStore configuration parameters are:
  41
  42 ======================= ==========
  43  Name                   Default
  44 ======================= ==========
  45 CMD_PSTORE_MEM_ADDR
  46 CMD_PSTORE_MEM_SIZE     0x10000
  47 CMD_PSTORE_RECORD_SIZE  0x1000
  48 CMD_PSTORE_CONSOLE_SIZE 0x1000
  49 CMD_PSTORE_FTRACE_SIZE  0x1000
  50 CMD_PSTORE_PMSG_SIZE    0x1000
  51 CMD_PSTORE_ECC_SIZE     0
  52 ======================= ==========
  53
  54 Records sizes should be a power of 2.
  55 The memory size and the record/console size must be non-zero.
  56
  57 Multiple 'dump' records can be stored in the memory reserved for PStore.
  58 The memory size has to be larger than the sum of the record sizes, i.e.::
  59
  60     MEM_SIZE >= RECORD_SIZE * n + CONSOLE_SIZE + FTRACE_SIZE + PMSG_SIZE
  61
  62 Usage
  63 -----
  64
  65 Generate kernel crash
  66 ~~~~~~~~~~~~~~~~~~~~~
  67
  68 For test purpose, you can generate a kernel crash by setting reboot timeout to
  69 10 seconds and trigger a panic
  70
  71 .. code-block:: console
  72
  73     $ sudo sh -c "echo 1 > /proc/sys/kernel/sysrq"
  74     $ sudo sh -c "echo 10 > /proc/sys/kernel/panic"
  75     $ sudo sh -c "echo c > /proc/sysrq-trigger"
  76
  77 Retrieve logs in U-Boot
  78 ~~~~~~~~~~~~~~~~~~~~~~~
  79
  80 First of all, unless PStore parameters as been set during U-Boot configuration
  81 and match kernel ramoops parameters, it needs to be set using 'pstore set', e.g.::
  82
  83     => pstore set 0x30000000 0x100000 0x2000 0x2000
  84
  85 Then all available dumps can be displayed
  86 using::
  87
  88     => pstore display
  89
  90 Or saved to an existing directory in an Ext2 or Ext4 partition, e.g. on root
  91 directory of 1st partition of the 2nd MMC::
  92
  93     => pstore save mmc 1:1 /