diff mbox series

[v4,24/63] Documentation: ACPI: move video_extension.txt to firmware-guide/acpi and convert to reST

Message ID 20190423162932.21428-25-changbin.du@gmail.com (mailing list archive)
State New, archived
Delegated to: Bjorn Helgaas
Headers show
Series Include linux ACPI/PCI/X86 docs into Sphinx TOC tree | expand

Commit Message

Changbin Du April 23, 2019, 4:28 p.m. UTC
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
 Documentation/firmware-guide/acpi/index.rst   |  1 +
 .../acpi/video_extension.rst}                 | 63 ++++++++++---------
 2 files changed, 36 insertions(+), 28 deletions(-)
 rename Documentation/{acpi/video_extension.txt => firmware-guide/acpi/video_extension.rst} (79%)

Comments

Mauro Carvalho Chehab April 24, 2019, 2:56 p.m. UTC | #1
Em Wed, 24 Apr 2019 00:28:53 +0800
Changbin Du <changbin.du@gmail.com> escreveu:

> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.
> 
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
> ---
>  Documentation/firmware-guide/acpi/index.rst   |  1 +
>  .../acpi/video_extension.rst}                 | 63 ++++++++++---------
>  2 files changed, 36 insertions(+), 28 deletions(-)
>  rename Documentation/{acpi/video_extension.txt => firmware-guide/acpi/video_extension.rst} (79%)
> 
> diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> index 0e60f4b7129a..ae609eec4679 100644
> --- a/Documentation/firmware-guide/acpi/index.rst
> +++ b/Documentation/firmware-guide/acpi/index.rst
> @@ -23,3 +23,4 @@ ACPI Support
>     i2c-muxes
>     acpi-lid
>     lpit
> +   video_extension
> diff --git a/Documentation/acpi/video_extension.txt b/Documentation/firmware-guide/acpi/video_extension.rst
> similarity index 79%
> rename from Documentation/acpi/video_extension.txt
> rename to Documentation/firmware-guide/acpi/video_extension.rst
> index 79bf6a4921be..06f7e3230b6e 100644
> --- a/Documentation/acpi/video_extension.txt
> +++ b/Documentation/firmware-guide/acpi/video_extension.rst
> @@ -1,5 +1,8 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=====================
>  ACPI video extensions
> -~~~~~~~~~~~~~~~~~~~~~
> +=====================
>  
>  This driver implement the ACPI Extensions For Display Adapters for
>  integrated graphics devices on motherboard, as specified in ACPI 2.0
> @@ -8,9 +11,10 @@ defining the video POST device, retrieving EDID information or to
>  setup a video output, etc.  Note that this is an ref. implementation
>  only.  It may or may not work for your integrated video device.
>  
> -The ACPI video driver does 3 things regarding backlight control:
> +The ACPI video driver does 3 things regarding backlight control.
>  
> -1 Export a sysfs interface for user space to control backlight level
> +1. Export a sysfs interface for user space to control backlight level
> +=====================================================================
>  
>  If the ACPI table has a video device, and acpi_backlight=vendor kernel
>  command line is not present, the driver will register a backlight device

Hmm... you didn't touch on this part of the document:

	And what ACPI video driver does is:
	actual_brightness: on read, control method _BQC will be evaluated to
	get the brightness level the firmware thinks it is at;
	bl_power: not implemented, will set the current brightness instead;
	brightness: on write, control method _BCM will run to set the requested
	brightness level;
	max_brightness: Derived from the _BCL package(see below);
	type: firmware

You should touch it. My suggestion here is:

	And what ACPI video driver does is:

	actual_brightness:
		on read, control method _BQC will be evaluated to
		get the brightness level the firmware thinks it is at;
	bl_power:
		not implemented, will set the current brightness instead;
	brightness:
		on write, control method _BCM will run to set the requested
		brightness level;
	max_brightness:
		Derived from the _BCL package(see below);
	type:
		firmware

