summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--Documentation/devicetree/bindings/open-pic.txt98
1 files changed, 98 insertions, 0 deletions
diff --git a/Documentation/devicetree/bindings/open-pic.txt b/Documentation/devicetree/bindings/open-pic.txt
new file mode 100644
index 000000000000..909a902dff85
--- /dev/null
+++ b/Documentation/devicetree/bindings/open-pic.txt
@@ -0,0 +1,98 @@
+* 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)
+