summaryrefslogtreecommitdiffstats
path: root/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/devicetree/bindings/mailbox/omap-mailbox.txt')
-rw-r--r--Documentation/devicetree/bindings/mailbox/omap-mailbox.txt180
1 files changed, 180 insertions, 0 deletions
diff --git a/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt
new file mode 100644
index 000000000..5fe80c1c1
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt
@@ -0,0 +1,180 @@
+OMAP2+ and K3 Mailbox
+=====================
+
+The OMAP mailbox hardware facilitates communication between different processors
+using a queued mailbox interrupt mechanism. The IP block is external to the
+various processor subsystems and is connected on an interconnect bus. The
+communication is achieved through a set of registers for message storage and
+interrupt configuration registers.
+
+Each mailbox IP block/cluster has a certain number of h/w fifo queues and output
+interrupt lines. An output interrupt line is routed to an interrupt controller
+within a processor subsystem, and there can be more than one line going to a
+specific processor's interrupt controller. The interrupt line connections are
+fixed for an instance and are dictated by the IP integration into the SoC
+(excluding the SoCs that have a Interrupt Crossbar IP). Each interrupt line is
+programmable through a set of interrupt configuration registers, and have a rx
+and tx interrupt source per h/w fifo. Communication between different processors
+is achieved through the appropriate programming of the rx and tx interrupt
+sources on the appropriate interrupt lines.
+
+The number of h/w fifo queues and interrupt lines dictate the usable registers.
+All the current OMAP SoCs except for the newest DRA7xx SoC has a single IP
+instance. DRA7xx has multiple instances with different number of h/w fifo queues
+and interrupt lines between different instances. The interrupt lines can also be
+routed to different processor sub-systems on DRA7xx as they are routed through
+the Crossbar, a kind of interrupt router/multiplexer. The K3 AM65x and J721E
+SoCs has each of these instances form a cluster and combine multiple clusters
+into a single IP block present within the Main NavSS. The interrupt lines from
+all these clusters are multiplexed and routed to different processor subsystems
+over a limited number of common interrupt output lines of an Interrupt Router.
+
+Mailbox Device Node:
+====================
+A Mailbox device node is used to represent a Mailbox IP instance/cluster within
+a SoC. The sub-mailboxes are represented as child nodes of this parent node.
+
+Required properties:
+--------------------
+- compatible: Should be one of the following,
+ "ti,omap2-mailbox" for OMAP2420, OMAP2430 SoCs
+ "ti,omap3-mailbox" for OMAP3430, OMAP3630 SoCs
+ "ti,omap4-mailbox" for OMAP44xx, OMAP54xx, AM33xx,
+ AM43xx and DRA7xx SoCs
+ "ti,am654-mailbox" for K3 AM65x and J721E SoCs
+- reg: Contains the mailbox register address range (base
+ address and length)
+- interrupts: Contains the interrupt information for the mailbox
+ device. The format is dependent on which interrupt
+ controller the Mailbox device uses
+- #mbox-cells: Common mailbox binding property to identify the number
+ of cells required for the mailbox specifier. Should be
+ 1
+- ti,mbox-num-users: Number of targets (processor devices) that the mailbox
+ device can interrupt
+- ti,mbox-num-fifos: Number of h/w fifo queues within the mailbox IP block
+
+SoC-specific Required properties:
+---------------------------------
+The following are mandatory properties for the OMAP architecture based SoCs
+only:
+- ti,hwmods: Name of the hwmod associated with the mailbox. This
+ should be defined in the mailbox node only if the node
+ is not defined as a child node of a corresponding sysc
+ interconnect node.
+
+The following are mandatory properties for the K3 AM65x and J721E SoCs only:
+- interrupt-parent: Should contain a phandle to the TI-SCI interrupt
+ controller node that is used to dynamically program
+ the interrupt routes between the IP and the main GIC
+ controllers. See the following binding for additional
+ details,
+ Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.yaml
+
+Child Nodes:
+============
+A child node is used for representing the actual sub-mailbox device that is
+used for the communication between the host processor and a remote processor.
+Each child node should have a unique node name across all the different
+mailbox device nodes.
+
+Required properties:
+--------------------
+- ti,mbox-tx: sub-mailbox descriptor property defining a Tx fifo
+- ti,mbox-rx: sub-mailbox descriptor property defining a Rx fifo
+
+Sub-mailbox Descriptor Data
+---------------------------
+Each of the above ti,mbox-tx and ti,mbox-rx properties should have 3 cells of
+data that represent the following:
+ Cell #1 (fifo_id) - mailbox fifo id used either for transmitting
+ (ti,mbox-tx) or for receiving (ti,mbox-rx)
+ Cell #2 (irq_id) - irq identifier index number to use from the parent's
+ interrupts data. Should be 0 for most of the cases, a
+ positive index value is seen only on mailboxes that have
+ multiple interrupt lines connected to the MPU processor.
+ Cell #3 (usr_id) - mailbox user id for identifying the interrupt line
+ associated with generating a tx/rx fifo interrupt.
+
+Optional Properties:
+--------------------
+- ti,mbox-send-noirq: Quirk flag to allow the client user of this sub-mailbox
+ to send messages without triggering a Tx ready interrupt,
+ and to control the Tx ticker. Should be used only on
+ sub-mailboxes used to communicate with WkupM3 remote
+ processor on AM33xx/AM43xx SoCs.
+
+Mailbox Users:
+==============
+A device needing to communicate with a target processor device should specify
+them using the common mailbox binding properties, "mboxes" and the optional
+"mbox-names" (please see Documentation/devicetree/bindings/mailbox/mailbox.txt
+for details). Each value of the mboxes property should contain a phandle to the
+mailbox controller device node and an args specifier that will be the phandle to
+the intended sub-mailbox child node to be used for communication. The equivalent
+"mbox-names" property value can be used to give a name to the communication channel
+to be used by the client user.
+
+
+Example:
+--------
+
+1. /* OMAP4 */
+mailbox: mailbox@4a0f4000 {
+ compatible = "ti,omap4-mailbox";
+ reg = <0x4a0f4000 0x200>;
+ interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>;
+ ti,hwmods = "mailbox";
+ #mbox-cells = <1>;
+ ti,mbox-num-users = <3>;
+ ti,mbox-num-fifos = <8>;
+ mbox_ipu: mbox_ipu {
+ ti,mbox-tx = <0 0 0>;
+ ti,mbox-rx = <1 0 0>;
+ };
+ mbox_dsp: mbox_dsp {
+ ti,mbox-tx = <3 0 0>;
+ ti,mbox-rx = <2 0 0>;
+ };
+};
+
+dsp {
+ ...
+ mboxes = <&mailbox &mbox_dsp>;
+ ...
+};
+
+2. /* AM33xx */
+mailbox: mailbox@480c8000 {
+ compatible = "ti,omap4-mailbox";
+ reg = <0x480C8000 0x200>;
+ interrupts = <77>;
+ ti,hwmods = "mailbox";
+ #mbox-cells = <1>;
+ ti,mbox-num-users = <4>;
+ ti,mbox-num-fifos = <8>;
+ mbox_wkupm3: wkup_m3 {
+ ti,mbox-tx = <0 0 0>;
+ ti,mbox-rx = <0 0 3>;
+ };
+};
+
+3. /* AM65x */
+&cbass_main {
+ cbass_main_navss: interconnect0 {
+ mailbox0_cluster0: mailbox@31f80000 {
+ compatible = "ti,am654-mailbox";
+ reg = <0x00 0x31f80000 0x00 0x200>;
+ #mbox-cells = <1>;
+ ti,mbox-num-users = <4>;
+ ti,mbox-num-fifos = <16>;
+ interrupt-parent = <&intr_main_navss>;
+ interrupts = <164 0>;
+
+ mbox_mcu_r5fss0_core0: mbox-mcu-r5fss0-core0 {
+ ti,mbox-tx = <1 0 0>;
+ ti,mbox-rx = <0 0 0>;
+ };
+ };
+ };
+};