> @@ -32,26 +36,26 @@ type: firmware
>  
>  Note that ACPI video backlight driver will always use index for
>  brightness, actual_brightness and max_brightness. So if we have
> -the following _BCL package:
> +the following _BCL package::
>  
> -Method (_BCL, 0, NotSerialized)
> -{
> -	Return (Package (0x0C)
> +	Method (_BCL, 0, NotSerialized)
>  	{
> -		0x64,
> -		0x32,
> -		0x0A,
> -		0x14,
> -		0x1E,
> -		0x28,
> -		0x32,
> -		0x3C,
> -		0x46,
> -		0x50,
> -		0x5A,
> -		0x64
> -	})
> -}
> +		Return (Package (0x0C)
> +		{
> +			0x64,
> +			0x32,
> +			0x0A,
> +			0x14,
> +			0x1E,
> +			0x28,
> +			0x32,
> +			0x3C,
> +			0x46,
> +			0x50,
> +			0x5A,
> +			0x64
> +		})
> +	}
>  
>  The first two levels are for when laptop are on AC or on battery and are
>  not used by Linux currently. The remaining 10 levels are supported levels
> @@ -62,13 +66,15 @@ as a "brightness level" indicator. Thus from the user space perspective
>  the range of available brightness levels is from 0 to 9 (max_brightness)
>  inclusive.
>  
> -2 Notify user space about hotkey event
> +2. Notify user space about hotkey event
> +=======================================
>  
>  There are generally two cases for hotkey event reporting:
> +
>  i) For some laptops, when user presses the hotkey, a scancode will be
>     generated and sent to user space through the input device created by
>     the keyboard driver as a key type input event, with proper remap, the
> -   following key code will appear to user space:
> +   following key code will appear to user space::
>  
>  	EV_KEY, KEY_BRIGHTNESSUP
>  	EV_KEY, KEY_BRIGHTNESSDOWN
> @@ -82,7 +88,7 @@ ii) For some laptops, the press of the hotkey will not generate the
>      about the event. The event value is defined in the ACPI spec. ACPI
>      video driver will generate an key type input event according to the
>      notify value it received and send the event to user space through the
> -    input device it created:
> +    input device it created::
>  
>  	event		keycode
>  	0x86		KEY_BRIGHTNESSUP

Perhaps making this as a table would work better:

    input device it created:

	=====		===================
	event		keycode
	=====		===================
	0x86		KEY_BRIGHTNESSUP
	0x87		KEY_BRIGHTNESSDOWN
	etc.
	=====		===================


> @@ -94,13 +100,14 @@ so this would lead to the same effect as case i) now.
>  Once user space tool receives this event, it can modify the backlight
>  level through the sysfs interface.
>  
> -3 Change backlight level in the kernel
> +3. Change backlight level in the kernel
> +=======================================
>  
>  This works for machines covered by case ii) in Section 2. Once the driver
>  received a notification, it will set the backlight level accordingly. This does
>  not affect the sending of event to user space, they are always sent to user
>  space regardless of whether or not the video module controls the backlight level
>  directly. This behaviour can be controlled through the brightness_switch_enabled
> -module parameter as documented in admin-guide/kernel-parameters.rst. It is recommended to
> -disable this behaviour once a GUI environment starts up and wants to have full
> -control of the backlight level.
> +module parameter as documented in admin-guide/kernel-parameters.rst. It is
> +recommended to disable this behaviour once a GUI environment starts up and
> +wants to have full control of the backlight level.



