Merge tag 'gpio-v3.13-2' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio

Pull GPIO fixes from Linus Walleij: "Here us a bunch of patches for the v3.13 series. Most important stuff is related to fixes and documentation for the new GPIO descriptor API. If the diffstat is scary you'll notice most of it is to Documentation/*: - A big slew of documentation for the gpiod transition that happened in the merge window, no semantic effect, but we should provide proper documentation with the new API. - Fix flags related to the new API. - Fix to the find_chip_by_name() lookup function related to the new API. - Fix of_find_gpio() when not using device tree. - Bug fix for the TB10x direction setting. - Error path fixes from Dan Carpenter. - Nasty IRQdomain bug relating to taking an unitialized spinlock. - Minor fixes here and there" * tag 'gpio-v3.13-2' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio: gpio: bcm281xx: Fix return value of bcm_kona_gpio_get() gpio: pl061: move irqdomain initialization gpio: ucb1400: Add MODULE_ALIAS gpiolib: fix of_find_gpio() when OF not defined gpio: fix memory leak in error path gpio: rcar: NULL dereference on error in probe() gpio: msm: make msm_gpio.summary_irq signed for error handling gpio: mvebu: make mvchip->irqbase signed for error handling gpiolib: use dedicated flags for GPIO properties gpiolib: fix find_chip_by_name() Documentation: gpiolib: document new interface gpio: tb10x: Set output value before setting direction to output

Linus Torvalds committed 12 years ago

Commit dda9cc32 parents 962ba26 e2f0b0015 files · +713 −37Browse files

Unified · Split

15 files

Documentation/gpio/board.txt +115 −0
Documentation/gpio/consumer.txt +197 −0
Documentation/gpio/driver.txt +75 −0
Documentation/gpio/gpio-legacy.txt +0 −0
Documentation/gpio/gpio.txt +119 −0
Documentation/gpio/sysfs.txt +155 −0
drivers/gpio/gpio-bcm-kona.c +1 −1
drivers/gpio/gpio-msm-v2.c +1 −1
drivers/gpio/gpio-mvebu.c +1 −1
drivers/gpio/gpio-pl061.c +5 −5
drivers/gpio/gpio-rcar.c +1 −1
drivers/gpio/gpio-tb10x.c +1 −0
drivers/gpio/gpio-ucb1400.c +1 −0
drivers/gpio/gpiolib.c +32 −26
include/linux/gpio/driver.h +9 −2

Documentation/gpio/board.txt+115−0

