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.txt 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 = ; 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>; }; }; }; };