1Specifying GPIO information for devices 2============================================ 3 41) gpios property 5----------------- 6 7Nodes that makes use of GPIOs should specify them using one or more 8properties, each containing a 'gpio-list': 9 10 gpio-list ::= <single-gpio> [gpio-list] 11 single-gpio ::= <gpio-phandle> <gpio-specifier> 12 gpio-phandle : phandle to gpio controller node 13 gpio-specifier : Array of #gpio-cells specifying specific gpio 14 (controller specific) 15 16GPIO properties should be named "[<name>-]gpios". Exact 17meaning of each gpios property must be documented in the device tree 18binding for each device. 19 20For example, the following could be used to describe gpios pins to use 21as chip select lines; with chip selects 0, 1 and 3 populated, and chip 22select 2 left empty: 23 24 gpio1: gpio1 { 25 gpio-controller 26 #gpio-cells = <2>; 27 }; 28 gpio2: gpio2 { 29 gpio-controller 30 #gpio-cells = <1>; 31 }; 32 [...] 33 chipsel-gpios = <&gpio1 12 0>, 34 <&gpio1 13 0>, 35 <0>, /* holes are permitted, means no GPIO 2 */ 36 <&gpio2 2>; 37 38Note that gpio-specifier length is controller dependent. In the 39above example, &gpio1 uses 2 cells to specify a gpio, while &gpio2 40only uses one. 41 42gpio-specifier may encode: bank, pin position inside the bank, 43whether pin is open-drain and whether pin is logically inverted. 44Exact meaning of each specifier cell is controller specific, and must 45be documented in the device tree binding for the device. 46 47Example of the node using GPIOs: 48 49 node { 50 gpios = <&qe_pio_e 18 0>; 51 }; 52 53In this example gpio-specifier is "18 0" and encodes GPIO pin number, 54and empty GPIO flags as accepted by the "qe_pio_e" gpio-controller. 55 562) gpio-controller nodes 57------------------------ 58 59Every GPIO controller node must both an empty "gpio-controller" 60property, and have #gpio-cells contain the size of the gpio-specifier. 61 62Example of two SOC GPIO banks defined as gpio-controller nodes: 63 64 qe_pio_a: gpio-controller@1400 { 65 #gpio-cells = <2>; 66 compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank"; 67 reg = <0x1400 0x18>; 68 gpio-controller; 69 }; 70 71 qe_pio_e: gpio-controller@1460 { 72 #gpio-cells = <2>; 73 compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; 74 reg = <0x1460 0x18>; 75 gpio-controller; 76 }; 77 782.1) gpio-controller and pinctrl subsystem 79------------------------------------------ 80 81gpio-controller on a SOC might be tightly coupled with the pinctrl 82subsystem, in the sense that the pins can be used by other functions 83together with optional gpio feature. 84 85While the pin allocation is totally managed by the pin ctrl subsystem, 86gpio (under gpiolib) is still maintained by gpio drivers. It may happen 87that different pin ranges in a SoC is managed by different gpio drivers. 88 89This makes it logical to let gpio drivers announce their pin ranges to 90the pin ctrl subsystem and call 'pinctrl_request_gpio' in order to 91request the corresponding pin before any gpio usage. 92 93For this, the gpio controller can use a pinctrl phandle and pins to 94announce the pinrange to the pin ctrl subsystem. For example, 95 96 qe_pio_e: gpio-controller@1460 { 97 #gpio-cells = <2>; 98 compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; 99 reg = <0x1460 0x18>; 100 gpio-controller; 101 gpio-ranges = <&pinctrl1 20 10>, <&pinctrl2 50 20>; 102 103 } 104 105where, 106 &pinctrl1 and &pinctrl2 is the phandle to the pinctrl DT node. 107 108 Next values specify the base pin and number of pins for the range 109 handled by 'qe_pio_e' gpio. In the given example from base pin 20 to 110 pin 29 under pinctrl1 and pin 50 to pin 69 under pinctrl2 is handled 111 by this gpio controller. 112 113The pinctrl node must have "#gpio-range-cells" property to show number of 114arguments to pass with phandle from gpio controllers node. 115