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

[Dheeraj Kumar Srivastava]

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@xxxxxxx>
---
 Documentation/ABI/testing/debugfs-amd-iommu | 140 ++++++++++++++++++++
 1 file changed, 140 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..7acdb38bdf7b
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-amd-iommu
@@ -0,0 +1,140 @@
+What:		/sys/kernel/debug/iommu/amd/iommu<x>/mmio
+Date:		September 2024
+Contact:	Dheeraj Kumar Srivastava <dheerajkumar.srivastava@xxxxxxx>
+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:
+		0x18
+
+What:		/sys/kernel/debug/iommu/amd/iommu<x>/mmio_dump
+Date:		September 2024
+Contact:	Dheeraj Kumar Srivastava <dheerajkumar.srivastava@xxxxxxx>
+Description:
+		This is an output read only file that contains mmio register
+		value at offset "/sys/kernel/debug/iommu/amd/iommu<x>/mmio".
+
+		Example:
+		$ cat /sys/kernel/debug/iommu/amd/iommu00/mmio_dump
+
+		Output:
+		0x0003f48d
+
+What:		/sys/kernel/debug/iommu/amd/iommu<x>/capability
+Date:		September 2024
+Contact:	Dheeraj Kumar Srivastava <dheerajkumar.srivastava@xxxxxxx>
+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:
+		0x10
+
+What:		/sys/kernel/debug/iommu/amd/iommu<x>/capability_dump
+Date:		September 2024
+Contact:	Dheeraj Kumar Srivastava <dheerajkumar.srivastava@xxxxxxx>
+Description:
+		This is an output read only file that contains capability register
+                value at offset "/sys/kernel/debug/iommu/amd/iommu<x>/capability".
+
+		Example:
+		$ cat /sys/kernel/debug/iommu/amd/iommu00/capability_dump
+
+		Output:
+		0x00203040
+
+What:		/sys/kernel/debug/iommu/amd/iommu<x>/cmdbuf
+Date:		September 2024
+Contact:	Dheeraj Kumar Srivastava <dheerajkumar.srivastava@xxxxxxx>
+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 pointer register:0x00000b90 Tail pointer register:0x00000b90
+		  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@xxxxxxx>
+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/devtbl
+Date:		September 2024
+Contact:	Dheeraj Kumar Srivastava <dheerajkumar.srivastava@xxxxxxx>
+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/devtbl
+Date:		September 2024
+Contact:	Dheeraj Kumar Srivastava <dheerajkumar.srivastava@xxxxxxx>
+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