[PATCH v3 8/8] iommu/amd: Add documentation for AMD IOMMU debugfs support

Dheeraj Kumar Srivastava
2025-02-06T06:03:17Z

Add documentation describing how to use AMD IOMMU debugfs support to
dump IOMMU data structures - IRT table, Device table, Registers (MMIO and
Capability) and command buffer.

Signed-off-by: Dheeraj Kumar Srivastava <dheerajkumar.srivastava@amd.com>
---
Documentation/ABI/testing/debugfs-amd-iommu | 114 ++++++++++++++++++++
1 file changed, 114 insertions(+)
create mode 100644 Documentation/ABI/testing/debugfs-amd-iommu

diff --git a/Documentation/ABI/testing/debugfs-amd-iommu b/Documentation/ABI/testing/debugfs-amd-iommu
new file mode 100644
index 000000000000..f318e3418435
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-amd-iommu
@@ -0,0 +1,114 @@
+What: /sys/kernel/debug/iommu/amd/iommu<x>/mmio
+Date: September 2024
+Contact: Dheeraj Kumar Srivastava <dheerajkumar.srivastava@amd.com>
+Description:
+ This is an input read/write access file. In this file, the user input
+ mmio register offset for iommu<x> to print corresponding mmio register
+ of iommu<x>.
+
+ Example:
+ $ echo "0x18" > /sys/kernel/debug/iommu/amd/iommu00/mmio
+ $ cat /sys/kernel/debug/iommu/amd/iommu00/mmio
+
+ Output:
+ Offset:0x18 Value:0x0003f48d
+
+What: /sys/kernel/debug/iommu/amd/iommu<x>/capability
+Date: September 2024
+Contact: Dheeraj Kumar Srivastava <dheerajkumar.srivastava@amd.com>
+Description:
+ This is an input read/write access file. In this file, the user input
+ capability register offset for iommu<x> to print corresponding capability
+ register of iommu<x>.
+
+ Example:
+ $ echo "0x10" > /sys/kernel/debug/iommu/amd/iommu00/capability
+ $ cat /sys/kernel/debug/iommu/amd/iommu00/capability
+
+ Output:
+ Offset:0x10 Value:0x00203040
+
+What: /sys/kernel/debug/iommu/amd/iommu<x>/cmdbuf
+Date: September 2024
+Contact: Dheeraj Kumar Srivastava <dheerajkumar.srivastava@amd.com>
+Description:
+ This file is an output read only file that contains iommu<x> command
+ buffer entries.
+
+ Examples:
+ $ cat /sys/kernel/debug/iommu/amd/iommu<x>/cmdbuf
+
+ Output:
+ CMD Buffer Head Offset:339 Tail Offset:339
+ 0: 008350011000000100003c0000000000
+ 1: 0000000030000005fffff0037fffffff
+ 2: 008350011000000100003c0100000000
+ 3: 0000000030000005fffff0037fffffff
+ 4: 008350011000000100003c0200000000
+ 5: 0000000030000005fffff0037fffffff
+ 6: 008350011000000100003c0300000000
+ 7: 0000000030000005fffff0037fffffff
+ 8: 008350011000000100003c0400000000
+ 9: 0000000030000005fffff0037fffffff
+ 10: 008350011000000100003c0500000000
+ 11: 0000000030000005fffff0037fffffff
+ [...]
+
+What: /sys/kernel/debug/iommu/amd/devid
+Date: September 2024
+Contact: Dheeraj Kumar Srivastava <dheerajkumar.srivastava@amd.com>
+Description:
+ This is an input read/write file that takes device id user input.
+ This input can be used for dumping iommu data structures like
+ interrupt remapping table, device table etc.
+
+ Example:
+ 1.
+ $ echo 0000:01:00.0 > /sys/kernel/debug/iommu/amd/devid
+ $ cat /sys/kernel/debug/iommu/amd/devid
+
+ Output:
+ 0000:01:00.0
+
+ 2.
+ $ echo 01:00.0 > /sys/kernel/debug/iommu/amd/devid
+ $ cat /sys/kernel/debug/iommu/amd/devid
+
+ Output:
+ 0000:01:00.0
+
+What: /sys/kernel/debug/iommu/amd/devtbl
+Date: September 2024
+Contact: Dheeraj Kumar Srivastava <dheerajkumar.srivastava@amd.com>
+Description:
+ This is an output read only file that contains device table entry for
+ the device id input given in /sys/kernel/debug/iommu/amd/devid.
+
+ Example:
+ $ cat /sys/kernel/debug/iommu/amd/devtbl
+
+ Output:
+ DeviceId QWORD[3] QWORD[2] QWORD[1] QWORD[0] iommu
+ 0000:01:00.0 0000000000000000 20000001373b8013 0000000000000038 6000000114d7b603 iommu3
+
+What: /sys/kernel/debug/iommu/amd/irqtbl
+Date: September 2024
+Contact: Dheeraj Kumar Srivastava <dheerajkumar.srivastava@amd.com>
+Description:
+ This is an output read only file that contains IRT table valid entries
+ for the device id input given in /sys/kernel/debug/iommu/amd/devid.
+
+ Example:
+ $ cat /sys/kernel/debug/iommu/amd/irqtbl
+
+ Output:
+ DeviceId 0000:01:00.0
+ IRT[0000] 00000000000000200000000000000241
+ IRT[0001] 00000000000000200000000000000841
+ IRT[0002] 00000000000000200000000000002041
+ IRT[0003] 00000000000000200000000000008041
+ IRT[0004] 00000000000000200000000000020041
+ IRT[0005] 00000000000000200000000000080041
+ IRT[0006] 00000000000000200000000000200041
+ IRT[0007] 00000000000000200000000000800041
+ [...]
--
2.25.1