diff options
author | Tom Rini <trini@konsulko.com> | 2020-10-14 13:35:05 -0400 |
---|---|---|
committer | Tom Rini <trini@konsulko.com> | 2020-10-14 13:35:05 -0400 |
commit | 6731c5a5ef30e1581e3042b11893627f42949cd7 (patch) | |
tree | a5c3fe0db688a28be279cac93174389863747d23 /doc | |
parent | 55fca74a5ba9bb0a101b247f421e81322b945a7b (diff) | |
parent | 40a3008632abd8bb393eefc212547456f2a5cb25 (diff) | |
download | u-boot-6731c5a5ef30e1581e3042b11893627f42949cd7.zip u-boot-6731c5a5ef30e1581e3042b11893627f42949cd7.tar.gz u-boot-6731c5a5ef30e1581e3042b11893627f42949cd7.tar.bz2 |
Merge branch '2020-10-14-assorted-changes'
- Add support for Linux "pstore" dumps.
- Button command fixup.
- gd cleanup and documentation.
- Assorted other cleanups.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/develop/global_data.rst | 53 | ||||
-rw-r--r-- | doc/develop/index.rst | 1 | ||||
-rw-r--r-- | doc/index.rst | 7 | ||||
-rw-r--r-- | doc/pstore.rst | 82 | ||||
-rw-r--r-- | doc/sphinx/cdomain.py | 5 |
5 files changed, 147 insertions, 1 deletions
diff --git a/doc/develop/global_data.rst b/doc/develop/global_data.rst new file mode 100644 index 0000000..9e7c8a2 --- /dev/null +++ b/doc/develop/global_data.rst @@ -0,0 +1,53 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Global data +=========== + +Globally required fields are held in the global data structure. A pointer to the +structure is available as symbol gd. The symbol is made available by the macro +%DECLARE_GLOBAL_DATA_PTR. + +Register pointing to global data +-------------------------------- + +On most architectures the global data pointer is stored in a register. + ++------------+----------+ +| ARC | r25 | ++------------+----------+ +| ARM 32bit | r9 | ++------------+----------+ +| ARM 64bit | x18 | ++------------+----------+ +| M68000 | d7 | ++------------+----------+ +| MicroBlaze | r31 | ++------------+----------+ +| NDS32 | r10 | ++------------+----------+ +| Nios II | gp | ++------------+----------+ +| PowerPC | r2 | ++------------+----------+ +| RISC-V | gp (x3) | ++------------+----------+ +| SuperH | r13 | ++------------+----------+ + +The sandbox, x86, and Xtensa are notable exceptions. + +Clang for ARM does not support assigning a global register. When using Clang +gd is defined as an inline function using assembly code. This adds a few bytes +to the code size. + +Binaries called by U-Boot are not aware of the register usage and will not +conserve gd. UEFI binaries call the API provided by U-Boot and may return to +U-Boot. The value of gd has to be saved every time U-Boot is left and restored +whenever U-Boot is reentered. This is also relevant for the implementation of +function tracing. For setting the value of gd function set_gd() can be used. + +Global data structure +--------------------- + +.. kernel-doc:: include/asm-generic/global_data.h + :internal: diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 98a95ad..89e80ea 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -9,4 +9,5 @@ Develop U-Boot coccinelle crash_dumps + global_data logging diff --git a/doc/index.rst b/doc/index.rst index fd9f10f..68a083b 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -109,6 +109,13 @@ 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 new file mode 100644 index 0000000..8427d8f --- /dev/null +++ b/doc/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 / diff --git a/doc/sphinx/cdomain.py b/doc/sphinx/cdomain.py index cf13ff3..cbac8e6 100644 --- a/doc/sphinx/cdomain.py +++ b/doc/sphinx/cdomain.py @@ -48,7 +48,10 @@ major, minor, patch = sphinx.version_info[:3] def setup(app): - app.override_domain(CDomain) + if (major == 1 and minor < 8): + app.override_domain(CDomain) + else: + app.add_domain(CDomain, override=True) return dict( version = __version__, |