diff mbox series

[v2,3/6] docs: qcom: Add qualcomm minidump guide

Message ID 1679491817-2498-4-git-send-email-quic_mojha@quicinc.com (mailing list archive)
State Superseded
Headers show
Series [v2,1/6] remoteproc: qcom: Expand MD_* as MINIDUMP_* | expand

Commit Message

Mukesh Ojha March 22, 2023, 1:30 p.m. UTC
Add the qualcomm minidump guide for the users which
tries to cover the dependency and the way to test
and collect minidump on Qualcomm supported platforms.

Signed-off-by: Mukesh Ojha <quic_mojha@quicinc.com>
---
 Documentation/admin-guide/qcom_minidump.rst | 240 ++++++++++++++++++++++++++++
 1 file changed, 240 insertions(+)
 create mode 100644 Documentation/admin-guide/qcom_minidump.rst

Comments

Srinivas Kandagatla April 13, 2023, 10:31 p.m. UTC | #1
On 22/03/2023 13:30, Mukesh Ojha wrote:
> +Dump collection
> +---------------
> +
> +The solution supports extracting the minidump produced either over USB or
> +stored to an attached storage device.
> +
> +By default, dumps are downloaded via USB to the attached x86_64 machine
> +running PCAT (Qualcomm tool) software. Upon download, we will see

Are these both PCAT and dexter tools public?

--srini
> +a set of binary blobs starts with name md_* in PCAT configured directory
> +in x86_64 machine, so for above example from the client it will be
> +md_REGION_A.BIN. This binary blob depends on region content to determine
> +whether it needs external parser support to get the content of the region,
> +so for simple plain ASCII text we don't need any parsing and the content
> +can be seen just opening the binary file.
> +
> +To collect the dump to attached storage type, one need to write appropriate
> +value to IMEM register, in that case dumps are collected in rawdump
> +partition on the target device itself.
> +
> +One need to read the entire rawdump partition and pull out content to
> +save it onto the attached x86_64 machine over USB. Later, this rawdump
> +can be pass it to another tool dexter.exe(Qualcomm tool) which converts
> +this into the similar binary blobs which we have got it when download type
> +was set to USB i.e a set of registered region as blobs and their name
> +starts with md_*.
> -- 2.7.4
Mukesh Ojha April 18, 2023, 3:19 p.m. UTC | #2
+@Brian

On 4/14/2023 4:01 AM, Srinivas Kandagatla wrote:
> 
> 
> On 22/03/2023 13:30, Mukesh Ojha wrote:
>> +Dump collection
>> +---------------
>> +
>> +The solution supports extracting the minidump produced either over 
>> USB or
>> +stored to an attached storage device.
>> +
>> +By default, dumps are downloaded via USB to the attached x86_64 machine
>> +running PCAT (Qualcomm tool) software. Upon download, we will see
> 
> Are these both PCAT and dexter tools public?

I think, PCAT comes as part of Qcom Package Kit.

Last time, I checked with @Brian, he was saying the they use PCAT 
software tool running on x86_64 machine attached to QCOM device to
get the dump(via USB) out of the device.

Dexter.exe seems private tool, that only requires if we use storage
(via ufs/emmc) to save minidump on the target device itself and later 
use adb to pull out the rawdump partition dump and pass it through
dexter to convert it to same binary blobs which we got directly through
PCAT.

I don't at least have any way to avoid dexter tool at the moment.
However, i will think if we can develop any script which does the
same.

-- Mukesh

