[deliverable/linux.git] / Documentation / devicetree / bindings / arm / cci.txt

=======================================================
ARM CCI cache coherent interconnect binding description
=======================================================

ARM multi-cluster systems maintain intra-cluster coherency through a
cache coherent interconnect (CCI) that is capable of monitoring bus
transactions and manage coherency, TLB invalidations and memory barriers.

It allows snooping and distributed virtual memory message broadcast across
clusters, through memory mapped interface, with a global control register
space and multiple sets of interface control registers, one per slave
interface.

Bindings for the CCI node follow the ePAPR standard, available from:

www.power.org/documentation/epapr-version-1-1/

with the addition of the bindings described in this document which are
specific to ARM.

* CCI interconnect node

	Description: Describes a CCI cache coherent Interconnect component

	Node name must be "cci".
	Node's parent must be the root node /, and the address space visible
	through the CCI interconnect is the same as the one seen from the
	root node (ie from CPUs perspective as per DT standard).
	Every CCI node has to define the following properties:

	- compatible
		Usage: required
		Value type: <string>
		Definition: must be set to
			    "arm,cci-400"

	- reg
		Usage: required
		Value type: Integer cells. A register entry, expressed as a pair
			    of cells, containing base and size.
		Definition: A standard property. Specifies base physical
			    address of CCI control registers common to all
			    interfaces.

	- ranges:
		Usage: required
		Value type: Integer cells. An array of range entries, expressed
			    as a tuple of cells, containing child address,
			    parent address and the size of the region in the
			    child address space.
		Definition: A standard property. Follow rules in the ePAPR for
			    hierarchical bus addressing. CCI interfaces
			    addresses refer to the parent node addressing
			    scheme to declare their register bases.

	CCI interconnect node can define the following child nodes:

	- CCI control interface nodes

		Node name must be "slave-if".
		Parent node must be CCI interconnect node.

		A CCI control interface node must contain the following
		properties:

		- compatible
			Usage: required
			Value type: <string>
			Definition: must be set to
				    "arm,cci-400-ctrl-if"

		- interface-type:
			Usage: required
			Value type: <string>
			Definition: must be set to one of {"ace", "ace-lite"}
				    depending on the interface type the node
				    represents.

		- reg:
			Usage: required
			Value type: Integer cells. A register entry, expressed
				    as a pair of cells, containing base and
				    size.
			Definition: the base address and size of the
				    corresponding interface programming
				    registers.

	- CCI PMU node

		Parent node must be CCI interconnect node.

		A CCI pmu node must contain the following properties:

		- compatible
			Usage: required
			Value type: <string>
			Definition: must be "arm,cci-400-pmu"

		- reg:
			Usage: required
			Value type: Integer cells. A register entry, expressed
				    as a pair of cells, containing base and
				    size.
			Definition: the base address and size of the
				    corresponding interface programming
				    registers.

		- interrupts:
			Usage: required
			Value type: Integer cells. Array of interrupt specifier
				    entries, as defined in
				    ../interrupt-controller/interrupts.txt.
			Definition: list of counter overflow interrupts, one per
				    counter. The interrupts must be specified
				    starting with the cycle counter overflow
				    interrupt, followed by counter0 overflow
				    interrupt, counter1 overflow interrupt,...
				    ,counterN overflow interrupt.

				    The CCI PMU has an interrupt signal for each
				    counter. The number of interrupts must be
				    equal to the number of counters.

* CCI interconnect bus masters

	Description: masters in the device tree connected to a CCI port
		     (inclusive of CPUs and their cpu nodes).

	A CCI interconnect bus master node must contain the following
	properties:

	- cci-control-port:
		Usage: required
		Value type: <phandle>
		Definition: a phandle containing the CCI control interface node
			    the master is connected to.