@@ -0,0 +1,115 @@
	1	+GPIO Mappings
	2	+=============
	3	+
	4	+This document explains how GPIOs can be assigned to given devices and functions.
	5	+Note that it only applies to the new descriptor-based interface. For a
	6	+description of the deprecated integer-based GPIO interface please refer to
	7	+gpio-legacy.txt (actually, there is no real mapping possible with the old
	8	+interface; you just fetch an integer from somewhere and request the
	9	+corresponding GPIO.
	10	+
	11	+Platforms that make use of GPIOs must select ARCH_REQUIRE_GPIOLIB (if GPIO usage
	12	+is mandatory) or ARCH_WANT_OPTIONAL_GPIOLIB (if GPIO support can be omitted) in
	13	+their Kconfig. Then, how GPIOs are mapped depends on what the platform uses to
	14	+describe its hardware layout. Currently, mappings can be defined through device
	15	+tree, ACPI, and platform data.
	16	+
	17	+Device Tree
	18	+-----------
	19	+GPIOs can easily be mapped to devices and functions in the device tree. The
	20	+exact way to do it depends on the GPIO controller providing the GPIOs, see the
	21	+device tree bindings for your controller.
	22	+
	23	+GPIOs mappings are defined in the consumer device's node, in a property named
	24	+<function>-gpios, where <function> is the function the driver will request
	25	+through gpiod_get(). For example:
	26	+
	27	+ foo_device {
	28	+ compatible = "acme,foo";
	29	+ ...
	30	+ led-gpios = <&gpio 15 GPIO_ACTIVE_HIGH>, /* red */
	31	+ <&gpio 16 GPIO_ACTIVE_HIGH>, /* green */
	32	+ <&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */
	33	+
	34	+ power-gpio = <&gpio 1 GPIO_ACTIVE_LOW>;
	35	+ };
	36	+
	37	+This property will make GPIOs 15, 16 and 17 available to the driver under the
	38	+"led" function, and GPIO 1 as the "power" GPIO:
	39	+
	40	+ struct gpio_desc red, green, blue, power;
	41	+
	42	+ red = gpiod_get_index(dev, "led", 0);
	43	+ green = gpiod_get_index(dev, "led", 1);
	44	+ blue = gpiod_get_index(dev, "led", 2);
	45	+
	46	+ power = gpiod_get(dev, "power");
	47	+
	48	+The led GPIOs will be active-high, while the power GPIO will be active-low (i.e.
	49	+gpiod_is_active_low(power) will be true).
	50	+
	51	+ACPI
	52	+----
	53	+ACPI does not support function names for GPIOs. Therefore, only the "idx"
	54	+argument of gpiod_get_index() is useful to discriminate between GPIOs assigned
	55	+to a device. The "con_id" argument can still be set for debugging purposes (it
	56	+will appear under error messages as well as debug and sysfs nodes).
	57	+
	58	+Platform Data
	59	+-------------
	60	+Finally, GPIOs can be bound to devices and functions using platform data. Board
	61	+files that desire to do so need to include the following header:
	62	+
	63	+ #include <linux/gpio/driver.h>
	64	+
	65	+GPIOs are mapped by the means of tables of lookups, containing instances of the
	66	+gpiod_lookup structure. Two macros are defined to help declaring such mappings:
	67	+
	68	+ GPIO_LOOKUP(chip_label, chip_hwnum, dev_id, con_id, flags)
	69	+ GPIO_LOOKUP_IDX(chip_label, chip_hwnum, dev_id, con_id, idx, flags)
	70	+
	71	+where
	72	+
	73	+ - chip_label is the label of the gpiod_chip instance providing the GPIO
	74	+ - chip_hwnum is the hardware number of the GPIO within the chip
	75	+ - dev_id is the identifier of the device that will make use of this GPIO. If
	76	+ NULL, the GPIO will be available to all devices.
	77	+ - con_id is the name of the GPIO function from the device point of view. It
	78	+ can be NULL.
	79	+ - idx is the index of the GPIO within the function.
	80	+ - flags is defined to specify the following properties:
	81	+ * GPIOF_ACTIVE_LOW - to configure the GPIO as active-low
	82	+ * GPIOF_OPEN_DRAIN - GPIO pin is open drain type.
	83	+ * GPIOF_OPEN_SOURCE - GPIO pin is open source type.
	84	+
	85	+In the future, these flags might be extended to support more properties.
	86	+
	87	+Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.
	88	+
	89	+A lookup table can then be defined as follows:
	90	+
	91	+ struct gpiod_lookup gpios_table[] = {
	92	+ GPIO_LOOKUP_IDX("gpio.0", 15, "foo.0", "led", 0, GPIO_ACTIVE_HIGH),
	93	+ GPIO_LOOKUP_IDX("gpio.0", 16, "foo.0", "led", 1, GPIO_ACTIVE_HIGH),
	94	+ GPIO_LOOKUP_IDX("gpio.0", 17, "foo.0", "led", 2, GPIO_ACTIVE_HIGH),
	95	+ GPIO_LOOKUP("gpio.0", 1, "foo.0", "power", GPIO_ACTIVE_LOW),
	96	+ };
	97	+
	98	+And the table can be added by the board code as follows:
	99	+
	100	+ gpiod_add_table(gpios_table, ARRAY_SIZE(gpios_table));
	101	+
	102	+The driver controlling "foo.0" will then be able to obtain its GPIOs as follows:
	103	+
	104	+ struct gpio_desc red, green, blue, power;
	105	+
	106	+ red = gpiod_get_index(dev, "led", 0);
	107	+ green = gpiod_get_index(dev, "led", 1);
	108	+ blue = gpiod_get_index(dev, "led", 2);
	109	+
	110	+ power = gpiod_get(dev, "power");
	111	+ gpiod_direction_output(power, 1);
	112	+
	113	+Since the "power" GPIO is mapped as active-low, its actual signal will be 0
	114	+after this code. Contrary to the legacy integer GPIO interface, the active-low
	115	+property is handled during mapping and is thus transparent to GPIO consumers.

Documentation/gpio/consumer.txt+197−0

@@ -0,0 +1,197 @@
	1	+GPIO Descriptor Consumer Interface
	2	+==================================
	3	+
	4	+This document describes the consumer interface of the GPIO framework. Note that
	5	+it describes the new descriptor-based interface. For a description of the
	6	+deprecated integer-based GPIO interface please refer to gpio-legacy.txt.
	7	+
	8	+
	9	+Guidelines for GPIOs consumers
	10	+==============================
	11	+
	12	+Drivers that can't work without standard GPIO calls should have Kconfig entries
	13	+that depend on GPIOLIB. The functions that allow a driver to obtain and use
	14	+GPIOs are available by including the following file:
	15	+
	16	+ #include <linux/gpio/consumer.h>
	17	+
	18	+All the functions that work with the descriptor-based GPIO interface are
	19	+prefixed with gpiod_. The gpio_ prefix is used for the legacy interface. No
	20	+other function in the kernel should use these prefixes.
	21	+
	22	+
	23	+Obtaining and Disposing GPIOs
	24	+=============================
	25	+
	26	+With the descriptor-based interface, GPIOs are identified with an opaque,
	27	+non-forgeable handler that must be obtained through a call to one of the
	28	+gpiod_get() functions. Like many other kernel subsystems, gpiod_get() takes the
	29	+device that will use the GPIO and the function the requested GPIO is supposed to
	30	+fulfill:
	31	+
	32	+ struct gpio_desc gpiod_get(struct device dev, const char *con_id)
	33	+
	34	+If a function is implemented by using several GPIOs together (e.g. a simple LED
	35	+device that displays digits), an additional index argument can be specified:
	36	+
	37	+ struct gpio_desc gpiod_get_index(struct device dev,
	38	+ const char *con_id, unsigned int idx)
	39	+
	40	+Both functions return either a valid GPIO descriptor, or an error code checkable
	41	+with IS_ERR(). They will never return a NULL pointer.
	42	+
	43	+Device-managed variants of these functions are also defined:
	44	+
	45	+ struct gpio_desc devm_gpiod_get(struct device dev, const char *con_id)
	46	+
	47	+ struct gpio_desc devm_gpiod_get_index(struct device dev,
	48	+ const char *con_id,
	49	+ unsigned int idx)
	50	+
	51	+A GPIO descriptor can be disposed of using the gpiod_put() function:
	52	+
	53	+ void gpiod_put(struct gpio_desc *desc)
	54	+
	55	+It is strictly forbidden to use a descriptor after calling this function. The
	56	+device-managed variant is, unsurprisingly:
	57	+
	58	+ void devm_gpiod_put(struct device dev, struct gpio_desc desc)
	59	+
	60	+
	61	+Using GPIOs
	62	+===========
	63	+
	64	+Setting Direction
	65	+-----------------
	66	+The first thing a driver must do with a GPIO is setting its direction. This is
	67	+done by invoking one of the gpiod_direction_*() functions:
	68	+
	69	+ int gpiod_direction_input(struct gpio_desc *desc)
	70	+ int gpiod_direction_output(struct gpio_desc *desc, int value)
	71	+
	72	+The return value is zero for success, else a negative errno. It should be
	73	+checked, since the get/set calls don't return errors and since misconfiguration
	74	+is possible. You should normally issue these calls from a task context. However,
	75	+for spinlock-safe GPIOs it is OK to use them before tasking is enabled, as part
	76	+of early board setup.
	77	+
	78	+For output GPIOs, the value provided becomes the initial output value. This
	79	+helps avoid signal glitching during system startup.
	80	+
	81	+A driver can also query the current direction of a GPIO:
	82	+
	83	+ int gpiod_get_direction(const struct gpio_desc *desc)
	84	+
	85	+This function will return either GPIOF_DIR_IN or GPIOF_DIR_OUT.
	86	+
	87	+Be aware that there is no default direction for GPIOs. Therefore, **using a GPIO
	88	+without setting its direction first is illegal and will result in undefined
	89	+behavior!**
	90	+
	91	+
	92	+Spinlock-Safe GPIO Access
	93	+-------------------------
	94	+Most GPIO controllers can be accessed with memory read/write instructions. Those
	95	+don't need to sleep, and can safely be done from inside hard (non-threaded) IRQ
	96	+handlers and similar contexts.
	97	+
	98	+Use the following calls to access GPIOs from an atomic context:
	99	+
	100	+ int gpiod_get_value(const struct gpio_desc *desc);
	101	+ void gpiod_set_value(struct gpio_desc *desc, int value);
	102	+
	103	+The values are boolean, zero for low, nonzero for high. When reading the value
	104	+of an output pin, the value returned should be what's seen on the pin. That
	105	+won't always match the specified output value, because of issues including
	106	+open-drain signaling and output latencies.
	107	+
	108	+The get/set calls do not return errors because "invalid GPIO" should have been
	109	+reported earlier from gpiod_direction_*(). However, note that not all platforms
	110	+can read the value of output pins; those that can't should always return zero.
	111	+Also, using these calls for GPIOs that can't safely be accessed without sleeping
	112	+(see below) is an error.
	113	+
	114	+
	115	+GPIO Access That May Sleep
	116	+--------------------------
	117	+Some GPIO controllers must be accessed using message based buses like I2C or
	118	+SPI. Commands to read or write those GPIO values require waiting to get to the
	119	+head of a queue to transmit a command and get its response. This requires
	120	+sleeping, which can't be done from inside IRQ handlers.
	121	+
	122	+Platforms that support this type of GPIO distinguish them from other GPIOs by
	123	+returning nonzero from this call:
	124	+
	125	+ int gpiod_cansleep(const struct gpio_desc *desc)
	126	+
	127	+To access such GPIOs, a different set of accessors is defined:
	128	+
	129	+ int gpiod_get_value_cansleep(const struct gpio_desc *desc)
	130	+ void gpiod_set_value_cansleep(struct gpio_desc *desc, int value)
	131	+
	132	+Accessing such GPIOs requires a context which may sleep, for example a threaded
	133	+IRQ handler, and those accessors must be used instead of spinlock-safe
	134	+accessors without the cansleep() name suffix.
	135	+
	136	+Other than the fact that these accessors might sleep, and will work on GPIOs
	137	+that can't be accessed from hardIRQ handlers, these calls act the same as the
	138	+spinlock-safe calls.
	139	+
	140	+
	141	+Active-low State and Raw GPIO Values
	142	+------------------------------------
	143	+Device drivers like to manage the logical state of a GPIO, i.e. the value their
	144	+device will actually receive, no matter what lies between it and the GPIO line.
	145	+In some cases, it might make sense to control the actual GPIO line value. The
	146	+following set of calls ignore the active-low property of a GPIO and work on the
	147	+raw line value:
	148	+
	149	+ int gpiod_get_raw_value(const struct gpio_desc *desc)
	150	+ void gpiod_set_raw_value(struct gpio_desc *desc, int value)
	151	+ int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc)
	152	+ void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value)
	153	+
	154	+The active-low state of a GPIO can also be queried using the following call:
	155	+
	156	+ int gpiod_is_active_low(const struct gpio_desc *desc)
	157	+
	158	+Note that these functions should only be used with great moderation ; a driver
	159	+should not have to care about the physical line level.
	160	+
	161	+GPIOs mapped to IRQs
	162	+--------------------
	163	+GPIO lines can quite often be used as IRQs. You can get the IRQ number
	164	+corresponding to a given GPIO using the following call:
	165	+
	166	+ int gpiod_to_irq(const struct gpio_desc *desc)
	167	+
	168	+It will return an IRQ number, or an negative errno code if the mapping can't be
	169	+done (most likely because that particular GPIO cannot be used as IRQ). It is an
	170	+unchecked error to use a GPIO that wasn't set up as an input using
	171	+gpiod_direction_input(), or to use an IRQ number that didn't originally come
	172	+from gpiod_to_irq(). gpiod_to_irq() is not allowed to sleep.
	173	+
	174	+Non-error values returned from gpiod_to_irq() can be passed to request_irq() or
	175	+free_irq(). They will often be stored into IRQ resources for platform devices,
	176	+by the board-specific initialization code. Note that IRQ trigger options are
	177	+part of the IRQ interface, e.g. IRQF_TRIGGER_FALLING, as are system wakeup
	178	+capabilities.
	179	+
	180	+
	181	+Interacting With the Legacy GPIO Subsystem
	182	+==========================================
	183	+Many kernel subsystems still handle GPIOs using the legacy integer-based
	184	+interface. Although it is strongly encouraged to upgrade them to the safer
	185	+descriptor-based API, the following two functions allow you to convert a GPIO
	186	+descriptor into the GPIO integer namespace and vice-versa:
	187	+
	188	+ int desc_to_gpio(const struct gpio_desc *desc)
	189	+ struct gpio_desc *gpio_to_desc(unsigned gpio)
	190	+
	191	+The GPIO number returned by desc_to_gpio() can be safely used as long as the
	192	+GPIO descriptor has not been freed. All the same, a GPIO number passed to
	193	+gpio_to_desc() must have been properly acquired, and usage of the returned GPIO
	194	+descriptor is only possible after the GPIO number has been released.
	195	+
	196	+Freeing a GPIO obtained by one API with the other API is forbidden and an
	197	+unchecked error.

