tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
dt-bindings: mailbox: arm,mhuv3: Add bindings
Add bindings for the ARM MHUv3 Mailbox controller.
Reviewed-by: Rob Herring <robh@kernel.org>
Signed-off-by: Cristian Marussi <cristian.marussi@arm.com>
Signed-off-by: Jassi Brar <jassisinghbrar@gmail.com>
authored by
Cristian Marussi
and committed by
Jassi Brar
cd251970
3f58c1f4
+237
+224
Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml
+224
Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml
···
1
+
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2
+
%YAML 1.2
3
+
---
4
+
$id: http://devicetree.org/schemas/mailbox/arm,mhuv3.yaml#
5
+
$schema: http://devicetree.org/meta-schemas/core.yaml#
6
+
7
+
title: ARM MHUv3 Mailbox Controller
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 types constants are defined in <dt-bindings/arm/mhuv3-dt.h>.
169
+
170
+
Extension type for DBE is DBE_EXT and the third parameter represents the
171
+
doorbell flag number to use.
172
+
Extension type for FCE is FCE_EXT, third parameter unused.
173
+
Extension type for FE is FE_EXT, third parameter unused.
174
+
175
+
mboxes = <&mhu DBE_EXT 0 5>; // DBE, Doorbell Channel Window 0, doorbell 5.
176
+
mboxes = <&mhu DBE_EXT 7>; // DBE, Doorbell Channel Window 1, doorbell 7.
177
+
mboxes = <&mhu FCE_EXT 0 0>; // FCE, FastChannel Window 0.
178
+
mboxes = <&mhu FCE_EXT 3 0>; // FCE, FastChannel Window 3.
179
+
mboxes = <&mhu FE_EXT 1 0>; // FE, FIFO Channel Window 1.
180
+
mboxes = <&mhu FE_EXT 7 0>; // FE, FIFO Channel Window 7.
181
+
const: 3
182
+
183
+
clocks:
184
+
maxItems: 1
185
+
186
+
required:
187
+
- compatible
188
+
- reg
189
+
- interrupts
190
+
- interrupt-names
191
+
- '#mbox-cells'
192
+
193
+
additionalProperties: false
194
+
195
+
examples:
196
+
- |
197
+
#include <dt-bindings/interrupt-controller/arm-gic.h>
198
+
199
+
soc {
200
+
#address-cells = <2>;
201
+
#size-cells = <2>;
202
+
203
+
mailbox@2aaa0000 {
204
+
compatible = "arm,mhuv3";
205
+
#mbox-cells = <3>;
206
+
reg = <0 0x2aaa0000 0 0x10000>;
207
+
clocks = <&clock 0>;
208
+
interrupt-names = "combined", "pbx-dbch-xfer-ack-1",
209
+
"ffch-high-tide-0";
210
+
interrupts = <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>,
211
+
<GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>;
212
+
};
213
+
214
+
mailbox@2ab00000 {
215
+
compatible = "arm,mhuv3";
216
+
#mbox-cells = <3>;
217
+
reg = <0 0x2aab0000 0 0x10000>;
218
+
clocks = <&clock 0>;
219
+
interrupt-names = "combined", "mbx-dbch-xfer-1", "ffch-low-tide-0";
220
+
interrupts = <GIC_SPI 35 IRQ_TYPE_LEVEL_HIGH>,
221
+
<GIC_SPI 38 IRQ_TYPE_LEVEL_HIGH>,
222
+
<GIC_SPI 39 IRQ_TYPE_LEVEL_HIGH>;
223
+
};
224
+
};
+13
include/dt-bindings/arm/mhuv3-dt.h
+13
include/dt-bindings/arm/mhuv3-dt.h
···
1
+
/* SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) */
2
+
/*
3
+
* This header provides constants for the defined MHUv3 types.
4
+
*/
5
+
6
+
#ifndef _DT_BINDINGS_ARM_MHUV3_DT_H
7
+
#define _DT_BINDINGS_ARM_MHUV3_DT_H
8
+
9
+
#define DBE_EXT 0
10
+
#define FCE_EXT 1
11
+
#define FE_EXT 2
12
+
13
+
#endif /* _DT_BINDINGS_ARM_MHUV3_DT_H */