[PATCH 0/3] ACPI video driver document update

[PATCH 0/3] ACPI video driver document update

[Aaron Lu]

ACPI video driver's document is pretty outdated and needs updating.
Patch 1 adds description for brightness_switch_enabled kernel command
line option;
Patch 2 moves the document for ACPI video driver from Documentation/power
to Documentation/ACPI, since it is a document for the ACPI video driver;
Patch 3 updates the video driver's document by focusing on how backlight
is controlled by it.

Aaron Lu (3):
  ACPI / video: add description for brightness_switch_enabled
  ACPI / video: move video_extension.txt to Documentation/acpi
  ACPI / video: update video_extension.txt for backlight control

 Documentation/acpi/video_extension.txt  | 106 ++++++++++++++++++++++++++++++++
 Documentation/kernel-parameters.txt     |   9 +++
 Documentation/power/video_extension.txt |  37 -----------
 3 files changed, 115 insertions(+), 37 deletions(-)
 create mode 100644 Documentation/acpi/video_extension.txt
 delete mode 100644 Documentation/power/video_extension.txt

-- 
1.8.3.3.gfada522

[PATCH 1/3] ACPI / video: add description for brightness_switch_enabled

[Aaron Lu]

Add description for video module's parameter brightness_switch_enabled
into kernel-parameters.txt.

Signed-off-by: Aaron Lu <aaron.lu@intel.com>
---
 Documentation/kernel-parameters.txt | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt
index 2fe6e76..7f64e0f 100644
--- a/Documentation/kernel-parameters.txt
+++ b/Documentation/kernel-parameters.txt
@@ -3229,6 +3229,15 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
 	video=		[FB] Frame buffer configuration
 			See Documentation/fb/modedb.txt.
 
+	video.brightness_switch_enabled= [0,1]
+			If set to 1, on receiving an ACPI notify event
+			generated by hotkey, video driver will adjust brightness
+			level and then send out the event to user space through
+			the allocated input device; If set to 0, video driver
+			will only send out the event without touching backlight
+			brightness level.
+			default: 1
+
 	virtio_mmio.device=
 			[VMMIO] Memory mapped virtio (platform) device.
 
-- 
1.8.3.3.gfada522

[PATCH 2/3] ACPI / video: move video_extension.txt to Documentation/acpi

[Aaron Lu]

ACPI video driver is written according to ACPI spec, appendix B: Video
Extensions. So it better be put under the acpi directory instead of the
power directory. This patch moves the file there without any other
change.

Signed-off-by: Aaron Lu <aaron.lu@intel.com>
---
 Documentation/{power => acpi}/video_extension.txt | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/{power => acpi}/video_extension.txt (100%)

diff --git a/Documentation/power/video_extension.txt b/Documentation/acpi/video_extension.txt
similarity index 100%
rename from Documentation/power/video_extension.txt
rename to Documentation/acpi/video_extension.txt
-- 
1.8.3.3.gfada522

[PATCH 3/3] ACPI / video: update video_extension.txt for backlight control

[Aaron Lu]

The ACPI video driver has changed a lot, and it doesn't export
interfaces in /proc any more, so the documentation for it should
be updated.
This update focuses on ACPI video driver's backlight control.

Signed-off-by: Aaron Lu <aaron.lu@intel.com>
---
 Documentation/acpi/video_extension.txt | 121 ++++++++++++++++++++++++++-------
 1 file changed, 95 insertions(+), 26 deletions(-)

diff --git a/Documentation/acpi/video_extension.txt b/Documentation/acpi/video_extension.txt
index b2f9b15..78b32ac 100644
--- a/Documentation/acpi/video_extension.txt
+++ b/Documentation/acpi/video_extension.txt
@@ -8,30 +8,99 @@ 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.
 
