[RFC PATCH 11/11] Documentation: ABI: add the sysfs attributes of the MediaTek DRAM ECC driver

[santino.wang <santino.wang@mediatek.com>]

From: Santino Wang <santino.wang@mediatek.com>

Document the error counters, the retired page counters, the recorded
error addresses and the policy attributes that the driver adds under
its class device.

Signed-off-by: Santino Wang <santino.wang@mediatek.com>
---
 .../ABI/testing/sysfs-class-mtk-dram-ecc      | 182 ++++++++++++++++++
 MAINTAINERS                                   |   1 +
 2 files changed, 183 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-class-mtk-dram-ecc

diff --git a/Documentation/ABI/testing/sysfs-class-mtk-dram-ecc b/Documentation/ABI/testing/sysfs-class-mtk-dram-ecc
new file mode 100644
index 000000000000..7b31bd663c53
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-mtk-dram-ecc
@@ -0,0 +1,182 @@
+What:		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/counters/volatile_ce
+		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/counters/volatile_uce_inline
+		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/counters/volatile_uce_ondie
+		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/counters/volatile_uce
+Date:		November 2026
+KernelVersion:	7.4
+Contact:	Santino Wang <santino.wang@mediatek.com>
+Description:
+		Number of corrected (CE) and uncorrectable (UCE) DRAM ECC errors
+		reported since the system booted, as a decimal number.
+
+		Inline ECC detects every UCE, including one that originates in the
+		DRAM die, so volatile_uce_inline is the total number of UCEs and
+		volatile_uce is equal to it. volatile_uce_ondie counts the subset
+		that on-die ECC also flagged.
+
+		Access: Read
+
+What:		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/counters/agg_ce
+		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/counters/agg_uce_inline
+		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/counters/agg_uce_ondie
+		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/counters/agg_uce
+Date:		November 2026
+KernelVersion:	7.4
+Contact:	Santino Wang <santino.wang@mediatek.com>
+Description:
+		Number of corrected (CE) and uncorrectable (UCE) DRAM ECC errors
+		accumulated across boots, as a decimal number. The counters are kept
+		in EFI variables that the system firmware creates.
+
+		As for the volatile counters, agg_uce_inline is the total number of
+		UCEs, agg_uce is equal to it and agg_uce_ondie counts the subset that
+		on-die ECC also flagged.
+
+		Access: Read
+
+What:		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/retired/by_ce
+		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/retired/by_uce
+Date:		November 2026
+KernelVersion:	7.4
+Contact:	Santino Wang <santino.wang@mediatek.com>
+Description:
+		Number of pages retired since the system booted because of
+		corrected errors (by_ce) or uncorrectable errors (by_uce), as a
+		decimal number. Each page is counted once.
+
+		Access: Read
+
+What:		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/addresses/current_boot_ce
+		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/addresses/current_boot_uce
+Date:		November 2026
+KernelVersion:	7.4
+Contact:	Santino Wang <santino.wang@mediatek.com>
+Description:
+		System physical addresses of the corrected (current_boot_ce) and
+		uncorrectable (current_boot_uce) errors reported since the system
+		booted, one hexadecimal address per line. At most 256 addresses are
+		kept for each kind.
+
+		Access: Read
+
+What:		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/policy/containment/enabled
+Date:		November 2026
+KernelVersion:	7.4
+Contact:	Santino Wang <santino.wang@mediatek.com>
+Description:
+		Whether the secure firmware handles and reports DRAM ECC errors.
+		While it is disabled, the secure firmware only clears the error
+		source and publishes no record. Writing the value sends it to
+		the secure firmware.
+
+		Access: Read, Write
+		Valid values: Represented as boolean
+
+What:		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/policy/containment/default_severity
+Date:		November 2026
+KernelVersion:	7.4
+Contact:	Santino Wang <santino.wang@mediatek.com>
+Description:
+		Severity the secure firmware reports for a contained uncorrectable
+		error that is not covered by an entry of policy/address_range.
+		Writing the value sends it to the secure firmware.
+
+		Access: Read, Write
+		Valid values: "fatal" or "recoverable"
+
+What:		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/policy/storm_protection/threshold
+Date:		November 2026
+KernelVersion:	7.4
+Contact:	Santino Wang <santino.wang@mediatek.com>
+Description:
+		Number of error interrupts within policy/storm_protection/time_window
+		at which the secure firmware stops reporting DRAM ECC interrupts, to
+		protect the system from an interrupt storm. Writing the value sends it
+		to the secure firmware.
+
+		Access: Read, Write
+		Valid values: Represented as unsigned integer
+
+What:		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/policy/storm_protection/time_window
+Date:		November 2026
+KernelVersion:	7.4
+Contact:	Santino Wang <santino.wang@mediatek.com>
+Description:
+		Length of the window, in milliseconds, in which the secure firmware
+		counts error interrupts for policy/storm_protection/threshold.
+		Writing the value sends it to the secure firmware.
+
+		Access: Read, Write
+		Valid values: Represented as unsigned integer
+
+What:		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/policy/storm_protection/cooldown
+Date:		November 2026
+KernelVersion:	7.4
+Contact:	Santino Wang <santino.wang@mediatek.com>
+Description:
+		Time, in milliseconds, after which the secure firmware reports DRAM
+		ECC interrupts again once storm protection has stopped them. Writing
+		the value sends it to the secure firmware.
+
+		Access: Read, Write
+		Valid values: Represented as unsigned integer
+
+What:		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/policy/leaky_bucket/threshold
+Date:		November 2026
+KernelVersion:	7.4
+Contact:	Santino Wang <santino.wang@mediatek.com>
+Description:
+		Number of corrected errors on a page at which the page is retired.
+		Writing 0 restores the default of 100.
+
+		Access: Read, Write
+		Valid values: 0 to 10000
+
+What:		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/policy/leaky_bucket/decay_interval_sec
+Date:		November 2026
+KernelVersion:	7.4
+Contact:	Santino Wang <santino.wang@mediatek.com>
+Description:
+		Interval, in seconds, at which the corrected error count of every
+		tracked page is decreased by one. Writing 0 restores the default of
+		3600.
+
+		Access: Read, Write
+		Valid values: 0 to 86400
+
+What:		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/policy/leaky_bucket/max_tracked
+Date:		November 2026
+KernelVersion:	7.4
+Contact:	Santino Wang <santino.wang@mediatek.com>
+Description:
+		Maximum number of pages whose corrected error count is tracked at
+		the same time. Writing 0 restores the default of 16.
+
+		Access: Read, Write
+		Valid values: 0 to 16
+
+What:		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/policy/address_range/entries
+Date:		November 2026
+KernelVersion:	7.4
+Contact:	Santino Wang <santino.wang@mediatek.com>
+Description:
+		Address ranges for which the secure firmware overrides the default
+		severity of an uncorrectable error. Reading lists the table held by
+		the secure firmware, one range per line, as
+		"<start> <end> <severity>" with hexadecimal addresses, where the end
+		address is exclusive.
+
+		Writing "<start> <end> <severity>" adds or updates one range. The
+		severity is "fatal" or "recoverable".
+
+		Access: Read, Write
+
+What:		/sys/class/mtk-dram-ecc/mtk-dram-ecc0/policy/address_range/clear
+Date:		November 2026
+KernelVersion:	7.4
+Contact:	Santino Wang <santino.wang@mediatek.com>
+Description:
+		Writing anything to this attribute removes every range from the
+		table of policy/address_range/entries.
+
+		Access: Write
diff --git a/MAINTAINERS b/MAINTAINERS
index e7d25be97f24..d1ab5806ad9c 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -17032,6 +17032,7 @@ L:	linux-kernel@vger.kernel.org
 L:	linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
 L:	linux-mediatek@lists.infradead.org (moderated for non-subscribers)
 S:	Maintained
+F:	Documentation/ABI/testing/sysfs-class-mtk-dram-ecc
 F:	drivers/soc/mediatek/dram-ecc/
 F:	include/uapi/linux/mtk_dram_ecc_netlink.h
 
-- 
2.45.2