1OMAP2+ and K3 Mailbox 2===================== 3 4The OMAP mailbox hardware facilitates communication between different processors 5using a queued mailbox interrupt mechanism. The IP block is external to the 6various processor subsystems and is connected on an interconnect bus. The 7communication is achieved through a set of registers for message storage and 8interrupt configuration registers. 9 10Each mailbox IP block/cluster has a certain number of h/w fifo queues and output 11interrupt lines. An output interrupt line is routed to an interrupt controller 12within a processor subsystem, and there can be more than one line going to a 13specific processor's interrupt controller. The interrupt line connections are 14fixed for an instance and are dictated by the IP integration into the SoC 15(excluding the SoCs that have a Interrupt Crossbar IP). Each interrupt line is 16programmable through a set of interrupt configuration registers, and have a rx 17and tx interrupt source per h/w fifo. Communication between different processors 18is achieved through the appropriate programming of the rx and tx interrupt 19sources on the appropriate interrupt lines. 20 21The number of h/w fifo queues and interrupt lines dictate the usable registers. 22All the current OMAP SoCs except for the newest DRA7xx SoC has a single IP 23instance. DRA7xx has multiple instances with different number of h/w fifo queues 24and interrupt lines between different instances. The interrupt lines can also be 25routed to different processor sub-systems on DRA7xx as they are routed through 26the Crossbar, a kind of interrupt router/multiplexer. The K3 AM65x and J721E 27SoCs has each of these instances form a cluster and combine multiple clusters 28into a single IP block present within the Main NavSS. The interrupt lines from 29all these clusters are multiplexed and routed to different processor subsystems 30over a limited number of common interrupt output lines of an Interrupt Router. 31 32Mailbox Device Node: 33==================== 34A Mailbox device node is used to represent a Mailbox IP instance/cluster within 35a SoC. The sub-mailboxes are represented as child nodes of this parent node. 36 37Required properties: 38-------------------- 39- compatible: Should be one of the following, 40 "ti,omap2-mailbox" for OMAP2420, OMAP2430 SoCs 41 "ti,omap3-mailbox" for OMAP3430, OMAP3630 SoCs 42 "ti,omap4-mailbox" for OMAP44xx, OMAP54xx, AM33xx, 43 AM43xx and DRA7xx SoCs 44 "ti,am654-mailbox" for K3 AM65x and J721E SoCs 45- reg: Contains the mailbox register address range (base 46 address and length) 47- interrupts: Contains the interrupt information for the mailbox 48 device. The format is dependent on which interrupt 49 controller the Mailbox device uses 50- #mbox-cells: Common mailbox binding property to identify the number 51 of cells required for the mailbox specifier. Should be 52 1 53- ti,mbox-num-users: Number of targets (processor devices) that the mailbox 54 device can interrupt 55- ti,mbox-num-fifos: Number of h/w fifo queues within the mailbox IP block 56 57SoC-specific Required properties: 58--------------------------------- 59The following are mandatory properties for the OMAP architecture based SoCs 60only: 61- ti,hwmods: Name of the hwmod associated with the mailbox. This 62 should be defined in the mailbox node only if the node 63 is not defined as a child node of a corresponding sysc 64 interconnect node. 65 66The following are mandatory properties for the K3 AM65x and J721E SoCs only: 67- interrupt-parent: Should contain a phandle to the TI-SCI interrupt 68 controller node that is used to dynamically program 69 the interrupt routes between the IP and the main GIC 70 controllers. See the following binding for additional 71 details, 72 Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.yaml 73 74Child Nodes: 75============ 76A child node is used for representing the actual sub-mailbox device that is 77used for the communication between the host processor and a remote processor. 78Each child node should have a unique node name across all the different 79mailbox device nodes. 80 81Required properties: 82-------------------- 83- ti,mbox-tx: sub-mailbox descriptor property defining a Tx fifo 84- ti,mbox-rx: sub-mailbox descriptor property defining a Rx fifo 85 86Sub-mailbox Descriptor Data 87--------------------------- 88Each of the above ti,mbox-tx and ti,mbox-rx properties should have 3 cells of 89data that represent the following: 90 Cell #1 (fifo_id) - mailbox fifo id used either for transmitting 91 (ti,mbox-tx) or for receiving (ti,mbox-rx) 92 Cell #2 (irq_id) - irq identifier index number to use from the parent's 93 interrupts data. Should be 0 for most of the cases, a 94 positive index value is seen only on mailboxes that have 95 multiple interrupt lines connected to the MPU processor. 96 Cell #3 (usr_id) - mailbox user id for identifying the interrupt line 97 associated with generating a tx/rx fifo interrupt. 98 99Optional Properties: 100-------------------- 101- ti,mbox-send-noirq: Quirk flag to allow the client user of this sub-mailbox 102 to send messages without triggering a Tx ready interrupt, 103 and to control the Tx ticker. Should be used only on 104 sub-mailboxes used to communicate with WkupM3 remote 105 processor on AM33xx/AM43xx SoCs. 106 107Mailbox Users: 108============== 109A device needing to communicate with a target processor device should specify 110them using the common mailbox binding properties, "mboxes" and the optional 111"mbox-names" (please see Documentation/devicetree/bindings/mailbox/mailbox.txt 112for details). Each value of the mboxes property should contain a phandle to the 113mailbox controller device node and an args specifier that will be the phandle to 114the intended sub-mailbox child node to be used for communication. The equivalent 115"mbox-names" property value can be used to give a name to the communication channel 116to be used by the client user. 117 118 119Example: 120-------- 121 1221. /* OMAP4 */ 123mailbox: mailbox@4a0f4000 { 124 compatible = "ti,omap4-mailbox"; 125 reg = <0x4a0f4000 0x200>; 126 interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>; 127 ti,hwmods = "mailbox"; 128 #mbox-cells = <1>; 129 ti,mbox-num-users = <3>; 130 ti,mbox-num-fifos = <8>; 131 mbox_ipu: mbox_ipu { 132 ti,mbox-tx = <0 0 0>; 133 ti,mbox-rx = <1 0 0>; 134 }; 135 mbox_dsp: mbox_dsp { 136 ti,mbox-tx = <3 0 0>; 137 ti,mbox-rx = <2 0 0>; 138 }; 139}; 140 141dsp { 142 ... 143 mboxes = <&mailbox &mbox_dsp>; 144 ... 145}; 146 1472. /* AM33xx */ 148mailbox: mailbox@480c8000 { 149 compatible = "ti,omap4-mailbox"; 150 reg = <0x480C8000 0x200>; 151 interrupts = <77>; 152 ti,hwmods = "mailbox"; 153 #mbox-cells = <1>; 154 ti,mbox-num-users = <4>; 155 ti,mbox-num-fifos = <8>; 156 mbox_wkupm3: wkup_m3 { 157 ti,mbox-tx = <0 0 0>; 158 ti,mbox-rx = <0 0 3>; 159 }; 160}; 161 1623. /* AM65x */ 163&cbass_main { 164 cbass_main_navss: interconnect0 { 165 mailbox0_cluster0: mailbox@31f80000 { 166 compatible = "ti,am654-mailbox"; 167 reg = <0x00 0x31f80000 0x00 0x200>; 168 #mbox-cells = <1>; 169 ti,mbox-num-users = <4>; 170 ti,mbox-num-fifos = <16>; 171 interrupt-parent = <&intr_main_navss>; 172 interrupts = <164 0>; 173 174 mbox_mcu_r5fss0_core0: mbox-mcu-r5fss0-core0 { 175 ti,mbox-tx = <1 0 0>; 176 ti,mbox-rx = <0 0 0>; 177 }; 178 }; 179 }; 180}; 181