Thanks,
Mauro
Changbin Du April 24, 2019, 5:31 p.m. UTC | #2
On Wed, Apr 24, 2019 at 11:56:47AM -0300, Mauro Carvalho Chehab wrote:
> Em Wed, 24 Apr 2019 00:28:53 +0800
> Changbin Du <changbin.du@gmail.com> escreveu:
> 
> > This converts the plain text documentation to reStructuredText format and
> > add it to Sphinx TOC tree. No essential content change.
> > 
> > Signed-off-by: Changbin Du <changbin.du@gmail.com>
> > ---
> >  Documentation/firmware-guide/acpi/index.rst   |  1 +
> >  .../acpi/video_extension.rst}                 | 63 ++++++++++---------
> >  2 files changed, 36 insertions(+), 28 deletions(-)
> >  rename Documentation/{acpi/video_extension.txt => firmware-guide/acpi/video_extension.rst} (79%)
> > 
> > diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> > index 0e60f4b7129a..ae609eec4679 100644
> > --- a/Documentation/firmware-guide/acpi/index.rst
> > +++ b/Documentation/firmware-guide/acpi/index.rst
> > @@ -23,3 +23,4 @@ ACPI Support
> >     i2c-muxes
> >     acpi-lid
> >     lpit
> > +   video_extension
> > diff --git a/Documentation/acpi/video_extension.txt b/Documentation/firmware-guide/acpi/video_extension.rst
> > similarity index 79%
> > rename from Documentation/acpi/video_extension.txt
> > rename to Documentation/firmware-guide/acpi/video_extension.rst
> > index 79bf6a4921be..06f7e3230b6e 100644
> > --- a/Documentation/acpi/video_extension.txt
> > +++ b/Documentation/firmware-guide/acpi/video_extension.rst
> > @@ -1,5 +1,8 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +=====================
> >  ACPI video extensions
> > -~~~~~~~~~~~~~~~~~~~~~
> > +=====================
> >  
> >  This driver implement the ACPI Extensions For Display Adapters for
> >  integrated graphics devices on motherboard, as specified in ACPI 2.0
> > @@ -8,9 +11,10 @@ defining the video POST device, retrieving EDID information or to
> >  setup a video output, etc.  Note that this is an ref. implementation
> >  only.  It may or may not work for your integrated video device.
> >  
> > -The ACPI video driver does 3 things regarding backlight control:
> > +The ACPI video driver does 3 things regarding backlight control.
> >  
> > -1 Export a sysfs interface for user space to control backlight level
> > +1. Export a sysfs interface for user space to control backlight level
> > +=====================================================================
> >  
> >  If the ACPI table has a video device, and acpi_backlight=vendor kernel
> >  command line is not present, the driver will register a backlight device
> 
> Hmm... you didn't touch on this part of the document:
> 
> 	And what ACPI video driver does is:
> 	actual_brightness: on read, control method _BQC will be evaluated to
> 	get the brightness level the firmware thinks it is at;
> 	bl_power: not implemented, will set the current brightness instead;
> 	brightness: on write, control method _BCM will run to set the requested
> 	brightness level;
> 	max_brightness: Derived from the _BCL package(see below);
> 	type: firmware
> 
> You should touch it. My suggestion here is:
> 
> 	And what ACPI video driver does is:
> 
> 	actual_brightness:
> 		on read, control method _BQC will be evaluated to
> 		get the brightness level the firmware thinks it is at;
> 	bl_power:
> 		not implemented, will set the current brightness instead;
> 	brightness:
> 		on write, control method _BCM will run to set the requested
> 		brightness level;
> 	max_brightness:
> 		Derived from the _BCL package(see below);
> 	type:
> 		firmware
>
Thanks, done.