Documentation/gpio/driver.txt+75−0

@@ -0,0 +1,75 @@
	1	+GPIO Descriptor Driver Interface
	2	+================================
	3	+
	4	+This document serves as a guide for GPIO chip drivers writers. Note that it
	5	+describes the new descriptor-based interface. For a description of the
	6	+deprecated integer-based GPIO interface please refer to gpio-legacy.txt.
	7	+
	8	+Each GPIO controller driver needs to include the following header, which defines
	9	+the structures used to define a GPIO driver:
	10	+
	11	+ #include <linux/gpio/driver.h>
	12	+
	13	+
	14	+Internal Representation of GPIOs
	15	+================================
	16	+
	17	+Inside a GPIO driver, individual GPIOs are identified by their hardware number,
	18	+which is a unique number between 0 and n, n being the number of GPIOs managed by
	19	+the chip. This number is purely internal: the hardware number of a particular
	20	+GPIO descriptor is never made visible outside of the driver.
	21	+
	22	+On top of this internal number, each GPIO also need to have a global number in
	23	+the integer GPIO namespace so that it can be used with the legacy GPIO
	24	+interface. Each chip must thus have a "base" number (which can be automatically
	25	+assigned), and for each GPIO the global number will be (base + hardware number).
	26	+Although the integer representation is considered deprecated, it still has many
	27	+users and thus needs to be maintained.
	28	+
	29	+So for example one platform could use numbers 32-159 for GPIOs, with a
	30	+controller defining 128 GPIOs at a "base" of 32 ; while another platform uses
	31	+numbers 0..63 with one set of GPIO controllers, 64-79 with another type of GPIO
	32	+controller, and on one particular board 80-95 with an FPGA. The numbers need not
	33	+be contiguous; either of those platforms could also use numbers 2000-2063 to
	34	+identify GPIOs in a bank of I2C GPIO expanders.
	35	+
	36	+
	37	+Controller Drivers: gpio_chip
	38	+=============================
	39	+
	40	+In the gpiolib framework each GPIO controller is packaged as a "struct
	41	+gpio_chip" (see linux/gpio/driver.h for its complete definition) with members
	42	+common to each controller of that type:
	43	+
	44	+ - methods to establish GPIO direction
	45	+ - methods used to access GPIO values
	46	+ - method to return the IRQ number associated to a given GPIO
	47	+ - flag saying whether calls to its methods may sleep
	48	+ - optional debugfs dump method (showing extra state like pullup config)
	49	+ - optional base number (will be automatically assigned if omitted)
	50	+ - label for diagnostics and GPIOs mapping using platform data
	51	+
	52	+The code implementing a gpio_chip should support multiple instances of the
	53	+controller, possibly using the driver model. That code will configure each
	54	+gpio_chip and issue gpiochip_add(). Removing a GPIO controller should be rare;
	55	+use gpiochip_remove() when it is unavoidable.
	56	+
	57	+Most often a gpio_chip is part of an instance-specific structure with state not
	58	+exposed by the GPIO interfaces, such as addressing, power management, and more.
	59	+Chips such as codecs will have complex non-GPIO state.
	60	+
	61	+Any debugfs dump method should normally ignore signals which haven't been
	62	+requested as GPIOs. They can use gpiochip_is_requested(), which returns either
	63	+NULL or the label associated with that GPIO when it was requested.
	64	+
	65	+Locking IRQ usage
	66	+-----------------
	67	+Input GPIOs can be used as IRQ signals. When this happens, a driver is requested
	68	+to mark the GPIO as being used as an IRQ:
	69	+
	70	+ int gpiod_lock_as_irq(struct gpio_desc *desc)
	71	+
	72	+This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock
	73	+is released:
	74	+
	75	+ void gpiod_unlock_as_irq(struct gpio_desc *desc)

