FreeBSD/Linux Kernel Cross Reference
sys/contrib/device-tree/Bindings/mailbox/omap-mailbox.txt

     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.
    The AM64x SoCS also uses a single IP block comprising of multiple clusters,
    but the number of clusters are smaller, and the interrupt output lines are
    connected directly to various processors.
    
    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
                                "ti,am64-mailbox" for K3 AM64x 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>;
                           };
                   };
           };
   };

Cache object: 69e6697e2d9c7dab7e901a2fab17c269