PRU-ICSS on TI SoCs
===================

Binding status: Unstable - Subject to changes to account for all sub-modules

The Programmable Real-Time Unit and Industrial Communication Subsystem
(PRU-ICSS) is present on various TI SoCs such as AM335x or AM437x. A
PRUSS consists of dual 32-bit RISC cores (Programmable Real-Time Units,
or PRUs), shared RAM, data and instruction RAMs, some internal peripheral
modules to facilitate industrial communication, and an interrupt controller.
The programmable nature of the PRUs provide flexibility to implement custom
peripheral interfaces, fast real-time responses, or specialized data handling.
The common peripheral modules include the following,
  - an Ethernet MII_RT module with two MII ports
  - an MDIO port to control external Ethernet PHYs
  - an Industrial Ethernet Peripheral (IEP) to manage/generate Industrial
    Ethernet functions
  - an Enhanced Capture Module (eCAP)
  - an Industrial Ethernet Timer with 7/9 capture and 16 compare events
  - a 16550-compatible UART to support PROFIBUS

A PRU-ICSS subsystem can have up to three shared data memories. A PRU core
acts on a primary Data RAM (there are usually 2 Data RAMs) at its address
0x0, but also has access to a secondary Data RAM (primary to the other PRU
core) at its address 0x2000. A shared Data RAM, if present, can be accessed
by both the PRU cores. The Interrupt Controller (INTC) and a CFG module are
common to both the PRU cores. Each PRU core also has a private instruction RAM,
and specific register spaces for Control and Debug functionalities.

PRU-ICSS SYSCFG wrapper Parent Node
====================================
This node is _required only_ for AM437x SoCs due to the chained SYSCFG
integration. The PRU-ICSS parent nodes are defined as child nodes of
this node on AM437x SoCs in addition to the following properties.

Required Properties:
--------------------
- compatible     : should be,
                       "ti,am4372-pruss-wrapper" for AM437x family of SoCs
- ti,hwmods      : name of the hwmod associated with the PRUSS instance
- reg            : base address and size of the PRUSS1 CFG sub-module
- #address-cells : should be 1
- #size-cells    : should be 1
- ranges         : no specific range translations required, child nodes have the
                   same address view as the parent, so should be mentioned without
                   any value for the property


PRU-ICSS Parent Node
=====================
Each PRU-ICSS subsystem instance is represented as a node with
the individual PRU processor cores, an INTC node and an MDIO node
represented as child nodes within the parent PRUSS node.

Required Properties:
--------------------
- compatible     : should be one of,
                       "ti,am3352-pruss" for AM335x family of SoCs
                       "ti,am4372-pruss" for AM437x family of SoCs
                       "ti,am5728-pruss" for AM57xx family of SoCs
                       "ti,k2g-pruss" for K2G SoC
- ti,hwmods      : name of the hwmod associated with the PRUSS instance
                   (does not apply for AM437x and K2G SoCs)
- reg            : base address and size for each of the sub-modules as
                   mentioned in reg-names, and in the same order as the
                   reg-names
- reg-names      : should contain a string from among the following names,
                   each representing a specific sub-module. A PRU-ICSS may
                   not have all of the Data RAMs. The binding is agnostic
                   of the order of these reg-names
                       "dram0" for Data RAM0,
                       "dram1" for Data RAM1,
                       "shrdram2" for Shared Data RAM,
                       "cfg" for CFG sub-module,
                       "iep" for IEP sub-module,
                       "mii_rt" for MII-RT sub-module,
- #address-cells : should be 1
- #size-cells    : should be 1
- ranges         : no specific range translations required, child nodes have the
                   same address view as the parent, so should be mentioned without
                   any value for the property


PRUSS INTC Child Node
======================
Each PRUSS has a single interrupt controller instance that is common to both
the PRU cores. Each interrupt controller can detect 64 input events which are
then mapped to 10 possible output interrupts through two levels of mapping. The
input events can be triggered by either the PRUs and/or various other PRUSS
internal and external peripherals.  The first 2 output interrupts are fed
exclusively to the internal PRU cores, with the remaining 8 connected to
external interrupt controllers including the MPU.

Required Properties:
--------------------
- compatible           : should be one of,
                             "ti,am3352-pruss-intc" for AM335x family of SoCs
                             "ti,am4372-pruss-intc" for AM437x family of SoCs
                             "ti,am5728-pruss-intc" for AM57xx family of SoCs
                             "ti,k2g-pruss-intc" for K2G SoC
