summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/ABI/obsolete/sysfs-gpio2
-rw-r--r--Documentation/devicetree/bindings/common-properties.txt26
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-max3191x.txt59
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-uniphier.txt52
-rw-r--r--Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt2
-rw-r--r--Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt1
-rw-r--r--Documentation/gpio/consumer.txt63
-rw-r--r--Documentation/gpio/driver.txt6
8 files changed, 193 insertions, 18 deletions
diff --git a/Documentation/ABI/obsolete/sysfs-gpio b/Documentation/ABI/obsolete/sysfs-gpio
index 867c1fab20e2..32513dc2eec9 100644
--- a/Documentation/ABI/obsolete/sysfs-gpio
+++ b/Documentation/ABI/obsolete/sysfs-gpio
@@ -11,7 +11,7 @@ Description:
Kernel code may export it for complete or partial access.
GPIOs are identified as they are inside the kernel, using integers in
- the range 0..INT_MAX. See Documentation/gpio.txt for more information.
+ the range 0..INT_MAX. See Documentation/gpio/gpio.txt for more information.
/sys/class/gpio
/export ... asks the kernel to export a GPIO to userspace
diff --git a/Documentation/devicetree/bindings/common-properties.txt b/Documentation/devicetree/bindings/common-properties.txt
index 697714f8d75c..a3448bfa1c82 100644
--- a/Documentation/devicetree/bindings/common-properties.txt
+++ b/Documentation/devicetree/bindings/common-properties.txt
@@ -1,4 +1,8 @@
Common properties
+=================
+
+Endianness
+----------
The Devicetree Specification does not define any properties related to hardware
byteswapping, but endianness issues show up frequently in porting Linux to
@@ -58,3 +62,25 @@ dev: dev@40031000 {
...
little-endian;
};
+
+Daisy-chained devices
+---------------------
+
+Many serially-attached GPIO and IIO devices are daisy-chainable. To the
+host controller, a daisy-chain appears as a single device, but the number
+of inputs and outputs it provides is the sum of inputs and outputs provided
+by all of its devices. The driver needs to know how many devices the
+daisy-chain comprises to determine the amount of data exchanged, how many
+inputs and outputs to register and so on.
+
+Optional properties:
+ - #daisy-chained-devices: Number of devices in the daisy-chain (default is 1).
+
+Example:
+gpio@0 {
+ compatible = "name";
+ reg = <0>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ #daisy-chained-devices = <3>;
+};
diff --git a/Documentation/devicetree/bindings/gpio/gpio-max3191x.txt b/Documentation/devicetree/bindings/gpio/gpio-max3191x.txt
new file mode 100644
index 000000000000..b3a6444b8f45
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/gpio-max3191x.txt
@@ -0,0 +1,59 @@
+GPIO driver for Maxim MAX3191x industrial serializer
+
+Required properties:
+ - compatible: Must be one of:
+ "maxim,max31910"
+ "maxim,max31911"
+ "maxim,max31912"
+ "maxim,max31913"
+ "maxim,max31953"
+ "maxim,max31963"
+ - reg: Chip select number.
+ - gpio-controller: Marks the device node as a GPIO controller.
+ - #gpio-cells: Should be two. For consumer use see gpio.txt.
+
+Optional properties:
+ - #daisy-chained-devices:
+ Number of chips in the daisy-chain (default is 1).
+ - maxim,modesel-gpios: GPIO pins to configure modesel of each chip.
+ The number of GPIOs must equal "#daisy-chained-devices"
+ (if each chip is driven by a separate pin) or 1
+ (if all chips are wired to the same pin).
+ - maxim,fault-gpios: GPIO pins to read fault of each chip.
+ The number of GPIOs must equal "#daisy-chained-devices"
+ or 1.
+ - maxim,db0-gpios: GPIO pins to configure debounce of each chip.
+ The number of GPIOs must equal "#daisy-chained-devices"
+ or 1.
+ - maxim,db1-gpios: GPIO pins to configure debounce of each chip.
+ The number of GPIOs must equal "maxim,db0-gpios".
+ - maxim,modesel-8bit: Boolean whether the modesel pin of the chips is
+ pulled high (8-bit mode). Use this if the modesel pin
+ is hardwired and consequently "maxim,modesel-gpios"
+ cannot be specified. By default if neither this nor
+ "maxim,modesel-gpios" is given, the driver assumes
+ that modesel is pulled low (16-bit mode).
+ - maxim,ignore-undervoltage:
+ Boolean whether to ignore undervoltage alarms signaled
+ by the "maxim,fault-gpios" or by the status byte
+ (in 16-bit mode). Use this if the chips are powered
+ through 5VOUT instead of VCC24V, in which case they
+ will constantly signal undervoltage.
+
+For other required and optional properties of SPI slave nodes please refer to
+../spi/spi-bus.txt.
+
+Example:
+ gpio@0 {
+ compatible = "maxim,max31913";
+ reg = <0>;
+ gpio-controller;
+ #gpio-cells = <2>;
+
+ maxim,modesel-gpios = <&gpio2 23>;
+ maxim,fault-gpios = <&gpio2 24 GPIO_ACTIVE_LOW>;
+ maxim,db0-gpios = <&gpio2 25>;
+ maxim,db1-gpios = <&gpio2 26>;
+
+ spi-max-frequency = <25000000>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-uniphier.txt b/Documentation/devicetree/bindings/gpio/gpio-uniphier.txt
new file mode 100644
index 000000000000..fed9158dd913
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/gpio-uniphier.txt
@@ -0,0 +1,52 @@
+UniPhier GPIO controller
+
+Required properties:
+- compatible: Should be "socionext,uniphier-gpio".
+- reg: Specifies offset and length of the register set for the device.
+- gpio-controller: Marks the device node as a GPIO controller.
+- #gpio-cells: Should be 2. The first cell is the pin number and the second
+ cell is used to specify optional parameters.
+- interrupt-parent: Specifies the parent interrupt controller.
+- interrupt-controller: Marks the device node as an interrupt controller.
+- #interrupt-cells: Should be 2. The first cell defines the interrupt number.
+ The second cell bits[3:0] is used to specify trigger type as follows:
+ 1 = low-to-high edge triggered
+ 2 = high-to-low edge triggered
+ 4 = active high level-sensitive
+ 8 = active low level-sensitive
+ Valid combinations are 1, 2, 3, 4, 8.
+- ngpios: Specifies the number of GPIO lines.
+- gpio-ranges: Mapping to pin controller pins (as described in gpio.txt)
+- socionext,interrupt-ranges: Specifies an interrupt number mapping between
+ this GPIO controller and its interrupt parent, in the form of arbitrary
+ number of <child-interrupt-base parent-interrupt-base length> triplets.
+
+Optional properties:
+- gpio-ranges-group-names: Used for named gpio ranges (as described in gpio.txt)
+
+Example:
+ gpio: gpio@55000000 {
+ compatible = "socionext,uniphier-gpio";
+ reg = <0x55000000 0x200>;
+ interrupt-parent = <&aidet>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ gpio-ranges = <&pinctrl 0 0 0>;
+ gpio-ranges-group-names = "gpio_range";
+ ngpios = <248>;
+ socionext,interrupt-ranges = <0 48 16>, <16 154 5>, <21 217 3>;
+ };
+
+Consumer Example:
+
+ sdhci0_pwrseq {
+ compatible = "mmc-pwrseq-emmc";
+ reset-gpios = <&gpio UNIPHIER_GPIO_PORT(29, 4) GPIO_ACTIVE_LOW>;
+ };
+
+Please note UNIPHIER_GPIO_PORT(29, 4) represents PORT294 in the SoC document.
+Unfortunately, only the one's place is octal in the port numbering. (That is,
+PORT 8, 9, 18, 19, 28, 29, ... are missing.) UNIPHIER_GPIO_PORT() is a helper
+macro to calculate 29 * 8 + 4.
diff --git a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt
index 51c86f69995e..a7ac460ad657 100644
--- a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt
+++ b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt
@@ -14,6 +14,8 @@ Required Properties:
- "renesas,gpio-r8a7794": for R8A7794 (R-Car E2) compatible GPIO controller.
- "renesas,gpio-r8a7795": for R8A7795 (R-Car H3) compatible GPIO controller.
- "renesas,gpio-r8a7796": for R8A7796 (R-Car M3-W) compatible GPIO controller.
+ - "renesas,gpio-r8a77970": for R8A77970 (R-Car V3M) compatible GPIO controller.
+ - "renesas,gpio-r8a77995": for R8A77995 (R-Car D3) compatible GPIO controller.
- "renesas,rcar-gen1-gpio": for a generic R-Car Gen1 GPIO controller.
- "renesas,rcar-gen2-gpio": for a generic R-Car Gen2 or RZ/G1 GPIO controller.
- "renesas,rcar-gen3-gpio": for a generic R-Car Gen3 GPIO controller.
diff --git a/Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt b/Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt
index 4d6c8cdc8586..4a75da7051bd 100644
--- a/Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt
+++ b/Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt
@@ -29,6 +29,7 @@ controller.
- interrupts : The interrupt to the parent controller raised when GPIOs
generate the interrupts.
- snps,nr-gpios : The number of pins in the port, a single cell.
+- resets : Reset line for the controller.
Example:
diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt
index 912568baabb9..63e1bd1d88e3 100644
--- a/Documentation/gpio/consumer.txt
+++ b/Documentation/gpio/consumer.txt
@@ -10,14 +10,30 @@ Guidelines for GPIOs consumers
==============================
Drivers that can't work without standard GPIO calls should have Kconfig entries
-that depend on GPIOLIB. The functions that allow a driver to obtain and use
-GPIOs are available by including the following file:
+that depend on GPIOLIB or select GPIOLIB. The functions that allow a driver to
+obtain and use GPIOs are available by including the following file:
#include <linux/gpio/consumer.h>
+There are static inline stubs for all functions in the header file in the case
+where GPIOLIB is disabled. When these stubs are called they will emit
+warnings. These stubs are used for two use cases:
+
+- Simple compile coverage with e.g. COMPILE_TEST - it does not matter that
+ the current platform does not enable or select GPIOLIB because we are not
+ going to execute the system anyway.
+
+- Truly optional GPIOLIB support - where the driver does not really make use
+ of the GPIOs on certain compile-time configurations for certain systems, but
+ will use it under other compile-time configurations. In this case the
+ consumer must make sure not to call into these functions, or the user will
+ be met with console warnings that may be perceived as intimidating.
+
All the functions that work with the descriptor-based GPIO interface are
prefixed with gpiod_. The gpio_ prefix is used for the legacy interface. No
-other function in the kernel should use these prefixes.
+other function in the kernel should use these prefixes. The use of the legacy
+functions is strongly discouraged, new code should use <linux/gpio/consumer.h>
+and descriptors exclusively.
Obtaining and Disposing GPIOs
@@ -279,9 +295,22 @@ as possible, especially by drivers which should not care about the actual
physical line level and worry about the logical value instead.
-Set multiple GPIO outputs with a single function call
------------------------------------------------------
-The following functions set the output values of an array of GPIOs:
+Access multiple GPIOs with a single function call
+-------------------------------------------------
+The following functions get or set the values of an array of GPIOs:
+
+ int gpiod_get_array_value(unsigned int array_size,
+ struct gpio_desc **desc_array,
+ int *value_array);
+ int gpiod_get_raw_array_value(unsigned int array_size,
+ struct gpio_desc **desc_array,
+ int *value_array);
+ int gpiod_get_array_value_cansleep(unsigned int array_size,
+ struct gpio_desc **desc_array,
+ int *value_array);
+ int gpiod_get_raw_array_value_cansleep(unsigned int array_size,
+ struct gpio_desc **desc_array,
+ int *value_array);
void gpiod_set_array_value(unsigned int array_size,
struct gpio_desc **desc_array,
@@ -296,34 +325,40 @@ The following functions set the output values of an array of GPIOs:
struct gpio_desc **desc_array,
int *value_array)
-The array can be an arbitrary set of GPIOs. The functions will try to set
+The array can be an arbitrary set of GPIOs. The functions will try to access
GPIOs belonging to the same bank or chip simultaneously if supported by the
corresponding chip driver. In that case a significantly improved performance
-can be expected. If simultaneous setting is not possible the GPIOs will be set
-sequentially.
+can be expected. If simultaneous access is not possible the GPIOs will be
+accessed sequentially.
-The gpiod_set_array() functions take three arguments:
+The functions take three arguments:
* array_size - the number of array elements
* desc_array - an array of GPIO descriptors
- * value_array - an array of values to assign to the GPIOs
+ * value_array - an array to store the GPIOs' values (get) or
+ an array of values to assign to the GPIOs (set)
The descriptor array can be obtained using the gpiod_get_array() function
or one of its variants. If the group of descriptors returned by that function
-matches the desired group of GPIOs, those GPIOs can be set by simply using
+matches the desired group of GPIOs, those GPIOs can be accessed by simply using
the struct gpio_descs returned by gpiod_get_array():
struct gpio_descs *my_gpio_descs = gpiod_get_array(...);
gpiod_set_array_value(my_gpio_descs->ndescs, my_gpio_descs->desc,
my_gpio_values);
-It is also possible to set a completely arbitrary array of descriptors. The
+It is also possible to access a completely arbitrary array of descriptors. The
descriptors may be obtained using any combination of gpiod_get() and
gpiod_get_array(). Afterwards the array of descriptors has to be setup
-manually before it can be used with gpiod_set_array().
+manually before it can be passed to one of the above functions.
Note that for optimal performance GPIOs belonging to the same chip should be
contiguous within the array of descriptors.
+The return value of gpiod_get_array_value() and its variants is 0 on success
+or negative on error. Note the difference to gpiod_get_value(), which returns
+0 or 1 on success to convey the GPIO value. With the array functions, the GPIO
+values are stored in value_array rather than passed back as return value.
+
GPIOs mapped to IRQs
--------------------
diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt
index fc1d2f83564d..d8de1c7de85a 100644
--- a/Documentation/gpio/driver.txt
+++ b/Documentation/gpio/driver.txt
@@ -254,7 +254,7 @@ GPIO irqchips usually fall in one of two categories:
static irqreturn_t omap_gpio_irq_handler(int irq, void *gpiobank)
unsigned long wa_lock_flags;
raw_spin_lock_irqsave(&bank->wa_lock, wa_lock_flags);
- generic_handle_irq(irq_find_mapping(bank->chip.irqdomain, bit));
+ generic_handle_irq(irq_find_mapping(bank->chip.irq.domain, bit));
raw_spin_unlock_irqrestore(&bank->wa_lock, wa_lock_flags);
* GENERIC CHAINED GPIO irqchips: these are the same as "CHAINED GPIO irqchips",
@@ -313,8 +313,8 @@ symbol:
mark all the child IRQs as having the other IRQ as parent.
If there is a need to exclude certain GPIOs from the IRQ domain, you can
-set .irq_need_valid_mask of the gpiochip before gpiochip_add_data() is
-called. This allocates an .irq_valid_mask with as many bits set as there
+set .irq.need_valid_mask of the gpiochip before gpiochip_add_data() is
+called. This allocates an .irq.valid_mask with as many bits set as there
are GPIOs in the chip. Drivers can exclude GPIOs by clearing bits from this
mask. The mask must be filled in before gpiochip_irqchip_add() or
gpiochip_irqchip_add_nested() is called.