diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/devicetree/bindings/gpio/gpio-axp209.txt | 49 | ||||
| -rw-r--r-- | Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt | 2 | ||||
| -rw-r--r-- | Documentation/gpio/board.txt | 14 | ||||
| -rw-r--r-- | Documentation/gpio/consumer.txt | 107 | ||||
| -rw-r--r-- | Documentation/gpio/driver.txt | 4 | ||||
| -rw-r--r-- | Documentation/gpio/sysfs.txt | 11 | ||||
| -rw-r--r-- | Documentation/w1/masters/w1-gpio | 17 |
7 files changed, 151 insertions, 53 deletions
diff --git a/Documentation/devicetree/bindings/gpio/gpio-axp209.txt b/Documentation/devicetree/bindings/gpio/gpio-axp209.txt index a6611304dd3c..fc42b2caa06d 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-axp209.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-axp209.txt @@ -1,10 +1,17 @@ -AXP209 GPIO controller +AXP209 GPIO & pinctrl controller This driver follows the usual GPIO bindings found in Documentation/devicetree/bindings/gpio/gpio.txt +This driver follows the usual pinctrl bindings found in +Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt + +This driver employs the per-pin muxing pattern. + Required properties: -- compatible: Should be "x-powers,axp209-gpio" +- compatible: Should be one of: + - "x-powers,axp209-gpio" + - "x-powers,axp813-gpio" - #gpio-cells: Should be two. The first cell is the pin number and the second is the GPIO flags. - gpio-controller: Marks the device node as a GPIO controller. @@ -28,3 +35,41 @@ axp209: pmic@34 { #gpio-cells = <2>; }; }; + +The GPIOs can be muxed to other functions and therefore, must be a subnode of +axp_gpio. + +Example: + +&axp_gpio { + gpio0_adc: gpio0-adc { + pins = "GPIO0"; + function = "adc"; + }; +}; + +&example_node { + pinctrl-names = "default"; + pinctrl-0 = <&gpio0_adc>; +}; + +GPIOs and their functions +------------------------- + +Each GPIO is independent from the other (i.e. GPIO0 in gpio_in function does +not force GPIO1 and GPIO2 to be in gpio_in function as well). + +axp209 +------ +GPIO | Functions +------------------------ +GPIO0 | gpio_in, gpio_out, ldo, adc +GPIO1 | gpio_in, gpio_out, ldo, adc +GPIO2 | gpio_in, gpio_out + +axp813 +------ +GPIO | Functions +------------------------ +GPIO0 | gpio_in, gpio_out, ldo, adc +GPIO1 | gpio_in, gpio_out, ldo diff --git a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt index a7ac460ad657..9474138d776e 100644 --- a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt +++ b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt @@ -5,7 +5,7 @@ Required Properties: - compatible: should contain one or more of the following: - "renesas,gpio-r8a7743": for R8A7743 (RZ/G1M) compatible GPIO controller. - "renesas,gpio-r8a7745": for R8A7745 (RZ/G1E) compatible GPIO controller. - - "renesas,gpio-r8a7778": for R8A7778 (R-Mobile M1) compatible GPIO controller. + - "renesas,gpio-r8a7778": for R8A7778 (R-Car M1) compatible GPIO controller. - "renesas,gpio-r8a7779": for R8A7779 (R-Car H1) compatible GPIO controller. - "renesas,gpio-r8a7790": for R8A7790 (R-Car H2) compatible GPIO controller. - "renesas,gpio-r8a7791": for R8A7791 (R-Car M2-W) compatible GPIO controller. diff --git a/Documentation/gpio/board.txt b/Documentation/gpio/board.txt index a0f61898d493..659bb19f5b3c 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 is 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 63e1bd1d88e3..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 @@ -184,7 +193,7 @@ A driver can also query the current direction of a GPIO: int gpiod_get_direction(const struct gpio_desc *desc) -This function will return either GPIOF_DIR_IN or GPIOF_DIR_OUT. +This function returns 0 for output, 1 for input, or an error code in case of error. Be aware that there is no default direction for GPIOs. Therefore, **using a GPIO without setting its direction first is illegal and will result in undefined @@ -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 diff --git a/Documentation/w1/masters/w1-gpio b/Documentation/w1/masters/w1-gpio index af5d3b4aa851..623961d9e83f 100644 --- a/Documentation/w1/masters/w1-gpio +++ b/Documentation/w1/masters/w1-gpio @@ -8,17 +8,27 @@ Description ----------- GPIO 1-wire bus master driver. The driver uses the GPIO API to control the -wire and the GPIO pin can be specified using platform data. +wire and the GPIO pin can be specified using GPIO machine descriptor tables. +It is also possible to define the master using device tree, see +Documentation/devicetree/bindings/w1/w1-gpio.txt Example (mach-at91) ------------------- +#include <linux/gpio/machine.h> #include <linux/w1-gpio.h> +static struct gpiod_lookup_table foo_w1_gpiod_table = { + .dev_id = "w1-gpio", + .table = { + GPIO_LOOKUP_IDX("at91-gpio", AT91_PIN_PB20, NULL, 0, + GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN), + }, +}; + static struct w1_gpio_platform_data foo_w1_gpio_pdata = { - .pin = AT91_PIN_PB20, - .is_open_drain = 1, + .ext_pullup_enable_pin = -EINVAL, }; static struct platform_device foo_w1_device = { @@ -30,4 +40,5 @@ static struct platform_device foo_w1_device = { ... at91_set_GPIO_periph(foo_w1_gpio_pdata.pin, 1); at91_set_multi_drive(foo_w1_gpio_pdata.pin, 1); + gpiod_add_lookup_table(&foo_w1_gpiod_table); platform_device_register(&foo_w1_device); |