diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/devicetree/bindings/gpio/cirrus,clps711x-mctrl-gpio.txt | 17 | ||||
| -rw-r--r-- | Documentation/devicetree/bindings/gpio/gpio-davinci.txt | 25 | ||||
| -rw-r--r-- | Documentation/devicetree/bindings/gpio/gpio-zevio.txt | 16 | ||||
| -rw-r--r-- | Documentation/devicetree/bindings/gpio/gpio.txt | 60 | ||||
| -rw-r--r-- | Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt | 60 | ||||
| -rw-r--r-- | Documentation/gpio/consumer.txt | 1 | ||||
| -rw-r--r-- | Documentation/gpio/driver.txt | 35 |
7 files changed, 204 insertions, 10 deletions
diff --git a/Documentation/devicetree/bindings/gpio/cirrus,clps711x-mctrl-gpio.txt b/Documentation/devicetree/bindings/gpio/cirrus,clps711x-mctrl-gpio.txt new file mode 100644 index 00000000000..94ae9f82dcf --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/cirrus,clps711x-mctrl-gpio.txt @@ -0,0 +1,17 @@ +* ARM Cirrus Logic CLPS711X SYSFLG1 MCTRL GPIOs + +Required properties: +- compatible: Should contain "cirrus,clps711x-mctrl-gpio". +- gpio-controller: Marks the device node as a gpio controller. +- #gpio-cells: Should be two. The first cell is the pin number and + the second cell is used to specify the gpio polarity: + 0 = Active high, + 1 = Active low. + +Example: + sysgpio: sysgpio { + compatible = "cirrus,ep7312-mctrl-gpio", + "cirrus,clps711x-mctrl-gpio"; + gpio-controller; + #gpio-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-davinci.txt b/Documentation/devicetree/bindings/gpio/gpio-davinci.txt index a2e839d6e33..5079ba7d656 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-davinci.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-davinci.txt @@ -1,13 +1,17 @@ -Davinci GPIO controller bindings +Davinci/Keystone GPIO controller bindings Required Properties: -- compatible: should be "ti,dm6441-gpio" +- compatible: should be "ti,dm6441-gpio", "ti,keystone-gpio" - reg: Physical base address of the controller and the size of memory mapped registers. - gpio-controller : Marks the device node as a gpio controller. +- #gpio-cells : Should be two. + - first cell is the pin number + - second cell is used to specify optional parameters (unused) + - interrupt-parent: phandle of the parent interrupt controller. - interrupts: Array of GPIO interrupt number. Only banked or unbanked IRQs are @@ -27,6 +31,7 @@ Example: gpio: gpio@1e26000 { compatible = "ti,dm6441-gpio"; gpio-controller; + #gpio-cells = <2>; reg = <0x226000 0x1000>; interrupt-parent = <&intc>; interrupts = <42 IRQ_TYPE_EDGE_BOTH 43 IRQ_TYPE_EDGE_BOTH @@ -39,3 +44,19 @@ gpio: gpio@1e26000 { interrupt-controller; #interrupt-cells = <2>; }; + +leds { + compatible = "gpio-leds"; + + led1 { + label = "davinci:green:usr1"; + gpios = <&gpio 10 GPIO_ACTIVE_HIGH>; + ... + }; + + led2 { + label = "davinci:red:debug1"; + gpios = <&gpio 11 GPIO_ACTIVE_HIGH>; + ... + }; +}; diff --git a/Documentation/devicetree/bindings/gpio/gpio-zevio.txt b/Documentation/devicetree/bindings/gpio/gpio-zevio.txt new file mode 100644 index 00000000000..a37bd9ae273 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-zevio.txt @@ -0,0 +1,16 @@ +Zevio GPIO controller + +Required properties: +- compatible: Should be "lsi,zevio-gpio" +- reg: Address and length of the register set for the device +- #gpio-cells: Should be two. The first cell is the pin number and the + second cell is used to specify optional parameters (currently unused). +- gpio-controller: Marks the device node as a GPIO controller. + +Example: + gpio: gpio@90000000 { + compatible = "lsi,zevio-gpio"; + reg = <0x90000000 0x1000>; + gpio-controller; + #gpio-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt index 0c85bb6e3a8..3fb8f53071b 100644 --- a/Documentation/devicetree/bindings/gpio/gpio.txt +++ b/Documentation/devicetree/bindings/gpio/gpio.txt @@ -13,11 +13,11 @@ properties, each containing a 'gpio-list': gpio-specifier : Array of #gpio-cells specifying specific gpio (controller specific) -GPIO properties should be named "[<name>-]gpios". Exact +GPIO properties should be named "[<name>-]gpios". The exact meaning of each gpios property must be documented in the device tree binding for each device. -For example, the following could be used to describe gpios pins to use +For example, the following could be used to describe GPIO pins used as chip select lines; with chip selects 0, 1 and 3 populated, and chip select 2 left empty: @@ -44,35 +44,79 @@ whether pin is open-drain and whether pin is logically inverted. Exact meaning of each specifier cell is controller specific, and must be documented in the device tree binding for the device. -Example of the node using GPIOs: +Example of a node using GPIOs: node { gpios = <&qe_pio_e 18 0>; }; In this example gpio-specifier is "18 0" and encodes GPIO pin number, -and empty GPIO flags as accepted by the "qe_pio_e" gpio-controller. +and GPIO flags as accepted by the "qe_pio_e" gpio-controller. + +1.1) GPIO specifier best practices +---------------------------------- + +A gpio-specifier should contain a flag indicating the GPIO polarity; active- +high or active-low. If it does, the follow best practices should be followed: + +The gpio-specifier's polarity flag should represent the physical level at the +GPIO controller that achieves (or represents, for inputs) a logically asserted +value at the device. The exact definition of logically asserted should be +defined by the binding for the device. If the board inverts the signal between +the GPIO controller and the device, then the gpio-specifier will represent the +opposite physical level than the signal at the device's pin. + +When the device's signal polarity is configurable, the binding for the +device must either: + +a) Define a single static polarity for the signal, with the expectation that +any software using that binding would statically program the device to use +that signal polarity. + +The static choice of polarity may be either: + +a1) (Preferred) Dictated by a binding-specific DT property. + +or: + +a2) Defined statically by the DT binding itself. + +In particular, the polarity cannot be derived from the gpio-specifier, since +that would prevent the DT from separately representing the two orthogonal +concepts of configurable signal polarity in the device, and possible board- +level signal inversion. + +or: + +b) Pick a single option for device signal polarity, and document this choice +in the binding. The gpio-specifier should represent the polarity of the signal +(at the GPIO controller) assuming that the device is configured for this +particular signal polarity choice. If software chooses to program the device +to generate or receive a signal of the opposite polarity, software will be +responsible for correctly interpreting (inverting) the GPIO signal at the GPIO +controller. 2) gpio-controller nodes ------------------------ -Every GPIO controller node must both an empty "gpio-controller" -property, and have #gpio-cells contain the size of the gpio-specifier. +Every GPIO controller node must contain both an empty "gpio-controller" +property, and a #gpio-cells integer property, which indicates the number of +cells in a gpio-specifier. Example of two SOC GPIO banks defined as gpio-controller nodes: qe_pio_a: gpio-controller@1400 { - #gpio-cells = <2>; compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank"; reg = <0x1400 0x18>; gpio-controller; + #gpio-cells = <2>; }; qe_pio_e: gpio-controller@1460 { - #gpio-cells = <2>; compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; reg = <0x1460 0x18>; gpio-controller; + #gpio-cells = <2>; }; 2.1) gpio- and pin-controller interaction diff --git a/Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt b/Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt new file mode 100644 index 00000000000..dd5d2c0394b --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt @@ -0,0 +1,60 @@ +* Synopsys DesignWare APB GPIO controller + +Required properties: +- compatible : Should contain "snps,dw-apb-gpio" +- reg : Address and length of the register set for the device. +- #address-cells : should be 1 (for addressing port subnodes). +- #size-cells : should be 0 (port subnodes). + +The GPIO controller has a configurable number of ports, each of which are +represented as child nodes with the following properties: + +Required properties: +- compatible : "snps,dw-apb-gpio-port" +- gpio-controller : Marks the device node as a gpio controller. +- #gpio-cells : Should be two. The first cell is the pin number and + the second cell is used to specify the gpio polarity: + 0 = active high + 1 = active low +- reg : The integer port index of the port, a single cell. + +Optional properties: +- interrupt-controller : The first port may be configured to be an interrupt +controller. +- #interrupt-cells : Specifies the number of cells needed to encode an + interrupt. Shall be set to 2. The first cell defines the interrupt number, + the second encodes the triger flags encoded as described in + Documentation/devicetree/bindings/interrupts.txt +- interrupt-parent : The parent interrupt 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. + +Example: + +gpio: gpio@20000 { + compatible = "snps,dw-apb-gpio"; + reg = <0x20000 0x1000>; + #address-cells = <1>; + #size-cells = <0>; + + porta: gpio-controller@0 { + compatible = "snps,dw-apb-gpio-port"; + gpio-controller; + #gpio-cells = <2>; + snps,nr-gpios = <8>; + reg = <0>; + interrupt-controller; + #interrupt-cells = <2>; + interrupt-parent = <&vic1>; + interrupts = <0>; + }; + + portb: gpio-controller@1 { + compatible = "snps,dw-apb-gpio-port"; + gpio-controller; + #gpio-cells = <2>; + snps,nr-gpios = <8>; + reg = <1>; + }; +}; diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt index e42f77d8d4c..09854fe5930 100644 --- a/Documentation/gpio/consumer.txt +++ b/Documentation/gpio/consumer.txt @@ -154,6 +154,7 @@ raw line value: 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: diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt index 9da0bfa7478..f73cc7b5dc8 100644 --- a/Documentation/gpio/driver.txt +++ b/Documentation/gpio/driver.txt @@ -62,6 +62,37 @@ Any debugfs dump method should normally ignore signals which haven't been requested as GPIOs. They can use gpiochip_is_requested(), which returns either NULL or the label associated with that GPIO when it was requested. + +GPIO drivers providing IRQs +--------------------------- +It is custom that GPIO drivers (GPIO chips) are also providing interrupts, +most often cascaded off a parent interrupt controller, and in some special +cases the GPIO logic is melded with a SoC's primary interrupt controller. + +The IRQ portions of the GPIO block are implemented using an irqchip, using +the header <linux/irq.h>. So basically such a driver is utilizing two sub- +systems simultaneously: gpio and irq. + +It is legal for any IRQ consumer to request an IRQ from any irqchip no matter +if that is a combined GPIO+IRQ driver. The basic premise is that gpio_chip and +irq_chip are orthogonal, and offering their services independent of each +other. + +gpiod_to_irq() is just a convenience function to figure out the IRQ for a +certain GPIO line and should not be relied upon to have been called before +the IRQ is used. + +So always prepare the hardware and make it ready for action in respective +callbacks from the GPIO and irqchip APIs. Do not rely on gpiod_to_irq() having +been called first. + +This orthogonality leads to ambiguities that we need to solve: if there is +competition inside the subsystem which side is using the resource (a certain +GPIO line and register for example) it needs to deny certain operations and +keep track of usage inside of the gpiolib subsystem. This is why the API +below exists. + + Locking IRQ usage ----------------- Input GPIOs can be used as IRQ signals. When this happens, a driver is requested @@ -73,3 +104,7 @@ 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) + +When implementing an irqchip inside a GPIO driver, these two functions should +typically be called in the .startup() and .shutdown() callbacks from the +irqchip. |