Let's have a separate chapter dedicated to using U-Boot.
Signed-off-by: Heinrich Schuchardt xypron.glpk@gmx.de --- v2: add doc/usage/index.rst --- doc/index.rst | 8 +---- doc/pstore.rst | 82 -------------------------------------------- doc/usage/index.rst | 12 +++++++ doc/usage/pstore.rst | 82 ++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 95 insertions(+), 89 deletions(-) delete mode 100644 doc/pstore.rst create mode 100644 doc/usage/index.rst create mode 100644 doc/usage/pstore.rst
diff --git a/doc/index.rst b/doc/index.rst index 68a083b16b..4c44955d67 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -25,6 +25,7 @@ trying to get it to work optimally on a given system. :maxdepth: 2
build/index + usage/index
Developer-oriented documentation -------------------------------- @@ -109,13 +110,6 @@ Android-specific features available in U-Boot.
android/index
-Command line ------------- -.. toctree:: - :maxdepth: 2 - - pstore.rst - Indices and tables ==================
diff --git a/doc/pstore.rst b/doc/pstore.rst deleted file mode 100644 index 8427d8fd97..0000000000 --- a/doc/pstore.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0+ - -PStore command -============== - -Design ------- - -Linux PStore and Ramoops modules (Linux config options PSTORE and PSTORE_RAM) -allow to use memory to pass data from the dying breath of a crashing kernel to -its successor. This command allows to read those records from U-Boot command -line. - -Ramoops is an oops/panic logger that writes its logs to RAM before the system -crashes. It works by logging oopses and panics in a circular buffer. Ramoops -needs a system with persistent RAM so that the content of that area can survive -after a restart. - -Ramoops uses a predefined memory area to store the dump. - -Ramoops parameters can be passed as kernel parameters or through Device Tree, -i.e.:: - - ramoops.mem_address=0x30000000 ramoops.mem_size=0x100000 ramoops.record_size=0x2000 ramoops.console_size=0x2000 memmap=0x100000$0x30000000 - -The same values should be set in U-Boot to be able to retrieve the records. -This values can be set at build time in U-Boot configuration file, or at runtime. -U-Boot automatically patches the Device Tree to pass the Ramoops parameters to -the kernel. - -The PStore configuration parameters are: - -======================= ========== - Name Default -======================= ========== -CMD_PSTORE_MEM_ADDR -CMD_PSTORE_MEM_SIZE 0x10000 -CMD_PSTORE_RECORD_SIZE 0x1000 -CMD_PSTORE_CONSOLE_SIZE 0x1000 -CMD_PSTORE_FTRACE_SIZE 0x1000 -CMD_PSTORE_PMSG_SIZE 0x1000 -CMD_PSTORE_ECC_SIZE 0 -======================= ========== - -Records sizes should be a power of 2. -The memory size and the record/console size must be non-zero. - -Multiple 'dump' records can be stored in the memory reserved for PStore. -The memory size has to be larger than the sum of the record sizes, i.e.:: - - MEM_SIZE >= RECORD_SIZE * n + CONSOLE_SIZE + FTRACE_SIZE + PMSG_SIZE - -Usage ------ - -Generate kernel crash -~~~~~~~~~~~~~~~~~~~~~ - -For test purpose, you can generate a kernel crash by setting reboot timeout to -10 seconds and trigger a panic:: - - $ sudo sh -c "echo 1 > /proc/sys/kernel/sysrq" - $ sudo sh -c "echo 10 > /proc/sys/kernel/panic" - $ sudo sh -c "echo c > /proc/sysrq-trigger" - -Retrieve logs in U-Boot -~~~~~~~~~~~~~~~~~~~~~~~ - -First of all, unless PStore parameters as been set during U-Boot configuration -and match kernel ramoops parameters, it needs to be set using 'pstore set', e.g.:: - - => pstore set 0x30000000 0x100000 0x2000 0x2000 - -Then all available dumps can be displayed -using:: - - => pstore display - -Or saved to an existing directory in an Ext2 or Ext4 partition, e.g. on root -directory of 1st partition of the 2nd MMC:: - - => pstore save mmc 1:1 / diff --git a/doc/usage/index.rst b/doc/usage/index.rst new file mode 100644 index 0000000000..af7d50650d --- /dev/null +++ b/doc/usage/index.rst @@ -0,0 +1,12 @@ +Use U-Boot +========== + +.. toctree:: + +Shell commands +-------------- + +.. toctree:: + :maxdepth: 1 + + pstore diff --git a/doc/usage/pstore.rst b/doc/usage/pstore.rst new file mode 100644 index 0000000000..8427d8fd97 --- /dev/null +++ b/doc/usage/pstore.rst @@ -0,0 +1,82 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +PStore command +============== + +Design +------ + +Linux PStore and Ramoops modules (Linux config options PSTORE and PSTORE_RAM) +allow to use memory to pass data from the dying breath of a crashing kernel to +its successor. This command allows to read those records from U-Boot command +line. + +Ramoops is an oops/panic logger that writes its logs to RAM before the system +crashes. It works by logging oopses and panics in a circular buffer. Ramoops +needs a system with persistent RAM so that the content of that area can survive +after a restart. + +Ramoops uses a predefined memory area to store the dump. + +Ramoops parameters can be passed as kernel parameters or through Device Tree, +i.e.:: + + ramoops.mem_address=0x30000000 ramoops.mem_size=0x100000 ramoops.record_size=0x2000 ramoops.console_size=0x2000 memmap=0x100000$0x30000000 + +The same values should be set in U-Boot to be able to retrieve the records. +This values can be set at build time in U-Boot configuration file, or at runtime. +U-Boot automatically patches the Device Tree to pass the Ramoops parameters to +the kernel. + +The PStore configuration parameters are: + +======================= ========== + Name Default +======================= ========== +CMD_PSTORE_MEM_ADDR +CMD_PSTORE_MEM_SIZE 0x10000 +CMD_PSTORE_RECORD_SIZE 0x1000 +CMD_PSTORE_CONSOLE_SIZE 0x1000 +CMD_PSTORE_FTRACE_SIZE 0x1000 +CMD_PSTORE_PMSG_SIZE 0x1000 +CMD_PSTORE_ECC_SIZE 0 +======================= ========== + +Records sizes should be a power of 2. +The memory size and the record/console size must be non-zero. + +Multiple 'dump' records can be stored in the memory reserved for PStore. +The memory size has to be larger than the sum of the record sizes, i.e.:: + + MEM_SIZE >= RECORD_SIZE * n + CONSOLE_SIZE + FTRACE_SIZE + PMSG_SIZE + +Usage +----- + +Generate kernel crash +~~~~~~~~~~~~~~~~~~~~~ + +For test purpose, you can generate a kernel crash by setting reboot timeout to +10 seconds and trigger a panic:: + + $ sudo sh -c "echo 1 > /proc/sys/kernel/sysrq" + $ sudo sh -c "echo 10 > /proc/sys/kernel/panic" + $ sudo sh -c "echo c > /proc/sysrq-trigger" + +Retrieve logs in U-Boot +~~~~~~~~~~~~~~~~~~~~~~~ + +First of all, unless PStore parameters as been set during U-Boot configuration +and match kernel ramoops parameters, it needs to be set using 'pstore set', e.g.:: + + => pstore set 0x30000000 0x100000 0x2000 0x2000 + +Then all available dumps can be displayed +using:: + + => pstore display + +Or saved to an existing directory in an Ext2 or Ext4 partition, e.g. on root +directory of 1st partition of the 2nd MMC:: + + => pstore save mmc 1:1 / -- 2.29.2