From nobody Mon Feb 9 17:58:41 2026 Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 70ACE15D5D6; Thu, 18 Apr 2024 10:52:35 +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=1713437557; cv=none; b=HJZ1krS9TJ/OCqxjkt+9G2Ru+DT9xt4ZhwYd9rHa2b1igMNrTW+S+UwPeq4kbvPlA9FTca2t+NQ872Ljwib643018P+Zgxk7VNyouAgaFKhRHWBrwIS9nwHrcfH3bnflYtHmgtFuACbrGX/93vR31ehywyBAnolBcrLAN3DorcI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1713437557; c=relaxed/simple; bh=O07uvBijdeWxh0c1JHJjki7H3hp3hIjqRRuaW+tdBFg=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=csGABys7KY3b3qJ3XcIh5c+3a43kCLAWq5DXRakYAp42KCnLGNmxKu+K+rameU/eSARrGq6haKkuJXbfo9/x+h90Wv+55GwOpzyvRqwMu9oFK1i5oSbYv0oA9RA3/hxyVbUZnOVUEEK+OKIbm1RH4pNR83BqnEN65c4eQBE+zZY= 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 B34AF339; Thu, 18 Apr 2024 03:53:02 -0700 (PDT) Received: from e120937-lin.. (usa-sjc-mx-foss1.foss.arm.com [172.31.20.19]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 6478D3F792; Thu, 18 Apr 2024 03:52:33 -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, Rob Herring Subject: [PATCH v5 1/2] dt-bindings: mailbox: arm,mhuv3: Add bindings Date: Thu, 18 Apr 2024 11:52:09 +0100 Message-Id: <20240418105210.290938-2-cristian.marussi@arm.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240418105210.290938-1-cristian.marussi@arm.com> References: <20240418105210.290938-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. Reviewed-by: Rob Herring Signed-off-by: Cristian Marussi --- v3 -> v4 - using ARM GIC defines in example - defined MHUv3 Extensions types in dt-bindings/arm/mhuv3-dt.h v2 -> v3 - fixed spurious tabs in dt_binding_check 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 | 224 ++++++++++++++++++ include/dt-bindings/arm/mhuv3-dt.h | 13 + 2 files changed, 237 insertions(+) create mode 100644 Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml create mode 100644 include/dt-bindings/arm/mhuv3-dt.h 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..449b55afeb7d --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml @@ -0,0 +1,224 @@ +# 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 types constants are defined in . + + Extension type for DBE is DBE_EXT and the third parameter represents= the + doorbell flag number to use. + Extension type for FCE is FCE_EXT, third parameter unused. + Extension type for FE is FE_EXT, third parameter unused. + + mboxes =3D <&mhu DBE_EXT 0 5>; // DBE, Doorbell Channel Window 0, do= orbell 5. + mboxes =3D <&mhu DBE_EXT 7>; // DBE, Doorbell Channel Window 1, door= bell 7. + mboxes =3D <&mhu FCE_EXT 0 0>; // FCE, FastChannel Window 0. + mboxes =3D <&mhu FCE_EXT 3 0>; // FCE, FastChannel Window 3. + mboxes =3D <&mhu FE_EXT 1 0>; // FE, FIFO Channel Window 1. + mboxes =3D <&mhu FE_EXT 7 0>; // FE, FIFO Channel Window 7. + const: 3 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - interrupt-names + - '#mbox-cells' + +additionalProperties: false + +examples: + - | + #include + + 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 , + ; + }; + + 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 , + , + ; + }; + }; diff --git a/include/dt-bindings/arm/mhuv3-dt.h b/include/dt-bindings/arm/m= huv3-dt.h new file mode 100644 index 000000000000..4575406919dd --- /dev/null +++ b/include/dt-bindings/arm/mhuv3-dt.h @@ -0,0 +1,13 @@ +/* SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) */ +/* + * This header provides constants for the defined MHUv3 types. + */ + +#ifndef _DT_BINDINGS_ARM_MHUV3_DT_H +#define _DT_BINDINGS_ARM_MHUV3_DT_H + +#define DBE_EXT 0 +#define FCE_EXT 1 +#define FE_EXT 2 + +#endif /* _DT_BINDINGS_ARM_MHUV3_DT_H */ --=20 2.34.1