> 
> --srini
>> +a set of binary blobs starts with name md_* in PCAT configured directory
>> +in x86_64 machine, so for above example from the client it will be
>> +md_REGION_A.BIN. This binary blob depends on region content to determine
>> +whether it needs external parser support to get the content of the 
>> region,
>> +so for simple plain ASCII text we don't need any parsing and the content
>> +can be seen just opening the binary file.
>> +
>> +To collect the dump to attached storage type, one need to write 
>> appropriate
>> +value to IMEM register, in that case dumps are collected in rawdump
>> +partition on the target device itself.
>> +
>> +One need to read the entire rawdump partition and pull out content to
>> +save it onto the attached x86_64 machine over USB. Later, this rawdump
>> +can be pass it to another tool dexter.exe(Qualcomm tool) which converts
>> +this into the similar binary blobs which we have got it when download 
>> type
>> +was set to USB i.e a set of registered region as blobs and their name
>> +starts with md_*.
>> -- 2.7.4
Srinivas Kandagatla April 18, 2023, 3:26 p.m. UTC | #3
On 18/04/2023 16:19, Mukesh Ojha wrote:
> +@Brian
> 
> On 4/14/2023 4:01 AM, Srinivas Kandagatla wrote:
>>
>>
>> On 22/03/2023 13:30, Mukesh Ojha wrote:
>>> +Dump collection
>>> +---------------
>>> +
>>> +The solution supports extracting the minidump produced either over 
>>> USB or
>>> +stored to an attached storage device.
>>> +
>>> +By default, dumps are downloaded via USB to the attached x86_64 machine
>>> +running PCAT (Qualcomm tool) software. Upon download, we will see
>>
>> Are these both PCAT and dexter tools public?
> 
> I think, PCAT comes as part of Qcom Package Kit.

yes, this is part of Qualcomm Package Manager.

> 
> Last time, I checked with @Brian, he was saying the they use PCAT 
> software tool running on x86_64 machine attached to QCOM device to
> get the dump(via USB) out of the device.
> 
> Dexter.exe seems private tool, that only requires if we use storage
> (via ufs/emmc) to save minidump on the target device itself and later 
> use adb to pull out the rawdump partition dump and pass it through
> dexter to convert it to same binary blobs which we got directly through
> PCAT.
> 
> I don't at least have any way to avoid dexter tool at the moment.
> However, i will think if we can develop any script which does the
> same.
That would be nice!

--srini
> 
> -- Mukesh
> 
>>
>> --srini
>>> +a set of binary blobs starts with name md_* in PCAT configured 
>>> directory
>>> +in x86_64 machine, so for above example from the client it will be
>>> +md_REGION_A.BIN. This binary blob depends on region content to 
>>> determine
>>> +whether it needs external parser support to get the content of the 
>>> region,
>>> +so for simple plain ASCII text we don't need any parsing and the 
>>> content
>>> +can be seen just opening the binary file.
>>> +
>>> +To collect the dump to attached storage type, one need to write 
>>> appropriate
>>> +value to IMEM register, in that case dumps are collected in rawdump
>>> +partition on the target device itself.
>>> +
>>> +One need to read the entire rawdump partition and pull out content to
>>> +save it onto the attached x86_64 machine over USB. Later, this rawdump
>>> +can be pass it to another tool dexter.exe(Qualcomm tool) which converts
>>> +this into the similar binary blobs which we have got it when 
>>> download type
>>> +was set to USB i.e a set of registered region as blobs and their name
>>> +starts with md_*.
>>> -- 2.7.4
diff mbox series

Patch

