From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.1 required=3.0 tests=DKIMWL_WL_HIGH,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,INCLUDES_PATCH,MAILING_LIST_MULTI,SIGNED_OFF_BY, SPF_PASS autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 00EEDC10F11 for ; Wed, 24 Apr 2019 14:57:02 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id BCEA521903 for ; Wed, 24 Apr 2019 14:57:01 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1556117821; bh=MB7DgREFx4xhQOu72JGnS2pWkknaYZorcsmqFXjSlDk=; h=Date:From:To:Cc:Subject:In-Reply-To:References:List-ID:From; b=DqXMknBeaOh1N0xUjrjD215uwvz6BNBEiGYzcXyR4RJsGWFlbPEv+bGmlVR9aDJnd 346RgMg7R/YBD829bglGMEp6zvqpU8zxmhYR5Q8tdn83z6rZ3J/LIHjCdjtSaS1uQ7 MhxQKd/SqsqP2fbfmhCEQPM4oNqFTRdoM/T1FVyI= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1732998AbfDXO5A (ORCPT ); Wed, 24 Apr 2019 10:57:00 -0400 Received: from casper.infradead.org ([85.118.1.10]:51590 "EHLO casper.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1728065AbfDXO45 (ORCPT ); Wed, 24 Apr 2019 10:56:57 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=casper.20170209; h=Content-Transfer-Encoding:Content-Type: MIME-Version:References:In-Reply-To:Message-ID:Subject:Cc:To:From:Date:Sender :Reply-To:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=HAegWhTw52zFr6txY4cu/OvT7InTwy7rOkvAWwmB5RM=; b=LJr48VvTgnXLO74Hxq76Gu1DM6 7NtAg0qBrp5QUUJrZqMmWDYOxG+soFK0D7BfNgJNYJxf/ujAROBCM6PQHsftBPTG2/+jbq9N6/vul ItTW+k/ATPBzYZlZbOkkhsWuctjlcx9rWNhKyxHRX9Yl7IegX4Gn8IkvtGv/J8NuhF51GO78WY34b 1Ljr+zvvyvvbGfGKdo2Javdy7kRperh3vnK8H5NhSw/rUg87/y30fgf6UL3+CJuCCU8s7x7ry5WgL aiP/1zCAd1MsiH6klZUyiuLZ9vNkri5n7DCdqNFX1+8sieblpcMquosw1mlRRYcy103ibNTlHgSSt RL2wT0Aw==; Received: from 177.17.136.231.dynamic.adsl.gvt.net.br ([177.17.136.231] helo=coco.lan) by casper.infradead.org with esmtpsa (Exim 4.90_1 #2 (Red Hat Linux)) id 1hJJKP-000176-Rq; Wed, 24 Apr 2019 14:56:54 +0000 Date: Wed, 24 Apr 2019 11:56:47 -0300 From: Mauro Carvalho Chehab To: Changbin Du , mingo@redhat.com Cc: Jonathan Corbet , Bjorn Helgaas , rjw@rjwysocki.net, linux-pci@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, tglx@linutronix.de, x86@kernel.org, fenghua.yu@intel.com, linuxppc-dev@lists.ozlabs.org, linux-acpi@vger.kernel.org, linux-gpio@vger.kernel.org Subject: Re: [PATCH v4 24/63] Documentation: ACPI: move video_extension.txt to firmware-guide/acpi and convert to reST Message-ID: <20190424115647.092dec38@coco.lan> In-Reply-To: <20190423162932.21428-25-changbin.du@gmail.com> References: <20190423162932.21428-1-changbin.du@gmail.com> <20190423162932.21428-25-changbin.du@gmail.com> X-Mailer: Claws Mail 3.17.3 (GTK+ 2.24.32; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Em Wed, 24 Apr 2019 00:28:53 +0800 Changbin Du 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 > --- > 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