* [PATCH v2 1/2] platform/chrome: Use tables for values lists of ChromeOS ACPI sysfs ABI
2022-05-18 8:35 [PATCH v2 0/2] Documentation update for Chrome OS ACPI Bagas Sanjaya
@ 2022-05-18 8:35 ` Bagas Sanjaya
2022-05-18 11:27 ` Muhammad Usama Anjum
2022-05-18 8:35 ` [PATCH v2 2/2] platform/chrome: Use imperative mood for ChromeOS ACPI sysfs ABI descriptions Bagas Sanjaya
2022-05-18 11:56 ` [PATCH v2 0/2] Documentation update for Chrome OS ACPI Tzung-Bi Shih
2 siblings, 1 reply; 6+ messages in thread
From: Bagas Sanjaya @ 2022-05-18 8:35 UTC (permalink / raw)
To: linux-doc
Cc: Bagas Sanjaya, Stephen Rothwell, Benson Leung, Guenter Roeck,
Andy Shevchenko, Greg Kroah-Hartman, Rafael J . Wysocki,
Dmitry Torokhov, Enric Balletbo i Serra, Muhammad Usama Anjum,
Tzung-Bi Shih, Linux Kernel Mailing List, Linux Next Mailing List
Stephen Rothwell reported htmldocs warning when merging chrome-platform
tree:
Documentation/ABI/testing/sysfs-driver-chromeos-acpi:2: WARNING: Unexpected indentation.
Documentation/ABI/testing/sysfs-driver-chromeos-acpi:11: WARNING: Unexpected indentation.
Documentation/ABI/testing/sysfs-driver-chromeos-acpi:22: WARNING: Unexpected indentation.
Documentation/ABI/testing/sysfs-driver-chromeos-acpi:56: WARNING: Unexpected indentation.
The warning is due to missing blank line separator surrounding values
lists.
Instead of using lists, use tables to be consistent with rest of sysfs
ABI documentation.
Link: https://lore.kernel.org/linux-next/20220516213832.19127535@canb.auug.org.au/
Fixes: 0a4cad9c11ad46 ("platform/chrome: Add ChromeOS ACPI device
driver")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Cc: Benson Leung <bleung@google.com>
Cc: Guenter Roeck <groeck@chromium.org>
Cc: Andy Shevchenko <andy.shevchenko@gmail.com>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Cc: Enric Balletbo i Serra <enric.balletbo@collabora.com>
Cc: Muhammad Usama Anjum <usama.anjum@collabora.com>
Cc: Tzung-Bi Shih <tzungbi@kernel.org>
Cc: Linux Kernel Mailing List <linux-kernel@vger.kernel.org>
Cc: Linux Next Mailing List <linux-next@vger.kernel.org>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
.../ABI/testing/sysfs-driver-chromeos-acpi | 52 ++++++++++++-------
1 file changed, 33 insertions(+), 19 deletions(-)
diff --git a/Documentation/ABI/testing/sysfs-driver-chromeos-acpi b/Documentation/ABI/testing/sysfs-driver-chromeos-acpi
index 5b59ef9d7b371c..cce45395170079 100644
--- a/Documentation/ABI/testing/sysfs-driver-chromeos-acpi
+++ b/Documentation/ABI/testing/sysfs-driver-chromeos-acpi
@@ -4,8 +4,11 @@ KernelVersion: 5.19
Description:
This file shows information about the current boot of
the active EC firmware.
- * 0 - Read only (recovery) firmware.
- * 1 - Rewritable firmware.
+
+ == ===============================
+ 0 Read only (recovery) firmware.
+ 1 Rewritable firmware.
+ == ===============================
What: /sys/bus/platform/devices/GGL0001:*/BINF.3
Date: May 2022
@@ -13,23 +16,28 @@ KernelVersion: 5.19
Description:
This file shows information about the current boot of
the active main firmware type.
- * 0 - Recovery.
- * 1 - Normal.
- * 2 - Developer.
- * 3 - Netboot (factory installation only).
+
+ == =====================================
+ 0 Recovery.
+ 1 Normal.
+ 2 Developer.
+ 3 Netboot (factory installation only).
+ == =====================================
What: /sys/bus/platform/devices/GGL0001:*/CHSW
Date: May 2022
KernelVersion: 5.19
Description:
This file shows the switch position for the Chrome OS specific
- hardware switches.
- * 0 - No changes.
- * 2 - Recovery button was pressed when firmware booted.
- * 4 - Recovery button was pressed when EC firmware booted.
- * 32 - Developer switch was enabled when firmware booted.
- * 512 - Firmware write protection was disabled when firmware
- booted.
+ hardware switches when the firmware is booted.
+
+ ==== ===========================================
+ 0 No changes.
+ 2 Recovery button was pressed.
+ 4 Recovery button was pressed (EC firmware).
+ 32 Developer switch was enabled.
+ 512 Firmware write protection was disabled.
+ ==== ===========================================
What: /sys/bus/platform/devices/GGL0001:*/FMAP
Date: May 2022
@@ -58,18 +66,24 @@ KernelVersion: 5.19
Description:
This file shows the type of the GPIO signal for the Chrome OS
specific GPIO assignments.
- * 1 - Recovery button.
- * 2 - Developer mode switch.
- * 3 - Firmware write protection switch.
- * 256 to 511 - Debug header GPIO 0 to GPIO 255.
+
+ =========== ==================================
+ 1 Recovery button.
+ 2 Developer mode switch.
+ 3 Firmware write protection switch.
+ 256 to 511 Debug header GPIO 0 to GPIO 255.
+ =========== ==================================
What: /sys/bus/platform/devices/GGL0001:*/GPIO.X/GPIO.1
Date: May 2022
KernelVersion: 5.19
Description:
This file shows the signal attributes of the GPIO signal.
- * 0 - Signal is active low.
- * 1 - Signal is active high.
+
+ == =======================
+ 0 Signal is active low.
+ 1 Signal is active high.
+ == =======================
What: /sys/bus/platform/devices/GGL0001:*/GPIO.X/GPIO.2
Date: May 2022
--
An old man doll... just what I always wanted! - Clara
^ permalink raw reply related [flat|nested] 6+ messages in thread* Re: [PATCH v2 1/2] platform/chrome: Use tables for values lists of ChromeOS ACPI sysfs ABI
2022-05-18 8:35 ` [PATCH v2 1/2] platform/chrome: Use tables for values lists of ChromeOS ACPI sysfs ABI Bagas Sanjaya
@ 2022-05-18 11:27 ` Muhammad Usama Anjum
0 siblings, 0 replies; 6+ messages in thread
From: Muhammad Usama Anjum @ 2022-05-18 11:27 UTC (permalink / raw)
To: Bagas Sanjaya, linux-doc
Cc: usama.anjum, Stephen Rothwell, Benson Leung, Guenter Roeck,
Andy Shevchenko, Greg Kroah-Hartman, Rafael J . Wysocki,
Dmitry Torokhov, Tzung-Bi Shih, Linux Kernel Mailing List,
Linux Next Mailing List
On 5/18/22 1:35 PM, Bagas Sanjaya wrote:
> Stephen Rothwell reported htmldocs warning when merging chrome-platform
> tree:
>
> Documentation/ABI/testing/sysfs-driver-chromeos-acpi:2: WARNING: Unexpected indentation.
> Documentation/ABI/testing/sysfs-driver-chromeos-acpi:11: WARNING: Unexpected indentation.
> Documentation/ABI/testing/sysfs-driver-chromeos-acpi:22: WARNING: Unexpected indentation.
> Documentation/ABI/testing/sysfs-driver-chromeos-acpi:56: WARNING: Unexpected indentation.
>
> The warning is due to missing blank line separator surrounding values
> lists.
>
> Instead of using lists, use tables to be consistent with rest of sysfs
> ABI documentation.
>
> Link: https://lore.kernel.org/linux-next/20220516213832.19127535@canb.auug.org.au/
> Fixes: 0a4cad9c11ad46 ("platform/chrome: Add ChromeOS ACPI device
> driver")
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Cc: Benson Leung <bleung@google.com>
> Cc: Guenter Roeck <groeck@chromium.org>
> Cc: Andy Shevchenko <andy.shevchenko@gmail.com>
> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Cc: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
> Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
> Cc: Enric Balletbo i Serra <enric.balletbo@collabora.com>
> Cc: Muhammad Usama Anjum <usama.anjum@collabora.com>
> Cc: Tzung-Bi Shih <tzungbi@kernel.org>
> Cc: Linux Kernel Mailing List <linux-kernel@vger.kernel.org>
> Cc: Linux Next Mailing List <linux-next@vger.kernel.org>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Reviewed-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
--
Muhammad Usama Anjum
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH v2 2/2] platform/chrome: Use imperative mood for ChromeOS ACPI sysfs ABI descriptions
2022-05-18 8:35 [PATCH v2 0/2] Documentation update for Chrome OS ACPI Bagas Sanjaya
2022-05-18 8:35 ` [PATCH v2 1/2] platform/chrome: Use tables for values lists of ChromeOS ACPI sysfs ABI Bagas Sanjaya
@ 2022-05-18 8:35 ` Bagas Sanjaya
2022-05-18 11:27 ` Muhammad Usama Anjum
2022-05-18 11:56 ` [PATCH v2 0/2] Documentation update for Chrome OS ACPI Tzung-Bi Shih
2 siblings, 1 reply; 6+ messages in thread
From: Bagas Sanjaya @ 2022-05-18 8:35 UTC (permalink / raw)
To: linux-doc
Cc: Bagas Sanjaya, Benson Leung, Guenter Roeck, Andy Shevchenko,
Greg Kroah-Hartman, Rafael J . Wysocki, Dmitry Torokhov,
Enric Balletbo i Serra, Muhammad Usama Anjum, Tzung-Bi Shih,
Linux Kernel Mailing List, Linux Next Mailing List
The current descriptions all begin with ("This file shows something")
clause, which is incorrect wording since these mean return value from
sysfs.
Use imperative mood ("Returns something") instead, in line with
corresponding ACPI documentation at firmware-guide/.
Cc: Benson Leung <bleung@google.com>
Cc: Guenter Roeck <groeck@chromium.org>
Cc: Andy Shevchenko <andy.shevchenko@gmail.com>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Cc: Enric Balletbo i Serra <enric.balletbo@collabora.com>
Cc: Muhammad Usama Anjum <usama.anjum@collabora.com>
Cc: Tzung-Bi Shih <tzungbi@kernel.org>
Cc: Linux Kernel Mailing List <linux-kernel@vger.kernel.org>
Cc: Linux Next Mailing List <linux-next@vger.kernel.org>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
.../ABI/testing/sysfs-driver-chromeos-acpi | 63 +++++++++----------
1 file changed, 30 insertions(+), 33 deletions(-)
diff --git a/Documentation/ABI/testing/sysfs-driver-chromeos-acpi b/Documentation/ABI/testing/sysfs-driver-chromeos-acpi
index cce45395170079..c308926e1568a7 100644
--- a/Documentation/ABI/testing/sysfs-driver-chromeos-acpi
+++ b/Documentation/ABI/testing/sysfs-driver-chromeos-acpi
@@ -2,8 +2,7 @@ What: /sys/bus/platform/devices/GGL0001:*/BINF.2
Date: May 2022
KernelVersion: 5.19
Description:
- This file shows information about the current boot of
- the active EC firmware.
+ Returns active EC firmware of current boot (boolean).
== ===============================
0 Read only (recovery) firmware.
@@ -14,8 +13,7 @@ What: /sys/bus/platform/devices/GGL0001:*/BINF.3
Date: May 2022
KernelVersion: 5.19
Description:
- This file shows information about the current boot of
- the active main firmware type.
+ Returns main firmware type for current boot (integer).
== =====================================
0 Recovery.
@@ -28,8 +26,8 @@ What: /sys/bus/platform/devices/GGL0001:*/CHSW
Date: May 2022
KernelVersion: 5.19
Description:
- This file shows the switch position for the Chrome OS specific
- hardware switches when the firmware is booted.
+ Returns switch position for Chrome OS specific hardware
+ switches when the firmware is booted (integer).
==== ===========================================
0 No changes.
@@ -43,29 +41,29 @@ What: /sys/bus/platform/devices/GGL0001:*/FMAP
Date: May 2022
KernelVersion: 5.19
Description:
- This file shows the physical memory address of the start of
- the main processor firmware flashmap.
+ Returns physical memory address of the start of the main
+ processor firmware flashmap.
What: /sys/bus/platform/devices/GGL0001:*/FRID
Date: May 2022
KernelVersion: 5.19
Description:
- This file shows the firmware version for the read-only portion
- of the main processor firmware.
+ Returns firmware version for the read-only portion of the
+ main processor firmware.
What: /sys/bus/platform/devices/GGL0001:*/FWID
Date: May 2022
KernelVersion: 5.19
Description:
- This file shows the firmware version for the rewritable portion
- of the main processor firmware.
+ Returns firmware version for the rewritable portion of the
+ main processor firmware.
What: /sys/bus/platform/devices/GGL0001:*/GPIO.X/GPIO.0
Date: May 2022
KernelVersion: 5.19
Description:
- This file shows the type of the GPIO signal for the Chrome OS
- specific GPIO assignments.
+ Returns type of the GPIO signal for the Chrome OS specific
+ GPIO assignments (integer).
=========== ==================================
1 Recovery button.
@@ -78,7 +76,7 @@ What: /sys/bus/platform/devices/GGL0001:*/GPIO.X/GPIO.1
Date: May 2022
KernelVersion: 5.19
Description:
- This file shows the signal attributes of the GPIO signal.
+ Returns signal attributes of the GPIO signal (integer bitfield).
== =======================
0 Signal is active low.
@@ -89,52 +87,51 @@ What: /sys/bus/platform/devices/GGL0001:*/GPIO.X/GPIO.2
Date: May 2022
KernelVersion: 5.19
Description:
- This file shows the GPIO number on the specified GPIO
+ Returns the GPIO number on the specified GPIO
controller.
What: /sys/bus/platform/devices/GGL0001:*/GPIO.X/GPIO.3
Date: May 2022
KernelVersion: 5.19
Description:
- This file shows the name of the GPIO controller.
+ Returns name of the GPIO controller.
What: /sys/bus/platform/devices/GGL0001:*/HWID
Date: May 2022
KernelVersion: 5.19
Description:
- This file shows the hardware ID for the Chromebook.
+ Returns hardware ID for the Chromebook.
What: /sys/bus/platform/devices/GGL0001:*/MECK
Date: May 2022
KernelVersion: 5.19
Description:
- This binary file returns the SHA-1 or SHA-256 hash that is
- read out of the Management Engine extended registers during
- boot. The hash is exported vi ACPI so the OS can verify that
- the Management Engine firmware has not changed. If Management
- Engine is not present, or if the firmware was unable to read the
- extended registers, this buffer size can be zero.
+ Returns the SHA-1 or SHA-256 hash that is read out of the
+ Management Engine extended registers during boot. The hash
+ is exported via ACPI so the OS can verify that the Management
+ Engine firmware has not changed. If Management Engine is not
+ present, or if the firmware was unable to read the extended registers, this buffer size can be zero.
What: /sys/bus/platform/devices/GGL0001:*/VBNV.0
Date: May 2022
KernelVersion: 5.19
Description:
- This file shows the offset in CMOS bank 0 of the verified boot
- non-volatile storage block, counting from the first writable
- CMOS byte (that is, 'offset = 0' is the byte following the 14
- bytes of clock data).
+ Returns offset in CMOS bank 0 of the verified boot non-volatile
+ storage block, counting from the first writable CMOS byte
+ (that is, 'offset = 0' is the byte following the 14 bytes of
+ clock data).
What: /sys/bus/platform/devices/GGL0001:*/VBNV.1
Date: May 2022
KernelVersion: 5.19
Description:
- This file shows the size in bytes of the verified boot
- non-volatile storage block.
+ Return the size in bytes of the verified boot non-volatile
+ storage block.
What: /sys/bus/platform/devices/GGL0001:*/VDAT
Date: May 2022
KernelVersion: 5.19
Description:
- This binary file returns the verified boot data block shared
- between the firmware verification step and the kernel
- verification step.
+ Returns the verified boot data block shared between the
+ firmware verification step and the kernel verification step
+ (binary).
--
An old man doll... just what I always wanted! - Clara
^ permalink raw reply related [flat|nested] 6+ messages in thread* Re: [PATCH v2 2/2] platform/chrome: Use imperative mood for ChromeOS ACPI sysfs ABI descriptions
2022-05-18 8:35 ` [PATCH v2 2/2] platform/chrome: Use imperative mood for ChromeOS ACPI sysfs ABI descriptions Bagas Sanjaya
@ 2022-05-18 11:27 ` Muhammad Usama Anjum
0 siblings, 0 replies; 6+ messages in thread
From: Muhammad Usama Anjum @ 2022-05-18 11:27 UTC (permalink / raw)
To: Bagas Sanjaya, linux-doc
Cc: usama.anjum, Benson Leung, Guenter Roeck, Andy Shevchenko,
Greg Kroah-Hartman, Rafael J . Wysocki, Dmitry Torokhov,
Tzung-Bi Shih, Linux Kernel Mailing List, Linux Next Mailing List
On 5/18/22 1:35 PM, Bagas Sanjaya wrote:
> The current descriptions all begin with ("This file shows something")
> clause, which is incorrect wording since these mean return value from
> sysfs.
>
> Use imperative mood ("Returns something") instead, in line with
> corresponding ACPI documentation at firmware-guide/.
>
> Cc: Benson Leung <bleung@google.com>
> Cc: Guenter Roeck <groeck@chromium.org>
> Cc: Andy Shevchenko <andy.shevchenko@gmail.com>
> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Cc: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
> Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
> Cc: Enric Balletbo i Serra <enric.balletbo@collabora.com>
> Cc: Muhammad Usama Anjum <usama.anjum@collabora.com>
> Cc: Tzung-Bi Shih <tzungbi@kernel.org>
> Cc: Linux Kernel Mailing List <linux-kernel@vger.kernel.org>
> Cc: Linux Next Mailing List <linux-next@vger.kernel.org>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Reviewed-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
--
Muhammad Usama Anjum
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH v2 0/2] Documentation update for Chrome OS ACPI
2022-05-18 8:35 [PATCH v2 0/2] Documentation update for Chrome OS ACPI Bagas Sanjaya
2022-05-18 8:35 ` [PATCH v2 1/2] platform/chrome: Use tables for values lists of ChromeOS ACPI sysfs ABI Bagas Sanjaya
2022-05-18 8:35 ` [PATCH v2 2/2] platform/chrome: Use imperative mood for ChromeOS ACPI sysfs ABI descriptions Bagas Sanjaya
@ 2022-05-18 11:56 ` Tzung-Bi Shih
2 siblings, 0 replies; 6+ messages in thread
From: Tzung-Bi Shih @ 2022-05-18 11:56 UTC (permalink / raw)
To: Bagas Sanjaya
Cc: linux-doc, Benson Leung, Guenter Roeck, Andy Shevchenko,
Greg Kroah-Hartman, Rafael J . Wysocki, Dmitry Torokhov,
Enric Balletbo i Serra, Muhammad Usama Anjum,
Linux Kernel Mailing List, Linux Next Mailing List
On Wed, May 18, 2022 at 03:35:22PM +0700, Bagas Sanjaya wrote:
> Two documentation patches touching Chrome OS ACPI sysfs.
>
> 1. Patch [1/2] fixes htmldocs warning reported in linux-next and should
> be merged before upcoming merge window.
> 2. Patch [2/2] rewrites symbol descriptions to use imperative mood. It
> can be merged when appropriate, independent of previous patch
> above.
>
> [...]
Applied, thanks!
[1/2] platform/chrome: Use tables for values lists of ChromeOS ACPI sysfs ABI
commit: 596cbc6ab0abd18206b3247aaeaa225788afaf8c
[2/2] platform/chrome: Use imperative mood for ChromeOS ACPI sysfs ABI descriptions
commit: 7bff62406671dd89e9d1a7bf00169197f2833c41
^ permalink raw reply [flat|nested] 6+ messages in thread