| Message ID | 20240403171346.3173843-2-cristian.marussi@arm.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | Add initial ARM MHUv3 mailbox support | expand |
On Wed, 03 Apr 2024 18:13:45 +0100, Cristian Marussi wrote: > Add bindings for the ARM MHUv3 Mailbox controller. > > Signed-off-by: Cristian Marussi <cristian.marussi@arm.com> > --- > 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 > My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check' on your patch (DT_CHECKER_FLAGS is new in v5.13): yamllint warnings/errors: ./Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml:86:1: [error] syntax error: found character '\t' that cannot start any token (syntax) dtschema/dtc warnings/errors: make[2]: *** Deleting file 'Documentation/devicetree/bindings/mailbox/arm,mhuv3.example.dts' Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml:86:1: found a tab character where an indentation space is expected make[2]: *** [Documentation/devicetree/bindings/Makefile:26: Documentation/devicetree/bindings/mailbox/arm,mhuv3.example.dts] Error 1 make[2]: *** Waiting for unfinished jobs.... ./Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml:86:1: found a tab character where an indentation space is expected /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml: ignoring, error parsing file make[1]: *** [/builds/robherring/dt-review-ci/linux/Makefile:1430: dt_binding_check] Error 2 make: *** [Makefile:240: __sub-make] Error 2 doc reference errors (make refcheckdocs): See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20240403171346.3173843-2-cristian.marussi@arm.com The base for the series is generally the latest rc1. A different dependency should be noted in *this* patch. If you already ran 'make dt_binding_check' and didn't see the above error(s), then make sure 'yamllint' is installed and dt-schema is up to date: pip3 install dtschema --upgrade Please check and re-submit after running the above command yourself. Note that DT_SCHEMA_FILES can be set to your schema file to speed up checking your schema. However, it must be unset to test all examples with your schema.
Hi Cristian, kernel test robot noticed the following build warnings: [auto build test WARNING on soc/for-next] [also build test WARNING on robh/for-next linus/master v6.9-rc2 next-20240403] [If your patch is applied to the wrong git tree, kindly drop us a note. And when submitting patch, we suggest to use '--base' as documented in https://git-scm.com/docs/git-format-patch#_base_tree_information] url: https://github.com/intel-lab-lkp/linux/commits/Cristian-Marussi/dt-bindings-mailbox-arm-mhuv3-Add-bindings/20240404-012010 base: https://git.kernel.org/pub/scm/linux/kernel/git/soc/soc.git for-next patch link: https://lore.kernel.org/r/20240403171346.3173843-2-cristian.marussi%40arm.com patch subject: [PATCH v2 1/2] dt-bindings: mailbox: arm,mhuv3: Add bindings compiler: loongarch64-linux-gcc (GCC) 13.2.0 reproduce: (https://download.01.org/0day-ci/archive/20240404/202404040918.E8nkWuIn-lkp@intel.com/reproduce) If you fix the issue in a separate patch/commit (i.e. not just a new version of the same patch/commit), kindly add following tags | Reported-by: kernel test robot <lkp@intel.com> | Closes: https://lore.kernel.org/oe-kbuild-all/202404040918.E8nkWuIn-lkp@intel.com/ dtcheck warnings: (new ones prefixed by >>) >> Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml:86:1: [error] syntax error: found character '\t' that cannot start any token (syntax) -- >> Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml:86:1: found a tab character where an indentation space is expected -- >> Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml: ignoring, error parsing file vim +86 Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml 8 9 maintainers: 10 - Sudeep Holla <sudeep.holla@arm.com> 11 - Cristian Marussi <cristian.marussi@arm.com> 12 13 description: | 14 The Arm Message Handling Unit (MHU) Version 3 is a mailbox controller that 15 enables unidirectional communications with remote processors through various 16 possible transport protocols. 17 The controller can optionally support a varying number of extensions that, in 18 turn, enable different kinds of transport to be used for communication. 19 Number, type and characteristics of each supported extension can be discovered 20 dynamically at runtime. 21 22 Given the unidirectional nature of the controller, an MHUv3 mailbox controller 23 is composed of a MHU Sender (MHUS) containing a PostBox (PBX) block and a MHU 24 Receiver (MHUR) containing a MailBox (MBX) block, where 25 26 PBX is used to 27 - Configure the MHU 28 - Send Transfers to the Receiver 29 - Optionally receive acknowledgment of a Transfer from the Receiver 30 31 MBX is used to 32 - Configure the MHU 33 - Receive Transfers from the Sender 34 - Optionally acknowledge Transfers sent by the Sender 35 36 Both PBX and MBX need to be present and defined in the DT description if you 37 need to establish a bidirectional communication, since you will have to 38 acquire two distinct unidirectional channels, one for each block. 39 40 As a consequence both blocks needs to be represented separately and specified 41 as distinct DT nodes in order to properly describe their resources. 42 43 Note that, though, thanks to the runtime discoverability, there is no need to 44 identify the type of blocks with distinct compatibles. 45 46 Following are the MHUv3 possible extensions. 47 48 - Doorbell Extension (DBE): DBE defines a type of channel called a Doorbell 49 Channel (DBCH). DBCH enables a single bit Transfer to be sent from the 50 Sender to Receiver. The Transfer indicates that an event has occurred. 51 When DBE is implemented, the number of DBCHs that an implementation of the 52 MHU can support is between 1 and 128, numbered starting from 0 in ascending 53 order and discoverable at run-time. 54 Each DBCH contains 32 individual fields, referred to as flags, each of which 55 can be used independently. It is possible for the Sender to send multiple 56 Transfers at once using a single DBCH, so long as each Transfer uses 57 a different flag in the DBCH. 58 Optionally, data may be transmitted through an out-of-band shared memory 59 region, wherein the MHU Doorbell is used strictly as an interrupt generation 60 mechanism, but this is out of the scope of these bindings. 61 62 - FastChannel Extension (FCE): FCE defines a type of channel called a Fast 63 Channel (FCH). FCH is intended for lower overhead communication between 64 Sender and Receiver at the expense of determinism. An FCH allows the Sender 65 to update the channel value at any time, regardless of whether the previous 66 value has been seen by the Receiver. When the Receiver reads the channel's 67 content it gets the last value written to the channel. 68 FCH is considered lossy in nature, and means that the Sender has no way of 69 knowing if, or when, the Receiver will act on the Transfer. 70 FCHs are expected to behave as RAM which generates interrupts when writes 71 occur to the locations within the RAM. 72 When FCE is implemented, the number of FCHs that an implementation of the 73 MHU can support is between 1-1024, if the FastChannel word-size is 32-bits, 74 or between 1-512, when the FastChannel word-size is 64-bits. 75 FCHs are numbered from 0 in ascending order. 76 Note that the number of FCHs and the word-size are implementation defined, 77 not configurable but discoverable at run-time. 78 Optionally, data may be transmitted through an out-of-band shared memory 79 region, wherein the MHU FastChannel is used as an interrupt generation 80 mechanism which carries also a pointer to such out-of-band data, but this 81 is out of the scope of these bindings. 82 83 - FIFO Extension (FE): FE defines a Channel type called a FIFO Channel (FFCH). 84 FFCH allows a Sender to send 85 - Multiple Transfers to the Receiver without having to wait for the > 86 previous Transfer to be acknowledged by the Receiver, as long as the 87 FIFO has room for the Transfer. 88 - Transfers which require the Receiver to provide acknowledgment. 89 - Transfers which have in-band payload. 90 In all cases, the data is guaranteed to be observed by the Receiver in the 91 same order which the Sender sent it. 92 When FE is implemented, the number of FFCHs that an implementation of the 93 MHU can support is between 1 and 64, numbered starting from 0 in ascending 94 order. The number of FFCHs, their depth (same for all implemented FFCHs) and 95 the access-granularity are implementation defined, not configurable but 96 discoverable at run-time. 97 Optionally, additional data may be transmitted through an out-of-band shared 98 memory region, wherein the MHU FIFO is used to transmit, in order, a small 99 part of the payload (like a header) and a reference to the shared memory 100 area holding the remaining, bigger, chunk of the payload, but this is out of 101 the scope of these bindings. 102 103 properties: 104 compatible: 105 const: arm,mhuv3 106 107 reg: 108 maxItems: 1 109 110 interrupts: 111 minItems: 1 112 maxItems: 74 113 114 interrupt-names: 115 description: | 116 The MHUv3 controller generates a number of events some of which are used 117 to generate interrupts; as a consequence it can expose a varying number of 118 optional PBX/MBX interrupts, representing the events generated during the 119 operation of the various transport protocols associated with different 120 extensions. All interrupts of the MHU are level-sensitive. 121 Some of these optional interrupts are defined per-channel, where the 122 number of channels effectively available is implementation defined and 123 run-time discoverable. 124 In the following names are enumerated using patterns, with per-channel 125 interrupts implicitly capped at the maximum channels allowed by the 126 specification for each extension type. 127 For the sake of simplicity maxItems is anyway capped to a most plausible 128 number, assuming way less channels would be implemented than actually 129 possible. 130 131 The only mandatory interrupts on the MHU are: 132 - combined 133 - mbx-fch-xfer-<N> but only if mbx-fcgrp-xfer-<N> is not implemented. 134 135 minItems: 1 136 maxItems: 74 137 items: 138 oneOf: 139 - const: combined 140 description: PBX/MBX Combined interrupt 141 - const: combined-ffch 142 description: PBX/MBX FIFO Combined interrupt 143 - pattern: '^ffch-low-tide-[0-9]+$' 144 description: PBX/MBX FIFO Channel <N> Low Tide interrupt 145 - pattern: '^ffch-high-tide-[0-9]+$' 146 description: PBX/MBX FIFO Channel <N> High Tide interrupt 147 - pattern: '^ffch-flush-[0-9]+$' 148 description: PBX/MBX FIFO Channel <N> Flush interrupt 149 - pattern: '^mbx-dbch-xfer-[0-9]+$' 150 description: MBX Doorbell Channel <N> Transfer interrupt 151 - pattern: '^mbx-fch-xfer-[0-9]+$' 152 description: MBX FastChannel <N> Transfer interrupt 153 - pattern: '^mbx-fchgrp-xfer-[0-9]+$' 154 description: MBX FastChannel <N> Group Transfer interrupt 155 - pattern: '^mbx-ffch-xfer-[0-9]+$' 156 description: MBX FIFO Channel <N> Transfer interrupt 157 - pattern: '^pbx-dbch-xfer-ack-[0-9]+$' 158 description: PBX Doorbell Channel <N> Transfer Ack interrupt 159 - pattern: '^pbx-ffch-xfer-ack-[0-9]+$' 160 description: PBX FIFO Channel <N> Transfer Ack interrupt 161 162 '#mbox-cells': 163 description: | 164 The first argument in the consumers 'mboxes' property represents the 165 extension type, the second is for the channel number while the third 166 depends on extension type. 167 168 Extension type for DBE is 0 and the third parameter represents the 169 doorbell flag number to use. 170 Extension type for FCE is 1, third parameter unused. 171 Extension type for FE is 2, third parameter unused. 172 173 mboxes = <&mhu 0 0 5>; // DBE, Doorbell Channel Window 0, doorbell flag 5. 174 mboxes = <&mhu 0 1 7>; // DBE, Doorbell Channel Window 1, doorbell flag 7. 175 mboxes = <&mhu 1 0 0>; // FCE, FastChannel Window 0. 176 mboxes = <&mhu 1 3 0>; // FCE, FastChannel Window 3. 177 mboxes = <&mhu 2 1 0>; // FE, FIFO Channel Window 1. 178 mboxes = <&mhu 2 7 0>; // FE, FIFO Channel Window 7. 179 const: 3 180 181 clocks: 182 maxItems: 1 183 184 required: 185 - compatible 186 - reg 187 - interrupts 188 - interrupt-names 189 - '#mbox-cells' 190
diff --git a/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml b/Documentation/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 <sudeep.holla@arm.com> + - Cristian Marussi <cristian.marussi@arm.com> + +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-<N> but only if mbx-fcgrp-xfer-<N> 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 <N> Low Tide interrupt + - pattern: '^ffch-high-tide-[0-9]+$' + description: PBX/MBX FIFO Channel <N> High Tide interrupt + - pattern: '^ffch-flush-[0-9]+$' + description: PBX/MBX FIFO Channel <N> Flush interrupt + - pattern: '^mbx-dbch-xfer-[0-9]+$' + description: MBX Doorbell Channel <N> Transfer interrupt + - pattern: '^mbx-fch-xfer-[0-9]+$' + description: MBX FastChannel <N> Transfer interrupt + - pattern: '^mbx-fchgrp-xfer-[0-9]+$' + description: MBX FastChannel <N> Group Transfer interrupt + - pattern: '^mbx-ffch-xfer-[0-9]+$' + description: MBX FIFO Channel <N> Transfer interrupt + - pattern: '^pbx-dbch-xfer-ack-[0-9]+$' + description: PBX Doorbell Channel <N> Transfer Ack interrupt + - pattern: '^pbx-ffch-xfer-ack-[0-9]+$' + description: PBX FIFO Channel <N> 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>; + }; + };
Add bindings for the ARM MHUv3 Mailbox controller. Signed-off-by: Cristian Marussi <cristian.marussi@arm.com> --- 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