Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755857AbdCWTq6 (ORCPT ); Thu, 23 Mar 2017 15:46:58 -0400 Received: from mga03.intel.com ([134.134.136.65]:59332 "EHLO mga03.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754335AbdCWTq2 (ORCPT ); Thu, 23 Mar 2017 15:46:28 -0400 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.36,211,1486454400"; d="scan'208";a="947563919" From: Andy Shevchenko To: Linus Walleij , Alexandre Courbot , linux-gpio@vger.kernel.org, Dmitry Torokhov , Hans de Goede , linux-kernel@vger.kernel.org, Mika Westerberg , Jarkko Nikula , linux-acpi@vger.kernel.org Cc: Andy Shevchenko Subject: [PATCH v1 6/8] gpio: acpi: Explain how to get GPIO descriptors in ACPI case Date: Thu, 23 Mar 2017 21:46:16 +0200 Message-Id: <20170323194618.26548-7-andriy.shevchenko@linux.intel.com> X-Mailer: git-send-email 2.11.0 In-Reply-To: <20170323194618.26548-1-andriy.shevchenko@linux.intel.com> References: <20170323194618.26548-1-andriy.shevchenko@linux.intel.com> Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 3018 Lines: 81 Documentation lacks of explanation how we actually use device properties for GPIO resources. Add a section to the documentation about that. Suggested-by: Mika Westerberg Signed-off-by: Andy Shevchenko --- Documentation/acpi/gpio-properties.txt | 60 ++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/Documentation/acpi/gpio-properties.txt b/Documentation/acpi/gpio-properties.txt index 2aff0349facd..07954b7c3a12 100644 --- a/Documentation/acpi/gpio-properties.txt +++ b/Documentation/acpi/gpio-properties.txt @@ -156,3 +156,63 @@ pointed to by its first argument. That should be done in the driver's .probe() routine. On removal, the driver should unregister its GPIO mapping table by calling acpi_dev_remove_driver_gpios() on the ACPI device object where that table was previously registered. + +Using the _CRS fallback +----------------------- + +If a device does not have _DSD or the driver does not create ACPI GPIO +mapping, the Linux GPIO framework refuses to return any GPIOs. This is +because the driver does not know what it actually gets. For example if we +have a device like below: + + Device (BTH) + { + Name (_HID, ...) + + Name (_CRS, ResourceTemplate () { + GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionNone, + "\\_SB.GPO0", 0, ResourceConsumer) {15} + GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionNone, + "\\_SB.GPO0", 0, ResourceConsumer) {27} + }) + } + +The driver might expect to get the right GPIO when it does: + + desc = gpiod_get(dev, "reset", GPIOD_OUT_LOW); + +but since there is no way to know the mapping between "reset" and +the GpioIo() in _CRS desc will hold ERR_PTR(-ENOENT). + +The driver author can solve this by passing the mapping explictly +(the recommended way and documented in the above chapter). + +Getting GPIO descriptor +----------------------- + +There are two main approaches to get GPIO resource from ACPI: + desc = gpiod_get(dev, connection_id, flags); + desc = gpiod_get_index(dev, connection_id, index, flags); + +We may consider two different cases here, i.e. when connection ID is +provided and otherwise. + +Case 1: + desc = gpiod_get(dev, "non-null-connection-id", flags); + desc = gpiod_get_index(dev, "non-null-connection-id", index, flags); + +Case 2: + desc = gpiod_get(dev, NULL, flags); + desc = gpiod_get_index(dev, NULL, index, flags); + +Case 1 assumes that corresponding ACPI device description must have +defined device properties and will prevent to getting any GPIO resources +otherwise. + +Case 2 explicitly tells GPIO core to look for resources in _CRS. + +Be aware that gpiod_get_index() in cases 1 and 2, assuming that there +are two versions of ACPI device description provided and no mapping is +present in the driver, will return different resources. That's why a +certain driver has to handle them carefully as explained in previous +chapter. -- 2.11.0