[PATCH 1/2] powerpc: document the MPIC device tree binding

[Yoder Stuart-B08248]

> From: Meador Inge <meador_inge at mentor.com>
> Date: Mon, Jan 17, 2011 at 6:52 PM
> Subject: [PATCH 1/2] powerpc: document the MPIC device tree binding
> To: linuxppc-dev at lists.ozlabs.org
> Cc: minge <meador_inge at mentor.com>,
> devicetree-discuss at lists.ozlabs.org, "Blanchard, Hollis"
> <Hollis_Blanchard at mentor.com>
> 
> 
> 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
> MPIC should be reset during runtime initialization.
> 
> Signed-off-by: Meador Inge <meador_inge at mentor.com>
> CC: Hollis Blanchard <hollis_blanchard at mentor.com>
> ---
>  Documentation/powerpc/dts-bindings/mpic.txt |   78

This is really the binding for an open-pic interrupt controller
and I think the name should reflect that-- open-pic.txt.

> +++++++++++++++++++++++++++
>  1 files changed, 78 insertions(+), 0 deletions(-)
>  create mode 100644 Documentation/powerpc/dts-bindings/mpic.txt
> 
> diff --git a/Documentation/powerpc/dts-bindings/mpic.txt
> b/Documentation/powerpc/dts-bindings/mpic.txt
> new file mode 100644
> index 0000000..3a67919
> --- /dev/null
> +++ b/Documentation/powerpc/dts-bindings/mpic.txt
> @@ -0,0 +1,78 @@
> +* MPIC Binding
> +
> +This binding specifies what properties and child nodes must be
> +available on the device tree representation of the "MPIC" interrupt
> +controller.  This binding is based on the binding defined for Open PIC
> +in [1] and is a superset of that binding.

I think it would be better to base this on the ePAPR binding which
was based on the original chrp binding.  Properties like "name"
and "device_type" are deprecated not being used in flat device trees.

<http://www.power.org/resources/downloads/Power_ePAPR_APPROVED_v1.0.pdf>

The proposed new properties really should go back into the ePAPR. 

> +
> +** Required properties:
> +
> +   NOTE: Many of these descriptions were paraphrased from [1] to aid
> +         readability.
> +
> +   - name : Specifies the name of the MPIC.

Drop this.  No DTS files use it.

> +   - device_type : Specifies the device type of this MPIC.  The value
> + of this
> +                   property shall be "open-pic".

device_type is deprecated, since this is not real open-firmware.  In
practice the kernel is matching on device_type, but we want to move
away from that to match on "compatible", just hasn't been implemented
yet.

> +   - reg : Specifies the base physical address(s) and size(s) of this
> + MPIC's
> +           addressable register space.
> +   - compatible : Specifies the compatibility list for the MPIC.  The
> + property
> +                  value shall include "chrp,open-pic".

In the ePAPR we modified this to just "open-pic", because this has
nothing to do with chrp anymore.   I think just "open-pic" is
what we want.

> +   - interrupt-controller : The presence of this property identifies
> + the node
> +                            as a MPIC.  No property value should be
> defined.
> +   - #address-cells : Specifies the number of cells needed to encode an
> +                      address.  The value of this property shall always
> + be 0
> +                      so that 'interrupt-map' nodes do not have to
> + specify a
> +                      parent unit address.
> +   - #interrupt-cells : Specifies the number of cells needed to encode
> + an
> +                        interrupt source.

Should be 2, correct?

> +** Optional properties:
> +
> +   - no-reset : The presence of this property indicates that the MPIC
> +                should not be reset during runtime initialization.
> +   - protected-sources : Specifies a list of interrupt sources that are
> + not
> +                         available for use and whose corresponding
> + vectors
> +                         should not be initialized.  A typical use case
> + for
> +                         this property is in AMP systems where multiple
> +                         independent operating systems need to share
> + the MPIC
> +                         without clobbering each other.

I do think you need to include the definition of interrupt
specifiers here.   Feel free to cut/paste text from my
Freescale mpic binding.

Stuart