1aa80be50SViresh Kumar# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) 2aa80be50SViresh Kumar%YAML 1.2 3aa80be50SViresh Kumar--- 4aa80be50SViresh Kumar$id: http://devicetree.org/schemas/mailbox/arm,mhuv2.yaml# 5aa80be50SViresh Kumar$schema: http://devicetree.org/meta-schemas/core.yaml# 6aa80be50SViresh Kumar 7aa80be50SViresh Kumartitle: ARM MHUv2 Mailbox Controller 8aa80be50SViresh Kumar 9aa80be50SViresh Kumarmaintainers: 10aa80be50SViresh Kumar - Tushar Khandelwal <tushar.khandelwal@arm.com> 11aa80be50SViresh Kumar - Viresh Kumar <viresh.kumar@linaro.org> 12aa80be50SViresh Kumar 13aa80be50SViresh Kumardescription: | 14aa80be50SViresh Kumar The Arm Message Handling Unit (MHU) Version 2 is a mailbox controller that has 15aa80be50SViresh Kumar between 1 and 124 channel windows (each 32-bit wide) to provide unidirectional 16aa80be50SViresh Kumar communication with remote processor(s), where the number of channel windows 17aa80be50SViresh Kumar are implementation dependent. 18aa80be50SViresh Kumar 19aa80be50SViresh Kumar Given the unidirectional nature of the controller, an MHUv2 mailbox may only 20aa80be50SViresh Kumar be written to or read from. If a pair of MHU controllers is implemented 21aa80be50SViresh Kumar between two processing elements to provide bidirectional communication, these 22aa80be50SViresh Kumar must be specified as two separate mailboxes. 23aa80be50SViresh Kumar 24aa80be50SViresh Kumar If the interrupts property is present in device tree node, then its treated as 25aa80be50SViresh Kumar a "receiver" mailbox, otherwise a "sender". 26aa80be50SViresh Kumar 27aa80be50SViresh Kumar An MHU controller must be specified along with the supported transport 28aa80be50SViresh Kumar protocols. The transport protocols determine the method of data transmission 29aa80be50SViresh Kumar as well as the number of provided mailbox channels. 30aa80be50SViresh Kumar 31aa80be50SViresh Kumar Following are the possible transport protocols. 32aa80be50SViresh Kumar 33aa80be50SViresh Kumar - Data-transfer: Each transfer is made of one or more words, using one or more 34aa80be50SViresh Kumar channel windows. 35aa80be50SViresh Kumar 36aa80be50SViresh Kumar - Doorbell: Each transfer is made up of single bit flag, using any one of the 37aa80be50SViresh Kumar bits in a channel window. A channel window can support up to 32 doorbells 38aa80be50SViresh Kumar and the entire window shall be used in doorbell protocol. Optionally, data 39aa80be50SViresh Kumar may be transmitted through a shared memory region, wherein the MHU is used 40aa80be50SViresh Kumar strictly as an interrupt generation mechanism but that is out of the scope 41aa80be50SViresh Kumar of these bindings. 42aa80be50SViresh Kumar 43aa80be50SViresh Kumar# We need a select here so we don't match all nodes with 'arm,primecell' 44aa80be50SViresh Kumarselect: 45aa80be50SViresh Kumar properties: 46aa80be50SViresh Kumar compatible: 47aa80be50SViresh Kumar contains: 48aa80be50SViresh Kumar enum: 49aa80be50SViresh Kumar - arm,mhuv2-tx 50aa80be50SViresh Kumar - arm,mhuv2-rx 51aa80be50SViresh Kumar required: 52aa80be50SViresh Kumar - compatible 53aa80be50SViresh Kumar 54aa80be50SViresh Kumarproperties: 55aa80be50SViresh Kumar compatible: 56aa80be50SViresh Kumar oneOf: 57aa80be50SViresh Kumar - description: Sender mode 58aa80be50SViresh Kumar items: 59aa80be50SViresh Kumar - const: arm,mhuv2-tx 60aa80be50SViresh Kumar - const: arm,primecell 61aa80be50SViresh Kumar 62aa80be50SViresh Kumar - description: Receiver-mode 63aa80be50SViresh Kumar items: 64aa80be50SViresh Kumar - const: arm,mhuv2-rx 65aa80be50SViresh Kumar - const: arm,primecell 66aa80be50SViresh Kumar 67aa80be50SViresh Kumar reg: 68aa80be50SViresh Kumar maxItems: 1 69aa80be50SViresh Kumar 70aa80be50SViresh Kumar interrupts: 71aa80be50SViresh Kumar description: | 72aa80be50SViresh Kumar The MHUv2 controller always implements an interrupt in the "receiver" 73aa80be50SViresh Kumar mode, while the interrupt in the "sender" mode was not available in the 74aa80be50SViresh Kumar version MHUv2.0, but the later versions do have it. 75aa80be50SViresh Kumar maxItems: 1 76aa80be50SViresh Kumar 77aa80be50SViresh Kumar clocks: 78aa80be50SViresh Kumar maxItems: 1 79aa80be50SViresh Kumar 80aa80be50SViresh Kumar clock-names: 81aa80be50SViresh Kumar maxItems: 1 82aa80be50SViresh Kumar 83aa80be50SViresh Kumar arm,mhuv2-protocols: 84aa80be50SViresh Kumar $ref: /schemas/types.yaml#/definitions/uint32-matrix 85aa80be50SViresh Kumar description: | 86aa80be50SViresh Kumar The MHUv2 controller may contain up to 124 channel windows (each 32-bit 87aa80be50SViresh Kumar wide). The hardware and the DT bindings allows any combination of those to 88aa80be50SViresh Kumar be used for various transport protocols. 89aa80be50SViresh Kumar 90aa80be50SViresh Kumar This property allows a platform to describe how these channel windows are 91aa80be50SViresh Kumar used in various transport protocols. The entries in this property shall be 92aa80be50SViresh Kumar present as an array of tuples, where each tuple describes details about 93aa80be50SViresh Kumar one of the transport protocol being implemented over some channel 94aa80be50SViresh Kumar window(s). 95aa80be50SViresh Kumar 96aa80be50SViresh Kumar The first field of a tuple signifies the transfer protocol, 0 is reserved 97aa80be50SViresh Kumar for doorbell protocol, and 1 is reserved for data-transfer protocol. 98aa80be50SViresh Kumar Using any other value in the first field of a tuple makes it invalid. 99aa80be50SViresh Kumar 100aa80be50SViresh Kumar The second field of a tuple signifies the number of channel windows where 101aa80be50SViresh Kumar the protocol would be used and should be set to a non zero value. For 102aa80be50SViresh Kumar doorbell protocol this field signifies the number of 32-bit channel 103aa80be50SViresh Kumar windows that implement the doorbell protocol. For data-transfer protocol, 104aa80be50SViresh Kumar this field signifies the number of 32-bit channel windows that implement 105aa80be50SViresh Kumar the data-transfer protocol. 106aa80be50SViresh Kumar 107aa80be50SViresh Kumar The total number of channel windows specified here shouldn't be more than 108aa80be50SViresh Kumar the ones implemented by the platform, though one can specify lesser number 109aa80be50SViresh Kumar of windows here than what the platform implements. 110aa80be50SViresh Kumar 111aa80be50SViresh Kumar mhu: mailbox@2b1f0000 { 112aa80be50SViresh Kumar ... 113aa80be50SViresh Kumar 114aa80be50SViresh Kumar arm,mhuv2-protocols = <0 2>, <1 1>, <1 5>, <1 7>; 115aa80be50SViresh Kumar } 116aa80be50SViresh Kumar 117aa80be50SViresh Kumar The above example defines the protocols of an ARM MHUv2 mailbox 118aa80be50SViresh Kumar controller, where a total of 15 channel windows are used. The first two 119aa80be50SViresh Kumar windows are used in doorbell protocol (64 doorbells), followed by 1, 5 and 120aa80be50SViresh Kumar 7 windows (separately) used in data-transfer protocol. 121aa80be50SViresh Kumar 122aa80be50SViresh Kumar minItems: 1 123aa80be50SViresh Kumar maxItems: 124 124aa80be50SViresh Kumar items: 125aa80be50SViresh Kumar items: 126aa80be50SViresh Kumar - enum: [ 0, 1 ] 127aa80be50SViresh Kumar - minimum: 0 128aa80be50SViresh Kumar maximum: 124 129aa80be50SViresh Kumar 130aa80be50SViresh Kumar 131aa80be50SViresh Kumar '#mbox-cells': 132aa80be50SViresh Kumar description: | 133aa80be50SViresh Kumar It is always set to 2. The first argument in the consumers 'mboxes' 134aa80be50SViresh Kumar property represents the channel window group, which may be used in 135aa80be50SViresh Kumar doorbell, or data-transfer protocol, and the second argument (only 136aa80be50SViresh Kumar relevant in doorbell protocol, should be 0 otherwise) represents the 137aa80be50SViresh Kumar doorbell number within the 32 bit wide channel window. 138aa80be50SViresh Kumar 139aa80be50SViresh Kumar From the example given above for arm,mhuv2-protocols, here is how a client 140aa80be50SViresh Kumar node can reference them. 141aa80be50SViresh Kumar 142aa80be50SViresh Kumar mboxes = <&mhu 0 5>; // Channel Window Group 0, doorbell 5. 143aa80be50SViresh Kumar mboxes = <&mhu 1 7>; // Channel Window Group 1, doorbell 7. 144aa80be50SViresh Kumar mboxes = <&mhu 2 0>; // Channel Window Group 2, data transfer protocol with 1 window. 145aa80be50SViresh Kumar mboxes = <&mhu 3 0>; // Channel Window Group 3, data transfer protocol with 5 windows. 146aa80be50SViresh Kumar mboxes = <&mhu 4 0>; // Channel Window Group 4, data transfer protocol with 7 windows. 147aa80be50SViresh Kumar 148aa80be50SViresh Kumar const: 2 149aa80be50SViresh Kumar 150aa80be50SViresh Kumarif: 151aa80be50SViresh Kumar # Interrupt is compulsory for receiver 152aa80be50SViresh Kumar properties: 153aa80be50SViresh Kumar compatible: 154aa80be50SViresh Kumar contains: 155aa80be50SViresh Kumar const: arm,mhuv2-rx 156aa80be50SViresh Kumarthen: 157aa80be50SViresh Kumar required: 158aa80be50SViresh Kumar - interrupts 159aa80be50SViresh Kumar 160aa80be50SViresh Kumarrequired: 161aa80be50SViresh Kumar - compatible 162aa80be50SViresh Kumar - reg 163aa80be50SViresh Kumar - '#mbox-cells' 164aa80be50SViresh Kumar - arm,mhuv2-protocols 165aa80be50SViresh Kumar 166aa80be50SViresh KumaradditionalProperties: false 167aa80be50SViresh Kumar 168aa80be50SViresh Kumarexamples: 169aa80be50SViresh Kumar # Multiple transport protocols implemented by the mailbox controllers 170aa80be50SViresh Kumar - | 171aa80be50SViresh Kumar soc { 172aa80be50SViresh Kumar #address-cells = <2>; 173aa80be50SViresh Kumar #size-cells = <2>; 174aa80be50SViresh Kumar 175aa80be50SViresh Kumar mhu_tx: mailbox@2b1f0000 { 176aa80be50SViresh Kumar #mbox-cells = <2>; 177aa80be50SViresh Kumar compatible = "arm,mhuv2-tx", "arm,primecell"; 178aa80be50SViresh Kumar reg = <0 0x2b1f0000 0 0x1000>; 179aa80be50SViresh Kumar clocks = <&clock 0>; 180aa80be50SViresh Kumar clock-names = "apb_pclk"; 181aa80be50SViresh Kumar interrupts = <0 45 4>; 182aa80be50SViresh Kumar arm,mhuv2-protocols = <1 5>, <1 2>, <1 5>, <1 7>, <0 2>; 183aa80be50SViresh Kumar }; 184aa80be50SViresh Kumar 185aa80be50SViresh Kumar mhu_rx: mailbox@2b1f1000 { 186aa80be50SViresh Kumar #mbox-cells = <2>; 187aa80be50SViresh Kumar compatible = "arm,mhuv2-rx", "arm,primecell"; 188aa80be50SViresh Kumar reg = <0 0x2b1f1000 0 0x1000>; 189aa80be50SViresh Kumar clocks = <&clock 0>; 190aa80be50SViresh Kumar clock-names = "apb_pclk"; 191aa80be50SViresh Kumar interrupts = <0 46 4>; 192aa80be50SViresh Kumar arm,mhuv2-protocols = <1 1>, <1 7>, <0 2>; 193aa80be50SViresh Kumar }; 194aa80be50SViresh Kumar 195*0daa6056SSudeep Holla mhu_client: dsp@596e8000 { 196*0daa6056SSudeep Holla compatible = "fsl,imx8qxp-dsp"; 197*0daa6056SSudeep Holla reg = <0 0x596e8000 0 0x88000>; 198*0daa6056SSudeep Holla clocks = <&adma_lpcg 0>, <&adma_lpcg 1>, <&adma_lpcg 2>; 199*0daa6056SSudeep Holla clock-names = "ipg", "ocram", "core"; 200*0daa6056SSudeep Holla power-domains = <&pd 0>, <&pd 1>, <&pd 2>, <&pd 3>; 201*0daa6056SSudeep Holla mbox-names = "txdb0", "txdb1", "rxdb0", "rxdb1"; 202*0daa6056SSudeep Holla mboxes = <&mhu_tx 2 0>, //data-transfer protocol with 5 windows, mhu-tx 203*0daa6056SSudeep Holla <&mhu_tx 3 0>, //data-transfer protocol with 7 windows, mhu-tx 204*0daa6056SSudeep Holla <&mhu_rx 2 27>, //doorbell protocol channel 2, doorbell 27, mhu-rx 205*0daa6056SSudeep Holla <&mhu_rx 0 0>; //data-transfer protocol with 1 window, mhu-rx 206*0daa6056SSudeep Holla memory-region = <&dsp_reserved>; 207aa80be50SViresh Kumar }; 208aa80be50SViresh Kumar }; 209