Add GPIO binding
PATCH 1/1 Add GPIO binding
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.
--- source/devicetree-basics.rst | 253 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 253 insertions(+)
source/devicetree-basics.rst +253 -0
@@ -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"; + }; + }; +
Signature · 1 line
2.11.0
A message that is not in the archive (sent off-list or not yet received): [email protected]
+Linus W
Quoted 291 lines · Grant Likely
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 <[email protected]>--- source/devicetree-basics.rst | 253 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 253 insertions(+)source/devicetree-basics.rst +253
-1@@ -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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): CAL_JsqJcCtAzV06BE_tuzQu6pz+3zNjfaE_EqU-5Ogw37WRLmg-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org
On Thu, Dec 7, 2017 at 9:51 PM, Rob Herring <[email protected]> wrote:
I don't really know the context but I guess devicetree.org standards document so I need to read it close :)
Quoted 6 lines
+Linus W
Quoted 3 lines · Grant Likely
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.
Two words: pin control - pin multiplexing is just half of the things pin control does. It also does electrical configuration of pins (pull ups etc) and that is not pinmux.
But I get what you mean.
Quoted 4 lines
Quoted 4 lines
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
Quoted 9 lines
Quoted 9 lines
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.
Ambitious! I like.
Quoted 8 lines
source/devicetree-basics.rst performed: · line 1293
Quoted 8 lines
source/devicetree-basics.rst +8
-0+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.
This reads like a textual form of the BNF-form specification that we have in the kernel. I assume other resources such as interrupts, clocks, regulators etc are described in similar wording so OK.
Quoted 3 lines
source/devicetree-basics.rst performed: · line 1297
Quoted 3 lines
source/devicetree-basics.rst +3
-0+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.
Good. That is a way of saying that when we say something is general purpose, it is actually general purpose. Should be evident from the name, but given how some electronics people call everything GPIO it needs to be pointed out I guess.
Quoted 6 lines
source/devicetree-basics.rst performed: · line 1303
Quoted 6 lines
source/devicetree-basics.rst +6
-0+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.
This kind of mandates that the OS implementing GPIO must provide accessors for setting pin direction and reading/writing lines. I guess mandating what an OS driver "must do" is not the scope of the spec but it is kind of hard to avoid it creeping in.
Quoted 5 lines
Quoted 5 lines
source/devicetree-basics.rst +5
-0+To conform to the generic GPIO binding, both the GPIO controller and consumer +nodes must conform to this binding as detailed below. + +GPIO Definitions +^^^^^^^^^^^^^^^^
Quoted 8 lines
source/devicetree-basics.rst performed: · line 1317
Quoted 8 lines
source/devicetree-basics.rst +8
-0+ +.. 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``.
Should it be "single-gpio" in the end there?
As it is named here:
Quoted 10 lines
source/devicetree-basics.rst performed: · line 1327
Quoted 10 lines
source/devicetree-basics.rst +10
-0+ ``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.
I would prefer to hammer down the gpio-specifier to 2 cells where the first cell specifies the line/signal and the second specifier electric properties, such as active low, open drain etc.
Quoted 4 lines
source/devicetree-basics.rst performed: · line 1331
Quoted 4 lines
source/devicetree-basics.rst +4
-0+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.
I don't see why we need to be vague and say "typically" here. It's better if we just
mandate it. I think the few existing GPIO drivers using one cell are an historical
artifact we should not standardize. We could just write "some older bindings use one cell" or so, and say that this is deprecated.
(I see the flags are specified under best practices, good!)
Quoted 1 line
Quoted 1 line
+GPIO Consumer Nodes
Mostly looks good!
Quoted 6 lines
Quoted 6 lines
source/devicetree-basics.rst +6
-0+GPIO Consumer Example +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: dts + + gpio1: gpio1 {
Quoted 8 lines
source/devicetree-basics.rst performed: · line 1378
Quoted 8 lines
source/devicetree-basics.rst +8
-0+ gpio-controller; + #gpio-cells = <2>; + }; + + gpio2: gpio2 { + gpio-controller; + #gpio-cells = <1>; + };
I think maybe we should cut that #gpio-cells = <1> example. Deprecate it IMO.
Quoted 2 lines
source/devicetree-basics.rst performed: · line 1381
Quoted 2 lines
source/devicetree-basics.rst +2
-0+ gpio-consumer { + enable-gpios = <&gpio2 2>;
Ditto. Use a twocell example instead.
Quoted 4 lines
source/devicetree-basics.rst performed: · line 1385
Quoted 4 lines
source/devicetree-basics.rst +4
-0+ data-gpios = <&gpio1 12 0>, + <&gpio1 13 0>, + <&gpio1 14 0>, + <&gpio1 15 0>;
This is good.
Quoted 8 lines
Quoted 8 lines
source/devicetree-basics.rst +8
-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 |
Quoted 8 lines
source/devicetree-basics.rst performed: · line 1404
Quoted 8 lines
+.. table:: GPIO Controller Properties
source/devicetree-basics.rst +7
-0+ + =================== ===== ================= ================================================ + 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.
I would strongly recommend that this be <2>.
Quoted 11 lines
source/devicetree-basics.rst performed: · line 1415
Quoted 11 lines
source/devicetree-basics.rst +11
-0+ ``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.
Good that you include this!
Quoted 4 lines
Quoted 4 lines
source/devicetree-basics.rst +4
-0+ ``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
Quoted 8 lines
source/devicetree-basics.rst performed: · line 1427
Quoted 8 lines
source/devicetree-basics.rst +8
-0+ 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.
Very nice.
Quoted 4 lines
Quoted 4 lines
source/devicetree-basics.rst +4
-0+GPIO Specifier Best Practices +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +How a ``gpio-specifier`` is encoded is defined by the GPIO controller binding,
Quoted 8 lines
source/devicetree-basics.rst performed: · line 1442
Quoted 8 lines
source/devicetree-basics.rst +8
-0+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.
I don't understand this 3 cell idea here.
Quoted 3 lines
source/devicetree-basics.rst performed: · line 1445
Quoted 3 lines
source/devicetree-basics.rst +3
-0+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.
I would prefer not to encourage the use of bank specifiers.
The best practice IMO is:
(A) model the banks as one device node per bank with n (typically 32) lines per device/bank and reference with two cells (handle and flags).
(B) represent all the GPIOs in the device as one long range, so if it is 6 banks of 32 lines, just expose a GPIO device, with two cells and GPIO numbers 0..191.
This is the most common in the kernel and I don't see why we should bring in the three-cell pattern at all. It should be deprecated if present in bindings IMO.
Quoted 2 lines
source/devicetree-basics.rst performed: · line 1447
Quoted 2 lines
source/devicetree-basics.rst +2
-0+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.
I disagree per above.
Quoted 1 line
Quoted 1 line
+Standard encoding for the flags cell are as follows
Awesome, thanks for wrapping this up in the spec.
Quoted 1 line
Quoted 1 line
+Example
Example is nice and to the point.
Quoted 8 lines
source/devicetree-basics.rst performed: · line 1490
Quoted 8 lines
source/devicetree-basics.rst +8
-0+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.
They even *MUST NOT* be referenced from consumer nodes.
Hogs are hoggy hogs that hog around. Very greedily.
So we need to say that hogs exclude a GPIO line from any use by any consumer node.
There has been a lot of back-and-forth of another type of self-reference specifying initial values and/or directions to a GPIO line, later to be taken (or not) by some consumer.
These discussions have stalled. It didn't lead anywhere.
Quoted 14 lines
Quoted 14 lines
source/devicetree-basics.rst +14
-0+ =================== ===== ======================== ================================================ + 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.
Quoted 8 lines
source/devicetree-basics.rst performed: · line 1517
Quoted 8 lines
source/devicetree-basics.rst +8
-0+ ``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
We should maybe state that the semantic effect of specifying a hog without specifying input, output-low or output-high is just that the line is left in its
initial state and made unavailable to consumers.
Quoted 1 line
Quoted 1 line
+GPIO Hogging Example
This looks good!
Yours,
Linus Walleij
A message that is not in the archive (sent off-list or not yet received): CACRpkdbntaEysFnHxZ1mVAnGTagy8Ek=a7dL0r_ciXjGZJR4ZQ-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org
Quoted 223 lines · Linus Walleij
On Thu, Dec 7, 2017 at 9:51 PM, Rob Herring <[email protected]> wrote:
I don't really know the context but I guess devicetree.org standards document so I need to read it close :)
Quoted 6 lines
+Linus W
Quoted 3 lines · Grant Likely
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.
Two words: pin control - pin multiplexing is just half of the things pin control does. It also does electrical configuration of pins (pull ups etc) and that is not pinmux.
But I get what you mean.
Quoted 4 lines
Quoted 4 lines
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
Quoted 9 lines
Quoted 9 lines
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.
Ambitious! I like.
Quoted 8 lines
source/devicetree-basics.rst performed: · line 1293
Quoted 8 lines
source/devicetree-basics.rst +8
-0+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.This reads like a textual form of the BNF-form specification that we have in the kernel. I assume other resources such as interrupts, clocks, regulators etc are described in similar wording so OK.
Quoted 3 lines
source/devicetree-basics.rst performed: · line 1297
Quoted 3 lines
source/devicetree-basics.rst +3
-0+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.Good. That is a way of saying that when we say something is general purpose, it is actually general purpose. Should be evident from the name, but given how some electronics people call everything GPIO it needs to be pointed out I guess.
Quoted 6 lines
source/devicetree-basics.rst performed: · line 1303
Quoted 6 lines
source/devicetree-basics.rst +6
-0+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.This kind of mandates that the OS implementing GPIO must provide accessors for setting pin direction and reading/writing lines. I guess mandating what an OS driver "must do" is not the scope of the spec but it is kind of hard to avoid it creeping in.
Quoted 5 lines
Quoted 5 lines
source/devicetree-basics.rst +5
-0+To conform to the generic GPIO binding, both the GPIO controller and consumer +nodes must conform to this binding as detailed below. + +GPIO Definitions +^^^^^^^^^^^^^^^^Quoted 8 lines
source/devicetree-basics.rst performed: · line 1317
Quoted 8 lines
source/devicetree-basics.rst +8
-0+ +.. 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``.Should it be "single-gpio" in the end there?
As it is named here:
Quoted 10 lines
source/devicetree-basics.rst performed: · line 1327
Quoted 10 lines
source/devicetree-basics.rst +10
-0+ ``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.I would prefer to hammer down the gpio-specifier to 2 cells where the first cell specifies the line/signal and the second specifier electric properties, such as active low, open drain etc.
Quoted 4 lines
source/devicetree-basics.rst performed: · line 1331
Quoted 4 lines
source/devicetree-basics.rst +4
-0+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.I don't see why we need to be vague and say "typically" here. It's better if we just
mandate it. I think the few existing GPIO drivers using one cell are an historical
artifact we should not standardize. We could just write "some older bindings use one cell" or so, and say that this is deprecated.(I see the flags are specified under best practices, good!)
Quoted 1 line
Quoted 1 line
+GPIO Consumer Nodes
Mostly looks good!
Quoted 6 lines
Quoted 6 lines
source/devicetree-basics.rst +6
-0+GPIO Consumer Example +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: dts + + gpio1: gpio1 {Quoted 8 lines
source/devicetree-basics.rst performed: · line 1378
Quoted 8 lines
source/devicetree-basics.rst +8
-0+ gpio-controller; + #gpio-cells = <2>; + }; + + gpio2: gpio2 { + gpio-controller; + #gpio-cells = <1>; + };I think maybe we should cut that #gpio-cells = <1> example. Deprecate it IMO.
Quoted 2 lines
source/devicetree-basics.rst performed: · line 1381
Quoted 2 lines
source/devicetree-basics.rst +2
-0+ gpio-consumer { + enable-gpios = <&gpio2 2>;Ditto. Use a twocell example instead.
Quoted 4 lines
source/devicetree-basics.rst performed: · line 1385
Quoted 4 lines
source/devicetree-basics.rst +4
-0+ data-gpios = <&gpio1 12 0>, + <&gpio1 13 0>, + <&gpio1 14 0>, + <&gpio1 15 0>;This is good.
Quoted 8 lines
Quoted 8 lines
source/devicetree-basics.rst +8
-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 |Quoted 8 lines
source/devicetree-basics.rst performed: · line 1404
Quoted 8 lines
+.. table:: GPIO Controller Properties
source/devicetree-basics.rst +7
-0+ + =================== ===== ================= ================================================ + 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.I would strongly recommend that this be <2>.
Quoted 11 lines
source/devicetree-basics.rst performed: · line 1415
Quoted 11 lines
source/devicetree-basics.rst +11
-0+ ``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.Good that you include this!
Quoted 4 lines
Quoted 4 lines
source/devicetree-basics.rst +4
-0+ ``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 theQuoted 8 lines
source/devicetree-basics.rst performed: · line 1427
Quoted 8 lines
source/devicetree-basics.rst +8
-0+ 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.Very nice.
Quoted 4 lines
Quoted 4 lines
source/devicetree-basics.rst +4
-0+GPIO Specifier Best Practices +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +How a ``gpio-specifier`` is encoded is defined by the GPIO controller binding,Quoted 8 lines
source/devicetree-basics.rst performed: · line 1442
Quoted 8 lines
source/devicetree-basics.rst +8
-0+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.I don't understand this 3 cell idea here.
Quoted 3 lines
source/devicetree-basics.rst performed: · line 1445
Quoted 3 lines
source/devicetree-basics.rst +3
-0+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.I would prefer not to encourage the use of bank specifiers.
The best practice IMO is:
(A) model the banks as one device node per bank with n (typically 32) lines per device/bank and reference with two cells (handle and flags).
Quoted 7 lines
(B) represent all the GPIOs in the device as one long range, so if it is 6 banks of 32 lines, just expose a GPIO device, with two cells and GPIO numbers 0..191.
This is the most common in the kernel and I don't see why we should bring in the three-cell pattern at all. It should be deprecated if present in bindings IMO.
We have to allow for oddball h/w in the spec even if 3 cells usually means you are doing it wrong.
Quoted 26 lines
Quoted 2 lines
source/devicetree-basics.rst performed: · line 1447
Quoted 2 lines
source/devicetree-basics.rst +2
-0+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.I disagree per above.
Quoted 1 line
Quoted 1 line
+Standard encoding for the flags cell are as follows
Awesome, thanks for wrapping this up in the spec.
Quoted 1 line
Quoted 1 line
+Example
Example is nice and to the point.
Quoted 8 lines
source/devicetree-basics.rst performed: · line 1490
Quoted 8 lines
source/devicetree-basics.rst +8
-0+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.They even *MUST NOT* be referenced from consumer nodes.
Hogs are hoggy hogs that hog around. Very greedily.
Quoted 8 lines
So we need to say that hogs exclude a GPIO line from any use by any consumer node.
There has been a lot of back-and-forth of another type of self-reference specifying initial values and/or directions to a GPIO line, later to be taken (or not) by some consumer.
These discussions have stalled. It didn't lead anywhere.
I would suggest we leave hogs out for now. I think the above needs to be resolved first. I'm not a fan of the gpio hogs binding so much, but I don't really have a better suggestion on how to handle it.
Rob
A message that is not in the archive (sent off-list or not yet received): CAL_JsqKLYe7e8kqXYWXXQ6mMY7CVXPDZYgCqZOfz3UCvUApkCg-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org
Quoted 275 lines · Rob Herring
Quoted 223 lines · Linus Walleij
On Thu, Dec 7, 2017 at 9:51 PM, Rob Herring <[email protected]> wrote:
I don't really know the context but I guess devicetree.org standards document so I need to read it close :)
Quoted 6 lines
+Linus W
Quoted 3 lines · Grant Likely
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.
Two words: pin control - pin multiplexing is just half of the things pin control does. It also does electrical configuration of pins (pull ups etc) and that is not pinmux.
But I get what you mean.
Quoted 4 lines
Quoted 4 lines
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
Quoted 9 lines
Quoted 9 lines
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.
Ambitious! I like.
Quoted 8 lines
Review
Quoted 8 lines
(quoted diff) +8
-0+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.This reads like a textual form of the BNF-form specification that we have in the kernel. I assume other resources such as interrupts, clocks, regulators etc are described in similar wording so OK.
Quoted 3 lines
Review
Quoted 3 lines
(quoted diff) +3
-0+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.Good. That is a way of saying that when we say something is general purpose, it is actually general purpose. Should be evident from the name, but given how some electronics people call everything GPIO it needs to be pointed out I guess.
Quoted 6 lines
Review
Quoted 6 lines
(quoted diff) +6
-0+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.This kind of mandates that the OS implementing GPIO must provide accessors for setting pin direction and reading/writing lines. I guess mandating what an OS driver "must do" is not the scope of the spec but it is kind of hard to avoid it creeping in.
Quoted 5 lines
Quoted 5 lines
(quoted diff) +5
-0+To conform to the generic GPIO binding, both the GPIO controller and consumer +nodes must conform to this binding as detailed below. + +GPIO Definitions +^^^^^^^^^^^^^^^^Quoted 8 lines
Review
Quoted 8 lines
(quoted diff) +8
-0+ +.. 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``.Should it be "single-gpio" in the end there?
As it is named here:
Quoted 10 lines
Review
Quoted 10 lines
(quoted diff) +10
-0+ ``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.I would prefer to hammer down the gpio-specifier to 2 cells where the first cell specifies the line/signal and the second specifier electric properties, such as active low, open drain etc.
Quoted 4 lines
Review
Quoted 4 lines
(quoted diff) +4
-0+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.I don't see why we need to be vague and say "typically" here. It's better if we just
mandate it. I think the few existing GPIO drivers using one cell are an historical
artifact we should not standardize. We could just write "some older bindings use one cell" or so, and say that this is deprecated.(I see the flags are specified under best practices, good!)
Quoted 1 line
Quoted 1 line
+GPIO Consumer Nodes
Mostly looks good!
Quoted 6 lines
Quoted 6 lines
(quoted diff) +6
-0+GPIO Consumer Example +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: dts + + gpio1: gpio1 {Quoted 8 lines
Review
Quoted 8 lines
(quoted diff) +8
-0+ gpio-controller; + #gpio-cells = <2>; + }; + + gpio2: gpio2 { + gpio-controller; + #gpio-cells = <1>; + };I think maybe we should cut that #gpio-cells = <1> example. Deprecate it IMO.
Quoted 2 lines
Review
Quoted 2 lines
(quoted diff) +2
-0+ gpio-consumer { + enable-gpios = <&gpio2 2>;Ditto. Use a twocell example instead.
Quoted 4 lines
Review
Quoted 4 lines
(quoted diff) +4
-0+ data-gpios = <&gpio1 12 0>, + <&gpio1 13 0>, + <&gpio1 14 0>, + <&gpio1 15 0>;This is good.
Quoted 8 lines
Quoted 8 lines
(quoted diff) +8
-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 |Quoted 8 lines
Review
Quoted 8 lines
+.. table:: GPIO Controller Properties
(quoted diff) +7
-0+ + =================== ===== ================= ================================================ + 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.I would strongly recommend that this be <2>.
Quoted 11 lines
Review
Quoted 11 lines
(quoted diff) +11
-0+ ``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.Good that you include this!
Quoted 4 lines
Quoted 4 lines
(quoted diff) +4
-0+ ``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 theQuoted 8 lines
Review
Quoted 8 lines
(quoted diff) +8
-0+ 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.Very nice.
Quoted 4 lines
Quoted 4 lines
(quoted diff) +4
-0+GPIO Specifier Best Practices +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +How a ``gpio-specifier`` is encoded is defined by the GPIO controller binding,Quoted 8 lines
Review
Quoted 8 lines
(quoted diff) +8
-0+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.I don't understand this 3 cell idea here.
Quoted 3 lines
Review
Quoted 3 lines
(quoted diff) +3
-0+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.I would prefer not to encourage the use of bank specifiers.
The best practice IMO is:
(A) model the banks as one device node per bank with n (typically 32) lines per device/bank and reference with two cells (handle and flags).
Quoted 7 lines
(B) represent all the GPIOs in the device as one long range, so if it is 6 banks of 32 lines, just expose a GPIO device, with two cells and GPIO numbers 0..191.
This is the most common in the kernel and I don't see why we should bring in the three-cell pattern at all. It should be deprecated if present in bindings IMO.
We have to allow for oddball h/w in the spec even if 3 cells usually means you are doing it wrong.
Quoted 26 lines
Quoted 2 lines
Review
Quoted 2 lines
(quoted diff) +2
-0+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.I disagree per above.
Quoted 1 line
Quoted 1 line
+Standard encoding for the flags cell are as follows
Awesome, thanks for wrapping this up in the spec.
Quoted 1 line
Quoted 1 line
+Example
Example is nice and to the point.
Quoted 8 lines
Review
Quoted 8 lines
(quoted diff) +8
-0+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.They even *MUST NOT* be referenced from consumer nodes.
Hogs are hoggy hogs that hog around. Very greedily.
Quoted 8 lines
So we need to say that hogs exclude a GPIO line from any use by any consumer node.
There has been a lot of back-and-forth of another type of self-reference specifying initial values and/or directions to a GPIO line, later to be taken (or not) by some consumer.
These discussions have stalled. It didn't lead anywhere.
I would suggest we leave hogs out for now. I think the above needs to be resolved first. I'm not a fan of the gpio hogs binding so much, but I don't really have a better suggestion on how to handle it.
Rob
Quoted 13 lines · Rob Herring
Quoted 12 lines · Linus Walleij
On Thu, Dec 7, 2017 at 9:51 PM, Rob Herring <[email protected]> wrote:
I don't really know the context but I guess devicetree.org standards document so I need to read it close :)
Quoted 6 lines
+Linus W
Quoted 3 lines · Grant Likely
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.
Quoted 5 lines
Quoted 5 lines
Two words: pin control - pin multiplexing is just half of the things pin control does. It also does electrical configuration of pins (pull ups etc) and that is not pinmux.
But I get what you mean.
I could use help with rewriting the section to properly reflect pin control. In this patch I've mostly just transcoding what has already been written.
[...]
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
(quoted diff) +4
-0+General Purpose IO (GPIO) +------------------------- + +GPIO signals are modelled in |spec| as a point to point connection between
Quoted 8 lines
Quoted 8 lines
Quoted 4 lines
Review
Quoted 4 lines
(quoted diff) +4
-0+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.This reads like a textual form of the BNF-form specification that we have in the kernel. I assume other resources such as interrupts, clocks, regulators etc are described in similar wording so OK.
Correct. The published document will probably continue to be formatted into something like BNF, but I want to move the source towards a usefully parseable syntax that can be used by tools
Quoted 9 lines
Quoted 9 lines
Quoted 4 lines
Review
Quoted 4 lines
(quoted diff) +3
-0+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.Good. That is a way of saying that when we say something is general purpose, it is actually general purpose. Should be evident from the name, but given how some electronics people call everything GPIO it needs to be pointed out I guess.
hahaha
Quoted 13 lines
Quoted 13 lines
Quoted 7 lines
Review
Quoted 7 lines
(quoted diff) +6
-0+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.This kind of mandates that the OS implementing GPIO must provide accessors for setting pin direction and reading/writing lines. I guess mandating what an OS driver "must do" is not the scope of the spec but it is kind of hard to avoid it creeping in.
Quoted 15 lines
Quoted 7 lines
Quoted 7 lines
Quoted 7 lines
(quoted diff) +7
-0+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 |Quoted 8 lines
Quoted 6 lines
Review
Quoted 6 lines
+.. table:: GPIO Binding Datatype Definitions
(quoted diff) +5
-0+ + =================== ============================== ================================================ + Type Definition Description + =================== ============================== ================================================ + ``gpio-list`` ``single-gpio [gpio-list]`` Array of one or more ``gpio-single``.Should it be "single-gpio" in the end there?
It's a recursive definition. :-)
This was from the original text. It could be reworded.
Quoted 17 lines
Quoted 17 lines
As it is named here:
Quoted 10 lines
Review
Quoted 10 lines
(quoted diff) +10
-0+ ``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.I would prefer to hammer down the gpio-specifier to 2 cells where the first cell specifies the line/signal and the second specifier electric properties, such as active low, open drain etc.
As Rob pointed out, this binding needs to account for more complicated scenarios, but it can be reworded to strongly recommend the 2-cell version.
Quoted 20 lines
Quoted 20 lines
Quoted 8 lines
Review
Quoted 8 lines
(quoted diff) +8
-0+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.They even *MUST NOT* be referenced from consumer nodes.
Hogs are hoggy hogs that hog around. Very greedily.
So we need to say that hogs exclude a GPIO line from any use by any consumer node.
There has been a lot of back-and-forth of another type of self-reference specifying initial values and/or directions to a GPIO line, later to be taken (or not) by some consumer.
Quoted 5 lines
Quoted 1 line
These discussions have stalled. It didn't lead anywhere.
I would suggest we leave hogs out for now. I think the above needs to be resolved first. I'm not a fan of the gpio hogs binding so much, but I don't really have a better suggestion on how to handle it.
Okay, will drop
g.