Example:

	cpus {
		#size-cells = <0>;
		#address-cells = <1>;

		CPU0: cpu@0 {
			device_type = "cpu";
			compatible = "arm,cortex-a15";
			cci-control-port = <&cci_control1>;
			reg = <0x0>;
		};

		CPU1: cpu@1 {
			device_type = "cpu";
			compatible = "arm,cortex-a15";
			cci-control-port = <&cci_control1>;
			reg = <0x1>;
		};

		CPU2: cpu@100 {
			device_type = "cpu";
			compatible = "arm,cortex-a7";
			cci-control-port = <&cci_control2>;
			reg = <0x100>;
		};

		CPU3: cpu@101 {
			device_type = "cpu";
			compatible = "arm,cortex-a7";
			cci-control-port = <&cci_control2>;
			reg = <0x101>;
		};

	};

	dma0: dma@3000000 {
		compatible = "arm,pl330", "arm,primecell";
		cci-control-port = <&cci_control0>;
		reg = <0x0 0x3000000 0x0 0x1000>;
		interrupts = <10>;
		#dma-cells = <1>;
		#dma-channels = <8>;
		#dma-requests = <32>;
	};

	cci@2c090000 {
		compatible = "arm,cci-400";
		#address-cells = <1>;
		#size-cells = <1>;
		reg = <0x0 0x2c090000 0 0x1000>;
		ranges = <0x0 0x0 0x2c090000 0x10000>;

		cci_control0: slave-if@1000 {
			compatible = "arm,cci-400-ctrl-if";
			interface-type = "ace-lite";
			reg = <0x1000 0x1000>;
		};

		cci_control1: slave-if@4000 {
			compatible = "arm,cci-400-ctrl-if";
			interface-type = "ace";
			reg = <0x4000 0x1000>;
		};

		cci_control2: slave-if@5000 {
			compatible = "arm,cci-400-ctrl-if";
			interface-type = "ace";
			reg = <0x5000 0x1000>;
		};

		pmu@9000 {
			 compatible = "arm,cci-400-pmu";
			 reg = <0x9000 0x5000>;
			 interrupts = <0 101 4>,
				      <0 102 4>,
				      <0 103 4>,
				      <0 104 4>,
				      <0 105 4>;
		};
	};

This CCI node corresponds to a CCI component whose control registers sits
at address 0x000000002c090000.
CCI slave interface @0x000000002c091000 is connected to dma controller dma0.
CCI slave interface @0x000000002c094000 is connected to CPUs {CPU0, CPU1};
CCI slave interface @0x000000002c095000 is connected to CPUs {CPU2, CPU3};
Commit	Line	Data
ed69bdd8 LP	1	=======================================================
	2	ARM CCI cache coherent interconnect binding description
	3	=======================================================
	4
	5	ARM multi-cluster systems maintain intra-cluster coherency through a
	6	cache coherent interconnect (CCI) that is capable of monitoring bus
	7	transactions and manage coherency, TLB invalidations and memory barriers.
	8
	9	It allows snooping and distributed virtual memory message broadcast across
	10	clusters, through memory mapped interface, with a global control register
	11	space and multiple sets of interface control registers, one per slave
	12	interface.
	13
	14	Bindings for the CCI node follow the ePAPR standard, available from:
	15
	16	www.power.org/documentation/epapr-version-1-1/
	17
	18	with the addition of the bindings described in this document which are
	19	specific to ARM.
	20
	21	* CCI interconnect node
	22
	23	Description: Describes a CCI cache coherent Interconnect component
	24
	25	Node name must be "cci".
	26	Node's parent must be the root node /, and the address space visible
	27	through the CCI interconnect is the same as the one seen from the
	28	root node (ie from CPUs perspective as per DT standard).
	29	Every CCI node has to define the following properties:
	30
	31	- compatible
	32	Usage: required
	33	Value type: <string>
	34	Definition: must be set to
	35	"arm,cci-400"
	36
	37	- reg
	38	Usage: required
fcb20f15 PA	39	Value type: Integer cells. A register entry, expressed as a pair
fcb20f15 PA	40	of cells, containing base and size.
ed69bdd8 LP	41	Definition: A standard property. Specifies base physical
	42	address of CCI control registers common to all
	43	interfaces.
	44
	45	- ranges:
	46	Usage: required
fcb20f15 PA	47	Value type: Integer cells. An array of range entries, expressed
	48	as a tuple of cells, containing child address,
	49	parent address and the size of the region in the
	50	child address space.
ed69bdd8 LP	51	Definition: A standard property. Follow rules in the ePAPR for
	52	hierarchical bus addressing. CCI interfaces
	53	addresses refer to the parent node addressing
	54	scheme to declare their register bases.
	55
	56	CCI interconnect node can define the following child nodes:
	57
	58	- CCI control interface nodes
	59
	60	Node name must be "slave-if".
	61	Parent node must be CCI interconnect node.
	62
	63	A CCI control interface node must contain the following
	64	properties:
	65
	66	- compatible
	67	Usage: required
	68	Value type: <string>
	69	Definition: must be set to
	70	"arm,cci-400-ctrl-if"
	71
	72	- interface-type:
	73	Usage: required
	74	Value type: <string>
	75	Definition: must be set to one of {"ace", "ace-lite"}
	76	depending on the interface type the node
	77	represents.
	78
	79	- reg:
	80	Usage: required
fcb20f15 PA	81	Value type: Integer cells. A register entry, expressed
	82	as a pair of cells, containing base and
	83	size.
ed69bdd8 LP	84	Definition: the base address and size of the
	85	corresponding interface programming
	86	registers.
	87
