[PATCH v2 2/3] powerpc: document the Open PIC device tree binding

[Grant Likely]

On Wed, Feb 2, 2011 at 6:51 PM, Meador Inge <meador_inge at mentor.com> wrote:
> This binding documents several properties that have been in use for quite
> some time, and adds one new property 'no-reset', which controls whether the
> Open PIC should be reset during runtime initialization.
>
> The general formatting and interrupt specifier definition is based off of
> Stuart Yoder's FSL MPIC binding.
>
> Signed-off-by: Meador Inge <meador_inge at mentor.com>
> CC: Hollis Blanchard <hollis_blanchard at mentor.com>
> CC: Stuart Yoder <stuart.yoder at freescale.com>
> ---
>  Documentation/powerpc/dts-bindings/open-pic.txt |  115 +++++++++++++++++++++++
>  1 files changed, 115 insertions(+), 0 deletions(-)
>  create mode 100644 Documentation/powerpc/dts-bindings/open-pic.txt
>
> diff --git a/Documentation/powerpc/dts-bindings/open-pic.txt b/Documentation/powerpc/dts-bindings/open-pic.txt
> new file mode 100644
> index 0000000..447ef65
> --- /dev/null
> +++ b/Documentation/powerpc/dts-bindings/open-pic.txt
> @@ -0,0 +1,115 @@
> +* Open PIC Binding
> +
> +This binding specifies what properties must be available in the device tree
> +representation of an Open PIC compliant interrupt controller.  This binding is
> +based on the binding defined for Open PIC in [1] and is a superset of that
> +binding.
> +
> +PROPERTIES
> +
> +  NOTE: Many of these descriptions were paraphrased here from [1] to aid
> +        readability.
> +
> +  - compatible
> +      Usage: required
> +      Value type: <string>
> +      Definition: Specifies the compatibility list for the PIC.  The
> +          property value shall include "open-pic".
> +
> +  - reg
> +      Usage: required
> +      Value type: <prop-encoded-array>
> +      Definition: Specifies the base physical address(s) and size(s) of this
> +          PIC's addressable register space.
> +
> +  - interrupt-controller
> +      Usage: required
> +      Value type: <empty>
> +      Definition: The presence of this property identifies the node
> +          as an Open PIC.  No property value should be defined.
> +
> +  - #interrupt-cells
> +      Usage: required
> +      Value type: <u32>
> +      Definition: Specifies the number of cells needed to encode an
> +          interrupt source.  Shall be 2.
> +
> +  - #address-cells
> +      Usage: required
> +      Value type: <u32>
> +      Definition: Specifies the number of cells needed to encode an
> +          address.  The value of this property shall always be 0.
> +          As such, 'interrupt-map' nodes do not have to specify a
> +          parent unit address.
> +
> +  - no-reset
> +      Usage: optional
> +      Value type: <empty>
> +      Definition: The presence of this property indicates that the PIC
> +          should not be reset during runtime initialization.  The presence of
> +          this property also mandates that any initialization related to
> +          interrupt sources shall be limited to sources explicitly referenced
> +          in the device tree.

Please follow the lead set by the other binding documentation which is
more concise and tends to be of the form:

    Required properties:
        - reg : <description>
        - interrupt-controller : <description>

    Optional Properties:
        - no-reset : blah

I'm considering formalizing the binding format so that fully specified
and cross-referenced documentation can be generated from the bindings
directory.

Also, to avoid the potential of a future namespace collision, it would
not be a bad idea to name this openpic-no-reset or something that
makes it clear that this is a binding specific property.  "no-reset"
sounds generic enough to give me pause.

> +
> +INTERRUPT SPECIFIER DEFINITION
> +
> +  Interrupt specifiers consists of 2 cells encoded as
> +  follows:
> +
> +   <1st-cell>   interrupt-number
> +
> +                Identifies the interrupt source.
> +
> +   <2nd-cell>   level-sense information, encoded as follows:
> +                    0 = low-to-high edge triggered
> +                    1 = active low level-sensitive
> +                    2 = active high level-sensitive
> +                    3 = high-to-low edge triggered
> +
> +EXAMPLE 1
> +
> +    /*
> +     * An Open PIC interrupt controller
> +     */
> +       mpic: pic at 40000 {
> +        // This is an interrupt controller node.
> +               interrupt-controller;
> +
> +        // No address cells so that 'interrupt-map' nodes which reference
> +        // this Open PIC node do not need a parent address specifier.
> +               #address-cells = <0>;
> +
> +        // Two cells to encode interrupt sources.
> +               #interrupt-cells = <2>;
> +
> +        // Offset address of 0x40000 and size of 0x40000.
> +               reg = <0x40000 0x40000>;
> +
> +        // Compatible with Open PIC.
> +               compatible = "open-pic";
> +
> +        // The PIC should not be reset.
> +               no-reset;
> +       };
> +
> +EXAMPLE 2
> +
> +    /*
> +     * An interrupt generating device that is wired to an Open PIC.
> +     */
> +    serial0: serial at 4500 {
> +        // Interrupt source '42' that is active high level-sensitive.
> +        // Note that there are only two cells as specified in the interrupt
> +        // parent's '#interrupt-cells' property.
> +        interrupts = <42 2>;
> +
> +        // The interrupt controller that this device is wired to.
> +        interrupt-parent = <&mpic>;
> +    };
> +
> +REFERENCES
> +
> +[1] Power.org (TM) Standard for Embedded Power Architecture (TM) Platform
> +    Requirements (ePAPR), Version 1.0, July 2008.
> +    (http://www.power.org/resources/downloads/Power_ePAPR_APPROVED_v1.0.pdf)
> +
> --
> 1.6.3.3
>
> _______________________________________________
> devicetree-discuss mailing list
> devicetree-discuss at lists.ozlabs.org
> https://lists.ozlabs.org/listinfo/devicetree-discuss
>



-- 
Grant Likely, B.Sc., P.Eng.
Secret Lab Technologies Ltd.