From patchwork Thu Jan 18 09:44:57 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Walleij X-Patchwork-Id: 124924 Delivered-To: patch@linaro.org Received: by 10.46.64.27 with SMTP id n27csp53842lja; Thu, 18 Jan 2018 01:47:09 -0800 (PST) X-Google-Smtp-Source: ACJfBov1pHk1xniMKya0dI7utIWXlAGe58clwjTf0Q/utZ7HKQP8b+BOIyzn2JP4i+DUgq+FFeTE X-Received: by 10.159.211.66 with SMTP id g2mr16812928plp.34.1516268829653; Thu, 18 Jan 2018 01:47:09 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1516268829; cv=none; d=google.com; s=arc-20160816; b=UZn6oZHSoOFozppRdzIXdqfsjRbcpKisyOTMWpoVgVoB2gsxXpzfTZdmAZgQHKL78r ux0z2H+XhQgWNx7LqZ1VnB99I5e4qFnjqs8ynrwo4M6uDNbv78twHUFYvT+FeHdWlSYB yBwt1FeKm7nvQuBpl+kwponfJSmN1YFPduigUddlA7iDbX8E0Yl346k7ySXmcmSBB4tj 5vYWpx2+BWQOa0Ujk7YnnuprVITYwV7oB94EcOKkIbevdmYWu8EINxw8+B4TnRq9TSXM U+k7RmVvYKKLMxIANIJ6XdGr7AxShMVaHMyk8t0NLsoBGKHRfbY48v+i2M/gnJ6USGMs mMcw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:message-id:date:subject:cc:to:from :dkim-signature:arc-authentication-results; bh=x6bKApl0onxrYqXFKc3G8jvOvyl3ibBrSa+y47kqeIo=; b=l29/iFzUfdgUIkLLU7tFsTu4wIg6PZldGmi+sNrQDbA1e7/N4B7/+n29hyVqI31Rbg O+hKulcQPv52M/xTIHRWnkutaGxoxDcJ7OZQ20JIyS8OkdxUzIl4oaVy0T/xDvBl4i6S I6q39vFPqrUe6/9O2lvqoh345GPsFVLqCgzu9f6dknIkpPITWLxD7fGAxnvbrVzeAC3x fIRlUusJtaVaMx5bXORzyI47K0NiFY6XL7yC0xqf0EB6OLCe6JiRJSHqRTySSQ31cwfg VjPrKfuM5HeOwBQbOAwLtzew8zvM6lmyN7qDEtYEAlgDZWOMcCImMdvfPLTJbg3CHxRD c2Iw== ARC-Authentication-Results: i=1; mx.google.com; dkim=neutral (body hash did not verify) header.i=@linaro.org header.s=google header.b=j6AfP4Df; spf=pass (google.com: best guess record for domain of linux-gpio-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-gpio-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id l3si2138673pgl.77.2018.01.18.01.47.09; Thu, 18 Jan 2018 01:47:09 -0800 (PST) Received-SPF: pass (google.com: best guess record for domain of linux-gpio-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; dkim=neutral (body hash did not verify) header.i=@linaro.org header.s=google header.b=j6AfP4Df; spf=pass (google.com: best guess record for domain of linux-gpio-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-gpio-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755323AbeARJrH (ORCPT + 6 others); Thu, 18 Jan 2018 04:47:07 -0500 Received: from mail-lf0-f65.google.com ([209.85.215.65]:43280 "EHLO mail-lf0-f65.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754902AbeARJrD (ORCPT ); Thu, 18 Jan 2018 04:47:03 -0500 Received: by mail-lf0-f65.google.com with SMTP id o89so21639995lfg.10 for ; Thu, 18 Jan 2018 01:47:02 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id; bh=zKnbppPMht20VUynFbCPflR9FSfS33+DzAxXC5c1iqA=; b=j6AfP4DfSS/QLmGICyrIvZXkKodHHJ9U2VEpKUC5+W9xzicJwbMv5Omrajb9bu5Xux l6MkeUacuxhMd8zv4KgolFFF9hAgVLzfpRcFtWpqlx8uGD9qPnrap+K9iPZFLz4Sod7O EtNuANGGWOaV05wFxYDRLVHCZ8knxMvZB1L7E= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=zKnbppPMht20VUynFbCPflR9FSfS33+DzAxXC5c1iqA=; b=AK8XNb/6ryYBK+DPgDsP20cGDAjmc9Hnl6PmbEaV+KwXZ18rCP/g2uUxNr8Qv6oNqb gVoDAML3OpA39jngxKgs45uWQvfhbU7gGaodxOnkpOkZeYAv8uzLH3qnix/Y+9Z5qD/K 2xD2Z1lHOFKDVLdpLgXemAx1bw/iJaHjF5sBwY6EONgcXKE/3KtpfovjkPitKBivjN+R 10Y3kaBLKwRXewyoFwLF1aF2zbmVbsv8Ie8tFenLJ1yuEz2oL8Q9LrocYjYk0uRJ8hzx Ze7tJSXGMwwNTP1InJdaRyOMYCh5wnPOgX0u/uzPhv2nTKMc5+jQCQqA/zc0yc1hqebO WeYg== X-Gm-Message-State: AKwxytdVwLpxSFaSF8QM/2BdB08mgtI3tPUb6lWQEZ6nf/iAkr3q6Q1h bjhA9lp4q1bpALP1sWRi7heKiHwCExw= X-Received: by 10.25.195.134 with SMTP id t128mr16377450lff.60.1516268821568; Thu, 18 Jan 2018 01:47:01 -0800 (PST) Received: from localhost.localdomain (c-cb7471d5.014-348-6c756e10.cust.bredbandsbolaget.se. [213.113.116.203]) by smtp.gmail.com with ESMTPSA id f73sm1130120lfg.93.2018.01.18.01.47.00 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 18 Jan 2018 01:47:00 -0800 (PST) From: Linus Walleij To: linux-gpio@vger.kernel.org Cc: Linus Walleij Subject: [PATCH] gpio: Documentation update Date: Thu, 18 Jan 2018 10:44:57 +0100 Message-Id: <20180118094457.15304-1-linus.walleij@linaro.org> X-Mailer: git-send-email 2.14.3 Sender: linux-gpio-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-gpio@vger.kernel.org Update a slew of documentation files with the latest changes in the API/ABI. Again stress that sysfs is deprecated. Add all new flags and clean up and move some text. Signed-off-by: Linus Walleij --- Documentation/gpio/board.txt | 14 ++++-- Documentation/gpio/consumer.txt | 105 ++++++++++++++++++++++++---------------- Documentation/gpio/driver.txt | 4 ++ Documentation/gpio/sysfs.txt | 11 +++++ 4 files changed, 88 insertions(+), 46 deletions(-) -- 2.14.3 -- To unsubscribe from this list: send the line "unsubscribe linux-gpio" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html diff --git a/Documentation/gpio/board.txt b/Documentation/gpio/board.txt index a0f61898d493..b1d106167baa 100644 --- a/Documentation/gpio/board.txt +++ b/Documentation/gpio/board.txt @@ -2,6 +2,7 @@ GPIO Mappings ============= This document explains how GPIOs can be assigned to given devices and functions. + Note that it only applies to the new descriptor-based interface. For a description of the deprecated integer-based GPIO interface please refer to gpio-legacy.txt (actually, there is no real mapping possible with the old @@ -49,7 +50,7 @@ This property will make GPIOs 15, 16 and 17 available to the driver under the power = gpiod_get(dev, "power", GPIOD_OUT_HIGH); -The led GPIOs will be active-high, while the power GPIO will be active-low (i.e. +The led GPIOs will be active high, while the power GPIO will be active low (i.e. gpiod_is_active_low(power) will be true). The second parameter of the gpiod_get() functions, the con_id string, has to be @@ -122,9 +123,14 @@ where can be NULL, in which case it will match any function. - idx is the index of the GPIO within the function. - flags is defined to specify the following properties: - * GPIOF_ACTIVE_LOW - to configure the GPIO as active-low - * GPIOF_OPEN_DRAIN - GPIO pin is open drain type. - * GPIOF_OPEN_SOURCE - GPIO pin is open source type. + * GPIO_ACTIVE_HIGH - GPIO line is active high + * GPIO_ACTIVE_LOW - GPIO line is active low + * GPIO_OPEN_DRAIN - GPIO line ise set up as open drain + * GPIO_OPEN_SOURCE - GPIO line is set up as open source + * GPIO_PERSISTENT - GPIO line is persistent during + suspend/resume and maintains its value + * GPIO_TRANSITORY - GPIO line is transitory and may loose its + electrical state during suspend/resume In the future, these flags might be extended to support more properties. diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt index 7aac33081510..d53e5b5cfc9c 100644 --- a/Documentation/gpio/consumer.txt +++ b/Documentation/gpio/consumer.txt @@ -66,6 +66,15 @@ for the GPIO. Values can be: * GPIOD_IN to initialize the GPIO as input. * GPIOD_OUT_LOW to initialize the GPIO as output with a value of 0. * GPIOD_OUT_HIGH to initialize the GPIO as output with a value of 1. +* GPIOD_OUT_LOW_OPEN_DRAIN same as GPIOD_OUT_LOW but also enforce the line + to be electrically used with open drain. +* GPIOD_OUT_HIGH_OPEN_DRAIN same as GPIOD_OUT_HIGH but also enforce the line + to be electrically used with open drain. + +The two last flags are used for use cases where open drain is mandatory, such +as I2C: if the line is not already configured as open drain in the mappings +(see board.txt), then open drain will be enforced anyway and a warning will be +printed that the board configuration needs to be updated to match the use case. Both functions return either a valid GPIO descriptor, or an error code checkable with IS_ERR() (they will never return a NULL pointer). -ENOENT will be returned @@ -240,59 +249,71 @@ that can't be accessed from hardIRQ handlers, these calls act the same as the spinlock-safe calls. -Active-low State and Raw GPIO Values ------------------------------------- -Device drivers like to manage the logical state of a GPIO, i.e. the value their -device will actually receive, no matter what lies between it and the GPIO line. -In some cases, it might make sense to control the actual GPIO line value. The -following set of calls ignore the active-low property of a GPIO and work on the -raw line value: - - int gpiod_get_raw_value(const struct gpio_desc *desc) - void gpiod_set_raw_value(struct gpio_desc *desc, int value) - int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc) - void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value) - int gpiod_direction_output_raw(struct gpio_desc *desc, int value) - -The active-low state of a GPIO can also be queried using the following call: - - int gpiod_is_active_low(const struct gpio_desc *desc) - -Note that these functions should only be used with great moderation ; a driver -should not have to care about the physical line level. - - -The active-low property ------------------------ - -As a driver should not have to care about the physical line level, all of the +The active low and open drain semantics +--------------------------------------- +As a consumer should not have to care about the physical line level, all of the gpiod_set_value_xxx() or gpiod_set_array_value_xxx() functions operate with -the *logical* value. With this they take the active-low property into account. -This means that they check whether the GPIO is configured to be active-low, +the *logical* value. With this they take the active low property into account. +This means that they check whether the GPIO is configured to be active low, and if so, they manipulate the passed value before the physical line level is driven. +The same is applicable for open drain or open source output lines: those do not +actively drive their output high (open drain) or low (open source), they just +switch their output to a high impedance value. The consumer should not need to +care. (For details read about open drain in driver.txt.) + With this, all the gpiod_set_(array)_value_xxx() functions interpret the -parameter "value" as "active" ("1") or "inactive" ("0"). The physical line +parameter "value" as "asserted" ("1") or "de-asserted" ("0"). The physical line level will be driven accordingly. -As an example, if the active-low property for a dedicated GPIO is set, and the -gpiod_set_(array)_value_xxx() passes "active" ("1"), the physical line level +As an example, if the active low property for a dedicated GPIO is set, and the +gpiod_set_(array)_value_xxx() passes "asserted" ("1"), the physical line level will be driven low. To summarize: -Function (example) active-low property physical line -gpiod_set_raw_value(desc, 0); don't care low -gpiod_set_raw_value(desc, 1); don't care high -gpiod_set_value(desc, 0); default (active-high) low -gpiod_set_value(desc, 1); default (active-high) high -gpiod_set_value(desc, 0); active-low high -gpiod_set_value(desc, 1); active-low low - -Please note again that the set_raw/get_raw functions should be avoided as much -as possible, especially by drivers which should not care about the actual -physical line level and worry about the logical value instead. +Function (example) line property physical line +gpiod_set_raw_value(desc, 0); don't care low +gpiod_set_raw_value(desc, 1); don't care high +gpiod_set_value(desc, 0); default (active high) low +gpiod_set_value(desc, 1); default (active high) high +gpiod_set_value(desc, 0); active low high +gpiod_set_value(desc, 1); active low low +gpiod_set_value(desc, 0); default (active high) low +gpiod_set_value(desc, 1); default (active high) high +gpiod_set_value(desc, 0); open drain low +gpiod_set_value(desc, 1); open drain high impedance +gpiod_set_value(desc, 0); open source high impedance +gpiod_set_value(desc, 1); open source high + +It is possible to override these semantics using the *set_raw/'get_raw functions +but it should be avoided as much as possible, especially by system-agnostic drivers +which should not need to care about the actual physical line level and worry about +the logical value instead. + + +Accessing raw GPIO values +------------------------- +Consumers exist that need to manage the logical state of a GPIO line, i.e. the value +their device will actually receive, no matter what lies between it and the GPIO +line. + +The following set of calls ignore the active-low or open drain property of a GPIO and +work on the raw line value: + + int gpiod_get_raw_value(const struct gpio_desc *desc) + void gpiod_set_raw_value(struct gpio_desc *desc, int value) + int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc) + void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value) + int gpiod_direction_output_raw(struct gpio_desc *desc, int value) + +The active low state of a GPIO can also be queried using the following call: + + int gpiod_is_active_low(const struct gpio_desc *desc) + +Note that these functions should only be used with great moderation; a driver +should not have to care about the physical line level or open drain semantics. Access multiple GPIOs with a single function call diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt index d8de1c7de85a..3392a0fd4c23 100644 --- a/Documentation/gpio/driver.txt +++ b/Documentation/gpio/driver.txt @@ -88,6 +88,10 @@ ending up in the pin control back-end "behind" the GPIO controller, usually closer to the actual pins. This way the pin controller can manage the below listed GPIO configurations. +If a pin controller back-end is used, the GPIO controller or hardware +description needs to provide "GPIO ranges" mapping the GPIO line offsets to pin +numbers on the pin controller so they can properly cross-reference each other. + GPIOs with debounce support --------------------------- diff --git a/Documentation/gpio/sysfs.txt b/Documentation/gpio/sysfs.txt index aeab01aa4d00..6cdeab8650cd 100644 --- a/Documentation/gpio/sysfs.txt +++ b/Documentation/gpio/sysfs.txt @@ -1,6 +1,17 @@ GPIO Sysfs Interface for Userspace ================================== +THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO +Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS +ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL +NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED. + +Refer to the examples in tools/gpio/* for an introduction to the new +character device ABI. Also see the userspace header in +include/uapi/linux/gpio.h + +The deprecated sysfs ABI +------------------------ Platforms which use the "gpiolib" implementors framework may choose to configure a sysfs user interface to GPIOs. This is different from the debugfs interface, since it provides control over GPIO direction and