83bc10a2 PA	88	- CCI PMU node
	89
	90	Parent node must be CCI interconnect node.
	91
	92	A CCI pmu node must contain the following properties:
	93
	94	- compatible
	95	Usage: required
	96	Value type: <string>
	97	Definition: must be "arm,cci-400-pmu"
	98
	99	- reg:
	100	Usage: required
	101	Value type: Integer cells. A register entry, expressed
	102	as a pair of cells, containing base and
	103	size.
	104	Definition: the base address and size of the
	105	corresponding interface programming
	106	registers.
	107
	108	- interrupts:
	109	Usage: required
	110	Value type: Integer cells. Array of interrupt specifier
	111	entries, as defined in
	112	../interrupt-controller/interrupts.txt.
	113	Definition: list of counter overflow interrupts, one per
	114	counter. The interrupts must be specified
	115	starting with the cycle counter overflow
	116	interrupt, followed by counter0 overflow
	117	interrupt, counter1 overflow interrupt,...
	118	,counterN overflow interrupt.
	119
	120	The CCI PMU has an interrupt signal for each
	121	counter. The number of interrupts must be
	122	equal to the number of counters.
	123
ed69bdd8 LP	124	* CCI interconnect bus masters
	125
	126	Description: masters in the device tree connected to a CCI port
	127	(inclusive of CPUs and their cpu nodes).
	128
	129	A CCI interconnect bus master node must contain the following
	130	properties:
	131
	132	- cci-control-port:
	133	Usage: required
	134	Value type: <phandle>
	135	Definition: a phandle containing the CCI control interface node
	136	the master is connected to.
	137
	138	Example:
	139
	140	cpus {
	141	#size-cells = <0>;
	142	#address-cells = <1>;
	143
	144	CPU0: cpu@0 {
	145	device_type = "cpu";
	146	compatible = "arm,cortex-a15";
	147	cci-control-port = <&cci_control1>;
	148	reg = <0x0>;
	149	};
	150
	151	CPU1: cpu@1 {
	152	device_type = "cpu";
	153	compatible = "arm,cortex-a15";
	154	cci-control-port = <&cci_control1>;
	155	reg = <0x1>;
	156	};
	157
	158	CPU2: cpu@100 {
	159	device_type = "cpu";
	160	compatible = "arm,cortex-a7";
	161	cci-control-port = <&cci_control2>;
	162	reg = <0x100>;
	163	};
	164
	165	CPU3: cpu@101 {
	166	device_type = "cpu";
	167	compatible = "arm,cortex-a7";
	168	cci-control-port = <&cci_control2>;
	169	reg = <0x101>;
	170	};
	171
	172	};
	173
	174	dma0: dma@3000000 {
	175	compatible = "arm,pl330", "arm,primecell";
	176	cci-control-port = <&cci_control0>;
	177	reg = <0x0 0x3000000 0x0 0x1000>;
	178	interrupts = <10>;
	179	#dma-cells = <1>;
	180	#dma-channels = <8>;
	181	#dma-requests = <32>;
	182	};
	183
	184	cci@2c090000 {
	185	compatible = "arm,cci-400";
	186	#address-cells = <1>;
	187	#size-cells = <1>;
188	reg = <0x0 0x2c090000 0 0x1000>;
83bc10a2	189	ranges = <0x0 0x0 0x2c090000 0x10000>;
ed69bdd8 LP	190
	191	cci_control0: slave-if@1000 {
	192	compatible = "arm,cci-400-ctrl-if";
	193	interface-type = "ace-lite";
	194	reg = <0x1000 0x1000>;
	195	};
	196
	197	cci_control1: slave-if@4000 {
	198	compatible = "arm,cci-400-ctrl-if";
	199	interface-type = "ace";
	200	reg = <0x4000 0x1000>;
	201	};
	202
	203	cci_control2: slave-if@5000 {
	204	compatible = "arm,cci-400-ctrl-if";
	205	interface-type = "ace";
	206	reg = <0x5000 0x1000>;
	207	};
83bc10a2 PA	208
	209	pmu@9000 {
	210	compatible = "arm,cci-400-pmu";
	211	reg = <0x9000 0x5000>;
	212	interrupts = <0 101 4>,
	213	<0 102 4>,
	214	<0 103 4>,
	215	<0 104 4>,
	216	<0 105 4>;
	217	};
ed69bdd8 LP	218	};
	219
	220	This CCI node corresponds to a CCI component whose control registers sits
	221	at address 0x000000002c090000.
	222	CCI slave interface @0x000000002c091000 is connected to dma controller dma0.
	223	CCI slave interface @0x000000002c094000 is connected to CPUs {CPU0, CPU1};
	224	CCI slave interface @0x000000002c095000 is connected to CPUs {CPU2, CPU3};