doc/usage/pstore.rst

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