* [PATCH] Add GPIO binding
@ 2017-12-07 17:10 Grant Likely
[not found] ` <20171207171059.24845-1-grant.likely-5wv7dgnIgG8@public.gmane.org>
0 siblings, 1 reply; 6+ messages in thread
From: Grant Likely @ 2017-12-07 17:10 UTC (permalink / raw)
To: devicetree-spec-u79uwXL29TY76Z2rM5mHXA; +Cc: 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 <grant.likely-5wv7dgnIgG8@public.gmane.org>
---
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
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH] Add GPIO binding
[not found] ` <20171207171059.24845-1-grant.likely-5wv7dgnIgG8@public.gmane.org>
@ 2017-12-07 20:51 ` Rob Herring
[not found] ` <CAL_JsqJcCtAzV06BE_tuzQu6pz+3zNjfaE_EqU-5Ogw37WRLmg-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
0 siblings, 1 reply; 6+ messages in thread
From: Rob Herring @ 2017-12-07 20:51 UTC (permalink / raw)
To: Grant Likely, Linus Walleij
Cc: devicetree-spec-u79uwXL29TY76Z2rM5mHXA@public.gmane.org,
Grant Likely
+Linus W
On Thu, Dec 7, 2017 at 11:10 AM, Grant Likely <grant.likely-s3s/WqlpOiPyB63q8FvJNQ@public.gmane.org> wrote:
> 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-5wv7dgnIgG8@public.gmane.org>
> ---
> 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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] Add GPIO binding
[not found] ` <CAL_JsqJcCtAzV06BE_tuzQu6pz+3zNjfaE_EqU-5Ogw37WRLmg-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
@ 2017-12-11 9:07 ` Linus Walleij
[not found] ` <CACRpkdbntaEysFnHxZ1mVAnGTagy8Ek=a7dL0r_ciXjGZJR4ZQ-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
0 siblings, 1 reply; 6+ messages in thread
From: Linus Walleij @ 2017-12-11 9:07 UTC (permalink / raw)
To: Rob Herring
Cc: Grant Likely,
devicetree-spec-u79uwXL29TY76Z2rM5mHXA@public.gmane.org,
Grant Likely
On Thu, Dec 7, 2017 at 9:51 PM, Rob Herring <robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> wrote:
I don't really know the context but I guess devicetree.org standards
document so I need to read it close :)
> +Linus W
>
> On Thu, Dec 7, 2017 at 11:10 AM, Grant Likely <grant.likely-s3s/WqlpOiPyB63q8FvJNQ@public.gmane.org> wrote:
>> 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.
>> 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.
Ambitious! I like.
>> +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.
>> +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.
>> +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.
>> +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``.
Should it be "single-gpio" in the end there?
As it is named here:
>> + ``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.
>> +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!)
>> +GPIO Consumer Nodes
Mostly looks good!
>> +GPIO Consumer Example
>> +~~~~~~~~~~~~~~~~~~~~~
>> +
>> +.. code-block:: dts
>> +
>> + gpio1: gpio1 {
>> + 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.
>> + gpio-consumer {
>> + enable-gpios = <&gpio2 2>;
Ditto. Use a twocell example instead.
>> + data-gpios = <&gpio1 12 0>,
>> + <&gpio1 13 0>,
>> + <&gpio1 14 0>,
>> + <&gpio1 15 0>;
This is good.
>> +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.
I would strongly recommend that this be <2>.
>> + ``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!
>> + ``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.
Very nice.
>> +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.
I don't understand this 3 cell idea here.
>> +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.
>> +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.
>> +Standard encoding for the flags cell are as follows
Awesome, thanks for wrapping this up in the spec.
>> +Example
Example is nice and to the point.
>> +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.
>> + =================== ===== ======================== ================================================
>> + 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
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.
>> +GPIO Hogging Example
This looks good!
Yours,
Linus Walleij
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] Add GPIO binding
[not found] ` <CACRpkdbntaEysFnHxZ1mVAnGTagy8Ek=a7dL0r_ciXjGZJR4ZQ-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
@ 2017-12-11 15:46 ` Rob Herring
[not found] ` <CAL_JsqKLYe7e8kqXYWXXQ6mMY7CVXPDZYgCqZOfz3UCvUApkCg-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
0 siblings, 1 reply; 6+ messages in thread
From: Rob Herring @ 2017-12-11 15:46 UTC (permalink / raw)
To: Linus Walleij
Cc: Grant Likely,
devicetree-spec-u79uwXL29TY76Z2rM5mHXA@public.gmane.org,
Grant Likely
On Mon, Dec 11, 2017 at 3:07 AM, Linus Walleij <linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org> wrote:
> On Thu, Dec 7, 2017 at 9:51 PM, Rob Herring <robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> wrote:
>
> I don't really know the context but I guess devicetree.org standards
> document so I need to read it close :)
>
>> +Linus W
>>
>> On Thu, Dec 7, 2017 at 11:10 AM, Grant Likely <grant.likely-s3s/WqlpOiPyB63q8FvJNQ@public.gmane.org> wrote:
>>> 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.
>
>>> 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.
>
> Ambitious! I like.
>
>>> +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.
>
>>> +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.
>
>>> +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.
>
>>> +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``.
>
> Should it be "single-gpio" in the end there?
>
> As it is named here:
>
>>> + ``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.
>
>>> +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!)
>
>>> +GPIO Consumer Nodes
>
> Mostly looks good!
>
>>> +GPIO Consumer Example
>>> +~~~~~~~~~~~~~~~~~~~~~
>>> +
>>> +.. code-block:: dts
>>> +
>>> + gpio1: gpio1 {
>>> + 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.
>
>>> + gpio-consumer {
>>> + enable-gpios = <&gpio2 2>;
>
> Ditto. Use a twocell example instead.
>
>>> + data-gpios = <&gpio1 12 0>,
>>> + <&gpio1 13 0>,
>>> + <&gpio1 14 0>,
>>> + <&gpio1 15 0>;
>
> This is good.
>
>>> +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.
>
> I would strongly recommend that this be <2>.
>
>>> + ``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!
>
>>> + ``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.
>
> Very nice.
>
>>> +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.
>
> I don't understand this 3 cell idea here.
>
>>> +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.
We have to allow for oddball h/w in the spec even if 3 cells usually
means you are doing it wrong.
>>> +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.
>
>>> +Standard encoding for the flags cell are as follows
>
> Awesome, thanks for wrapping this up in the spec.
>
>>> +Example
>
> Example is nice and to the point.
>
>>> +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.
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] Add GPIO binding
[not found] ` <CAL_JsqKLYe7e8kqXYWXXQ6mMY7CVXPDZYgCqZOfz3UCvUApkCg-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
@ 2017-12-12 11:51 ` Grant Likely
2017-12-12 12:44 ` Grant Likely
1 sibling, 0 replies; 6+ messages in thread
From: Grant Likely @ 2017-12-12 11:51 UTC (permalink / raw)
To: Rob Herring
Cc: Linus Walleij,
devicetree-spec-u79uwXL29TY76Z2rM5mHXA@public.gmane.org,
Grant Likely
On Mon, Dec 11, 2017 at 3:46 PM, Rob Herring <robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> wrote:
> On Mon, Dec 11, 2017 at 3:07 AM, Linus Walleij <linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org> wrote:
>> On Thu, Dec 7, 2017 at 9:51 PM, Rob Herring <robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> wrote:
>>
>> I don't really know the context but I guess devicetree.org standards
>> document so I need to read it close :)
>>
>>> +Linus W
>>>
>>> On Thu, Dec 7, 2017 at 11:10 AM, Grant Likely <grant.likely-s3s/WqlpOiPyB63q8FvJNQ@public.gmane.org> wrote:
>>>> 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.
>>
>>>> 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.
>>
>> Ambitious! I like.
>>
>>>> +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.
>>
>>>> +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.
>>
>>>> +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.
>>
>>>> +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``.
>>
>> Should it be "single-gpio" in the end there?
>>
>> As it is named here:
>>
>>>> + ``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.
>>
>>>> +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!)
>>
>>>> +GPIO Consumer Nodes
>>
>> Mostly looks good!
>>
>>>> +GPIO Consumer Example
>>>> +~~~~~~~~~~~~~~~~~~~~~
>>>> +
>>>> +.. code-block:: dts
>>>> +
>>>> + gpio1: gpio1 {
>>>> + 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.
>>
>>>> + gpio-consumer {
>>>> + enable-gpios = <&gpio2 2>;
>>
>> Ditto. Use a twocell example instead.
>>
>>>> + data-gpios = <&gpio1 12 0>,
>>>> + <&gpio1 13 0>,
>>>> + <&gpio1 14 0>,
>>>> + <&gpio1 15 0>;
>>
>> This is good.
>>
>>>> +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.
>>
>> I would strongly recommend that this be <2>.
>>
>>>> + ``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!
>>
>>>> + ``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.
>>
>> Very nice.
>>
>>>> +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.
>>
>> I don't understand this 3 cell idea here.
>>
>>>> +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.
>
> We have to allow for oddball h/w in the spec even if 3 cells usually
> means you are doing it wrong.
>
>>>> +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.
>>
>>>> +Standard encoding for the flags cell are as follows
>>
>> Awesome, thanks for wrapping this up in the spec.
>>
>>>> +Example
>>
>> Example is nice and to the point.
>>
>>>> +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.
>
> 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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] Add GPIO binding
[not found] ` <CAL_JsqKLYe7e8kqXYWXXQ6mMY7CVXPDZYgCqZOfz3UCvUApkCg-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2017-12-12 11:51 ` Grant Likely
@ 2017-12-12 12:44 ` Grant Likely
1 sibling, 0 replies; 6+ messages in thread
From: Grant Likely @ 2017-12-12 12:44 UTC (permalink / raw)
To: Rob Herring
Cc: Linus Walleij,
devicetree-spec-u79uwXL29TY76Z2rM5mHXA@public.gmane.org,
Grant Likely
On Mon, Dec 11, 2017 at 3:46 PM, Rob Herring <robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> wrote:
> On Mon, Dec 11, 2017 at 3:07 AM, Linus Walleij <linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org> wrote:
>> On Thu, Dec 7, 2017 at 9:51 PM, Rob Herring <robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> wrote:
>>
>> I don't really know the context but I guess devicetree.org standards
>> document so I need to read it close :)
>>
>>> +Linus W
>>>
>>> On Thu, Dec 7, 2017 at 11:10 AM, Grant Likely <grant.likely-s3s/WqlpOiPyB63q8FvJNQ@public.gmane.org> wrote:
>>>> 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.
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.
[...]
>>>> +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.
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
>>
>>>> +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
>>
>>>> +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.
>>
>>>> +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``.
>>
>> Should it be "single-gpio" in the end there?
It's a recursive definition. :-)
This was from the original text. It could be reworded.
>>
>> As it is named here:
>>
>>>> + ``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.
>>>> +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.
>
> 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.
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2017-12-12 12:44 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2017-12-07 17:10 [PATCH] Add GPIO binding Grant Likely
[not found] ` <20171207171059.24845-1-grant.likely-5wv7dgnIgG8@public.gmane.org>
2017-12-07 20:51 ` Rob Herring
[not found] ` <CAL_JsqJcCtAzV06BE_tuzQu6pz+3zNjfaE_EqU-5Ogw37WRLmg-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2017-12-11 9:07 ` Linus Walleij
[not found] ` <CACRpkdbntaEysFnHxZ1mVAnGTagy8Ek=a7dL0r_ciXjGZJR4ZQ-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2017-12-11 15:46 ` Rob Herring
[not found] ` <CAL_JsqKLYe7e8kqXYWXXQ6mMY7CVXPDZYgCqZOfz3UCvUApkCg-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2017-12-12 11:51 ` Grant Likely
2017-12-12 12:44 ` Grant Likely
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).