Add the GPIOs binding as described in the Linux kernel. All of the binding except pinmux has been included. Pinmux is omitted until the pinmux binding is similar transferred. The source binding in the Linux kernel tree can be found here: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/gpio/gpio.txt This patch is provided for review, but also as an exploration of bringing a full binding file over from the Linux freeform text into the specification document, and it shows the weakness of the current approach. All of the work done on this patch gives the text more structure and more formatting options, but it doesn't do anything to make binding files machine readable. I intend to iterate this patch to split the binding content off into a machine parsable file that can be parsed to emit Sphinx markup. This patch can be considered as the baseline. Signed-off-by: Grant Likely <grant.likely@xxxxxxx> --- source/devicetree-basics.rst | 253 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 253 insertions(+) diff --git a/source/devicetree-basics.rst b/source/devicetree-basics.rst index 6de1d5d..104178f 100644 --- a/source/devicetree-basics.rst +++ b/source/devicetree-basics.rst @@ -1283,3 +1283,256 @@ performed: * That result is looked up in the *interrupt-map* table, which maps to the parent interrupt specifier ``<4 1>``. +General Purpose IO (GPIO) +------------------------- + +GPIO signals are modelled in |spec| as a point to point connection between +a GPIO controller node which provides the GPIO signal, +and a GPIO consumer node. +A connection is described with a ``single-gpio`` which is placed in the +consumer node, and identifies a specific GPIO controller and signal. + +In this model, the purpose of a GPIO signal is determined by the GPIO consumer +node, which is entirely dependant on what device the consumer node represents. +The GPIO controller does not make any assumptions about how GPIOs will be used. +For example, an MMC controller may use a GPIO connection to communicate the RW/RO pin state. +In this case the MMC controller node would identify the specific GPIO signal +used to detect RW/RO state, +and the MMC controller driver would know to configure it as an input. +The GPIO controller node has no knowledge of how the pin should be used and +merely provides a pin control interface to the MMC driver. + +To conform to the generic GPIO binding, both the GPIO controller and consumer +nodes must conform to this binding as detailed below. + +GPIO Definitions +^^^^^^^^^^^^^^^^ + +.. tabularcolumns:: | l l J | +.. table:: GPIO Binding Datatype Definitions + + =================== ============================== ================================================ + Type Definition Description + =================== ============================== ================================================ + ``gpio-list`` ``single-gpio [gpio-list]`` Array of one or more ``gpio-single``. + ``single-gpio`` ``<phandle> <gpio-specifier>`` Reference to a single GPIO signal specifying + both GPIO controller (``phandle``) and GPIO + signal from that controller (``gpio-specifier``) + ``gpio-specifier`` ``<u32>[0..#gpio-cells]`` Array of ``cells``. Array size defined by + value of *#gpio-cells* in GPIO controller node. + In other words, the size of a ``gpio-specifier`` + is dependent on the GPIO controller. + =================== ============================== ================================================ + +A ``gpio-specifier`` is an array of 1 or more ``cells`` indicating the specific GPIO signal and configuration of that signal. +The GPIO controller binding must describe what information is encoded into its gpio-specifier, +which could include bank number, pin position, driver configuration, or signal inversion. +Typically a GPIO controller will set ``#gpio-cells=<2>``, with the first cell encoding the signal number, +and the second encoding flags for pin configuration. + +GPIO Consumer Nodes +^^^^^^^^^^^^^^^^^^^ + +GPIO consumers use properties named *<name>-gpios* to hold a ``gpio-list``. +The purpose of each GPIO reference is defined by the consumer device binding, +and is expected to be documented as part of that binding. +The ``<name>`` part should refer to the function of the GPIO signal + +Normally each *<name>-gpios* property contains only one GPIO reference, +and bindings should use different *<name>* values for each GPIO function. +However, if multiple GPIOs are used for the same function (e.g. an set of +parallel IO lines) then a *<name>-gpios* property may reference multiple +GPIO signals. + +Some older bindings use *gpio*, *gpios* or *<name>-gpio* properties to hold +the ``gpio-list``. +These property names are deprecated and should not be used in new GPIO consumer bindings. + +.. tabularcolumns:: | l c l J | +.. table:: GPIO Consumer Properties + + =================== ===== ================= ================================================ + Property Name Usage Value Type Definition + =================== ===== ================= ================================================ + ``<name>-gpios`` R ``<gpio-list>`` Reference to a GPIO signal. + ``name`` should reference the GPIO function. + ``<name>-gpio`` O ``<single-gpio>`` Deprecated + ``gpios`` O ``<gpio-list>`` Deprecated + ``gpio`` O ``<single-gpio>`` Deprecated + Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition + ============================================================================================ + +GPIO Consumer Example +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: dts + + gpio1: gpio1 { + gpio-controller; + #gpio-cells = <2>; + }; + + gpio2: gpio2 { + gpio-controller; + #gpio-cells = <1>; + }; + + gpio-consumer { + enable-gpios = <&gpio2 2>; + data-gpios = <&gpio1 12 0>, + <&gpio1 13 0>, + <&gpio1 14 0>, + <&gpio1 15 0>; + }; + + +GPIO Controller Nodes +^^^^^^^^^^^^^^^^^^^^^ + +Every GPIO controller node must contain an empty *gpio-controller* property, +and a *gpio-cells* integer property, which indicates the number of cells in a +``single-gpio``. + +.. tabularcolumns:: | l c l J | +.. table:: GPIO Controller Properties + + =================== ===== ================= ================================================ + Property Name Usage Value Type Definition + =================== ===== ================= ================================================ + ``#gpio-cells`` R ``<u32>`` Specifies the number of ``<u32>`` cells to + represent the address in the ``reg`` property in + children of root. + ``gpio-controller`` R ``<empty>`` Declares the device as a GPIO controller that + can be referenced using a ``single-gpio`` + ``ngpios`` OR ``<u32>`` Optional property describing the number + of GPIO signals provided by the controller. + This property may be used when the controller + provides fewer signals than the driver binding + supports. For example, a MMIO GPIO controller + with 32-bit registers might theoretically + support 32 GPIO signals, but only numbers 0 + through 11 wired up. In this case + "ngpios = <12>;" should be set. + ``gpio-line-names`` O ``<stringlist>`` An array of names for each of the GPIO signals + provided by the controller. This name should be + the most meaningful producer name for the + system, such as a rail name indicating the + usage. Package names such as pin names are + discouraged. For example, "MMC-CD", + "Red LED Vdd" and "Ethernet RST" are reasonable + line names as they describe what the line is + used for. Names like "GPIO0" are discouraged. + Additionally, placeholder names are discouraged. + If a signal does not have a name defined, then + use "" (blank string) as the placeholder. + Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition + ============================================================================================ + +GPIO Specifier Best Practices +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +How a ``gpio-specifier`` is encoded is defined by the GPIO controller binding, +and so it allows quite a bit of flexibility to encode extra information required +by the interrupt controller into the ``gpio-specifier`` itself. +However, most GPIO controllers encode the same information so it is strongly recommended +to follow established convention for ``gpio-specifier`` format. + +Established convention for ``gpio-specifier`` is to use either 2 or 3 cells to describe +a GPIO signal depending on whether or not the GPIO controller provides multiple "banks" +of GPIO registers. +If the controller does use banks, then 3 cells should be used with the bank encoded +into the first cell, the pin within the bank in the second, and the flags in the third +cell. +If the controller does not use banks, then 2 cells are sufficient; the first cell +encoding the signal number and the second encoding the flags. + +Standard encoding for the flags cell are as follows + +.. tabularcolumns:: | l J | +.. table:: GPIO Standard Flags Bitfield + + ========== ======================================================================== + Bit number Meaning + ========== ======================================================================== + 0 (LSB) Signal Polarity - 0 Means Active High. 1 Means Active Low + 1 Driver type - 0 means push-pull. 1 means single-ended + 2 Input type - 0 means open-source, 1 means open-drain + 3 Sleep mode - 0 means state must be maintained during sleep/low-power + 1 means state can be losts after sleep/low-power + ========== ======================================================================== + +Example +~~~~~~~ + +Here is an example of a simple memory mapped GPIO controller + +.. code-block:: dts + + gpio-controller@c8008000 { + compatible = "acme,gpio"; + reg = <0xc8008000 0x1000}; + gpio-controller; + #gpio-cells = <2>; + ngpios = <18>; + gpio-line-names = "MMC-CD", "MMC-WP", "VDD eth", "RST eth", "LED R", + "LED G", "LED B", "Col A", "Col B", "Col C", "Col D", + "Row A", "Row B", "Row C", "Row D", "NMI button", + "poweroff", "reset"; + }; + +GPIO Hogging +~~~~~~~~~~~~ + +A GPIO controller may provide automatic configuration information for one or more GPIO +signals by adding ``GPIO hog`` child nodes. +GPIO hogging informs the GPIO controller driver that some pins must be configured in a +particular way at driver initialization time, without requiring a reference from a GPIO +consumer node. + +.. tabularcolumns:: | l c l J | +.. table:: GPIO Hog Child Node Properties + + + =================== ===== ======================== ================================================ + Property Name Usage Value Type Definition + =================== ===== ======================== ================================================ + ``gpio-hog`` R ``<empty>`` Declares the child node as a GPIO hog node + containing GPIO configuration information. + ``gpios`` R ``<prop-encoded-array>`` Array of ``gpio-specifier`` listing a set + of GPIOs to be preconfigured at initialization + time. + ``input`` O ``<empty>`` indicates listed GPIOs must be configured as + inputs. + ``output-low`` O ``<empty>`` indicates listed GPIOs must be configured as + output driven low. + ``output-low`` has no effect if the ``input`` + property is present. + ``output-high`` O ``<empty>`` indicates listed GPIOs must be configured as + output driven high. + ``output-high`` has no effect if either the + ``input`` or ``output-low`` properties are + present. + ``line-name`` O ``<string>`` The GPIO label name. If omitted, the GPIO hog + node name is used. + Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition + =================================================================================================== + +GPIO Hogging Example +~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: dts + + qe_pio_a: gpio-controller@1400 { + compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank"; + reg = <0x1400 0x18>; + gpio-controller; + #gpio-cells = <2>; + + line_b { + gpio-hog; + gpios = <6 0>; + output-low; + line-name = "foo-bar-gpio"; + }; + }; + -- 2.11.0 -- To unsubscribe from this list: send the line "unsubscribe devicetree-spec" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
