Re: [PATCH] docs: ABI: sysfs-class-firmware-attributes: solve some warnings

[Hans de Goede]

Hi,

On 10/29/20 10:31 AM, Mauro Carvalho Chehab wrote:
> The Description: tag is missing on some places, causing
> scripts/get_abi.pl warnings:
> 
> 	Warning: file Documentation/ABI/testing/sysfs-class-firmware-attributes#172:
> 		What '/sys/class/firmware-attributes/*/authentication/' doesn't have a description
> 
> Also, some warnings are produced when generating html documentation:
> 
> 	.../Documentation/ABI/testing/sysfs-class-firmware-attributes:2: WARNING: Title underline too short.
> 
> 	Dell specific class extensions
> 	--------------------------
> 	.../Documentation/ABI/testing/sysfs-class-firmware-attributes:2: WARNING: Unexpected indentation.
> 	.../Documentation/ABI/testing/sysfs-class-firmware-attributes:2: WARNING: Unexpected indentation.
> 	.../Documentation/ABI/testing/sysfs-class-firmware-attributes:2: WARNING: Block quote ends without a blank line; unexpected unindent.
> 	.../Documentation/ABI/testing/sysfs-class-firmware-attributes:173: WARNING: Unexpected indentation.
> 	.../Documentation/ABI/testing/sysfs-class-firmware-attributes:173: WARNING: Unexpected indentation.
> 	.../Documentation/ABI/testing/sysfs-class-firmware-attributes:173: WARNING: Block quote ends without a blank line; unexpected unindent.
> 	.../Documentation/ABI/testing/sysfs-class-firmware-attributes:111: WARNING: Inline emphasis start-string without end-string.
> 
> Address the warnings, making it to produce the expected
> output for the documentation ABI.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>

Thank you for your patch, I've applied this patch to my review-hans 
branch:
https://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86.git/log/?h=review-hans

Note it will show up in my review-hans branch once I've pushed my
local branch there, which might take a while.

Once I've run some tests on this branch the patches there will be
added to the platform-drivers-x86/for-next branch and eventually
will be included in the pdx86 pull-request to Linus for the next
merge-window.

Regards,

Hans


