From: qiruipeng <qiruipeng@xxxxxxxxxxx>
Add osdump guide for the users who try to compile with osdump enabled,
use, and analysis real system problem.
Signed-off-by: qiruipeng <qiruipeng@xxxxxxxxxxx>
---
Documentation/admin-guide/index.rst | 1 +
Documentation/admin-guide/osdump.rst | 94 ++++++++++++++++++++++++++++
2 files changed, 95 insertions(+)
create mode 100644 Documentation/admin-guide/osdump.rst
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 43ea35613dfc..1212ff4d130e 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -116,6 +116,7 @@ configure specific aspects of kernel behavior to your liking.
mono
namespaces/index
numastat
+ osdump
parport
perf-security
pm/index
diff --git a/Documentation/admin-guide/osdump.rst b/Documentation/admin-guide/osdump.rst
new file mode 100644
index 000000000000..5738b03ff684
--- /dev/null
+++ b/Documentation/admin-guide/osdump.rst
@@ -0,0 +1,94 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================================================
+Documentation for osdump - The Os Minidump Solution
+===================================================
+
+Overview
+========
+
+Osdump is a new crash dumping solution aiming at specific embedded
+devices within Automotive or Industrial having the following features:
+ - limited memory.
+ - require quick reboots after system faults.
+
+To minimize the dump file size and maximize the dump process speed,
+Osdump provides the following features:
+ - excludes userspace memory, focusing solely on resolving OS-related issues.
+ - eliminates constant data such as text segments.
+ - core OS data for dumping, this includes:
+ - static allocated bss and data segments
+ - dynamic data such as:
+ - slub data for small-sized data
+ - some large-sized data alloced in pages.
+ - compresses dump data to help reduce dump file size
+
+Considering the large volume of non-contiguous data, a binary data format is
+used directly.
+
+By utilizing the dump file and vmlinux, a standard elf format file can be
+reassembled and parsed using crash tool.
+
+Declare
+========
+Mainly test on arm64 with 2G DDR, selecting slub as SLAB allocator, 39-bit for
+address space size.
+
+Configure and Build
+===================
+
+Kernel config
+-------------
+Disable CRASH_CORE, SLUB_DEBUG, and SLUB_TINY, and then select CONFIG_OS_MINIDUMP.
+
+Dts config
+----------
+Add one reserved region for osdump. Its size depends DDR size you are using. Here
+add one 16M reserved region with 2G's DDR.
+
+osdump {
+ compatible = "osdump";
+ reg = <0 0x64000000 0 0x1000000>;
+};
+
+Build the image after you have done with configuration.
+
+Trigger one panic and analysis it
+=================================
+
+0) Precondition
+---------------
+DDR won't poweroff during panic. Its content should not be lose.
+
+1) Generate dump file
+---------------------
+When a panic occurs, it will dump core data into specific reserved region.
+
+echo c > /proc/sysrq-trigger
+
+2) Get dump file
+----------------
+When system reboot from panic, run the following command to get dump file.
+
+cat /proc/osdump > ./osdump
+
+Got 13M dump file on my side.
+
+3) Run crash tool to generate standard elf file
+-----------------------------------------------
+
+crash --enable_raw_dumpfile ./vmlinux ./osdump -m vabits_actual=39 --machdep\
+ kimage_voffset=0xffffffbf8f000000 --machdep phys_offset=0x80000000
+
+Add new feature for crash tool that reassemble a standard elf format file with
+the dump file and vmlinux. Will submit this patch later.
+
+4) Analysis with crash tool
+---------------------------
+
+crash ./vmlinux ./osdump_elf
+
+
+Note
+====
+disable when select CRASH_CORE, SLUB_DEBUG, or SLUB_TINY.
--
2.17.1
