From patchwork Fri Oct 30 07:40:56 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11868633 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=-12.8 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,INCLUDES_PATCH,MAILING_LIST_MULTI,SIGNED_OFF_BY,SPF_HELO_NONE, SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT 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 CCC4FC56201 for ; Fri, 30 Oct 2020 07:41:11 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 828192223F for ; Fri, 30 Oct 2020 07:41:10 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=kernel.org header.i=@kernel.org header.b="FL9ZuXNn" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 828192223F Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=kernel.org Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=dri-devel-bounces@lists.freedesktop.org Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 8277E6E963; Fri, 30 Oct 2020 07:41:06 +0000 (UTC) Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by gabe.freedesktop.org (Postfix) with ESMTPS id 938BF6E95F for ; Fri, 30 Oct 2020 07:41:04 +0000 (UTC) Received: from mail.kernel.org (ip5f5ad5bb.dynamic.kabel-deutschland.de [95.90.213.187]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 1188B2415B; Fri, 30 Oct 2020 07:41:04 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1604043664; bh=laqfKgYIOZkUNXl8RbAmpD7Q4frs1RmcXkjACWIQfJw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FL9ZuXNn8Q9elmy6sIUFm4wj5f/9GQy6wetZUEm3ih4849MQ616Dr0o2iJtEXnD6r E66jYp5wti8IGBK524rceDsoPnA31rgoH6ww91ZSW8gDR/5IUkBSzDayXttL3UgCYa hoXt1ME6ysZ6pyXUW5Lju93c4hX/zMvXyqL6XeFk= Received: from mchehab by mail.kernel.org with local (Exim 4.94) (envelope-from ) id 1kYP1y-004Ogv-0f; Fri, 30 Oct 2020 08:41:02 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Subject: [PATCH v2 37/39] docs: ABI: sysfs-class-backlight: unify ABI documentation Date: Fri, 30 Oct 2020 08:40:56 +0100 Message-Id: <342195ad5a819d9bcfcebc133c77ab69b4211672.1604042072.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.26.2 In-Reply-To: References: MIME-Version: 1.0 X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Daniel Thompson , Jonathan Corbet , Mauro Carvalho Chehab , Jingoo Han , linux-kernel@vger.kernel.org, dri-devel@lists.freedesktop.org, Lee Jones Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" Both adp8860 and adp8870 define some extensions to the backlight class. This causes warnings: Warning: /sys/class/backlight//ambient_light_level is defined 2 times: /sys/class/backlight//ambient_light_level:8 /sys/class/backlight//ambient_light_level:30 Warning: /sys/class/backlight//ambient_light_zone is defined 2 times: /sys/class/backlight//ambient_light_zone:18 /sys/class/backlight//ambient_light_zone:40 As ABI definitions shouldn't be duplicated. Unfortunately, the ABI is dependent on the specific device features. As such, ambient_light_level range is somewhat different among the supported devices. The ambient_light_zone is even worse: the meanings of each preset are different, and there's no ABI to retrieve the supported types nor their meanins. Unfortunately, it is too late to fix it without causing regressions, as this has been used since Kernel v2.6.35. Rewrite those ABI documentation using the current documentation as a reference, and double-checking at the datasheets: https://www.analog.com/media/en/technical-documentation/data-sheets/ADP8870.pdf https://www.analog.com/media/en/technical-documentation/data-sheets/ADP8860.pdf in order to properly document the differences between those two drivers. Signed-off-by: Mauro Carvalho Chehab --- .../ABI/testing/sysfs-class-backlight | 60 +++++++++++++++++++ .../ABI/testing/sysfs-class-backlight-adp8860 | 21 +------ .../sysfs-class-backlight-driver-adp8870 | 30 +--------- 3 files changed, 65 insertions(+), 46 deletions(-) diff --git a/Documentation/ABI/testing/sysfs-class-backlight b/Documentation/ABI/testing/sysfs-class-backlight index 3ab175a3f5cb..1fc86401bf95 100644 --- a/Documentation/ABI/testing/sysfs-class-backlight +++ b/Documentation/ABI/testing/sysfs-class-backlight @@ -24,3 +24,63 @@ Description: non-linear The brightness changes non-linearly with each step. Brightness controls should use a linear mapping for a linear perception. + +What: /sys/class/backlight//ambient_light_level +Date: Apr, 2010 +KernelVersion: v2.6.35 +Contact: Michael Hennerich +Description: + (RO) Get conversion value of the light sensor. + + The value is automatically updated every 80 ms when the + light sensor is enabled. + + The value range is device-driver specific: + + For ADP8870: + + It returns integer between 0 (dark) and 8000 (max ambient + brightness). + + For ADP8860: + + It returns a 13-bits integer. + +What: /sys/class/backlight//ambient_light_zone +Date: Apr, 2010 +KernelVersion: v2.6.35 +Contact: Michael Hennerich , + device-drivers-devel@blackfin.uclinux.org + +Description: + (RW) Read or write the specific brightness level at which the + backlight operates. + + The value meaning is device-driver specific: + + For ADP8860: + + == ========================== + 0 Off: Backlight set to 0 mA + 1 Level 1: daylight + 2 Level 2: bright + 3 Level 3: dark + == ========================== + + For ADP8870: + + == ========================== + 0 Off: Backlight set to 0 mA + 1 Level 1: daylight + 2 Level 2: bright + 3 Level 3: office + 4 Level 4: indoor + 5 Level 5: dark + == ========================== + + Writing 0 returns to normal/automatic ambient light level + operation. + + It can be enabled by writing the value stored in + /sys/class/backlight//max_brightness to + /sys/class/backlight//brightness. diff --git a/Documentation/ABI/testing/sysfs-class-backlight-adp8860 b/Documentation/ABI/testing/sysfs-class-backlight-adp8860 index 54d61c788b1b..6610ac73f9ba 100644 --- a/Documentation/ABI/testing/sysfs-class-backlight-adp8860 +++ b/Documentation/ABI/testing/sysfs-class-backlight-adp8860 @@ -6,25 +6,8 @@ adp8860, adp8861 and adp8863 devices: daylight (level 1), office (level 2) and dark (level 3). By default the brightness operates at the daylight brightness level. -What: /sys/class/backlight//ambient_light_level -Date: Apr, 2010 -KernelVersion: v2.6.35 -Contact: Michael Hennerich -Description: - (RO) 13-bit conversion value for the first light sensor—high - byte (Bit 12 to Bit 8). The value is updated every 80 ms (when - the light sensor is enabled). - - -What: /sys/class/backlight//ambient_light_zone -Date: Apr, 2010 -KernelVersion: v2.6.35 -Contact: Michael Hennerich -Description: - (RW) Read or write the specific level at which the backlight - operates. Value "0" enables automatic ambient light sensing, and - values "1", "2" or "3" set the control to daylight, office or - dark respectively. +See also /sys/class/backlight//ambient_light_level and +/sys/class/backlight//ambient_light_zone. What: /sys/class/backlight//l1_daylight_max diff --git a/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870 b/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870 index 33e648808117..b08ca912cad4 100644 --- a/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870 +++ b/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870 @@ -1,3 +1,6 @@ +See also /sys/class/backlight//ambient_light_level and +/sys/class/backlight//ambient_light_zone. + What: /sys/class/backlight//_max What: /sys/class/backlight//l1_daylight_max What: /sys/class/backlight//l2_bright_max @@ -27,30 +30,3 @@ Description: set to 0. Full off when the backlight is disabled. This file will also show the dim brightness level stored for this . - -What: /sys/class/backlight//ambient_light_level -Date: May 2011 -KernelVersion: 3.0 -Contact: device-drivers-devel@blackfin.uclinux.org -Description: - Get conversion value of the light sensor. - This value is updated every 80 ms (when the light sensor - is enabled). Returns integer between 0 (dark) and - 8000 (max ambient brightness) - -What: /sys/class/backlight//ambient_light_zone -Date: May 2011 -KernelVersion: 3.0 -Contact: device-drivers-devel@blackfin.uclinux.org -Description: - Get/Set current ambient light zone. Reading returns - integer between 1..5 (1 = daylight, 2 = bright, ..., 5 = dark). - Writing a value between 1..5 forces the backlight controller - to enter the corresponding ambient light zone. - Writing 0 returns to normal/automatic ambient light level - operation. The ambient light sensing feature on these devices - is an extension to the API documented in - Documentation/ABI/stable/sysfs-class-backlight. - It can be enabled by writing the value stored in - /sys/class/backlight//max_brightness to - /sys/class/backlight//brightness.