> > @@ -32,26 +36,26 @@ type: firmware
> >  
> >  Note that ACPI video backlight driver will always use index for
> >  brightness, actual_brightness and max_brightness. So if we have
> > -the following _BCL package:
> > +the following _BCL package::
> >  
> > -Method (_BCL, 0, NotSerialized)
> > -{
> > -	Return (Package (0x0C)
> > +	Method (_BCL, 0, NotSerialized)
> >  	{
> > -		0x64,
> > -		0x32,
> > -		0x0A,
> > -		0x14,
> > -		0x1E,
> > -		0x28,
> > -		0x32,
> > -		0x3C,
> > -		0x46,
> > -		0x50,
> > -		0x5A,
> > -		0x64
> > -	})
> > -}
> > +		Return (Package (0x0C)
> > +		{
> > +			0x64,
> > +			0x32,
> > +			0x0A,
> > +			0x14,
> > +			0x1E,
> > +			0x28,
> > +			0x32,
> > +			0x3C,
> > +			0x46,
> > +			0x50,
> > +			0x5A,
> > +			0x64
> > +		})
> > +	}
> >  
> >  The first two levels are for when laptop are on AC or on battery and are
> >  not used by Linux currently. The remaining 10 levels are supported levels
> > @@ -62,13 +66,15 @@ as a "brightness level" indicator. Thus from the user space perspective
> >  the range of available brightness levels is from 0 to 9 (max_brightness)
> >  inclusive.
> >  
> > -2 Notify user space about hotkey event
> > +2. Notify user space about hotkey event
> > +=======================================
> >  
> >  There are generally two cases for hotkey event reporting:
> > +
> >  i) For some laptops, when user presses the hotkey, a scancode will be
> >     generated and sent to user space through the input device created by
> >     the keyboard driver as a key type input event, with proper remap, the
> > -   following key code will appear to user space:
> > +   following key code will appear to user space::
> >  
> >  	EV_KEY, KEY_BRIGHTNESSUP
> >  	EV_KEY, KEY_BRIGHTNESSDOWN
> > @@ -82,7 +88,7 @@ ii) For some laptops, the press of the hotkey will not generate the
> >      about the event. The event value is defined in the ACPI spec. ACPI
> >      video driver will generate an key type input event according to the
> >      notify value it received and send the event to user space through the
> > -    input device it created:
> > +    input device it created::
> >  
> >  	event		keycode
> >  	0x86		KEY_BRIGHTNESSUP
> 
> Perhaps making this as a table would work better:
> 
>     input device it created:
> 
> 	=====		===================
> 	event		keycode
> 	=====		===================
> 	0x86		KEY_BRIGHTNESSUP
> 	0x87		KEY_BRIGHTNESSDOWN
> 	etc.
> 	=====		===================
> 
> 
Done.

> > @@ -94,13 +100,14 @@ so this would lead to the same effect as case i) now.
> >  Once user space tool receives this event, it can modify the backlight
> >  level through the sysfs interface.
> >  
> > -3 Change backlight level in the kernel
> > +3. Change backlight level in the kernel
> > +=======================================
> >  
> >  This works for machines covered by case ii) in Section 2. Once the driver
> >  received a notification, it will set the backlight level accordingly. This does
> >  not affect the sending of event to user space, they are always sent to user
> >  space regardless of whether or not the video module controls the backlight level
> >  directly. This behaviour can be controlled through the brightness_switch_enabled
> > -module parameter as documented in admin-guide/kernel-parameters.rst. It is recommended to
> > -disable this behaviour once a GUI environment starts up and wants to have full
> > -control of the backlight level.
> > +module parameter as documented in admin-guide/kernel-parameters.rst. It is
> > +recommended to disable this behaviour once a GUI environment starts up and
> > +wants to have full control of the backlight level.
> 
> 
> 
> Thanks,
> Mauro
diff mbox series

Patch

diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
index 0e60f4b7129a..ae609eec4679 100644
--- a/Documentation/firmware-guide/acpi/index.rst
+++ b/Documentation/firmware-guide/acpi/index.rst
@@ -23,3 +23,4 @@  ACPI Support
    i2c-muxes
    acpi-lid
    lpit
+   video_extension
diff --git a/Documentation/acpi/video_extension.txt b/Documentation/firmware-guide/acpi/video_extension.rst
similarity index 79%
rename from Documentation/acpi/video_extension.txt
rename to Documentation/firmware-guide/acpi/video_extension.rst
index 79bf6a4921be..06f7e3230b6e 100644
--- a/Documentation/acpi/video_extension.txt
+++ b/Documentation/firmware-guide/acpi/video_extension.rst
@@ -1,5 +1,8 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================
 ACPI video extensions