Documentation/gpio/gpio-legacy.txtrenamed from Documentation/gpio.txt+0−0

File renamed without changes.

Documentation/gpio/gpio.txt+119−0

@@ -0,0 +1,119 @@
	1	+GPIO Interfaces
	2	+===============
	3	+
	4	+The documents in this directory give detailed instructions on how to access
	5	+GPIOs in drivers, and how to write a driver for a device that provides GPIOs
	6	+itself.
	7	+
	8	+Due to the history of GPIO interfaces in the kernel, there are two different
	9	+ways to obtain and use GPIOs:
	10	+
	11	+ - The descriptor-based interface is the preferred way to manipulate GPIOs,
	12	+and is described by all the files in this directory excepted gpio-legacy.txt.
	13	+ - The legacy integer-based interface which is considered deprecated (but still
	14	+usable for compatibility reasons) is documented in gpio-legacy.txt.
	15	+
	16	+The remainder of this document applies to the new descriptor-based interface.
	17	+gpio-legacy.txt contains the same information applied to the legacy
	18	+integer-based interface.
	19	+
	20	+
	21	+What is a GPIO?
	22	+===============
	23	+
	24	+A "General Purpose Input/Output" (GPIO) is a flexible software-controlled
	25	+digital signal. They are provided from many kinds of chip, and are familiar
	26	+to Linux developers working with embedded and custom hardware. Each GPIO
	27	+represents a bit connected to a particular pin, or "ball" on Ball Grid Array
	28	+(BGA) packages. Board schematics show which external hardware connects to
	29	+which GPIOs. Drivers can be written generically, so that board setup code
	30	+passes such pin configuration data to drivers.
	31	+
	32	+System-on-Chip (SOC) processors heavily rely on GPIOs. In some cases, every
	33	+non-dedicated pin can be configured as a GPIO; and most chips have at least
	34	+several dozen of them. Programmable logic devices (like FPGAs) can easily
	35	+provide GPIOs; multifunction chips like power managers, and audio codecs
	36	+often have a few such pins to help with pin scarcity on SOCs; and there are
	37	+also "GPIO Expander" chips that connect using the I2C or SPI serial buses.
	38	+Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS
	39	+firmware knowing how they're used).
	40	+
	41	+The exact capabilities of GPIOs vary between systems. Common options:
	42	+
	43	+ - Output values are writable (high=1, low=0). Some chips also have
	44	+ options about how that value is driven, so that for example only one
	45	+ value might be driven, supporting "wire-OR" and similar schemes for the
	46	+ other value (notably, "open drain" signaling).
	47	+
	48	+ - Input values are likewise readable (1, 0). Some chips support readback
	49	+ of pins configured as "output", which is very useful in such "wire-OR"
	50	+ cases (to support bidirectional signaling). GPIO controllers may have
	51	+ input de-glitch/debounce logic, sometimes with software controls.
	52	+
	53	+ - Inputs can often be used as IRQ signals, often edge triggered but
	54	+ sometimes level triggered. Such IRQs may be configurable as system
	55	+ wakeup events, to wake the system from a low power state.
	56	+
	57	+ - Usually a GPIO will be configurable as either input or output, as needed
	58	+ by different product boards; single direction ones exist too.
	59	+
	60	+ - Most GPIOs can be accessed while holding spinlocks, but those accessed
	61	+ through a serial bus normally can't. Some systems support both types.
	62	+
	63	+On a given board each GPIO is used for one specific purpose like monitoring
	64	+MMC/SD card insertion/removal, detecting card write-protect status, driving
	65	+a LED, configuring a transceiver, bit-banging a serial bus, poking a hardware
	66	+watchdog, sensing a switch, and so on.
	67	+
	68	+
	69	+Common GPIO Properties
	70	+======================
	71	+
	72	+These properties are met through all the other documents of the GPIO interface
	73	+and it is useful to understand them, especially if you need to define GPIO
	74	+mappings.
	75	+
	76	+Active-High and Active-Low
	77	+--------------------------
	78	+It is natural to assume that a GPIO is "active" when its output signal is 1
	79	+("high"), and inactive when it is 0 ("low"). However in practice the signal of a
	80	+GPIO may be inverted before is reaches its destination, or a device could decide
	81	+to have different conventions about what "active" means. Such decisions should
	82	+be transparent to device drivers, therefore it is possible to define a GPIO as
	83	+being either active-high ("1" means "active", the default) or active-low ("0"
	84	+means "active") so that drivers only need to worry about the logical signal and
	85	+not about what happens at the line level.
	86	+
	87	+Open Drain and Open Source
	88	+--------------------------
	89	+Sometimes shared signals need to use "open drain" (where only the low signal
	90	+level is actually driven), or "open source" (where only the high signal level is
	91	+driven) signaling. That term applies to CMOS transistors; "open collector" is
	92	+used for TTL. A pullup or pulldown resistor causes the high or low signal level.
	93	+This is sometimes called a "wire-AND"; or more practically, from the negative
	94	+logic (low=true) perspective this is a "wire-OR".
	95	+
	96	+One common example of an open drain signal is a shared active-low IRQ line.
	97	+Also, bidirectional data bus signals sometimes use open drain signals.
	98	+
	99	+Some GPIO controllers directly support open drain and open source outputs; many
	100	+don't. When you need open drain signaling but your hardware doesn't directly
	101	+support it, there's a common idiom you can use to emulate it with any GPIO pin
	102	+that can be used as either an input or an output:
	103	+
	104	+ LOW: gpiod_direction_output(gpio, 0) ... this drives the signal and overrides
	105	+ the pullup.
	106	+
	107	+ HIGH: gpiod_direction_input(gpio) ... this turns off the output, so the pullup
	108	+ (or some other device) controls the signal.
	109	+
	110	+The same logic can be applied to emulate open source signaling, by driving the
	111	+high signal and configuring the GPIO as input for low. This open drain/open
	112	+source emulation can be handled transparently by the GPIO framework.
	113	+
	114	+If you are "driving" the signal high but gpiod_get_value(gpio) reports a low
	115	+value (after the appropriate rise time passes), you know some other component is
	116	+driving the shared signal low. That's not necessarily an error. As one common
	117	+example, that's how I2C clocks are stretched: a slave that needs a slower clock
	118	+delays the rising edge of SCK, and the I2C master adjusts its signaling rate
	119	+accordingly.

