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