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