Received: by 2002:ab2:2441:0:b0:1f3:1f8c:d0c6 with SMTP id k1csp79882lqe; Wed, 3 Apr 2024 23:26:11 -0700 (PDT) X-Forwarded-Encrypted: i=3; AJvYcCX9A+ZujlA0rQiUK2qafPfh88fXVZy53qbMUTNECqpRrpIfapYtjNGj9ot99zqEoJ1Fs1/Jp28QrPGH0JMpLdszWHnULbnIjTv3qeZl7w== X-Google-Smtp-Source: AGHT+IFfdMeF+6cxYF/aHTpjooUof8hSDGAcplLI2qVxlNroIaW4Zhp5smYr13lw/kkNak7ex0Us X-Received: by 2002:a17:90a:d917:b0:2a0:9b18:daf with SMTP id c23-20020a17090ad91700b002a09b180dafmr1604588pjv.42.1712211971150; Wed, 03 Apr 2024 23:26:11 -0700 (PDT) ARC-Seal: i=2; a=rsa-sha256; t=1712211971; cv=pass; d=google.com; s=arc-20160816; b=px6KApINFTRGUIj1uvV6OsdS5WDASGBDw7zBBBPjZ+IYZnRBU1RrVYe27gc1CBahfu 8B0+uTi08EcwWPNvqRd9i/2itXg5PswLAVGlIElKzy1g2+5/y1WSaj6zKXDjh7PMYj2M N0m+1cwRzZQwWMTF787WREvKzhtm3D7cQW3TL44pj7hEpEDL5SBZFc0qCK+w9SPQrKER FwKjtkdt/AE0UPauBCvnz7yEBnmbzb27q4N92/2psMslEnSovEMIesTZaXbsnbUtguMG N+Iy9UulVPj/hd/iMS/xXjXNRCBvgCZvO6+EPihEjpAtz3FgW1iOuA09kFAAr7/XEW0N TqeQ== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:references:in-reply-to:message-id :date:subject:cc:to:from; bh=QQS0GdhUaj0Hoyzd+r1WcVx8/LXpDSKN5OS5ZeF5NLY=; fh=ywDOwMeF3nUPzfNhDWigcAreP7tvcjmsydOm5rG9sYM=; b=Gec1drSAXzfdKHZvNgRBq/p/Mm56nvsmqStYq1mWtRLNFTXwfVHzHP0QBMos+PXCEp ai6IewxGpLzX89NLU3HBDljflEo9aFsZiF2yjy4iBjaZmorJCPxQ3R+gPj2NX9yY3mJV QKi8Lj/ZJiiqxRQpAEELmJ7EATy+oHWx5hPtQ2F5p24JkNm2l7xbBLqvaLmzf0S4G5lR b0TY3wJ12OhtY4skC0xnYxmI+Hm5Rwnl/LLELaaRiI8soFljRCuFFuAl0l3E/HpsCdRj NmNm6c3YkRl/YjVF0S/B+bZgcvNnqEviuvHmYvooe5xnR8kR2pAPddVsNIvi2VNr9IuA a3ug==; dara=google.com ARC-Authentication-Results: i=2; mx.google.com; arc=pass (i=1 spf=pass spfdomain=arm.com dmarc=pass fromdomain=arm.com); spf=pass (google.com: domain of linux-kernel+bounces-130974-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45e3:2400::1 as permitted sender) smtp.mailfrom="linux-kernel+bounces-130974-linux.lists.archive=gmail.com@vger.kernel.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=arm.com Return-Path: Received: from sv.mirrors.kernel.org (sv.mirrors.kernel.org. [2604:1380:45e3:2400::1]) by mx.google.com with ESMTPS id o8-20020a17090a55c800b002a2a877e246si1047860pjm.35.2024.04.03.23.26.10 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 03 Apr 2024 23:26:11 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel+bounces-130974-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45e3:2400::1 as permitted sender) client-ip=2604:1380:45e3:2400::1; Authentication-Results: mx.google.com; arc=pass (i=1 spf=pass spfdomain=arm.com dmarc=pass fromdomain=arm.com); spf=pass (google.com: domain of linux-kernel+bounces-130974-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45e3:2400::1 as permitted sender) smtp.mailfrom="linux-kernel+bounces-130974-linux.lists.archive=gmail.com@vger.kernel.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=arm.com Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sv.mirrors.kernel.org (Postfix) with ESMTPS id F2AD828A3ED for ; Thu, 4 Apr 2024 06:25:37 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 6124A52F9A; Thu, 4 Apr 2024 06:25:20 +0000 (UTC) Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by smtp.subspace.kernel.org (Postfix) with ESMTP id AA5C045945; Thu, 4 Apr 2024 06:25:17 +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=1712211919; cv=none; b=VAJrOMJzvVd4CtdSkZ9eZSZgi8ltbevK34cuC9BwZgW5RA+4Y7Z+I77y7AG0r/ZqPhRQ81Ef+XuaNkiBjk7JKdKwPiC6nrFj1Oy3rSOgXNV5PikIrMrKkkKPaR1ah9mMLQAtVJlufOtNmlTQ7F4T7dn96u3z7GPjAR541cdG5xw= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1712211919; c=relaxed/simple; bh=ISgwnw21gGhb3cZF4WvzBJcvlFYcGebQMPrI/rZzlN4=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=R3fxbDtyTn6u6lXGyaMjBO1QENqQZgmCBZaJaf29cPZn1yZKyy2u/dywd66kdNajIFH7SI5CvpCXWJo3m0IyTgjsTtXD5n6VMp+8SsYFIbVf9YeaoFZ1scPQgzG9+Cl/HHAt7M4Bdkoth9Tj2RSA1Lg/09O22OGn/29N1JxXIaQ= 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 9CF1E143D; Wed, 3 Apr 2024 23:25:47 -0700 (PDT) Received: from e120937-lin.. (unknown [172.31.20.19]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 5B0B03F64C; Wed, 3 Apr 2024 23:25:15 -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 v3 1/2] dt-bindings: mailbox: arm,mhuv3: Add bindings Date: Thu, 4 Apr 2024 07:23:46 +0100 Message-Id: <20240404062347.3219795-2-cristian.marussi@arm.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240404062347.3219795-1-cristian.marussi@arm.com> References: <20240404062347.3219795-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: 8bit Add bindings for the ARM MHUv3 Mailbox controller. Signed-off-by: Cristian Marussi --- v2 -> v3 - fixed spurious tabs in dt_binding_check v1 -> v2 - clarified extension descriptions around configurability and discoverability - 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/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml new file mode 100644 index 000000000000..32a8bb711464 --- /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 that + enables unidirectional communications with remote processors through various + possible transport protocols. + The controller can optionally support a varying number of extensions that, in + turn, enable different kinds of transport to be used for communication. + Number, type and characteristics of each supported extension can be discovered + dynamically at runtime. + + Given the unidirectional nature of the controller, an MHUv3 mailbox controller + 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 specified + as distinct DT nodes in order to properly describe their resources. + + Note that, though, thanks to the runtime discoverability, there is no need 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 Doorbell + 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 ascending + 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 multiple + 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 memory + region, wherein the MHU Doorbell is used strictly as an interrupt generation + mechanism, but this is out of the scope of these bindings. + + - FastChannel Extension (FCE): FCE defines a type of channel called a Fast + Channel (FCH). FCH is intended for lower overhead communication between + Sender and Receiver at the expense of determinism. An FCH allows the Sender + to update the channel value at any time, regardless of whether the previous + value has been seen by the Receiver. When the Receiver reads the channel's + content it gets the last value written to the channel. + FCH is considered lossy in nature, and means that the Sender has no way of + knowing if, or when, the Receiver will act on the Transfer. + FCHs are expected to behave as RAM which generates interrupts when writes + 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 defined, + not configurable but discoverable at run-time. + Optionally, data may be transmitted through an out-of-band shared memory + region, wherein the MHU FastChannel is used as an interrupt generation + mechanism which carries also a pointer to such out-of-band data, but this + 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 ascending + order. The number of FFCHs, their depth (same for all implemented FFCHs) 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 small + part of the payload (like a header) and a reference to the shared memory + 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 number of + optional PBX/MBX interrupts, representing the events generated during the + operation of the various transport protocols associated with different + 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 and + run-time discoverable. + In the following names are enumerated using patterns, with per-channel + 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 plausible + 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 implemented. + + 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 = <&mhu 0 0 5>; // DBE, Doorbell Channel Window 0, doorbell flag 5. + mboxes = <&mhu 0 1 7>; // DBE, Doorbell Channel Window 1, doorbell flag 7. + mboxes = <&mhu 1 0 0>; // FCE, FastChannel Window 0. + mboxes = <&mhu 1 3 0>; // FCE, FastChannel Window 3. + mboxes = <&mhu 2 1 0>; // FE, FIFO Channel Window 1. + mboxes = <&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 = <2>; + #size-cells = <2>; + + mailbox@2aaa0000 { + compatible = "arm,mhuv3"; + #mbox-cells = <3>; + reg = <0 0x2aaa0000 0 0x10000>; + clocks = <&clock 0>; + interrupt-names = "combined", "pbx-dbch-xfer-ack-1", + "ffch-high-tide-0"; + interrupts = <0 36 4>, <0 37 4>; + }; + + mailbox@2ab00000 { + compatible = "arm,mhuv3"; + #mbox-cells = <3>; + reg = <0 0x2aab0000 0 0x10000>; + clocks = <&clock 0>; + interrupt-names = "combined", "mbx-dbch-xfer-1", "ffch-low-tide-0"; + interrupts = <0 35 4>, <0 38 4>, <0 39 4>; + }; + }; -- 2.34.1