-Interfaces exposed to userland through /proc/acpi/video:
-
-VGA/info : display the supported video bus device capability like Video ROM, CRT/LCD/TV.
-VGA/ROM :  Used to get a copy of the display devices' ROM data (up to 4k).
-VGA/POST_info : Used to determine what options are implemented.
-VGA/POST : Used to get/set POST device.
-VGA/DOS : Used to get/set ownership of output switching:
-	Please refer ACPI spec B.4.1 _DOS
-VGA/CRT : CRT output
-VGA/LCD : LCD output
-VGA/TVO : TV output
-VGA/*/brightness : Used to get/set brightness of output device
-
-Notify event through /proc/acpi/event:
-
-#define ACPI_VIDEO_NOTIFY_SWITCH        0x80
-#define ACPI_VIDEO_NOTIFY_PROBE         0x81
-#define ACPI_VIDEO_NOTIFY_CYCLE         0x82
-#define ACPI_VIDEO_NOTIFY_NEXT_OUTPUT   0x83
-#define ACPI_VIDEO_NOTIFY_PREV_OUTPUT   0x84
-
-#define ACPI_VIDEO_NOTIFY_CYCLE_BRIGHTNESS      0x82
-#define ACPI_VIDEO_NOTIFY_INC_BRIGHTNESS        0x83
-#define ACPI_VIDEO_NOTIFY_DEC_BRIGHTNESS        0x84
-#define ACPI_VIDEO_NOTIFY_ZERO_BRIGHTNESS       0x85
-#define ACPI_VIDEO_NOTIFY_DISPLAY_OFF           0x86
+The ACPI video driver does 3 things regarding backlight control:
 
+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
+and set the required backlight operation structure for it for the sysfs
+interface control. For every registered class device, there will be a
+directory named acpi_videoX under /sys/class/backlight.
+
+The backlight sysfs interface has a standard definition here:
+Documentation/ABI/stable/sysfs-class-backlight.
+
+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
+
+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:
+
+Method (_BCL, 0, NotSerialized)
+{
+	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
+that we can choose from. The applicable index values are from 0 (that
+corresponds to the 0x0A brightness value) to 9 (that corresponds to the
+0x64 brightness value) inclusive. Each of those index values is regarded
+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
+
+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:
+
+	EV_KEY, KEY_BRIGHTNESSUP
+	EV_KEY, KEY_BRIGHTNESSDOWN
+	etc.
+
+For this case, ACPI video driver does not need to do anything(actually,
+it doesn't even know this happened).
+
+ii) For some laptops, the press of the hotkey will not generate the
+    scancode, instead, firmware will notify the video device ACPI node
+    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:
+
+	event		keycode
+	0x86		KEY_BRIGHTNESSUP
+	0x87		KEY_BRIGHTNESSDOWN
+	etc.
+
+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
+
+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 kernel-parameters.txt. It is recommended to
+disable this behaviour once a GUI environment starts up and wants to have full
+control of the backlight level.
-- 
1.8.3.3.gfada522

Re: [PATCH 0/3] ACPI video driver document update

[Rafael J. Wysocki]

On Thursday, June 20, 2013 03:08:54 PM Aaron Lu wrote:
> ACPI video driver's document is pretty outdated and needs updating.
> Patch 1 adds description for brightness_switch_enabled kernel command
> line option;
> Patch 2 moves the document for ACPI video driver from Documentation/power
> to Documentation/ACPI, since it is a document for the ACPI video driver;
> Patch 3 updates the video driver's document by focusing on how backlight
> is controlled by it.
> 
> Aaron Lu (3):
>   ACPI / video: add description for brightness_switch_enabled
>   ACPI / video: move video_extension.txt to Documentation/acpi
>   ACPI / video: update video_extension.txt for backlight control
> 
>  Documentation/acpi/video_extension.txt  | 106 ++++++++++++++++++++++++++++++++
>  Documentation/kernel-parameters.txt     |   9 +++
>  Documentation/power/video_extension.txt |  37 -----------
>  3 files changed, 115 insertions(+), 37 deletions(-)
>  create mode 100644 Documentation/acpi/video_extension.txt
>  delete mode 100644 Documentation/power/video_extension.txt

All queued up for 3.11.

Thanks,
Rafael