docs: ABI: power: Clean it up
cover docs: ABI: power: Clean it up
While working on adding sysfs support for system load control [1], kernel test robot reported some warnings. This patch series fixes those and some additional ones that were discovered during discussions [2].
[1] https://lore.kernel.org/lkml/[email protected]/
[2] https://lore.kernel.org/oe-kbuild-all/[email protected]/
Waqar Hameed (7):
docs: ABI: power: rt9471: Fix invalid inline emphasis
docs: ABI: power: rt9471: Add newline for paragraphs
docs: ABI: power: rt9471: Fix mismatched quote
docs: ABI: power: rt9467: Fix invalid inline emphasis
docs: ABI: power: rt9467: Add newline for paragraphs
docs: ABI: power: rt9467: Fix mismatched quote
docs: ABI: power: rt9756: Fix invalid inline emphasis
Documentation/ABI/testing/sysfs-class-power-rt9467 | 5 +++-- Documentation/ABI/testing/sysfs-class-power-rt9471 | 8 +++++--- Documentation/ABI/testing/sysfs-class-power-rt9756 | 4 ++-- 3 files changed, 10 insertions(+), 7 deletions(-)
base-commit: 734bef548a96e8774d6eef5dfa2026c6edc4e80b
Signature · 1 line
2.43.0
PATCH 1/7 docs: ABI: power: rt9471: Fix invalid inline emphasis
docutils warns:
Documentation/ABI/testing/sysfs-class-power-rt9471:1: (WARNING/2) Inline emphasis start-string without end-string. Documentation/ABI/testing/sysfs-class-power-rt9471:20: (WARNING/2) Inline emphasis start-string without end-string.
Fix this by escaping the *.
--- Documentation/ABI/testing/sysfs-class-power-rt9471 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/ABI/testing/sysfs-class-power-rt9471 +2 -2
@@ -1,4 +1,4 @@ -What: /sys/class/power_supply/rt9471-*/sysoff_enable +What: /sys/class/power_supply/rt9471-\*/sysoff_enable Date: Feb 2023 KernelVersion: 6.3 Contact: ChiYuan Huang <[email protected]>
@@ -16,7 +16,7 @@ Description: - 1: enabled - 0: disabled -What: /sys/class/power_supply/rt9471-*/port_detect_enable +What: /sys/class/power_supply/rt9471-\*/port_detect_enable Date: Feb 2023 KernelVersion: 6.3 Contact: ChiYuan Huang <[email protected]>
Signature · 1 line
2.43.0
Re: [PATCH 1/7] docs: ABI: power: rt9471: Fix invalid inline emphasis
Quoted 6 lines · Waqar Hameed
docutilswarns:
Documentation/ABI/testing/sysfs-class-power-rt9471:1: (WARNING/2) Inline emphasis start-string without end-string.Documentation/ABI/testing/sysfs-class-power-rt9471:20: (WARNING/2) Inline emphasis start-string without end-string.Fix this by escaping the
*.
I'm still seeing this issue after the patch is applied (same for patch 4/7). Maybe we are fighting a docutils your-version vs. my-version problem or just a moving target.
$ docutils --version docutils-3.13 (Docutils 0.23, Python 3.13.16, on linux)
Quoted 26 lines
Reported-by kernel test robot <[email protected]>Signed-off-by Waqar Hameed <[email protected]>--- Documentation/ABI/testing/sysfs-class-power-rt9471 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)Documentation/ABI/testing/sysfs-class-power-rt9471 +2
-2@@ -1,4 +1,4 @@ -What: /sys/class/power_supply/rt9471-*/sysoff_enable +What: /sys/class/power_supply/rt9471-\*/sysoff_enable Date: Feb 2023 KernelVersion: 6.3 Contact: ChiYuan Huang <[email protected]>@@ -16,7 +16,7 @@ Description: - 1: enabled - 0: disabled -What: /sys/class/power_supply/rt9471-*/port_detect_enable +What: /sys/class/power_supply/rt9471-\*/port_detect_enable Date: Feb 2023 KernelVersion: 6.3 Contact: ChiYuan Huang <[email protected]>
Signature · 1 line
~Randy
Re: [PATCH 1/7] docs: ABI: power: rt9471: Fix invalid inline emphasis
Quoted 7 lines · On Sun, Oct 25, 2026 at 19:39 -0700 Randy Dunlap <[email protected]> wrote:
Quoted 6 lines · Waqar Hameed
docutilswarns:
Documentation/ABI/testing/sysfs-class-power-rt9471:1: (WARNING/2) Inline emphasis start-string without end-string.Documentation/ABI/testing/sysfs-class-power-rt9471:20: (WARNING/2) Inline
emphasis start-string without end-string.
Quoted 5 lines
Quoted 1 line
Fix this by escaping the
*.I'm still seeing this issue after the patch is applied (same for patch 4/7). Maybe we are fighting a docutils your-version vs. my-version problem or just a moving target.
Hm, that's weird. What output do you actually get? The '*' is escaped now, so it shouldn't complain...
Quoted 3 lines
$ docutils --version docutils-3.13 (Docutils 0.23, Python 3.13.16, on linux)
I have
docutils (Docutils 0.20.1, Python 3.12.3, on linux)
Quoted 27 lines
Quoted 27 lines
Reported-by kernel test robot <[email protected]>Signed-off-by Waqar Hameed <[email protected]>--- Documentation/ABI/testing/sysfs-class-power-rt9471 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)Documentation/ABI/testing/sysfs-class-power-rt9471 +2
-2@@ -1,4 +1,4 @@ -What: /sys/class/power_supply/rt9471-*/sysoff_enable +What: /sys/class/power_supply/rt9471-\*/sysoff_enable Date: Feb 2023 KernelVersion: 6.3 Contact: ChiYuan Huang <[email protected]>@@ -16,7 +16,7 @@ Description: - 1: enabled - 0: disabled -What: /sys/class/power_supply/rt9471-*/port_detect_enable +What: /sys/class/power_supply/rt9471-\*/port_detect_enable Date: Feb 2023 KernelVersion: 6.3 Contact: ChiYuan Huang <[email protected]>
Re: [PATCH 1/7] docs: ABI: power: rt9471: Fix invalid inline emphasis
Quoted 9 lines · Waqar Hameed
Quoted 7 lines · On Sun, Oct 25, 2026 at 19:39 -0700 Randy Dunlap <[email protected]> wrote:
Quoted 6 lines · Waqar Hameed
docutilswarns:
Documentation/ABI/testing/sysfs-class-power-rt9471:1: (WARNING/2) Inline emphasis start-string without end-string.Documentation/ABI/testing/sysfs-class-power-rt9471:20: (WARNING/2) Inline
emphasis start-string without end-string.
Quoted 9 lines
Quoted 5 lines
Quoted 1 line
Fix this by escaping the
*.I'm still seeing this issue after the patch is applied (same for patch 4/7). Maybe we are fighting a docutils your-version vs. my-version problem or just a moving target.
Hm, that's weird. What output do you actually get? The '*' is escaped now, so it shouldn't complain...
docutils still complains:
Documentation/ABI/testing/sysfs-class-power-rt9467:1: WARNING: Inline emphasis start-string without end-string. [docutils] Documentation/ABI/testing/sysfs-class-power-rt9471:1: WARNING: Inline emphasis start-string without end-string. [docutils]
and running the command that Mauro provided:
$ ./tools/docs/get_abi.py -D Documentation/ABI/testing/ rest --enable-lineno|grep -A20 rt9467
gives me:
.. LINENO Documentation/ABI/testing/sysfs-class-power-rt9467#1
.. _abi_sys_class_power_supply_rt9467_sysoff_enable:
+------------------------------------------------------------+ | **\/sys\/class\/power_supply\/rt9467\-\\*\/sysoff_enable** | +------------------------------------------------------------+
Defined on file :ref:sysfs-class-power-rt9467 <abi_file_testing_sysfs_class_pow er_rt9467>
This entry allows enabling the sysoff mode of rt9467 charger devices.
If enabled and the input is removed, the internal battery FET is turned off to reduce the leakage from the BAT pin. See device datasheet for details. It's commonly used when the product enter shipping stage. After entering shipping mode, only 'VBUS' or 'Power key' pressed can make it leave this mode. 'Disable' also can help to leave it, but it's more like to abort the action before the device really enter shipping mode.
Note: use /sys/class/power_supply/rt9467-*/load_switch instead.
---
Aha. It's the line above that now needs to have the '*' character escaped. I have no warnings after that is done.
Quoted 35 lines
Quoted 3 lines
$ docutils --version docutils-3.13 (Docutils 0.23, Python 3.13.16, on linux)I have
docutils (Docutils 0.20.1, Python 3.12.3, on linux)
Quoted 27 lines
Quoted 27 lines
Reported-by kernel test robot <[email protected]>Signed-off-by Waqar Hameed <[email protected]>--- Documentation/ABI/testing/sysfs-class-power-rt9471 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)Documentation/ABI/testing/sysfs-class-power-rt9471 +2
-2@@ -1,4 +1,4 @@ -What: /sys/class/power_supply/rt9471-*/sysoff_enable +What: /sys/class/power_supply/rt9471-\*/sysoff_enable Date: Feb 2023 KernelVersion: 6.3 Contact: ChiYuan Huang <[email protected]>@@ -16,7 +16,7 @@ Description: - 1: enabled - 0: disabled -What: /sys/class/power_supply/rt9471-*/port_detect_enable +What: /sys/class/power_supply/rt9471-\*/port_detect_enable Date: Feb 2023 KernelVersion: 6.3 Contact: ChiYuan Huang <[email protected]>
Signature · 1 line
~Randy
Re: [PATCH 1/7] docs: ABI: power: rt9471: Fix invalid inline emphasis
Quoted 50 lines · On Mon, Oct 26, 2026 at 13:13 -0700 Randy Dunlap <[email protected]> wrote:
Quoted 9 lines · Waqar Hameed
Quoted 7 lines · On Sun, Oct 25, 2026 at 19:39 -0700 Randy Dunlap <[email protected]> wrote:
Quoted 6 lines · Waqar Hameed
docutilswarns:
Documentation/ABI/testing/sysfs-class-power-rt9471:1: (WARNING/2) Inline emphasis start-string without end-string.Documentation/ABI/testing/sysfs-class-power-rt9471:20: (WARNING/2) Inline
emphasis start-string without end-string.Quoted 9 lines
Quoted 5 lines
Quoted 1 line
Fix this by escaping the
*.I'm still seeing this issue after the patch is applied (same for patch 4/7). Maybe we are fighting a docutils your-version vs. my-version problem or just a moving target.
Hm, that's weird. What output do you actually get? The '*' is escaped now, so it shouldn't complain...
docutils still complains:
Documentation/ABI/testing/sysfs-class-power-rt9467:1: WARNING: Inline emphasis start-string without end-string. [docutils]Documentation/ABI/testing/sysfs-class-power-rt9471:1: WARNING: Inline emphasis start-string without end-string. [docutils]and running the command that Mauro provided:
$ ./tools/docs/get_abi.py -D Documentation/ABI/testing/ rest --enable-lineno|grep -A20 rt9467gives me:
.. LINENO Documentation/ABI/testing/sysfs-class-power-rt9467#1..
_abi_sys_class_power_supply_rt9467_sysoff_enable:+------------------------------------------------------------+ | **\/sys\/class\/power_supply\/rt9467\-\\*\/sysoff_enable** | +------------------------------------------------------------+Defined on file :ref:
sysfs-class-power-rt9467 <abi_file_testing_sysfs_class_pow er_rt9467>This entry allows enabling the sysoff mode of rt9467 charger devices.
If enabled and the input is removed, the internal battery FET is turned off to reduce the leakage from the BAT pin. See device datasheet for details. It's commonly used when the product enter shipping stage. After entering shipping mode, only 'VBUS' or 'Power key' pressed can make it leave this mode. 'Disable' also can help to leave it, but it's more like to abort the action before the device really enter shipping mode.
Quoted 5 lines
Note: use
/sys/class/power_supply/rt9467-*/load_switchinstead.
---Aha. It's the line above that now needs to have the '*' character escaped. I have no warnings after that is done.
Ah, linux-next just got updated (merged) with the changes from Sebastian's tree. I'll rebase the series and of course fix this one as well!
PATCH 2/7 docs: ABI: power: rt9471: Add newline for paragraphs
In reply to Waqar HameedTo split paragraphs in reStructuredText, an empty line is needed. Otherwise the output will be:
Access: Read, Write Valid values: - 1: enabled - 0: disabled
Add a newline in order to properly format it as intended:
--- Documentation/ABI/testing/sysfs-class-power-rt9471 | 2 ++ 1 file changed, 2 insertions(+)
Documentation/ABI/testing/sysfs-class-power-rt9471 +2 -0
@@ -12,6 +12,7 @@ Description: the action before the device really enter shipping mode. Access: Read, Write + Valid values: - 1: enabled - 0: disabled
@@ -27,6 +28,7 @@ Description: datasheet for details. Normally controlled when TypeC/USBPD port integrated. Access: Read, Write + Valid values: - 1: enabled - 0: disabled
Signature · 1 line
2.43.0
Re: [PATCH 2/7] docs: ABI: power: rt9471: Add newline for paragraphs
Hi,
Quoted 19 lines · Waqar Hameed
To split paragraphs in reStructuredText, an empty line is needed. Otherwise the output will be:
Access: Read, Write Valid values: - 1: enabled - 0: disabled
Add a newline in order to properly format it as intended:
Reported-by Mauro Carvalho Chehab <[email protected]>Signed-off-by Waqar Hameed <[email protected]>--- Documentation/ABI/testing/sysfs-class-power-rt9471 | 2 ++ 1 file changed, 2 insertions(+)Documentation/ABI/testing/sysfs-class-power-rt9471 +0
-0
Documentation/ABI/testing/sysfs-class-power-rt9471 Description: · line 16
Quoted 5 lines
Documentation/ABI/testing/sysfs-class-power-rt9471 +1
-0@@ -12,6 +12,7 @@ Description: the action before the device really enter shipping mode. Access: Read, Write + Valid values:
It would look nicer to add a blank line here (and below) so that the 2 following lines are processed as bullet items.
(as Mauro suggested)
Same for patch 5/7.
Quoted 10 lines
Documentation/ABI/testing/sysfs-class-power-rt9471 +1
-0- 1: enabled - 0: disabled@@ -27,6 +28,7 @@ Description: datasheet for details. Normally controlled when TypeC/USBPD port integrated. Access: Read, Write + Valid values: - 1: enabled - 0: disabled
Signature · 1 line
~Randy
Re: [PATCH 2/7] docs: ABI: power: rt9471: Add newline for paragraphs
Quoted 32 lines · On Sun, Oct 25, 2026 at 19:29 -0700 Randy Dunlap <[email protected]> wrote:
Hi,
Quoted 19 lines · Waqar Hameed
To split paragraphs in reStructuredText, an empty line is needed. Otherwise the output will be:
Access: Read, Write Valid values: - 1: enabled - 0: disabled
Add a newline in order to properly format it as intended:
Reported-by Mauro Carvalho Chehab <[email protected]>Signed-off-by Waqar Hameed <[email protected]>--- Documentation/ABI/testing/sysfs-class-power-rt9471 | 2 ++ 1 file changed, 2 insertions(+)Documentation/ABI/testing/sysfs-class-power-rt9471 +0
-0Documentation/ABI/testing/sysfs-class-power-rt9471 Description: · line 16
Quoted 5 lines
Documentation/ABI/testing/sysfs-class-power-rt9471 +1
-0@@ -12,6 +12,7 @@ Description: the action before the device really enter shipping mode. Access: Read, Write + Valid values:It would look nicer to add a blank line here (and below) so that the 2 following lines are processed as bullet items.
(as Mauro suggested)
Quoted 1 line
Same for patch 5/7.
Oh, missed that one! Will fix in next version then. Thanks!
There are _a lot_ similar cases of this in the directory. I'll let someone else clean those up...
[...]
PATCH 3/7 docs: ABI: power: rt9471: Fix mismatched quote
In reply to Waqar HameedQuotes should have matching characters. Fix this by replacing '"' with '''.
--- Documentation/ABI/testing/sysfs-class-power-rt9471 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/ABI/testing/sysfs-class-power-rt9471 +1 -1
@@ -7,7 +7,7 @@ Description: If enabled and the input is removed, the internal battery FET is turned off to reduce the leakage from the BAT pin. See device datasheet for details. It's commonly used when the product enter shipping stage. After entering - shipping mode, only 'VBUS' or 'Power key" pressed can make it leave this + shipping mode, only 'VBUS' or 'Power' pressed can make it leave this mode. 'Disable' also can help to leave it, but it's more like to abort the action before the device really enter shipping mode.
Signature · 1 line
2.43.0
Re: [PATCH 3/7] docs: ABI: power: rt9471: Fix mismatched quote
Quoted 6 lines · Waqar Hameed
Quotes should have matching characters. Fix this by replacing '"' with '''.
Thanks.
Quoted 17 lines
--- Documentation/ABI/testing/sysfs-class-power-rt9471 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/ABI/testing/sysfs-class-power-rt9471 +1
-1@@ -7,7 +7,7 @@ Description: If enabled and the input is removed, the internal battery FET is turned off to reduce the leakage from the BAT pin. See device datasheet for details. It's commonly used when the product enter shipping stage. After entering - shipping mode, only 'VBUS' or 'Power key" pressed can make it leave this + shipping mode, only 'VBUS' or 'Power' pressed can make it leave this mode. 'Disable' also can help to leave it, but it's more like to abort the action before the device really enter shipping mode.
Signature · 1 line
~Randy
PATCH 4/7 docs: ABI: power: rt9467: Fix invalid inline emphasis
In reply to Waqar Hameeddocutils warns:
Documentation/ABI/testing/sysfs-class-power-rt9467:1: (WARNING/2) Inline emphasis start-string without end-string.
Fix this by escaping the *.
--- Documentation/ABI/testing/sysfs-class-power-rt9467 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/ABI/testing/sysfs-class-power-rt9467 +1 -1
@@ -1,4 +1,4 @@ -What: /sys/class/power_supply/rt9467-*/sysoff_enable +What: /sys/class/power_supply/rt9467-\*/sysoff_enable Date: Feb 2023 KernelVersion: 6.3 Contact: ChiaEn Wu <[email protected]>
Signature · 1 line
2.43.0
PATCH 5/7 docs: ABI: power: rt9467: Add newline for paragraphs
In reply to Waqar HameedTo split paragraphs in reStructuredText, an empty line is needed. Otherwise the output will be:
Access: Read, Write Valid values: - 1: enabled - 0: disabled
Add a newline in order to properly format it as intended:
--- Documentation/ABI/testing/sysfs-class-power-rt9467 | 1 + 1 file changed, 1 insertion(+)
Documentation/ABI/testing/sysfs-class-power-rt9467 +1 -0
@@ -14,6 +14,7 @@ Description: abort the action before the device really enter shipping mode. Access: Read, Write + Valid values: - 1: enabled - 0: disabled
Signature · 1 line
2.43.0
PATCH 6/7 docs: ABI: power: rt9467: Fix mismatched quote
In reply to Waqar HameedQuotes should have matching characters. Fix this by replacing '"' with '''.
--- Documentation/ABI/testing/sysfs-class-power-rt9467 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/ABI/testing/sysfs-class-power-rt9467 +1 -1
@@ -9,7 +9,7 @@ Description: is turned off to reduce the leakage from the BAT pin. See device datasheet for details. It's commonly used when the product enter shipping stage. After entering shipping mode, - only 'VBUS' or 'Power key" pressed can make it leave this mode. + only 'VBUS' or 'Power key' pressed can make it leave this mode. 'Disable' also can help to leave it, but it's more like to abort the action before the device really enter shipping mode.
Signature · 1 line
2.43.0
Re: [PATCH 6/7] docs: ABI: power: rt9467: Fix mismatched quote
Quoted 6 lines · Waqar Hameed
Quotes should have matching characters. Fix this by replacing '"' with '''.
Thanks.
Quoted 17 lines
--- Documentation/ABI/testing/sysfs-class-power-rt9467 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/ABI/testing/sysfs-class-power-rt9467 +1
-1@@ -9,7 +9,7 @@ Description: is turned off to reduce the leakage from the BAT pin. See device datasheet for details. It's commonly used when the product enter shipping stage. After entering shipping mode, - only 'VBUS' or 'Power key" pressed can make it leave this mode. + only 'VBUS' or 'Power key' pressed can make it leave this mode. 'Disable' also can help to leave it, but it's more like to abort the action before the device really enter shipping mode.
Signature · 1 line
~Randy
PATCH 7/7 docs: ABI: power: rt9756: Fix invalid inline emphasis
In reply to Waqar Hameeddocutils warns:
Documentation/ABI/testing/sysfs-class-power-rt9756:1: (WARNING/2) Inline emphasis start-string without end-string. Documentation/ABI/testing/sysfs-class-power-rt9756:17: (WARNING/2) Inline emphasis start-string without end-string.
Fix this by escaping the *.
--- Documentation/ABI/testing/sysfs-class-power-rt9756 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/ABI/testing/sysfs-class-power-rt9756 +2 -2
@@ -1,4 +1,4 @@ -What: /sys/class/power_supply/rt9756-*/watchdog_timer +What: /sys/class/power_supply/rt9756-\*/watchdog_timer Date: Dec 2025 KernelVersion: 6.19 Contact: ChiYuan Huang <[email protected]>
@@ -14,7 +14,7 @@ Description: - 500, 1000, 5000, 30000, 40000, 80000, 128000 or 255000 (milliseconds), - 0: disabled -What: /sys/class/power_supply/rt9756-*/operation_mode +What: /sys/class/power_supply/rt9756-\*/operation_mode Date: Dec 2025 KernelVersion: 6.19 Contact: ChiYuan Huang <[email protected]>
Signature · 1 line
2.43.0