summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2014-08-08 18:00:35 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2014-08-08 18:00:35 -0700
commit06b49ea43c0cdd22625883e555e45e66ef29e201 (patch)
tree9c72c88541e2bec5a95354504708a066fd8e50aa /Documentation
parent664fb23070ae66a023250a83870a5bae7cd0efeb (diff)
parentbdc6e95e1273b5cef01590273c1a240c53ceeea0 (diff)
Merge tag 'gpio-v3.17-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio
Pull GPIO update from Linus Walleij: "This is the bulk of GPIO changes for the v3.17 development cycle, and this time we got a lot of action going on and it will continue: - The core GPIO library implementation has been split up in three different files: - gpiolib.c for the latest and greatest and shiny GPIO library code using GPIO descriptors only - gpiolib-legacy.c for the old integer number space API that we are phasing out gradually - gpiolib-sysfs.c for the sysfs interface that we are not entirely happy with, but has to live on for ABI compatibility - Add a flags argument to *gpiod_get* functions, with some backward-compatibility macros to ease transitions. We should have had the flags there from the beginning it seems, now we need to clean up the mess. There is a plan on how to move forward here devised by Alexandre Courbot and Mark Brown - Split off a special <linux/gpio/machine.h> header for the board gpio table registration, as per example from the regulator subsystem - Start to kill off the return value from gpiochip_remove() by removing the __must_check attribute and removing all checks inside the drivers/gpio directory. The rationale is: well what were we supposed to do if there is an error code? Not much: print an error message. And gpiolib already does that. So make this function return void eventually - Some cleanups of hairy gpiolib code, make some functions not to be used outside the library private and make sure they are not exported, remove gpiod_lock/unlock_as_irq() as the existing function is for driver-internal use and fine as it is, delete gpio_ensure_requested() as it is not meaningful anymore - Support the GPIOF_ACTIVE_LOW flag from gpio_request_one() function calls, which is logical since this is already supported when referencing GPIOs from e.g. device trees - Switch STMPE, intel-mid, lynxpoint and ACPI (!) to use the gpiolib irqchip helpers cutting down on GPIO irqchip boilerplate a bit more - New driver for the Zynq GPIO block - The usual incremental improvements around a bunch of drivers - Janitorial syntactic and semantic cleanups by Jingoo Han, and Rickard Strandqvist especially" * tag 'gpio-v3.17-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio: (37 commits) MAINTAINERS: update GPIO include files gpio: add missing includes in machine.h gpio: add flags argument to gpiod_get*() functions MAINTAINERS: Update Samsung pin control entry gpio / ACPI: Move event handling registration to gpiolib irqchip helpers gpio: lynxpoint: Convert to use gpiolib irqchip gpio: split gpiod board registration into machine header gpio: remove gpio_ensure_requested() gpio: remove useless check in gpiolib_sysfs_init() gpiolib: Export gpiochip_request_own_desc and gpiochip_free_own_desc gpio: move gpio_ensure_requested() into legacy C file gpio: remove gpiod_lock/unlock_as_irq() gpio: make gpiochip_get_desc() gpiolib-private gpio: simplify gpiochip_export() gpio: remove export of private of_get_named_gpio_flags() gpio: Add support for GPIOF_ACTIVE_LOW to gpio_request_one functions gpio: zynq: Clear pending interrupt when enabling a IRQ gpio: drop retval check enforcing from gpiochip_remove() gpio: remove all usage of gpio_remove retval in driver/gpio devicetree: Add Zynq GPIO devicetree bindings documentation ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-zynq.txt26
-rw-r--r--Documentation/gpio/board.txt2
-rw-r--r--Documentation/gpio/consumer.txt26
-rw-r--r--Documentation/gpio/driver.txt25
4 files changed, 70 insertions, 9 deletions
diff --git a/Documentation/devicetree/bindings/gpio/gpio-zynq.txt b/Documentation/devicetree/bindings/gpio/gpio-zynq.txt
new file mode 100644
index 000000000000..986371a4be2c
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/gpio-zynq.txt
@@ -0,0 +1,26 @@
+Xilinx Zynq GPIO controller Device Tree Bindings
+-------------------------------------------
+
+Required properties:
+- #gpio-cells : Should be two
+ - First cell is the GPIO line number
+ - Second cell is used to specify optional
+ parameters (unused)
+- compatible : Should be "xlnx,zynq-gpio-1.0"
+- clocks : Clock specifier (see clock bindings for details)
+- gpio-controller : Marks the device node as a GPIO controller.
+- interrupts : Interrupt specifier (see interrupt bindings for
+ details)
+- interrupt-parent : Must be core interrupt controller
+- reg : Address and length of the register set for the device
+
+Example:
+ gpio@e000a000 {
+ #gpio-cells = <2>;
+ compatible = "xlnx,zynq-gpio-1.0";
+ clocks = <&clkc 42>;
+ gpio-controller;
+ interrupt-parent = <&intc>;
+ interrupts = <0 20 4>;
+ reg = <0xe000a000 0x1000>;
+ };
diff --git a/Documentation/gpio/board.txt b/Documentation/gpio/board.txt
index ba169faad5c6..4452786225b8 100644
--- a/Documentation/gpio/board.txt
+++ b/Documentation/gpio/board.txt
@@ -60,7 +60,7 @@ Platform Data
Finally, GPIOs can be bound to devices and functions using platform data. Board
files that desire to do so need to include the following header:
- #include <linux/gpio/driver.h>
+ #include <linux/gpio/machine.h>
GPIOs are mapped by the means of tables of lookups, containing instances of the
gpiod_lookup structure. Two macros are defined to help declaring such mappings:
diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt
index d8abfc31abbe..76546324e968 100644
--- a/Documentation/gpio/consumer.txt
+++ b/Documentation/gpio/consumer.txt
@@ -29,13 +29,24 @@ gpiod_get() functions. Like many other kernel subsystems, gpiod_get() takes the
device that will use the GPIO and the function the requested GPIO is supposed to
fulfill:
- struct gpio_desc *gpiod_get(struct device *dev, const char *con_id)
+ struct gpio_desc *gpiod_get(struct device *dev, const char *con_id,
+ enum gpiod_flags flags)
If a function is implemented by using several GPIOs together (e.g. a simple LED
device that displays digits), an additional index argument can be specified:
struct gpio_desc *gpiod_get_index(struct device *dev,
- const char *con_id, unsigned int idx)
+ const char *con_id, unsigned int idx,
+ enum gpiod_flags flags)
+
+The flags parameter is used to optionally specify a direction and initial value
+for the GPIO. Values can be:
+
+* GPIOD_ASIS or 0 to not initialize the GPIO at all. The direction must be set
+ later with one of the dedicated functions.
+* 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.
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
@@ -46,11 +57,13 @@ errors and an absence of GPIO for optional GPIO parameters.
Device-managed variants of these functions are also defined:
- struct gpio_desc *devm_gpiod_get(struct device *dev, const char *con_id)
+ struct gpio_desc *devm_gpiod_get(struct device *dev, const char *con_id,
+ enum gpiod_flags flags)
struct gpio_desc *devm_gpiod_get_index(struct device *dev,
const char *con_id,
- unsigned int idx)
+ unsigned int idx,
+ enum gpiod_flags flags)
A GPIO descriptor can be disposed of using the gpiod_put() function:
@@ -67,8 +80,9 @@ Using GPIOs
Setting Direction
-----------------
-The first thing a driver must do with a GPIO is setting its direction. This is
-done by invoking one of the gpiod_direction_*() functions:
+The first thing a driver must do with a GPIO is setting its direction. If no
+direction-setting flags have been given to gpiod_get*(), this is done by
+invoking one of the gpiod_direction_*() functions:
int gpiod_direction_input(struct gpio_desc *desc)
int gpiod_direction_output(struct gpio_desc *desc, int value)
diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt
index fa9a0a8b3734..18790c237977 100644
--- a/Documentation/gpio/driver.txt
+++ b/Documentation/gpio/driver.txt
@@ -157,13 +157,34 @@ Locking IRQ usage
Input GPIOs can be used as IRQ signals. When this happens, a driver is requested
to mark the GPIO as being used as an IRQ:
- int gpiod_lock_as_irq(struct gpio_desc *desc)
+ int gpio_lock_as_irq(struct gpio_chip *chip, unsigned int offset)
This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock
is released:
- void gpiod_unlock_as_irq(struct gpio_desc *desc)
+ void gpio_unlock_as_irq(struct gpio_chip *chip, unsigned int offset)
When implementing an irqchip inside a GPIO driver, these two functions should
typically be called in the .startup() and .shutdown() callbacks from the
irqchip.
+
+
+Requesting self-owned GPIO pins
+-------------------------------
+
+Sometimes it is useful to allow a GPIO chip driver to request its own GPIO
+descriptors through the gpiolib API. Using gpio_request() for this purpose
+does not help since it pins the module to the kernel forever (it calls
+try_module_get()). A GPIO driver can use the following functions instead
+to request and free descriptors without being pinned to the kernel forever.
+
+ int gpiochip_request_own_desc(struct gpio_desc *desc, const char *label)
+
+ void gpiochip_free_own_desc(struct gpio_desc *desc)
+
+Descriptors requested with gpiochip_request_own_desc() must be released with
+gpiochip_free_own_desc().
+
+These functions must be used with care since they do not affect module use
+count. Do not use the functions to request gpio descriptors not owned by the
+calling driver.