-~~~~~~~~~~~~~~~~~~~~~
+=====================
 
 This driver implement the ACPI Extensions For Display Adapters for
 integrated graphics devices on motherboard, as specified in ACPI 2.0
@@ -8,9 +11,10 @@  defining the video POST device, retrieving EDID information or to
 setup a video output, etc.  Note that this is an ref. implementation
 only.  It may or may not work for your integrated video device.
 
-The ACPI video driver does 3 things regarding backlight control:
+The ACPI video driver does 3 things regarding backlight control.
 
-1 Export a sysfs interface for user space to control backlight level
+1. Export a sysfs interface for user space to control backlight level
+=====================================================================
 
 If the ACPI table has a video device, and acpi_backlight=vendor kernel
 command line is not present, the driver will register a backlight device
@@ -32,26 +36,26 @@  type: firmware
 
 Note that ACPI video backlight driver will always use index for
 brightness, actual_brightness and max_brightness. So if we have
-the following _BCL package:
+the following _BCL package::
 
-Method (_BCL, 0, NotSerialized)
-{
-	Return (Package (0x0C)
+	Method (_BCL, 0, NotSerialized)
 	{
-		0x64,
-		0x32,
-		0x0A,
-		0x14,
-		0x1E,
-		0x28,
-		0x32,
-		0x3C,
-		0x46,
-		0x50,
-		0x5A,
-		0x64
-	})
-}
+		Return (Package (0x0C)
+		{
+			0x64,
+			0x32,
+			0x0A,
+			0x14,
+			0x1E,
+			0x28,
+			0x32,
+			0x3C,
+			0x46,
+			0x50,
+			0x5A,
+			0x64
+		})
+	}
 
 The first two levels are for when laptop are on AC or on battery and are
 not used by Linux currently. The remaining 10 levels are supported levels
@@ -62,13 +66,15 @@  as a "brightness level" indicator. Thus from the user space perspective
 the range of available brightness levels is from 0 to 9 (max_brightness)
 inclusive.
 
-2 Notify user space about hotkey event
+2. Notify user space about hotkey event
+=======================================
 
 There are generally two cases for hotkey event reporting:
+
 i) For some laptops, when user presses the hotkey, a scancode will be
    generated and sent to user space through the input device created by
    the keyboard driver as a key type input event, with proper remap, the
-   following key code will appear to user space:
+   following key code will appear to user space::
 
 	EV_KEY, KEY_BRIGHTNESSUP
 	EV_KEY, KEY_BRIGHTNESSDOWN
@@ -82,7 +88,7 @@  ii) For some laptops, the press of the hotkey will not generate the
     about the event. The event value is defined in the ACPI spec. ACPI
     video driver will generate an key type input event according to the
     notify value it received and send the event to user space through the
-    input device it created:
+    input device it created::
 
 	event		keycode
 	0x86		KEY_BRIGHTNESSUP
@@ -94,13 +100,14 @@  so this would lead to the same effect as case i) now.
 Once user space tool receives this event, it can modify the backlight
 level through the sysfs interface.
 
-3 Change backlight level in the kernel
+3. Change backlight level in the kernel
+=======================================
 
 This works for machines covered by case ii) in Section 2. Once the driver
 received a notification, it will set the backlight level accordingly. This does
 not affect the sending of event to user space, they are always sent to user
 space regardless of whether or not the video module controls the backlight level
 directly. This behaviour can be controlled through the brightness_switch_enabled
-module parameter as documented in admin-guide/kernel-parameters.rst. It is recommended to
-disable this behaviour once a GUI environment starts up and wants to have full
-control of the backlight level.
+module parameter as documented in admin-guide/kernel-parameters.rst. It is
+recommended to disable this behaviour once a GUI environment starts up and
+wants to have full control of the backlight level.