From patchwork Tue Jan 8 07:18:55 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alexandre Courbot X-Patchwork-Id: 1944421 Return-Path: X-Original-To: patchwork-linux-arm@patchwork.kernel.org Delivered-To: patchwork-process-083081@patchwork2.kernel.org Received: from merlin.infradead.org (merlin.infradead.org [205.233.59.134]) by patchwork2.kernel.org (Postfix) with ESMTP id 609E5DF23A for ; Tue, 8 Jan 2013 07:22:45 +0000 (UTC) Received: from localhost ([::1] helo=merlin.infradead.org) by merlin.infradead.org with esmtp (Exim 4.76 #1 (Red Hat Linux)) id 1TsTTn-0000X4-17; Tue, 08 Jan 2013 07:20:11 +0000 Received: from hqemgate04.nvidia.com ([216.228.121.35]) by merlin.infradead.org with esmtps (Exim 4.76 #1 (Red Hat Linux)) id 1TsTT6-0000Kw-Ka for linux-arm-kernel@lists.infradead.org; Tue, 08 Jan 2013 07:19:30 +0000 Received: from hqnvupgp06.nvidia.com (Not Verified[216.228.121.13]) by hqemgate04.nvidia.com id ; Mon, 07 Jan 2013 23:19:10 -0800 Received: from hqemhub01.nvidia.com ([172.17.108.22]) by hqnvupgp06.nvidia.com (PGP Universal service); Mon, 07 Jan 2013 23:16:40 -0800 X-PGP-Universal: processed; by hqnvupgp06.nvidia.com on Mon, 07 Jan 2013 23:16:40 -0800 Received: from percival.nvidia.com (172.20.144.16) by hqemhub01.nvidia.com (172.20.150.30) with Microsoft SMTP Server (TLS) id 8.3.279.1; Mon, 7 Jan 2013 23:19:26 -0800 From: Alexandre Courbot To: Grant Likely , Linus Walleij , Arnd Bergmann Subject: [PATCH 4/4] gpiolib: add documentation for new gpiod_ API Date: Tue, 8 Jan 2013 16:18:55 +0900 Message-ID: <1357629535-26033-5-git-send-email-acourbot@nvidia.com> X-Mailer: git-send-email 1.8.1 In-Reply-To: <1357629535-26033-1-git-send-email-acourbot@nvidia.com> References: <1357629535-26033-1-git-send-email-acourbot@nvidia.com> X-NVConfidentiality: public MIME-Version: 1.0 X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20130108_021928_971733_B6775B97 X-CRM114-Status: GOOD ( 20.71 ) X-Spam-Score: -7.6 (-------) X-Spam-Report: SpamAssassin version 3.3.2 on merlin.infradead.org summary: Content analysis details: (-7.6 points) pts rule name description ---- ---------------------- -------------------------------------------------- -5.0 RCVD_IN_DNSWL_HI RBL: Sender listed at http://www.dnswl.org/, high trust [216.228.121.35 listed in list.dnswl.org] -0.0 SPF_HELO_PASS SPF: HELO matches SPF record -0.0 SPF_PASS SPF: sender matches SPF record -0.7 RP_MATCHES_RCVD Envelope sender domain matches handover relay domain -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] Cc: linux-arch@vger.kernel.org, Alexandre Courbot , devicetree-discuss@lists.ozlabs.org, linux-kernel@vger.kernel.org, Alexandre Courbot , linux-arm-kernel@lists.infradead.org, Guenter Roeck X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: linux-arm-kernel-bounces@lists.infradead.org Errors-To: linux-arm-kernel-bounces+patchwork-linux-arm=patchwork.kernel.org@lists.infradead.org Signed-off-by: Alexandre Courbot --- Documentation/gpio.txt | 94 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 92 insertions(+), 2 deletions(-) \ No newline at end of file diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt index 77a1d11..871ccda 100644 --- a/Documentation/gpio.txt +++ b/Documentation/gpio.txt @@ -120,7 +120,8 @@ example, a number might be valid but temporarily unused on a given board. Whether a platform supports multiple GPIO controllers is a platform-specific implementation issue, as are whether that support can leave "holes" in the space -of GPIO numbers, and whether new controllers can be added at runtime. Such issues +of GPIO numbers, and whether new controllers can be added at runtime. Such +issues can affect things including whether adjacent GPIO numbers are both valid. Using GPIOs @@ -302,7 +303,8 @@ are claimed, three additional calls are defined: * 'flags', identical to gpio_request() wrt other arguments and * return value */ - int gpio_request_one(unsigned gpio, unsigned long flags, const char *label); + int gpio_request_one(unsigned gpio, unsigned long flags, const char +*label); /* request multiple GPIOs in a single call */ @@ -773,3 +775,91 @@ differences between boards from user space. This only affects the sysfs interface. Polarity change can be done both before and after gpio_export(), and previously enabled poll(2) support for either rising or falling edge will be reconfigured to follow this setting. + +GPIO descriptor interface +========================= +A more secure, alternative GPIO interface is available through GPIOlib. Instead +of relying on integers (which can easily be forged and used without being +properly requested) to reference GPIOs, it uses a system of opaque descriptors +that must be properly obtained and disposed through the common get/put set of +functions. This ensures that all GPIO descriptors are valid at any time and +makes it unnecessary to check the validity of a GPIO. Apart from this +difference, the interface is similar to the integer-based one, excepted that the +gpio_ prefix is changed to gpiod_. + +This interface can be used in conjonction with the integer-based API, however +new drivers should really try to use the safer descriptor-based interface. +Drivers using this interface should depend on CONFIG_GPIOLIB being set, as it is +only available when GPIOlib is compiled in. + +Using GPIOs +----------- +GPIO consumers should include which declares the +consumer-side GPIO functions. GPIOs are obtained through gpiod_get: + + struct gpio_desc *gpiod_get(struct device *dev, + const char *con_id); + +This will return the GPIO descriptor corresponding to the con_id function of +dev, or an error code in case of error. A devm variant is also available: + + struct gpio_desc *devm_gpiod_get(struct device *dev, + const char *con_id); + +GPIO descriptors are disposed using the corresponding put functions: + + void gpiod_put(struct gpio_desc *desc); + void devm_gpiod_put(struct device *dev, struct gpio_desc *desc); + +A valid descriptor can then be used with one of the gpiod_ functions. Their +interface is identical to the integer-based API, excepted that they take a GPIO +descriptor instead of an integer: + + int gpiod_direction_input(struct gpio_desc *desc); + int gpiod_direction_output(struct gpio_desc *desc, int value); + int gpiod_get_value(struct gpio_desc *desc); + void gpiod_set_value(struct gpio_desc *desc, int value); + ... + +If you need to convert a descriptor to an integer or vice-versa, you can use +gpio_to_desc or desc_to_gpio: + + struct gpio_desc *gpio_to_desc(unsigned gpio); + int desc_to_gpio(const struct gpio_desc *desc); + +The same GPIO can be used by both interfaces as long as it has properly been +acquired by one of them (i.e. using either gpio_request() or gpiod_get()). + +Declaring GPIOs +--------------- +GPIOs can be made available for devices either through board-specific lookup +tables, or using the device tree. + +Board-specific lookup tables match a device name and consumer ID to a GPIO chip +and GPIO number relative to that chip. They are declared as follows: + + static struct gpio_lookup board_gpio_lookup[] = { + GPIO_LOOKUP("tegra-gpio", 28, "backlight.1", "power"), + }; + + static void __init board_init(void) + { + ... + gpiod_add_table(board_gpio_lookup, + ARRAY_SIZE(board_gpio_lookup)); + ... + } + +In the driver side, the following code: + + gpiod_get(dev, "power"); + +will return the descriptor for GPIO 28 of the "tegra-gpio" chip provided +strcmp(dev_name(dev), "backlight.1") == 0. + +If the device tree is used, then the same "power" GPIO can be declared into the +device's node as follows: + + power-gpios = <&gpio 28 0>; + +Note that gpiod_get() only allows to access the first GPIO specifier.