Commit a99eff39 authored by Meador Inge's avatar Meador Inge Committed by Benjamin Herrenschmidt
Browse files

powerpc: Document the Open PIC device tree binding 



This binding documents several properties that have been in use for quite
some time, and adds one new property 'pic-no-reset', which controls the
runtime initialization behavior of the PIC.  More specifically, the presence
of 'pic-no-reset' mandates that the PIC shall not be reset during runtime
initialization and that any initialization related to interrupt sources
shall be limited to sources explicitly referenced in the device tree.  This
functionality is useful in AMP systems where multiple OSes are sharing the
PIC and the reinitialization of the PIC can interfere with OSes that are
already up and running.

The interrupt specifier definition is based off of Stuart Yoder's FSL MPIC
binding.

Signed-off-by: default avatarMeador Inge <meador_inge@mentor.com>
Cc: Grant Likely <grant.likely@secretlab.ca>
Cc: Stuart Yoder <stuart.yoder@freescale.com>
Cc: Hollis Blanchard <hollis_blanchard@mentor.com>
Signed-off-by: default avatarBenjamin Herrenschmidt <benh@kernel.crashing.org>
parent 90407c99

Documentation/devicetree/bindings/open-pic.txt

0 → 100644
+98 −0
Original line number Diff line number Diff line 
* 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.



Required properties:



  NOTE: Many of these descriptions were paraphrased here from [1] to aid

        readability.



    - compatible: Specifies the compatibility list for the PIC.  The type

      shall be <string> and the value shall include "open-pic".



    - reg: Specifies the base physical address(s) and size(s) of this

      PIC's addressable register space.  The type shall be <prop-encoded-array>.



    - interrupt-controller: The presence of this property identifies the node

      as an Open PIC.  No property value shall be defined.



    - #interrupt-cells: Specifies the number of cells needed to encode an

      interrupt source.  The type shall be a <u32> and the value shall be 2.



    - #address-cells: Specifies the number of cells needed to encode an

      address.  The type shall be <u32> and the value shall be 0.  As such,

      'interrupt-map' nodes do not have to specify a parent unit address.



Optional properties:



    - pic-no-reset: The presence of this property indicates that the PIC

      shall not be reset during runtime initialization.  No property value shall

      be defined.  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.



* Interrupt Specifier Definition



  Interrupt specifiers consists of 2 cells encoded as

  follows:



    - <1st-cell>: The interrupt-number that identifies the interrupt source.



    - <2nd-cell>: The 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



* Examples



Example 1:



	/*

	 * An Open PIC interrupt controller

	 */

	mpic: pic@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 shall not be reset.

		pic-no-reset;

	};



Example 2:



	/*

	 * An interrupt generating device that is wired to an Open PIC.

	 */

	serial0: serial@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)

CRA Git | Maintained and supported by SUSTech CRA and CCSE