Documentation/gpio/sysfs.txt+155−0

@@ -0,0 +1,155 @@
	1	+GPIO Sysfs Interface for Userspace
	2	+==================================
	3	+
	4	+Platforms which use the "gpiolib" implementors framework may choose to
	5	+configure a sysfs user interface to GPIOs. This is different from the
	6	+debugfs interface, since it provides control over GPIO direction and
	7	+value instead of just showing a gpio state summary. Plus, it could be
	8	+present on production systems without debugging support.
	9	+
	10	+Given appropriate hardware documentation for the system, userspace could
	11	+know for example that GPIO #23 controls the write protect line used to
	12	+protect boot loader segments in flash memory. System upgrade procedures
	13	+may need to temporarily remove that protection, first importing a GPIO,
	14	+then changing its output state, then updating the code before re-enabling
	15	+the write protection. In normal use, GPIO #23 would never be touched,
	16	+and the kernel would have no need to know about it.
	17	+
	18	+Again depending on appropriate hardware documentation, on some systems
	19	+userspace GPIO can be used to determine system configuration data that
	20	+standard kernels won't know about. And for some tasks, simple userspace
	21	+GPIO drivers could be all that the system really needs.
	22	+
	23	+Note that standard kernel drivers exist for common "LEDs and Buttons"
	24	+GPIO tasks: "leds-gpio" and "gpio_keys", respectively. Use those
	25	+instead of talking directly to the GPIOs; they integrate with kernel
	26	+frameworks better than your userspace code could.
	27	+
	28	+
	29	+Paths in Sysfs
	30	+--------------
	31	+There are three kinds of entry in /sys/class/gpio:
	32	+
	33	+ - Control interfaces used to get userspace control over GPIOs;
	34	+
	35	+ - GPIOs themselves; and
	36	+
	37	+ - GPIO controllers ("gpio_chip" instances).
	38	+
	39	+That's in addition to standard files including the "device" symlink.
	40	+
	41	+The control interfaces are write-only:
	42	+
	43	+ /sys/class/gpio/
	44	+
	45	+ "export" ... Userspace may ask the kernel to export control of
	46	+ a GPIO to userspace by writing its number to this file.
	47	+
	48	+ Example: "echo 19 > export" will create a "gpio19" node
	49	+ for GPIO #19, if that's not requested by kernel code.
	50	+
	51	+ "unexport" ... Reverses the effect of exporting to userspace.
	52	+
	53	+ Example: "echo 19 > unexport" will remove a "gpio19"
	54	+ node exported using the "export" file.
	55	+
	56	+GPIO signals have paths like /sys/class/gpio/gpio42/ (for GPIO #42)
	57	+and have the following read/write attributes:
	58	+
	59	+ /sys/class/gpio/gpioN/
	60	+
	61	+ "direction" ... reads as either "in" or "out". This value may
	62	+ normally be written. Writing as "out" defaults to
	63	+ initializing the value as low. To ensure glitch free
	64	+ operation, values "low" and "high" may be written to
	65	+ configure the GPIO as an output with that initial value.
	66	+
	67	+ Note that this attribute will not exist if the kernel
	68	+ doesn't support changing the direction of a GPIO, or
	69	+ it was exported by kernel code that didn't explicitly
	70	+ allow userspace to reconfigure this GPIO's direction.
	71	+
	72	+ "value" ... reads as either 0 (low) or 1 (high). If the GPIO
	73	+ is configured as an output, this value may be written;
	74	+ any nonzero value is treated as high.
	75	+
	76	+ If the pin can be configured as interrupt-generating interrupt
	77	+ and if it has been configured to generate interrupts (see the
	78	+ description of "edge"), you can poll(2) on that file and
	79	+ poll(2) will return whenever the interrupt was triggered. If
	80	+ you use poll(2), set the events POLLPRI and POLLERR. If you
	81	+ use select(2), set the file descriptor in exceptfds. After
	82	+ poll(2) returns, either lseek(2) to the beginning of the sysfs
	83	+ file and read the new value or close the file and re-open it
	84	+ to read the value.
	85	+
	86	+ "edge" ... reads as either "none", "rising", "falling", or
	87	+ "both". Write these strings to select the signal edge(s)
	88	+ that will make poll(2) on the "value" file return.
	89	+
	90	+ This file exists only if the pin can be configured as an
	91	+ interrupt generating input pin.
	92	+
	93	+ "active_low" ... reads as either 0 (false) or 1 (true). Write
	94	+ any nonzero value to invert the value attribute both
	95	+ for reading and writing. Existing and subsequent
	96	+ poll(2) support configuration via the edge attribute
	97	+ for "rising" and "falling" edges will follow this
	98	+ setting.
	99	+
	100	+GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for the
	101	+controller implementing GPIOs starting at #42) and have the following
	102	+read-only attributes:
	103	+
	104	+ /sys/class/gpio/gpiochipN/
	105	+
	106	+ "base" ... same as N, the first GPIO managed by this chip
	107	+
	108	+ "label" ... provided for diagnostics (not always unique)
	109	+
	110	+ "ngpio" ... how many GPIOs this manges (N to N + ngpio - 1)
	111	+
	112	+Board documentation should in most cases cover what GPIOs are used for
	113	+what purposes. However, those numbers are not always stable; GPIOs on
	114	+a daughtercard might be different depending on the base board being used,
	115	+or other cards in the stack. In such cases, you may need to use the
	116	+gpiochip nodes (possibly in conjunction with schematics) to determine
	117	+the correct GPIO number to use for a given signal.
	118	+
	119	+
	120	+Exporting from Kernel code
	121	+--------------------------
	122	+Kernel code can explicitly manage exports of GPIOs which have already been
	123	+requested using gpio_request():
	124	+
	125	+ /* export the GPIO to userspace */
	126	+ int gpiod_export(struct gpio_desc *desc, bool direction_may_change);
	127	+
	128	+ /* reverse gpio_export() */
	129	+ void gpiod_unexport(struct gpio_desc *desc);
	130	+
	131	+ /* create a sysfs link to an exported GPIO node */
	132	+ int gpiod_export_link(struct device dev, const char name,
	133	+ struct gpio_desc *desc);
	134	+
	135	+ /* change the polarity of a GPIO node in sysfs */
	136	+ int gpiod_sysfs_set_active_low(struct gpio_desc *desc, int value);
	137	+
	138	+After a kernel driver requests a GPIO, it may only be made available in
	139	+the sysfs interface by gpiod_export(). The driver can control whether the
	140	+signal direction may change. This helps drivers prevent userspace code
	141	+from accidentally clobbering important system state.
	142	+
	143	+This explicit exporting can help with debugging (by making some kinds
	144	+of experiments easier), or can provide an always-there interface that's
	145	+suitable for documenting as part of a board support package.
	146	+
	147	+After the GPIO has been exported, gpiod_export_link() allows creating
	148	+symlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers can
	149	+use this to provide the interface under their own device in sysfs with
	150	+a descriptive name.
	151	+
	152	+Drivers can use gpiod_sysfs_set_active_low() to hide GPIO line polarity
	153	+differences between boards from user space. Polarity change can be done both
	154	+before and after gpiod_export(), and previously enabled poll(2) support for
	155	+either rising or falling edge will be reconfigured to follow this setting.

drivers/gpio/gpio-bcm-kona.c+1−1

@@ -158,7 +158,7 @@ static int bcm_kona_gpio_get(struct gpio_chip *chip, unsigned gpio) · 157 unmodified lines
158	158	spin_unlock_irqrestore(&kona_gpio->lock, flags);
159	159
160	160	/* return the specified bit status */
161		− return !!(val & bit);
	161	+ return !!(val & BIT(bit));
162	162	}
163	163
164	164	static int bcm_kona_gpio_direction_input(struct gpio_chip *chip, unsigned gpio)

