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@xxxxxxxxx> 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@xxxxxxxxx>
> > ---
> > 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
--
Cheers,
Changbin Du