> ---
>  .../testing/sysfs-class-firmware-attributes   | 138 +++++++++++-------
>  1 file changed, 86 insertions(+), 52 deletions(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-class-firmware-attributes b/Documentation/ABI/testing/sysfs-class-firmware-attributes
> index 04a15c72e883..8ea59fea4709 100644
> --- a/Documentation/ABI/testing/sysfs-class-firmware-attributes
> +++ b/Documentation/ABI/testing/sysfs-class-firmware-attributes
> @@ -12,17 +12,20 @@ Description:
>  		Unless otherwise specified in an attribute description all attributes are optional
>  		and will accept UTF-8 input.
>  
> -		type: A file that can be read to obtain the type of attribute.  This attribute is
> -			mandatory.
> +		type:
> +		    A file that can be read to obtain the type of attribute.
> +		    This attribute is mandatory.
>  
>  		The following are known types:
> +
>  			- enumeration: a set of pre-defined valid values
>  			- integer: a range of numerical values
>  			- string
>  
>  		All attribute types support the following values:
>  
> -		current_value:	A file that can be read to obtain the current
> +		current_value:
> +				A file that can be read to obtain the current
>  				value of the <attr>.
>  
>  				This file can also be written to in order to update the value of a
> @@ -30,59 +33,71 @@ Description:
>  
>  				This attribute is mandatory.
>  
> -		default_value:	A file that can be read to obtain the default
> +		default_value:
> +				A file that can be read to obtain the default
>  				value of the <attr>
>  
> -		display_name:	A file that can be read to obtain a user friendly
> +		display_name:
> +				A file that can be read to obtain a user friendly
>  				description of the at <attr>
>  
> -		display_name_language_code:	A file that can be read to obtain
> +		display_name_language_code:
> +						A file that can be read to obtain
>  						the IETF language tag corresponding to the
>  						"display_name" of the <attr>
>  
>  		"enumeration"-type specific properties:
>  
> -		possible_values:	A file that can be read to obtain the possible
> +		possible_values:
> +					A file that can be read to obtain the possible
>  					values of the <attr>. Values are separated using
>  					semi-colon (``;``).
>  
>  		"integer"-type specific properties:
>  
> -		min_value:	A file that can be read to obtain the lower
> +		min_value:
> +				A file that can be read to obtain the lower
>  				bound value of the <attr>
>  
> -		max_value:	A file that can be read to obtain the upper
> +		max_value:
> +				A file that can be read to obtain the upper
>  				bound value of the <attr>
>  
> -		scalar_increment:	A file that can be read to obtain the scalar value used for
> +		scalar_increment:
> +					A file that can be read to obtain the scalar value used for
>  					increments of current_value this attribute accepts.
>  
>  		"string"-type specific properties:
>  
> -		max_length:	A file that can be read to obtain the maximum
> +		max_length:
> +				A file that can be read to obtain the maximum
>  				length value of the <attr>
>  
> -		min_length:	A file that can be read to obtain the minimum
> +		min_length:
> +				A file that can be read to obtain the minimum
>  				length value of the <attr>
>  
>  		Dell specific class extensions
> -		--------------------------
> +		------------------------------
>  
>  		On Dell systems the following additional attributes are available:
>  
> -		dell_modifier:	A file that can be read to obtain attribute-level
> +		dell_modifier:
> +				A file that can be read to obtain attribute-level
>  				dependency rule. It says an attribute X will become read-only or
>  				suppressed, if/if-not attribute Y is configured.
>  
> -				modifier rules can be in following format:
> -				[ReadOnlyIf:<attribute>=<value>]
> -				[ReadOnlyIfNot:<attribute>=<value>]
> -				[SuppressIf:<attribute>=<value>]
> -				[SuppressIfNot:<attribute>=<value>]
> +				modifier rules can be in following format::
>  
> -				For example:
> -				AutoOnFri/dell_modifier has value,
> -					[SuppressIfNot:AutoOn=SelectDays]
> +				    [ReadOnlyIf:<attribute>=<value>]
> +				    [ReadOnlyIfNot:<attribute>=<value>]
> +				    [SuppressIf:<attribute>=<value>]
> +				    [SuppressIfNot:<attribute>=<value>]
> +
> +				For example::
> +
> +				    AutoOnFri/dell_modifier has value,
> +					    [SuppressIfNot:AutoOn=SelectDays]
>  
>  				This means AutoOnFri will be suppressed in BIOS setup if AutoOn
>  				attribute is not "SelectDays" and its value will not be effective
> @@ -90,18 +105,22 @@ Description:
>  
>  		Enumeration attributes also support the following:
>  
> -		dell_value_modifier:	A file that can be read to obtain value-level dependency.
> +		dell_value_modifier:
> +					A file that can be read to obtain value-level dependency.
>  					This file is similar to dell_modifier but here,	an
>  					attribute's current value will be forcefully changed based
>  					dependent attributes value.
>  
> -					dell_value_modifier rules can be in following format:
> -					<value>[ForceIf:<attribute>=<value>]
> -					<value>[ForceIfNot:<attribute>=<value>]
> +					dell_value_modifier rules can be in following format::
> +
> +					    <value>[ForceIf:<attribute>=<value>]
> +					    <value>[ForceIfNot:<attribute>=<value>]
> +
> +					For example:
> +
> +					    LegacyOrom/dell_value_modifier has value:
> +						    Disabled[ForceIf:SecureBoot=Enabled]
>  
> -					For example,
> -					LegacyOrom/dell_value_modifier has value:
> -						Disabled[ForceIf:SecureBoot=Enabled]
>  					This means LegacyOrom's current value will be forced to
>  					"Disabled" in BIOS setup if SecureBoot is Enabled and its
>  					value will not be effective through sysfs until this rule is
> @@ -113,12 +132,13 @@ KernelVersion:	5.11
>  Contact:	Divya Bharathi <Divya.Bharathi@xxxxxxxx>,
>  		Mario Limonciello <mario.limonciello@xxxxxxxx>,
>  		Prasanth KSR <prasanth.ksr@xxxxxxxx>
> -
> +Description:
>  		Devices support various authentication mechanisms which can be exposed
>  		as a separate configuration object.
>  
>  		For example a "BIOS Admin" password and "System" Password can be set,
>  		reset or cleared using these attributes.
> +
>  		- An "Admin" password is used for preventing modification to the BIOS
>  		  settings.
>  		- A "System" password is required to boot a machine.
> @@ -126,39 +146,50 @@ Contact:	Divya Bharathi <Divya.Bharathi@xxxxxxxx>,
>  		Change in any of these two authentication methods will also generate an
>  		uevent KOBJ_CHANGE.
>  
> -		is_enabled:		A file that can be read to obtain a 0/1 flag to see if
> +		is_enabled:
> +					A file that can be read to obtain a 0/1 flag to see if
>  					<attr> authentication is enabled.
>  					This attribute is mandatory.
>  
> -		role:			The type of authentication used.
> +		role:
> +					The type of authentication used.
>  					This attribute is mandatory.
> +
>  					Known types:
> -						bios-admin: Representing BIOS administrator password
> -						power-on: Representing a password required to use
> -							  the system
> +						bios-admin:
> +							Representing BIOS administrator password
> +						power-on:
> +							Representing a password required to use
> +							the system
>  
> -		mechanism:		The means of authentication.  This attribute is mandatory.
> +		mechanism:
> +					The means of authentication.  This attribute is mandatory.
>  					Only supported type currently is "password".
>  
> -		max_password_length:	A file that can be read to obtain the
> +		max_password_length:
> +					A file that can be read to obtain the
>  					maximum length of the Password
>  
> -		min_password_length:	A file that can be read to obtain the
> +		min_password_length:
> +					A file that can be read to obtain the
>  					minimum length of the Password
>  
> -		current_password:	A write only value used for privileged access such as
> +		current_password:
> +					A write only value used for privileged access such as
>  					setting	attributes when a system or admin password is set
>  					or resetting to a new password
>  
>  					This attribute is mandatory when mechanism == "password".
>  
> -		new_password:		A write only value that when used in tandem with
> +		new_password:
> +					A write only value that when used in tandem with
>  					current_password will reset a system or admin password.
>  
>  		Note, password management is session specific. If Admin password is set,
>  		same password must be written into current_password file (required for
>  		password-validation) and must be cleared once the session is over.
> -		For example:
> +		For example::
> +
>  			echo "password" > current_password
>  			echo "disabled" > TouchScreen/current_value
>  			echo "" > current_password
> @@ -180,12 +211,15 @@ Description:
>  		pending BIOS attribute changes. Also, an uevent_KOBJ_CHANGE is
>  		generated when it changes to 1.
>  
> -			0:	All BIOS attributes setting are current
> -			1:	A reboot is necessary to get pending BIOS attribute changes
> -				applied
> +			==	=========================================
> +			0	All BIOS attributes setting are current
> +			1	A reboot is necessary to get pending BIOS
> +			        attribute changes applied
> +			==	=========================================
>  
>  		Note, userspace applications need to follow below steps for efficient
>  		BIOS management,
> +
>  		1.	Check if admin password is set. If yes, follow session method for
>  			password management as briefed under authentication section above.
>  		2.	Before setting any attribute, check if it has any modifiers
> @@ -208,17 +242,17 @@ Description:
>  
>  		Reading from it returns a list of supported options encoded as:
>  
> -			'builtinsafe' (Built in safe configuration profile)
> -			'lastknowngood' (Last known good saved configuration profile)
> -			'factory' (Default factory settings configuration profile)
> -			'custom' (Custom saved configuration profile)
> +			- 'builtinsafe' (Built in safe configuration profile)
> +			- 'lastknowngood' (Last known good saved configuration profile)
> +			- 'factory' (Default factory settings configuration profile)
> +			- 'custom' (Custom saved configuration profile)
>  
>  		The currently selected option is printed in square brackets as
> -		shown below:
> +		shown below::
>  
> -		# echo "factory" > /sys/class/firmware-attributes/*/device/attributes/reset_bios
> -		# cat /sys/class/firmware-attributes/*/device/attributes/reset_bios
> -		# builtinsafe lastknowngood [factory] custom
> +		    # echo "factory" > /sys/class/firmware-attributes/*/device/attributes/reset_bios
> +		    # cat /sys/class/firmware-attributes/*/device/attributes/reset_bios
> +		    # builtinsafe lastknowngood [factory] custom
>  
>  		Note that any changes to this attribute requires a reboot
>  		for changes to take effect.
>