Documentation/ABI: platform/x86: Sphinx warning fixes
cover Documentation/ABI: platform/x86: Sphinx warning fixes
Hi All,
After Stephen reported some Sphinx warnings for files under Documentation/ABI/testing, I had to first figure out how to reproduce these. It turns out that to regenerate the htmldocs for files under Documentation/ABI/testing once has to run:
touch Documentation/admin-guide/abi-testing.rst && make htmldocs
This turned up warnings in multiple sysfs ABI files for platform/x86 drivers, as well as in some new functionality in sysfs-class-power, which was merged through the platform-drivers-x86 tree.
I plan to merge this series through the platform-drivers-x86 tree and send this out in a fixed pull-req to Linus once 5.18-rc1 is out.
Regards,
Hans
p.s.
platform-drivers-x86 authors, for future patch submissions touching files under Documentation/ABI/testing please run:
touch Documentation/admin-guide/abi-testing.rst && make htmldocs
and make sure no warnings are introduced.
Hans de Goede (4):
Documentation/ABI: sysfs-driver-intel_sdsi: Fix sphinx warnings Documentation/ABI: sysfs-class-firmware-attributes: Fix Sphinx errors Documentation/ABI: sysfs-class-firmware-attributes: Misc. cleanups Documentation/ABI: sysfs-class-power: Fix Sphinx error
.../testing/sysfs-class-firmware-attributes | 48 ++++++++++--------- Documentation/ABI/testing/sysfs-class-power | 1 + .../ABI/testing/sysfs-driver-intel_sdsi | 18 +++---- 3 files changed, 37 insertions(+), 30 deletions(-)
Signature · 1 line
2.35.1
PATCH 1/4 Documentation/ABI: sysfs-driver-intel_sdsi: Fix sphinx warnings
Fix the following warnings from "make htmldocs":
Documentation/ABI/testing/sysfs-driver-intel_sdsi:2:
WARNING: Unexpected indentation.
WARNING: Block quote ends without a blank line; unexpected unindent.
WARNING: Definition list ends without a blank line; unexpected unindent.
By turning the error-code table into a proper ReST table. While at it also fix the error-code table mixing tab and spaces for indentation (switch to all tabs).
--- .../ABI/testing/sysfs-driver-intel_sdsi | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-)
Documentation/ABI/testing/sysfs-driver-intel_sdsi +10 -8
@@ -13,17 +13,19 @@ Description: Should the operation fail, one of the following error codes may be returned: + ========== ===== Error Code Cause - ---------- ----- - EIO General mailbox failure. Log may indicate cause. - EBUSY Mailbox is owned by another agent. - EPERM SDSI capability is not enabled in hardware. - EPROTO Failure in mailbox protocol detected by driver. + ========== ===== + EIO General mailbox failure. Log may indicate cause. + EBUSY Mailbox is owned by another agent. + EPERM SDSI capability is not enabled in hardware. + EPROTO Failure in mailbox protocol detected by driver. See log for details. - EOVERFLOW For provision commands, the size of the data + EOVERFLOW For provision commands, the size of the data exceeds what may be written. - ESPIPE Seeking is not allowed. - ETIMEDOUT Failure to complete mailbox transaction in time. + ESPIPE Seeking is not allowed. + ETIMEDOUT Failure to complete mailbox transaction in time. + ========== ===== What: /sys/bus/auxiliary/devices/intel_vsec.sdsi.X/guid Date: Feb 2022
Signature · 1 line
2.35.1
Re: [PATCH 1/4] Documentation/ABI: sysfs-driver-intel_sdsi: Fix sphinx warnings
Quoted 10 lines · Hans de Goede
Fix the following warnings from "make htmldocs":
Documentation/ABI/testing/sysfs-driver-intel_sdsi:2:
WARNING: Unexpected indentation.
WARNING: Block quote ends without a blank line; unexpected unindent.
WARNING: Definition list ends without a blank line; unexpected unindent.By turning the error-code table into a proper ReST table. While at it also fix the error-code table mixing tab and spaces for indentation (switch to all tabs).
Thanks for the fix and for clarifying how to reproduce.
David
Quoted 44 lines
Reported-by Stephen Rothwell <[email protected]>Signed-off-by Hans de Goede <[email protected]>--- .../ABI/testing/sysfs-driver-intel_sdsi | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-)Documentation/ABI/testing/sysfs-driver-intel_sdsi +1
-2@@ -13,17 +13,19 @@ Description: Should the operation fail, one of the following error codes may be returned: + ========== ===== Error Code Cause - ---------- ----- - EIO General mailbox failure. Log may indicatecause.
Documentation/ABI/testing/sysfs-driver-intel_sdsi +0
-3- EBUSY Mailbox is owned by another agent. - EPERM SDSI capability is not enabled in hardware. - EPROTO Failure in mailbox protocol detected bydriver.
Documentation/ABI/testing/sysfs-driver-intel_sdsi +2
-0+ ========== ===== + EIO General mailbox failure. Log may indicatecause.
Documentation/ABI/testing/sysfs-driver-intel_sdsi +3
-0+ EBUSY Mailbox is owned by another agent. + EPERM SDSI capability is not enabled in hardware. + EPROTO Failure in mailbox protocol detected bydriver.
Documentation/ABI/testing/sysfs-driver-intel_sdsi +4
-3See log for details. - EOVERFLOW For provision commands, the size of the data + EOVERFLOW For provision commands, the size of the data exceeds what may be written. - ESPIPE Seeking is not allowed. - ETIMEDOUT Failure to complete mailbox transaction in time. + ESPIPE Seeking is not allowed. + ETIMEDOUT Failure to complete mailbox transaction in time. + ========== ===== What: /sys/bus/auxiliary/devices/intel_vsec.sdsi.X/guid Date: Feb 2022
PATCH 2/4 Documentation/ABI: sysfs-class-firmware-attributes: Fix Sphinx errors
In reply to Hans de GoedeFix the following warnings from "make htmldocs":
Documentation/ABI/testing/sysfs-class-firmware-attributes:130:
ERROR: Unexpected indentation.
ERROR: Unexpected indentation.
ERROR: Unexpected indentation.
--- .../testing/sysfs-class-firmware-attributes | 42 ++++++++++--------- 1 file changed, 23 insertions(+), 19 deletions(-)
Documentation/ABI/testing/sysfs-class-firmware-attributes +23 -19
@@ -246,9 +246,7 @@ Description: that is being referenced (e.g hdd0, hdd1 etc) This attribute defaults to device 0. - certificate: - signature: - save_signature: + certificate, signature, save_signature: These attributes are used for certificate based authentication. This is used in conjunction with a signing server as an alternative to password based authentication.
@@ -257,22 +255,27 @@ Description: The attributes can be displayed to check the stored value. Some usage examples: - Installing a certificate to enable feature: - echo <supervisor password > authentication/Admin/current_password - echo <signed certificate> > authentication/Admin/certificate - Updating the installed certificate: - echo <signature> > authentication/Admin/signature - echo <signed certificate> > authentication/Admin/certificate + Installing a certificate to enable feature:: - Removing the installed certificate: - echo <signature> > authentication/Admin/signature - echo '' > authentication/Admin/certificate + echo "supervisor password" > authentication/Admin/current_password + echo "signed certificate" > authentication/Admin/certificate - Changing a BIOS setting: - echo <signature> > authentication/Admin/signature - echo <save signature> > authentication/Admin/save_signature - echo Enable > attribute/PasswordBeep/current_value + Updating the installed certificate:: + + echo "signature" > authentication/Admin/signature + echo "signed certificate" > authentication/Admin/certificate + + Removing the installed certificate:: + + echo "signature" > authentication/Admin/signature + echo "" > authentication/Admin/certificate + + Changing a BIOS setting:: + + echo "signature" > authentication/Admin/signature + echo "save signature" > authentication/Admin/save_signature + echo Enable > attribute/PasswordBeep/current_value You cannot enable certificate authentication if a supervisor password has not been set.
@@ -288,9 +291,10 @@ Description: certificate_to_password: Write only attribute used to switch from certificate based authentication back to password based. - Usage: - echo <signature> > authentication/Admin/signature - echo <password> > authentication/Admin/certificate_to_password + Usage:: + + echo "signature" > authentication/Admin/signature + echo "password" > authentication/Admin/certificate_to_password What: /sys/class/firmware-attributes/*/attributes/pending_reboot
Signature · 1 line
2.35.1
Re: [External] [PATCH 2/4] Documentation/ABI: sysfs-class-firmware-attributes: Fix Sphinx errors
Thanks Hans
Quoted 72 lines · Hans de Goede
Fix the following warnings from "make htmldocs":
Documentation/ABI/testing/sysfs-class-firmware-attributes:130:
ERROR: Unexpected indentation.
ERROR: Unexpected indentation.
ERROR: Unexpected indentation.Signed-off-by Hans de Goede <[email protected]>--- .../testing/sysfs-class-firmware-attributes | 42 ++++++++++--------- 1 file changed, 23 insertions(+), 19 deletions(-)Documentation/ABI/testing/sysfs-class-firmware-attributes +19
-16@@ -246,9 +246,7 @@ Description: that is being referenced (e.g hdd0, hdd1 etc) This attribute defaults to device 0. - certificate: - signature: - save_signature: + certificate, signature, save_signature: These attributes are used for certificate based authentication. This is used in conjunction with a signing server as an alternative to password based authentication.@@ -257,22 +255,27 @@ Description: The attributes can be displayed to check the stored value. Some usage examples: - Installing a certificate to enable feature: - echo <supervisor password > authentication/Admin/current_password - echo <signed certificate> > authentication/Admin/certificate - Updating the installed certificate: - echo <signature> > authentication/Admin/signature - echo <signed certificate> > authentication/Admin/certificate + Installing a certificate to enable feature:: - Removing the installed certificate: - echo <signature> > authentication/Admin/signature - echo '' > authentication/Admin/certificate + echo "supervisor password" > authentication/Admin/current_password + echo "signed certificate" > authentication/Admin/certificate - Changing a BIOS setting: - echo <signature> > authentication/Admin/signature - echo <save signature> > authentication/Admin/save_signature - echo Enable > attribute/PasswordBeep/current_value + Updating the installed certificate:: + + echo "signature" > authentication/Admin/signature + echo "signed certificate" > authentication/Admin/certificate + + Removing the installed certificate:: + + echo "signature" > authentication/Admin/signature + echo "" > authentication/Admin/certificate + + Changing a BIOS setting:: + + echo "signature" > authentication/Admin/signature + echo "save signature" > authentication/Admin/save_signature + echo Enable > attribute/PasswordBeep/current_value You cannot enable certificate authentication if a supervisor password has not been set.@@ -288,9 +291,10 @@ Description: certificate_to_password: Write only attribute used to switch from certificate based authentication back to password based.
Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 300
Quoted 10 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +4
-3- Usage: - echo <signature> > authentication/Admin/signature - echo <password> > authentication/Admin/certificate_to_password + Usage:: + + echo "signature" > authentication/Admin/signature + echo "password" > authentication/Admin/certificate_to_password What: /sys/class/firmware-attributes/*/attributes/pending_reboot
Looks good!
Mark
PATCH 3/4 Documentation/ABI: sysfs-class-firmware-attributes: Misc. cleanups
In reply to Hans de GoedeCleanup / fix some minor issues.
--- Documentation/ABI/testing/sysfs-class-firmware-attributes | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/ABI/testing/sysfs-class-firmware-attributes +3 -3
@@ -116,7 +116,7 @@ Description: <value>[ForceIf:<attribute>=<value>] <value>[ForceIfNot:<attribute>=<value>] - For example: + For example:: LegacyOrom/dell_value_modifier has value: Disabled[ForceIf:SecureBoot=Enabled]
@@ -212,7 +212,7 @@ Description: the next boot. Lenovo specific class extensions - ------------------------------ + -------------------------------- On Lenovo systems the following additional settings are available:
@@ -349,7 +349,7 @@ Description: # echo "factory" > /sys/class/firmware-attributes/*/device/attributes/reset_bios # cat /sys/class/firmware-attributes/*/device/attributes/reset_bios - # builtinsafe lastknowngood [factory] custom + builtinsafe lastknowngood [factory] custom Note that any changes to this attribute requires a reboot for changes to take effect.
Signature · 1 line
2.35.1
Re: [External] [PATCH 3/4] Documentation/ABI: sysfs-class-firmware-attributes: Misc. cleanups
Quoted 30 lines · Hans de Goede
Cleanup / fix some minor issues.
Signed-off-by Hans de Goede <[email protected]>--- Documentation/ABI/testing/sysfs-class-firmware-attributes | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)Documentation/ABI/testing/sysfs-class-firmware-attributes +2
-2@@ -116,7 +116,7 @@ Description: <value>[ForceIf:<attribute>=<value>] <value>[ForceIfNot:<attribute>=<value>] - For example: + For example:: LegacyOrom/dell_value_modifier has value: Disabled[ForceIf:SecureBoot=Enabled]@@ -212,7 +212,7 @@ Description: the next boot. Lenovo specific class extensions - ------------------------------ + -------------------------------- On Lenovo systems the following additional settings are available:
Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 355
Quoted 8 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +1
-1@@ -349,7 +349,7 @@ Description: # echo "factory" > /sys/class/firmware-attributes/*/device/attributes/reset_bios # cat /sys/class/firmware-attributes/*/device/attributes/reset_bios - # builtinsafe lastknowngood [factory] custom + builtinsafe lastknowngood [factory] custom Note that any changes to this attribute requires a reboot for changes to take effect.
Looks good - thanks for taking care of this
Mark
PATCH 4/4 Documentation/ABI: sysfs-class-power: Fix Sphinx error
In reply to Hans de GoedeFix the following error from "make htmldocs":
Documentation/ABI/testing/sysfs-class-power:459: ERROR:
No bottom table border found.
================ ====================================
auto: Charge normally, respect thresholds inhibit-charge: Do not charge while AC is attached force-discharge: Force discharge while AC is attached
--- Documentation/ABI/testing/sysfs-class-power | 1 + 1 file changed, 1 insertion(+)
Documentation/ABI/testing/sysfs-class-power +1 -0
@@ -468,6 +468,7 @@ Description: auto: Charge normally, respect thresholds inhibit-charge: Do not charge while AC is attached force-discharge: Force discharge while AC is attached + ================ ==================================== What: /sys/class/power_supply/<supply_name>/technology Date: May 2007
Signature · 1 line
2.35.1
Re: [PATCH 4/4] Documentation/ABI: sysfs-class-power: Fix Sphinx error
Hi,
Quoted 20 lines · Hans de Goede
Fix the following error from "make htmldocs":
Documentation/ABI/testing/sysfs-class-power:459: ERROR:
No bottom table border found.================ ====================================
auto: Charge normally, respect thresholds inhibit-charge: Do not charge while AC is attached force-discharge: Force discharge while AC is attachedSigned-off-by Hans de Goede <[email protected]>--- Documentation/ABI/testing/sysfs-class-power | 1 + 1 file changed, 1 insertion(+)Documentation/ABI/testing/sysfs-class-power +0
-0
Documentation/ABI/testing/sysfs-class-power Description: · line 474
Quoted 7 lines
Documentation/ABI/testing/sysfs-class-power +1
-0@@ -468,6 +468,7 @@ Description: auto: Charge normally, respect thresholds inhibit-charge: Do not charge while AC is attached force-discharge: Force discharge while AC is attached + ================ ==================================== What: /sys/class/power_supply/<supply_name>/technology Date: May 2007
I see a similar change has already landed in linux-power-supply/for-next, so I'll drop this patch from the set.
Regards,
Hans