diff --git a/Documentation/admin-guide/qcom_minidump.rst b/Documentation/admin-guide/qcom_minidump.rst
new file mode 100644
index 0000000..bdff1c9
--- /dev/null
+++ b/Documentation/admin-guide/qcom_minidump.rst
@@ -0,0 +1,240 @@ 
+Qualcomm Minidump Feature
+=========================
+
+Introduction
+------------
+
+Minidump is a best effort mechanism to collect useful and predefined
+data for first level of debugging on end user devices running on
+Qualcomm SoCs. It is built on the premise that System on Chip (SoC)
+or subsystem part of SoC crashes, due to a range of hardware and
+software bugs. Hence, the ability to collect accurate data is only
+a best-effort. The data collected could be invalid or corrupted, data
+collection itself could fail, and so on.
+
+Qualcomm devices in engineering mode provides a mechanism for generating
+full system ramdumps for post mortem debugging. But in some cases it's
+however not feasible to capture the entire content of RAM. The minidump
+mechanism provides the means for selecting region should be included in
+the ramdump.
+
+::
+
+   +-----------------------------------------------+
+   |   DDR                       +-------------+   |
+   |                             |      SS0-ToC|   |
+   | +----------------+     +----------------+ |   |
+   | |Shared memory   |     |         SS1-ToC| |   |
+   | |(SMEM)          |     |                | |   |
+   | |                | +-->|--------+       | |   |
+   | |G-ToC           | |   | SS-ToC  \      | |   |
+   | |+-------------+ | |   | +-----------+  | |   |
+   | ||-------------| | |   | |-----------|  | |   |
+   | || SS0-ToC     | | | +-|<|SS1 region1|  | |   |
+   | ||-------------| | | | | |-----------|  | |   |
+   | || SS1-ToC     |-|>+ | | |SS1 region2|  | |   |
+   | ||-------------| |   | | |-----------|  | |   |
+   | || SS2-ToC     | |   | | |  ...      |  | |   |
+   | ||-------------| |   | | |-----------|  | |   |
+   | ||  ...        | |   |-|<|SS1 regionN|  | |   |
+   | ||-------------| |   | | |-----------|  | |   |
+   | || SSn-ToC     | |   | | +-----------+  | |   |
+   | |+-------------+ |   | |                | |   |
+   | |                |   | |----------------| |   |
+   | |                |   +>|  regionN       | |   |
+   | |                |   | |----------------| |   |
+   | +----------------+   | |                | |   |
+   |                      | |----------------| |   |
+   |                      +>|  region1       | |   |
+   |                        |----------------| |   |
+   |                        |                | |   |
+   |                        |----------------|-+   |
+   |                        |  region5       |     |
+   |                        |----------------|     |
+   |                        |                |     |
+   |  Region information    +----------------+     |
+   | +---------------+                             |
+   | |region name    |                             |
+   | |---------------|                             |
+   | |region address |                             |
+   | |---------------|                             |
+   | |region size    |                             |
+   | +---------------+                             |
+   +-----------------------------------------------+
+       G-ToC: Global table of content
+       SS-ToC: Subsystem table of content
+       SS0-SSn: Subsystem numbered from 0 to n
+
+The core of minidump feature is part of Qualcomm's boot firmware code.
+It initializes shared memory(SMEM), which is a part of DDR and
+allocates a small section of it to minidump table i.e also called
+global table of content (G-ToC). Each subsystem (APSS, ADSP, ...) has
+their own table of segments to be included in the minidump, all
+references from a descriptor in SMEM (G-ToC). Each segment/region has
+some details like name, physical address and it's size etc. and it
+could be anywhere scattered in the DDR.
+
+Minidump kernel driver concept
+------------------------------
+
+Qualcomm minidump kernel driver adds the capability to add linux region
+to be dumped as part of ram dump collection. It provides appropriate
+symbol to check its enablement and register client region.
+
+To simplify post mortem debugging, it creates and maintain an ELF
+header as first region that gets updated each time a new region gets
+registered.
+
+The solution supports extracting the ramdump/minidump produced either
+over USB or stored to an attached storage device.
+
+Dependency of minidump kernel driver
+------------------------------------
+
+It is noted that minidump kernel driver depends on Qualcomm's
+shared memory (SMEM) driver and its device tree entry (device
+presence). If above support is present and Qualcomm boot firmware
+has minidump support, so it is possible to dump linux region as
+part of minidump collection.
+
+How a kernel client driver can register region with minidump
+------------------------------------------------------------
+
+Client driver can use qcom_minidump_ready() symbol to check if the
+minidump driver is supported on the target and if it return -ENODEV
+then it means minidump is not supported on this target and the client
+should not try to register their minidump region further and
+continue with their normal execution, and if it is supported it
+can go ahead register its region with qcom_minidump_region_register().
+
+Client need to fill their region by filling qcom_minidump_region
+structure object which consist of the region name, region's
+virtual and physical address and its size.
+
+Below is one sample client driver snippet which try to allocate
+a region from kernel heap of certain size and it writes a certain
+known pattern (that can help in verification after collection
+that we got the exact pattern, what we wrote) and registers with
+minidump.
+
+ .. code-block:: c
+
+  #include <soc/qcom/minidump.h>
+  [...]
+
+
+  [... inside a function ...]
+  struct qcom_minidump_region region;
+
+  [...]
+
+  client_mem_region = kzalloc(region_size, GFP_KERNEL);
+  if (!client_mem_region)
+	return -ENOMEM;
+
+  [... Just write a pattern ...]
+  memset(client_mem_region, 0xAB, region_size);
+
+  [... Check if minidump is ready return -EPROBE_DEFER
+   if this is a probe function otherwise return accordingly ...]
+  err = qcom_minidump_ready();
+  if (err && err != -ENODEV)
+	return -EPROBE_DEFER;
+
+  strlcpy(region.name, "REGION_A", sizeof(region.name));
+  region.virt_addr = client_mem_region;
+  region.phys_addr = virt_to_phys(client_mem_region);
+  region.size = region_size;
+
+  if (!err) {
+	ret = qcom_minidump_region_register(&region);
+	if (ret < 0) {
+		pr_err("failed to add region in minidump: err: %d\n", ret);
+		return ret;
+	}
+  }
+
+  [...]
+
+
+Test
+----
+
+Existing Qualcomm devices already supports entire ddr dump (also called
+full dump) via writing appropriate value to Qualcomm's top control and
+status register(tcsr) in driver/firmware/qcom_scm.c .
+
+SCM device Tree bindings required to support download mode
+For example (sm8450) ::
+
+	/ {
+
+	[...]
+
+		firmware {
+			scm: scm {
+				compatible = "qcom,scm-sm8450", "qcom,scm";
+				[... tcsr register ... ]
+				qcom,dload-mode = <&tcsr 0x13000>;
+
+				[...]
+			};
+		};
+
+	[...]
+
+		soc: soc@0 {
+
+			[...]
+
+			tcsr: syscon@1fc0000 {
+				compatible = "qcom,sm8450-tcsr", "syscon";
+				reg = <0x0 0x1fc0000 0x0 0x30000>;
+			};
+
+			[...]
+		};
+	[...]
+
+	};
+
+User of minidump can pass qcom_scm.download_mode="mini" to kernel
+commandline to set the current download mode to minidump.
+
+Similarly, "full" is passed to set the download mode to full dump
+where entire ddr dump will be collected while setting it "both"
+will set the mode to both (mini + full).
+
+sysfs can also be used to set the mode to minidump.
+
+::
+	echo "mini" > /sys/module/qcom_scm/parameter/download_mode
+
+Once the download mode is set, any kind of crash will make the device collect
+respective dump as per set download mode.
+
+Dump collection
+---------------
+
+The solution supports extracting the minidump produced either over USB or
+stored to an attached storage device.
+
+By default, dumps are downloaded via USB to the attached x86_64 machine
+running PCAT (Qualcomm tool) software. Upon download, we will see
+a set of binary blobs starts with name md_* in PCAT configured directory
+in x86_64 machine, so for above example from the client it will be
+md_REGION_A.BIN. This binary blob depends on region content to determine
+whether it needs external parser support to get the content of the region,
+so for simple plain ASCII text we don't need any parsing and the content
+can be seen just opening the binary file.
+
+To collect the dump to attached storage type, one need to write appropriate
+value to IMEM register, in that case dumps are collected in rawdump
+partition on the target device itself.
+
+One need to read the entire rawdump partition and pull out content to
+save it onto the attached x86_64 machine over USB. Later, this rawdump
+can be pass it to another tool dexter.exe(Qualcomm tool) which converts
+this into the similar binary blobs which we have got it when download type
+was set to USB i.e a set of registered region as blobs and their name
+starts with md_*.