- reg                  : base address and size for the PRUSS INTC sub-module
- reg-names            : should contain the string "intc"
- interrupts           : all the interrupts generated towards the main host
                         processor in the SoC. The format depends on the
                         interrupt specifier for the particular SoC's MPU
                         parent interrupt controller
- interrupt-names      : should use one of the following names for each
                         interrupt, the name should match the corresponding
                         host interrupt number,
                             "host2", "host3", "host4", "host5", "host6",
                             "host7", "host8" or "host9"
                         NOTE: AM437x and K2G SoCs do not have "host7" interrupt
                               connected to MPU
- interrupt-controller : mark this node as an interrupt controller
- #interrupt-cells     : should be 1. Client users shall use the PRU System
                         event number (the interrupt source that the client
                         is interested in) as the value of the interrupts
                         property in their node


PRU Child Node
===============
Each PRUSS has dual PRU cores, each represented by a PRU child node. Each node
can optionally be rendered inactive by using the standard DT string property,
"status".

Each PRU child node must either be named "pru0" or "pru1", for the first and
and second PRUs respectively.

Required Properties:
--------------------
- compatible     : should be
                       "ti,am3352-pru" for AM335x family of SoCs
                       "ti,am4372-pru" for AM437x family of SoCs
                       "ti,am5728-pru" for AM57xx family of SoCs
                       "ti,k2g-pru" for K2G SoC
- reg            : base address and size for each of the 3 sub-module address
                   spaces as mentioned in reg-names, and in the same order as
                   the reg-names
- reg-names      : should contain each of the following 3 names, with the "iram"
                   entry being the first one
                       "iram" for Instruction RAM,
                       "control" for the CTRL sub-module registers,
                       "debug" for the Debug sub-module registers,

Optional Properties:
--------------------
The virtio based communication between the MPU and a PRU core _requires_
either the 'mboxes' property to be defined, or the set of 'interrupt-parent',
'interrupts' and 'interrupt-names' properties to be defined. The 'mboxes'
property is not applicable for K2G SoC.

- mboxes           : OMAP Mailbox specifier denoting the sub-mailbox, if using
                     a mailbox for IPC signalling between host and a PRU core.
                     The specifier format is as per the bindings,
                         Documentation/devicetree/bindings/mailbox/omap-mailbox.txt
                     This property should match with the sub-mailbox node used
                     in the corresponding firmware image.
- interrupt-parent : phandle to the PRUSS INTC node. Should be defined if
                     interrupts property is to be used.
- interrupts       : array of interrupt specifiers if using PRU system events
                     for IPC signalling between host and a PRU core. This
                     property should match with the PRU system event used in
                     the corresponding firmware image.
- interrupt-names  : should use one of the following names for each interrupt,
                     the name should match the corresponding PRU system event
                     number,
                         "vring" - for PRU to HOST virtqueue signalling
                         "kick"  - for HOST to PRU virtqueue signalling
- ti,pruss-gp-mux-sel : integer value of the GP MUX mode needed by an
                        application to be run on a PRU. Currently to be used
                        _only_ for PRU Ethernet usecase on AM571x IDK board
                        and K2G ICE EVM boards.

MDIO Child Node
================
Each PRUSS has an MDIO module that can be used to control external PHYs. The
MDIO module used within the PRU-ICSS is an instance of the MDIO Controller
used in TI Davinci SoCs. Please refer to the corresponding binding document,
Documentation/devicetree/bindings/net/davinci-mdio.txt for details.


Application/User Nodes
=======================
The PRUSS device node will typically get used by application/user nodes that
define/represent a PRU application. Each application/client node would need a
reference to the PRUSS node or directly the PRU nodes in general.

Optional Properties:
--------------------
- pruss          : phandle to a PRUSS node


