Subject: Re: linux-next: build warnings after merge of the drivers-x86 tree

From: Jonathan Corbet <[email-masked]>
Date: Thu, 21 Oct 2021 15:10:28 -0600

[CC += Mauro]

Stephen Rothwell <[email-masked]> writes:

> On Thu, 21 Oct 2021 09:07:03 +0000 Vadim Pasternak <[email-masked]> wrote:
>>
>> What is wrong with the syntax at line 230 and where blank line is expected?
>> 
>> What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/bios_active_image
>> What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/bios_auth_fail
>> What:		/sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/bios_upgrade_fail
>> Date:		October 2021	<--- this is line 230
>> KernelVersion:	5.16
>
> I am sorry, I don't know.  Added Jon to cc for advice.

The problem isn't that line at all, it's the use of a bulleted list a
few lines further down; that doesn't work in ABI files.

Mauro, this ABI stuff is fragile, and this kind of problem occurs fairly
often.  How hard would it be to (1) make it a bit more robust, (2) make
it issue useful warnings where it can't be robust, and (3) properly
document the restrictions for ABI files?

Meanwhile, the attached patch fixes it; feel free to use it or to just
fold the change into your work.

Thanks,

jon

-----------------------------
>From 97371e6afda75eef71b7d5d1794645e5cfaf1811 Mon Sep 17 00:00:00 2001
From: Jonathan Corbet <[email-masked]>
Date: Thu, 21 Oct 2021 15:02:43 -0600
Subject: [PATCH] docs: ABI: fix documentation warning in sysfs-driver-mlxreg-io

The use of a Sphinx list within this ABI file caused the following warning:

  Documentation/ABI/stable/sysfs-driver-mlxreg-io:230: WARNING: Unexpected indentation.
  Documentation/ABI/stable/sysfs-driver-mlxreg-io:230: WARNING: Block quote ends without a blank line; unexpected unindent.

Remove the bullets to make the warning go away and get proper formatting.

Reported-by: Stephen Rothwell <[email-masked]>
Signed-off-by: Jonathan Corbet <[email-masked]>
---
 .../ABI/stable/sysfs-driver-mlxreg-io         | 23 +++++++++++--------
 1 file changed, 13 insertions(+), 10 deletions(-)

diff --git a/Documentation/ABI/stable/sysfs-driver-mlxreg-io b/Documentation/ABI/stable/sysfs-driver-mlxreg-io
index c84795ccecad..12c3f895cd2f 100644
--- a/Documentation/ABI/stable/sysfs-driver-mlxreg-io
+++ b/Documentation/ABI/stable/sysfs-driver-mlxreg-io
@@ -231,16 +231,19 @@ Date:		October 2021
 KernelVersion:	5.16
 Contact:	Vadim Pasternak <[email-masked]>
 Description:	The files represent BIOS statuses:
-		- bios_active_image: location of current active BIOS image:
-		  0: Top, 1: Bottom.
-		  The reported value should correspond to value expected by OS
-		  in case of BIOS safe mode is 0. This bit is related to Intel
-		  top-swap feature of DualBios on the same flash.
-		- bios_auth_fail: BIOS upgrade is failed because provided BIOS
-		  image is not signed correctly.
-		- bios_upgrade_fail: BIOS upgrade is failed by some other
-		  reason not because authentication. For example due to
-		  physical SPI flash problem.
+
+		bios_active_image: location of current active BIOS image:
+		0: Top, 1: Bottom.
+		The reported value should correspond to value expected by OS
+		in case of BIOS safe mode is 0. This bit is related to Intel
+		top-swap feature of DualBios on the same flash.
+
+		bios_auth_fail: BIOS upgrade is failed because provided BIOS
+		image is not signed correctly.
+
+		bios_upgrade_fail: BIOS upgrade is failed by some other
+		reason not because authentication. For example due to
+		physical SPI flash problem.
 
 		The files are read only.
 
-- 
2.31.1