drivers/gpio/gpio-msm-v2.c+1−1

@@ -102,7 +102,7 @@ struct msm_gpio_dev { · 101 unmodified lines
102	102	DECLARE_BITMAP(wake_irqs, MAX_NR_GPIO);
103	103	DECLARE_BITMAP(dual_edge_irqs, MAX_NR_GPIO);
104	104	struct irq_domain *domain;
105		− unsigned int summary_irq;
	105	+ int summary_irq;
106	106	void __iomem *msm_tlmm_base;
107	107	};
108	108

drivers/gpio/gpio-mvebu.c+1−1

@@ -79,7 +79,7 @@ struct mvebu_gpio_chip { · 78 unmodified lines
79	79	spinlock_t lock;
80	80	void __iomem *membase;
81	81	void __iomem *percpu_membase;
82		− unsigned int irqbase;
	82	+ int irqbase;
83	83	struct irq_domain *domain;
84	84	int soc_variant;
85	85	};

drivers/gpio/gpio-pl061.c+5−5

@@ -286,11 +286,6 @@ static int pl061_probe(struct amba_device adev, const struct amba_id id) · 285 unmodified lines
286	286	if (!chip->base)
287	287	return -ENOMEM;
288	288
289		− chip->domain = irq_domain_add_simple(adev->dev.of_node, PL061_GPIO_NR,
290		− irq_base, &pl061_domain_ops, chip);
291		− if (!chip->domain)
292		− return -ENODEV;
293		−
294	289	spin_lock_init(&chip->lock);
295	290
296	291	chip->gc.request = pl061_gpio_request;
@@ -320,6 +315,11 @@ static int pl061_probe(struct amba_device adev, const struct amba_id id) · 23 unmodified lines
320	315	irq_set_chained_handler(irq, pl061_irq_handler);
321	316	irq_set_handler_data(irq, chip);
322	317
	318	+ chip->domain = irq_domain_add_simple(adev->dev.of_node, PL061_GPIO_NR,
	319	+ irq_base, &pl061_domain_ops, chip);
	320	+ if (!chip->domain)
	321	+ return -ENODEV;
	322	+