Example:
========
1.	/* AM33xx PRU-ICSS */
	pruss: pruss@4a300000 {
		compatible = "ti,am3352-pruss";
		ti,hwmods = "pruss";
		reg = <0x4a300000 0x2000>,
		      <0x4a302000 0x2000>,
		      <0x4a310000 0x3000>,
		      <0x4a326000 0x2000>,
		      <0x4a32e000 0x31c>,
		      <0x4a332000 0x58>;
		reg-names = "dram0", "dram1", "shrdram2", "cfg",
			    "iep", "mii_rt";
		#address-cells = <1>;
		#size-cells = <1>;
		ranges;

		pruss_intc: intc@4a320000 {
			compatible = "ti,am3352-pruss-intc";
			reg = <0x4a320000 0x2000>;
			reg-names = "intc";
			interrupts = <20 21 22 23 24 25 26 27>;
			interrupt-names = "host2", "host3", "host4",
					  "host5", "host6", "host7",
					  "host8", "host9";
			interrupt-controller;
			#interrupt-cells = <1>;
		};

		pru0: pru0@4a334000 {
			compatible = "ti,am3352-pru";
			reg = <0x4a334000 0x2000>,
			      <0x4a322000 0x400>,
			      <0x4a322400 0x100>;
			reg-names = "iram", "control", "debug";
			mboxes = <&mailbox &mbox_pru0>;
		};

		pru1: pru1@4a338000 {
			compatible = "ti,am3352-pru";
			reg = <0x4a338000 0x2000>,
			      <0x4a324000 0x400>,
			      <0x4a324400 0x100>;
			reg-names = "iram", "control", "debug";
			interrupt-parent = <&pruss_intc>;
			interrupts = <18>, <19>;
			interrupt-names = "vring", "kick";
		};

		pruss_mdio: mdio@4a332400 {
			compatible = "ti,davinci_mdio";
			reg = <0x4a332400 0x90>;
			clocks = <&dpll_core_m4_ck>;
			clock-names = "fck";
			bus_freq = <1000000>;
			#address-cells = <1>;
			#size-cells = <0>;
		};
	};

2.	/* AM43xx PRU-ICSS with PRUSS1 node (PRUSS0 not shown) */
	pruss_wrapper: pruss_wrapper@54426000 {
		compatible = "ti,am4372-pruss-wrapper";
		reg = <0x54426000 0x2000>;
		ti,hwmods = "pruss";
		#address-cells = <1>;
		#size-cells = <1>;
		ranges;

		pruss1: pruss@54400000 {
			compatible = "ti,am4372-pruss";
			reg = <0x54400000 0x2000>,
			      <0x54402000 0x2000>,
			      <0x54410000 0x8000>,
			      <0x54426000 0x2000>,
			      <0x5442e000 0x31c>,
			      <0x54432000 0x58>;
			reg-names = "dram0", "dram1", "shrdram2", "cfg",
				    "iep", "mii_rt";
			#address-cells = <1>;
			#size-cells = <1>;
			ranges;

			pruss1_intc: intc@54420000 {
				compatible = "ti,am4372-pruss-intc";
				reg = <0x54420000 0x2000>;
				reg-names = "intc";
				interrupts =
				    <GIC_SPI 20 IRQ_TYPE_LEVEL_HIGH
				     GIC_SPI 21 IRQ_TYPE_LEVEL_HIGH
				     GIC_SPI 22 IRQ_TYPE_LEVEL_HIGH
				     GIC_SPI 23 IRQ_TYPE_LEVEL_HIGH
				     GIC_SPI 24 IRQ_TYPE_LEVEL_HIGH
				     GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH
				     GIC_SPI 27 IRQ_TYPE_LEVEL_HIGH>;
				interrupt-names = "host2", "host3",
						  "host4", "host5",
						  "host6", "host8",
						  "host9";
				interrupt-controller;
				#interrupt-cells = <1>;
			};

			pru1_0: pru0@54434000 {
				compatible = "ti,am4372-pru";
				reg = <0x54434000 0x3000>,
				      <0x54422000 0x400>,
				      <0x54422400 0x100>;
				reg-names = "iram", "control", "debug";
				interrupt-parent = <&pruss1_intc>;
				interrupts = <16>, <17>;
				interrupt-names = "vring", "kick";
			};

			pru1_1: pru1@54438000 {
				compatible = "ti,am4372-pru";
				reg = <0x54438000 0x3000>,
				      <0x54424000 0x400>,
				      <0x54424400 0x100>;
				reg-names = "iram", "control", "debug";
				interrupt-parent = <&pruss1_intc>;
				interrupts = <18>, <19>;
				interrupt-names = "vring", "kick";
			};

			pruss1_mdio: mdio@54432400 {
				compatible = "ti,davinci_mdio";
				reg = <0x54432400 0x90>;
				clocks = <&dpll_core_m4_ck>;
				clock-names = "fck";
				bus_freq = <1000000>;
				#address-cells = <1>;
				#size-cells = <0>;
				status = "disabled";
			};
		};
	};