Received-SPF: pass (google.com: domain of linux-kernel+bounces-8492-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:40f1:3f00::1 as permitted sender) client-ip=2604:1380:40f1:3f00::1;
From: Ruipeng Qi <ruipengqi7@gmail.com>
To: corbet@lwn.net,
	rafael.j.wysocki@intel.com,
	gregkh@linuxfoundation.org,
	bagasdotme@gmail.com,
	carlos.bilbao@amd.com,
	vegard.nossum@oracle.com
Cc: skhan@linuxfoundation.org,
	srinivas.pandruvada@linux.intel.com,
	qiruipeng@lixiang.com,
	linux@leemhuis.info,
	linux-doc@vger.kernel.org,
	linux-kernel@vger.kernel.org
Subject: [RFC PATCH 3/7] doc: Add osdump guide
Date: Thu, 21 Dec 2023 21:29:43 +0800
Message-Id: <20231221132943.653-1-ruipengqi7@gmail.com>
Precedence: bulk

From: qiruipeng <qiruipeng@lixiang.com>

Add osdump guide for the users who try to compile with osdump enabled,
use, and analysis real system problem.

Signed-off-by: qiruipeng <qiruipeng@lixiang.com>
---
 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