323	323	for (i = 0; i < PL061_GPIO_NR; i++) {
324	324	if (pdata) {
325	325	if (pdata->directions & (1 << i))

drivers/gpio/gpio-rcar.c+1−1

@@ -381,7 +381,7 @@ static int gpio_rcar_probe(struct platform_device *pdev) · 380 unmodified lines
381	381	if (!p->irq_domain) {
382	382	ret = -ENXIO;
383	383	dev_err(&pdev->dev, "cannot initialize irq domain\n");
384		− goto err1;
	384	+ goto err0;
385	385	}
386	386
387	387	if (devm_request_irq(&pdev->dev, irq->start,

drivers/gpio/gpio-tb10x.c+1−0

@@ -132,6 +132,7 @@ static int tb10x_gpio_direction_out(struct gpio_chip *chip, · 131 unmodified lines
132	132	int mask = BIT(offset);
133	133	int val = TB10X_GPIO_DIR_OUT << offset;
134	134
	135	+ tb10x_gpio_set(chip, offset, value);
135	136	tb10x_set_bits(tb10x_gpio, OFFSET_TO_REG_DDR, mask, val);
136	137
137	138	return 0;

drivers/gpio/gpio-ucb1400.c+1−0

@@ -105,3 +105,4 @@ module_platform_driver(ucb1400_gpio_driver); · 104 unmodified lines
105	105
106	106	MODULE_DESCRIPTION("Philips UCB1400 GPIO driver");
107	107	MODULE_LICENSE("GPL");
	108	+MODULE_ALIAS("platform:ucb1400_gpio");

drivers/gpio/gpiolib.c+32−26

@@ -14,6 +14,7 @@ · 13 unmodified lines
14	14	#include <linux/idr.h>
15	15	#include <linux/slab.h>
16	16	#include <linux/acpi.h>
	17	+#include <linux/gpio/driver.h>
17	18
18	19	#define CREATE_TRACE_POINTS
19	20	#include <trace/events/gpio.h>
@@ -1308,6 +1309,18 @@ struct gpio_chip gpiochip_find(void data, · 1288 unmodified lines
1308	1309	}
1309	1310	EXPORT_SYMBOL_GPL(gpiochip_find);
1310	1311
	1312	+static int gpiochip_match_name(struct gpio_chip chip, void data)
	1313	+{
	1314	+ const char *name = data;
	1315	+
	1316	+ return !strcmp(chip->label, name);
	1317	+}
	1318	+
	1319	+static struct gpio_chip find_chip_by_name(const char name)
	1320	+{
	1321	+ return gpiochip_find((void *)name, gpiochip_match_name);
	1322	+}
	1323	+
1311	1324	#ifdef CONFIG_PINCTRL
1312	1325
1313	1326	/**
@@ -1341,8 +1354,10 @@ int gpiochip_add_pingroup_range(struct gpio_chip *chip, · 27 unmodified lines
1341	1354	ret = pinctrl_get_group_pins(pctldev, pin_group,
1342	1355	&pin_range->range.pins,
1343	1356	&pin_range->range.npins);
1344		− if (ret < 0)
	1357	+ if (ret < 0) {
	1358	+ kfree(pin_range);
1345	1359	return ret;
	1360	+ }
1346	1361
1347	1362	pinctrl_add_gpio_range(pctldev, &pin_range->range);
1348	1363
@@ -2260,26 +2275,10 @@ void gpiod_add_table(struct gpiod_lookup *table, size_t size) · 911 unmodified lines
2260	2275	mutex_unlock(&gpio_lookup_lock);
2261	2276	}
2262	2277
2263		−/*
2264		− * Caller must have a acquired gpio_lookup_lock
2265		− */
2266		−static struct gpio_chip find_chip_by_name(const char name)
2267		−{
2268		− struct gpio_chip *chip = NULL;
2269		−
2270		− list_for_each_entry(chip, &gpio_lookup_list, list) {
2271		− if (chip->label == NULL)
2272		− continue;
2273		− if (!strcmp(chip->label, name))
2274		− break;
2275		− }
2276		−
2277		− return chip;
2278		−}
2279		−
2280	2278	#ifdef CONFIG_OF
2281	2279	static struct gpio_desc of_find_gpio(struct device dev, const char *con_id,
2282		− unsigned int idx, unsigned long *flags)
	2280	+ unsigned int idx,
	2281	+ enum gpio_lookup_flags *flags)
2283	2282	{
2284	2283	char prop_name[32]; /* 32 is max size of property name */
2285	2284	enum of_gpio_flags of_flags;
@@ -2297,20 +2296,22 @@ static struct gpio_desc of_find_gpio(struct device dev, const char *con_id, · 11 unmodified lines
2297	2296	return desc;
2298	2297
2299	2298	if (of_flags & OF_GPIO_ACTIVE_LOW)
2300		− *flags \|= GPIOF_ACTIVE_LOW;
	2299	+ *flags \|= GPIO_ACTIVE_LOW;
2301	2300
2302	2301	return desc;
2303	2302	}
2304	2303	#else
2305	2304	static struct gpio_desc of_find_gpio(struct device dev, const char *con_id,
2306		− unsigned int idx, unsigned long *flags)
	2305	+ unsigned int idx,
	2306	+ enum gpio_lookup_flags *flags)
2307	2307	{
2308	2308	return ERR_PTR(-ENODEV);
2309	2309	}
2310	2310	#endif
2311	2311
2312	2312	static struct gpio_desc acpi_find_gpio(struct device dev, const char *con_id,
2313		− unsigned int idx, unsigned long *flags)
	2313	+ unsigned int idx,
	2314	+ enum gpio_lookup_flags *flags)
2314	2315	{
2315	2316	struct acpi_gpio_info info;
2316	2317	struct gpio_desc *desc;
@@ -2320,13 +2321,14 @@ static struct gpio_desc acpi_find_gpio(struct device dev, const char *con_id, · 3 unmodified lines
2320	2321	return desc;
2321	2322
2322	2323	if (info.gpioint && info.active_low)
2323		− *flags \|= GPIOF_ACTIVE_LOW;
	2324	+ *flags \|= GPIO_ACTIVE_LOW;
2324	2325
2325	2326	return desc;
2326	2327	}
2327	2328
2328	2329	static struct gpio_desc gpiod_find(struct device dev, const char *con_id,
2329		− unsigned int idx, unsigned long *flags)
	2330	+ unsigned int idx,
	2331	+ enum gpio_lookup_flags *flags)
2330	2332	{
2331	2333	const char *dev_id = dev ? dev_name(dev) : NULL;
2332	2334	struct gpio_desc *desc = ERR_PTR(-ENODEV);
@@ -2418,7 +2420,7 @@ struct gpio_desc __must_check gpiod_get_index(struct device dev, · 85 unmodified lines
2418	2420	{
2419	2421	struct gpio_desc *desc;
2420	2422	int status;
2421		− unsigned long flags = 0;
	2423	+ enum gpio_lookup_flags flags = 0;
2422	2424
2423	2425	dev_dbg(dev, "GPIO lookup for consumer %s\n", con_id);
2424	2426
@@ -2444,8 +2446,12 @@ struct gpio_desc __must_check gpiod_get_index(struct device dev, · 19 unmodified lines
2444	2446	if (status < 0)
2445	2447	return ERR_PTR(status);
2446	2448
2447		− if (flags & GPIOF_ACTIVE_LOW)
	2449	+ if (flags & GPIO_ACTIVE_LOW)
2448	2450	set_bit(FLAG_ACTIVE_LOW, &desc->flags);
	2451	+ if (flags & GPIO_OPEN_DRAIN)
	2452	+ set_bit(FLAG_OPEN_DRAIN, &desc->flags);
	2453	+ if (flags & GPIO_OPEN_SOURCE)
	2454	+ set_bit(FLAG_OPEN_SOURCE, &desc->flags);
2449	2455
2450	2456	return desc;
2451	2457	}

include/linux/gpio/driver.h+9−2

@@ -125,6 +125,13 @@ extern struct gpio_chip gpiochip_find(void data, · 124 unmodified lines
125	125	int gpiod_lock_as_irq(struct gpio_desc *desc);
126	126	void gpiod_unlock_as_irq(struct gpio_desc *desc);
127	127
	128	+enum gpio_lookup_flags {
	129	+ GPIO_ACTIVE_HIGH = (0 << 0),
	130	+ GPIO_ACTIVE_LOW = (1 << 0),
	131	+ GPIO_OPEN_DRAIN = (1 << 1),
	132	+ GPIO_OPEN_SOURCE = (1 << 2),
	133	+};
	134	+
128	135	/**
129	136	* Lookup table for associating GPIOs to specific devices and functions using
130	137	* platform data.
@@ -152,9 +159,9 @@ struct gpiod_lookup { · 21 unmodified lines
152	159	*/
153	160	unsigned int idx;
154	161	/*
155		− * mask of GPIOF_* values
	162	+ * mask of GPIO_* values
156	163	*/
157		− unsigned long flags;
	164	+ enum gpio_lookup_flags flags;
158	165	};
159	166
160	167	/*