From nobody Thu Feb 12 13:21:13 2026 Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by smtp.subspace.kernel.org (Postfix) with ESMTP id D0490152DE1; Wed, 3 Apr 2024 17:14:13 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=217.140.110.172 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1712164456; cv=none; b=OQ6zaPCZP3POfJG0Ua3fCKzAXJVxX8nKIjgk8GL3reGrZpWCGcN1bCMOpFjXd8gCv4YQ8b0sN03fDNvJ8U3MGXfc2KryC6WPVAxsJ//yRGKsRrxsuQrEt7Ar30Z5Z3w4Gv/qMLu6Kr5o9VfGrpTvwxj8oSvVUzHs/SP9ybTX47A= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1712164456; c=relaxed/simple; bh=XbbvatYPa8+pwHVn1GQtKyg0I3U4YcIlnfhacLsHIZQ=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=Plly8CX6uT9RfziYHqRwfrHbG78cbkFFcH4fUd5sGLD0tsYrYjNQd4kwEmT4ZJMUGp5LYSx2IGzuRbwLvF73mca+BA/Gh5H7qzAdjYTZqwEhVGd28ixKLMpkHHqJBvEUkSOeNUpfrk1SlQlbudOgw6LnMSWZq4scH8Fnhhp2SgU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=arm.com; spf=pass smtp.mailfrom=arm.com; arc=none smtp.client-ip=217.140.110.172 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=arm.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=arm.com Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 379621595; Wed, 3 Apr 2024 10:14:44 -0700 (PDT) Received: from e120937-lin.. (unknown [172.31.20.19]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id BB3F03F766; Wed, 3 Apr 2024 10:14:11 -0700 (PDT) From: Cristian Marussi To: linux-kernel@vger.kernel.org, linux-arm-kernel@lists.infradead.org, devicetree@vger.kernel.org Cc: sudeep.holla@arm.com, cristian.marussi@arm.com, jassisinghbrar@gmail.com, robh+dt@kernel.org, krzysztof.kozlowski+dt@linaro.org, conor+dt@kernel.org Subject: [PATCH v2 1/2] dt-bindings: mailbox: arm,mhuv3: Add bindings Date: Wed, 3 Apr 2024 18:13:45 +0100 Message-Id: <20240403171346.3173843-2-cristian.marussi@arm.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240403171346.3173843-1-cristian.marussi@arm.com> References: <20240403171346.3173843-1-cristian.marussi@arm.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Add bindings for the ARM MHUv3 Mailbox controller. Signed-off-by: Cristian Marussi --- v1 -> v2 - clarified extension descriptions around configurability and discoverabili= ty - removed unused labels from the example - using pattern properties to define interrupt-names - bumped interrupt maxItems to 74 (allowing uo to 8 channels per extension) --- .../bindings/mailbox/arm,mhuv3.yaml | 217 ++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml diff --git a/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml b/Doc= umentation/devicetree/bindings/mailbox/arm,mhuv3.yaml new file mode 100644 index 000000000000..d781045521da --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml @@ -0,0 +1,217 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mailbox/arm,mhuv3.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ARM MHUv3 Mailbox Controller + +maintainers: + - Sudeep Holla + - Cristian Marussi + +description: | + The Arm Message Handling Unit (MHU) Version 3 is a mailbox controller th= at + enables unidirectional communications with remote processors through var= ious + possible transport protocols. + The controller can optionally support a varying number of extensions tha= t, in + turn, enable different kinds of transport to be used for communication. + Number, type and characteristics of each supported extension can be disc= overed + dynamically at runtime. + + Given the unidirectional nature of the controller, an MHUv3 mailbox cont= roller + is composed of a MHU Sender (MHUS) containing a PostBox (PBX) block and = a MHU + Receiver (MHUR) containing a MailBox (MBX) block, where + + PBX is used to + - Configure the MHU + - Send Transfers to the Receiver + - Optionally receive acknowledgment of a Transfer from the Receiver + + MBX is used to + - Configure the MHU + - Receive Transfers from the Sender + - Optionally acknowledge Transfers sent by the Sender + + Both PBX and MBX need to be present and defined in the DT description if= you + need to establish a bidirectional communication, since you will have to + acquire two distinct unidirectional channels, one for each block. + + As a consequence both blocks needs to be represented separately and spec= ified + as distinct DT nodes in order to properly describe their resources. + + Note that, though, thanks to the runtime discoverability, there is no ne= ed to + identify the type of blocks with distinct compatibles. + + Following are the MHUv3 possible extensions. + + - Doorbell Extension (DBE): DBE defines a type of channel called a Doorb= ell + Channel (DBCH). DBCH enables a single bit Transfer to be sent from the + Sender to Receiver. The Transfer indicates that an event has occurred. + When DBE is implemented, the number of DBCHs that an implementation of= the + MHU can support is between 1 and 128, numbered starting from 0 in asce= nding + order and discoverable at run-time. + Each DBCH contains 32 individual fields, referred to as flags, each of= which + can be used independently. It is possible for the Sender to send multi= ple + Transfers at once using a single DBCH, so long as each Transfer uses + a different flag in the DBCH. + Optionally, data may be transmitted through an out-of-band shared memo= ry + region, wherein the MHU Doorbell is used strictly as an interrupt gene= ration + mechanism, but this is out of the scope of these bindings. + + - FastChannel Extension (FCE): FCE defines a type of channel called a Fa= st + Channel (FCH). FCH is intended for lower overhead communication between + Sender and Receiver at the expense of determinism. An FCH allows the S= ender + to update the channel value at any time, regardless of whether the pre= vious + value has been seen by the Receiver. When the Receiver reads the chann= el's + content it gets the last value written to the channel. + FCH is considered lossy in nature, and means that the Sender has no wa= y of + knowing if, or when, the Receiver will act on the Transfer. + FCHs are expected to behave as RAM which generates interrupts when wri= tes + occur to the locations within the RAM. + When FCE is implemented, the number of FCHs that an implementation of = the + MHU can support is between 1-1024, if the FastChannel word-size is 32-= bits, + or between 1-512, when the FastChannel word-size is 64-bits. + FCHs are numbered from 0 in ascending order. + Note that the number of FCHs and the word-size are implementation defi= ned, + not configurable but discoverable at run-time. + Optionally, data may be transmitted through an out-of-band shared memo= ry + region, wherein the MHU FastChannel is used as an interrupt generation + mechanism which carries also a pointer to such out-of-band data, but t= his + is out of the scope of these bindings. + + - FIFO Extension (FE): FE defines a Channel type called a FIFO Channel (= FFCH). + FFCH allows a Sender to send + - Multiple Transfers to the Receiver without having to wait for the + previous Transfer to be acknowledged by the Receiver, as long as the + FIFO has room for the Transfer. + - Transfers which require the Receiver to provide acknowledgment. + - Transfers which have in-band payload. + In all cases, the data is guaranteed to be observed by the Receiver in= the + same order which the Sender sent it. + When FE is implemented, the number of FFCHs that an implementation of = the + MHU can support is between 1 and 64, numbered starting from 0 in ascen= ding + order. The number of FFCHs, their depth (same for all implemented FFCH= s) and + the access-granularity are implementation defined, not configurable but + discoverable at run-time. + Optionally, additional data may be transmitted through an out-of-band = shared + memory region, wherein the MHU FIFO is used to transmit, in order, a s= mall + part of the payload (like a header) and a reference to the shared memo= ry + area holding the remaining, bigger, chunk of the payload, but this is = out of + the scope of these bindings. + +properties: + compatible: + const: arm,mhuv3 + + reg: + maxItems: 1 + + interrupts: + minItems: 1 + maxItems: 74 + + interrupt-names: + description: | + The MHUv3 controller generates a number of events some of which are = used + to generate interrupts; as a consequence it can expose a varying num= ber of + optional PBX/MBX interrupts, representing the events generated durin= g the + operation of the various transport protocols associated with differe= nt + extensions. All interrupts of the MHU are level-sensitive. + Some of these optional interrupts are defined per-channel, where the + number of channels effectively available is implementation defined a= nd + run-time discoverable. + In the following names are enumerated using patterns, with per-chann= el + interrupts implicitly capped at the maximum channels allowed by the + specification for each extension type. + For the sake of simplicity maxItems is anyway capped to a most plaus= ible + number, assuming way less channels would be implemented than actually + possible. + + The only mandatory interrupts on the MHU are: + - combined + - mbx-fch-xfer- but only if mbx-fcgrp-xfer- is not implement= ed. + + minItems: 1 + maxItems: 74 + items: + oneOf: + - const: combined + description: PBX/MBX Combined interrupt + - const: combined-ffch + description: PBX/MBX FIFO Combined interrupt + - pattern: '^ffch-low-tide-[0-9]+$' + description: PBX/MBX FIFO Channel Low Tide interrupt + - pattern: '^ffch-high-tide-[0-9]+$' + description: PBX/MBX FIFO Channel High Tide interrupt + - pattern: '^ffch-flush-[0-9]+$' + description: PBX/MBX FIFO Channel Flush interrupt + - pattern: '^mbx-dbch-xfer-[0-9]+$' + description: MBX Doorbell Channel Transfer interrupt + - pattern: '^mbx-fch-xfer-[0-9]+$' + description: MBX FastChannel Transfer interrupt + - pattern: '^mbx-fchgrp-xfer-[0-9]+$' + description: MBX FastChannel Group Transfer interrupt + - pattern: '^mbx-ffch-xfer-[0-9]+$' + description: MBX FIFO Channel Transfer interrupt + - pattern: '^pbx-dbch-xfer-ack-[0-9]+$' + description: PBX Doorbell Channel Transfer Ack interrupt + - pattern: '^pbx-ffch-xfer-ack-[0-9]+$' + description: PBX FIFO Channel Transfer Ack interrupt + + '#mbox-cells': + description: | + The first argument in the consumers 'mboxes' property represents the + extension type, the second is for the channel number while the third + depends on extension type. + + Extension type for DBE is 0 and the third parameter represents the + doorbell flag number to use. + Extension type for FCE is 1, third parameter unused. + Extension type for FE is 2, third parameter unused. + + mboxes =3D <&mhu 0 0 5>; // DBE, Doorbell Channel Window 0, doorbell= flag 5. + mboxes =3D <&mhu 0 1 7>; // DBE, Doorbell Channel Window 1, doorbell= flag 7. + mboxes =3D <&mhu 1 0 0>; // FCE, FastChannel Window 0. + mboxes =3D <&mhu 1 3 0>; // FCE, FastChannel Window 3. + mboxes =3D <&mhu 2 1 0>; // FE, FIFO Channel Window 1. + mboxes =3D <&mhu 2 7 0>; // FE, FIFO Channel Window 7. + const: 3 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - interrupt-names + - '#mbox-cells' + +additionalProperties: false + +examples: + - | + soc { + #address-cells =3D <2>; + #size-cells =3D <2>; + + mailbox@2aaa0000 { + compatible =3D "arm,mhuv3"; + #mbox-cells =3D <3>; + reg =3D <0 0x2aaa0000 0 0x10000>; + clocks =3D <&clock 0>; + interrupt-names =3D "combined", "pbx-dbch-xfer-ack-1", + "ffch-high-tide-0"; + interrupts =3D <0 36 4>, <0 37 4>; + }; + + mailbox@2ab00000 { + compatible =3D "arm,mhuv3"; + #mbox-cells =3D <3>; + reg =3D <0 0x2aab0000 0 0x10000>; + clocks =3D <&clock 0>; + interrupt-names =3D "combined", "mbx-dbch-xfer-1", "ffch-low-t= ide-0"; + interrupts =3D <0 35 4>, <0 38 4>, <0 39 4>; + }; + }; --=20 2.34.1