| Message ID | 20190717192616.1731-1-tushar.khandelwal@arm.com |
|---|---|
| Headers | show |
| Series | Arm MHUv2 Mailbox Controller Driver | expand |
On Sun, Jul 21, 2019 at 4:58 PM Jassi Brar <jassisinghbrar@gmail.com> wrote: > > On Wed, Jul 17, 2019 at 2:26 PM Tushar Khandelwal > <tushar.khandelwal@arm.com> wrote: > > > diff --git a/Documentation/devicetree/bindings/mailbox/arm,mhuv2.txt b/Documentation/devicetree/bindings/mailbox/arm,mhuv2.txt > > new file mode 100644 > > index 000000000000..3a05593414bc > > --- /dev/null > > +++ b/Documentation/devicetree/bindings/mailbox/arm,mhuv2.txt > > @@ -0,0 +1,108 @@ > > +Arm MHUv2 Mailbox Driver > > +======================== > > + > > +The Arm Message-Handling-Unit (MHU) Version 2 is a mailbox controller that has > > +between 1 and 124 channel windows to provide unidirectional communication with > > +remote processor(s). > > + > > +Given the unidirectional nature of the device, an MHUv2 mailbox may only be > > +written to or read from. If a pair of MHU devices is implemented between two > > +processing elements to provide bidirectional communication, these must be > > +specified as two separate mailboxes. > > + > > +A device tree node for an Arm MHUv2 device must specify either a receiver frame > > +or a sender frame, indicating which end of the unidirectional MHU device which > > +the device node entry describes. > > + > > +An MHU device must be specified with a transport protocol. The transport > > +protocol of an MHU device determines the method of data transmission as well as > > +the number of provided mailboxes. > > +Following are the possible transport protocol types: > > +- Single-word: An MHU device implements as many mailboxes as it > > + provides channel windows. Data is transmitted through > > + the MHU registers. > > +- Multi-word: An MHU device implements a single mailbox. All channel windows > > + will be used during transmission. Data is transmitted through > > + the MHU registers. > > +- Doorbell: An MHU device implements as many mailboxes as there are flag > > + bits available in its channel windows. Optionally, data may > > + be transmitted through a shared memory region, wherein the MHU > > + is used strictly as an interrupt generation mechanism. > > + > > +Mailbox Device Node: > > +==================== > > + > > +Required properties: > > +-------------------- > > +- compatible: Shall be "arm,mhuv2" & "arm,primecell" > > +- reg: Contains the mailbox register address range (base > > + address and length) > > +- #mbox-cells Shall be 1 - the index of the channel needed. > > +- mhu-frame Frame type of the device. > > + Shall be either "sender" or "receiver" > > +- mhu-protocol Transport protocol of the device. Shall be one of the > > + following: "single-word", "multi-word", "doorbell" > > + > > +Required properties (receiver frame): > > +------------------------------------- > > +- interrupts: Contains the interrupt information corresponding to the > > + combined interrupt of the receiver frame > > + > > +Example: > > +-------- > > + > > + mbox_mw_tx: mhu@10000000 { > > + compatible = "arm,mhuv2","arm,primecell"; > > + reg = <0x10000000 0x1000>; > > + clocks = <&refclk100mhz>; > > + clock-names = "apb_pclk"; > > + #mbox-cells = <1>; > > + mhu-protocol = "multi-word"; > > + mhu-frame = "sender"; > > + }; > > + > > + mbox_sw_tx: mhu@10000000 { > > + compatible = "arm,mhuv2","arm,primecell"; > > + reg = <0x11000000 0x1000>; > > + clocks = <&refclk100mhz>; > > + clock-names = "apb_pclk"; > > + #mbox-cells = <1>; > > + mhu-protocol = "single-word"; > > + mhu-frame = "sender"; > > + }; > > + > > + mbox_db_rx: mhu@10000000 { > > + compatible = "arm,mhuv2","arm,primecell"; > > + reg = <0x12000000 0x1000>; > > + clocks = <&refclk100mhz>; > > + clock-names = "apb_pclk"; > > + #mbox-cells = <1>; > > + interrupts = <0 45 4>; > > + interrupt-names = "mhu_rx"; > > + mhu-protocol = "doorbell"; > > + mhu-frame = "receiver"; > > + }; > > + > > + mhu_client: scb@2e000000 { > > + compatible = "fujitsu,mb86s70-scb-1.0"; > > + reg = <0 0x2e000000 0x4000>; > > + mboxes = > > + // For multi-word frames, client may only instantiate a single > > + // mailbox for a mailbox controller > > + <&mbox_mw_tx 0>, > > + > > + // For single-word frames, client may instantiate as many > > + // mailboxes as there are channel windows in the MHU > > + <&mbox_sw_tx 0>, > > + <&mbox_sw_tx 1>, > > + <&mbox_sw_tx 2>, > > + <&mbox_sw_tx 3>, > > + > > + // For doorbell frames, client may instantiate as many mailboxes > > + // as there are bits available in the combined number of channel > > + // windows ((channel windows * 32) mailboxes) > > + <mbox_db_rx 0>, > > + <mbox_db_rx 1>, > > + ... > > + <mbox_db_rx 17>; > > + }; > > If the mhuv2 instance implements, say, 3 channel windows between > sender (linux) and receiver (firmware), and Linux runs two protocols > each requiring 1 and 2-word sized messages respectively. The hardware > supports that by assigning windows [0] and [1,2] to each protocol. > However, I don't think the driver can support that. Or does it? > Thinking about it, IMO, the mbox-cell should carry a 128 (4x32) bit mask specifying the set of windows (corresponding to the bits set in the mask) associated with the channel. And the controller driver should see any channel as associated with variable number of windows 'N', where N is [0,124] mhu_client1: proto1@2e000000 { ..... mboxes = <&mbox 0x0 0x0 0x0 0x1> } mhu_client2: proto2@2f000000 { ..... mboxes = <&mbox 0x0 0x0 0x0 0x6> } Cheers!
On 7/21/19 11:58 PM, Jassi Brar wrote: > On Wed, Jul 17, 2019 at 2:26 PM Tushar Khandelwal > <tushar.khandelwal@arm.com> wrote: > >> diff --git a/Documentation/devicetree/bindings/mailbox/arm,mhuv2.txt b/Documentation/devicetree/bindings/mailbox/arm,mhuv2.txt >> new file mode 100644 >> index 000000000000..3a05593414bc >> --- /dev/null >> +++ b/Documentation/devicetree/bindings/mailbox/arm,mhuv2.txt >> @@ -0,0 +1,108 @@ >> +Arm MHUv2 Mailbox Driver >> +======================== >> + >> +The Arm Message-Handling-Unit (MHU) Version 2 is a mailbox controller that has >> +between 1 and 124 channel windows to provide unidirectional communication with >> +remote processor(s). >> + >> +Given the unidirectional nature of the device, an MHUv2 mailbox may only be >> +written to or read from. If a pair of MHU devices is implemented between two >> +processing elements to provide bidirectional communication, these must be >> +specified as two separate mailboxes. >> + >> +A device tree node for an Arm MHUv2 device must specify either a receiver frame >> +or a sender frame, indicating which end of the unidirectional MHU device which >> +the device node entry describes. >> + >> +An MHU device must be specified with a transport protocol. The transport >> +protocol of an MHU device determines the method of data transmission as well as >> +the number of provided mailboxes. >> +Following are the possible transport protocol types: >> +- Single-word: An MHU device implements as many mailboxes as it >> + provides channel windows. Data is transmitted through >> + the MHU registers. >> +- Multi-word: An MHU device implements a single mailbox. All channel windows >> + will be used during transmission. Data is transmitted through >> + the MHU registers. >> +- Doorbell: An MHU device implements as many mailboxes as there are flag >> + bits available in its channel windows. Optionally, data may >> + be transmitted through a shared memory region, wherein the MHU >> + is used strictly as an interrupt generation mechanism. >> + >> +Mailbox Device Node: >> +==================== >> + >> +Required properties: >> +-------------------- >> +- compatible: Shall be "arm,mhuv2" & "arm,primecell" >> +- reg: Contains the mailbox register address range (base >> + address and length) >> +- #mbox-cells Shall be 1 - the index of the channel needed. >> +- mhu-frame Frame type of the device. >> + Shall be either "sender" or "receiver" >> +- mhu-protocol Transport protocol of the device. Shall be one of the >> + following: "single-word", "multi-word", "doorbell" >> + >> +Required properties (receiver frame): >> +------------------------------------- >> +- interrupts: Contains the interrupt information corresponding to the >> + combined interrupt of the receiver frame >> + >> +Example: >> +-------- >> + >> + mbox_mw_tx: mhu@10000000 { >> + compatible = "arm,mhuv2","arm,primecell"; >> + reg = <0x10000000 0x1000>; >> + clocks = <&refclk100mhz>; >> + clock-names = "apb_pclk"; >> + #mbox-cells = <1>; >> + mhu-protocol = "multi-word"; >> + mhu-frame = "sender"; >> + }; >> + >> + mbox_sw_tx: mhu@10000000 { >> + compatible = "arm,mhuv2","arm,primecell"; >> + reg = <0x11000000 0x1000>; >> + clocks = <&refclk100mhz>; >> + clock-names = "apb_pclk"; >> + #mbox-cells = <1>; >> + mhu-protocol = "single-word"; >> + mhu-frame = "sender"; >> + }; >> + >> + mbox_db_rx: mhu@10000000 { >> + compatible = "arm,mhuv2","arm,primecell"; >> + reg = <0x12000000 0x1000>; >> + clocks = <&refclk100mhz>; >> + clock-names = "apb_pclk"; >> + #mbox-cells = <1>; >> + interrupts = <0 45 4>; >> + interrupt-names = "mhu_rx"; >> + mhu-protocol = "doorbell"; >> + mhu-frame = "receiver"; >> + }; >> + >> + mhu_client: scb@2e000000 { >> + compatible = "fujitsu,mb86s70-scb-1.0"; >> + reg = <0 0x2e000000 0x4000>; >> + mboxes = >> + // For multi-word frames, client may only instantiate a single >> + // mailbox for a mailbox controller >> + <&mbox_mw_tx 0>, >> + >> + // For single-word frames, client may instantiate as many >> + // mailboxes as there are channel windows in the MHU >> + <&mbox_sw_tx 0>, >> + <&mbox_sw_tx 1>, >> + <&mbox_sw_tx 2>, >> + <&mbox_sw_tx 3>, >> + >> + // For doorbell frames, client may instantiate as many mailboxes >> + // as there are bits available in the combined number of channel >> + // windows ((channel windows * 32) mailboxes) >> + <mbox_db_rx 0>, >> + <mbox_db_rx 1>, >> + ... >> + <mbox_db_rx 17>; >> + }; > > If the mhuv2 instance implements, say, 3 channel windows between > sender (linux) and receiver (firmware), and Linux runs two protocols > each requiring 1 and 2-word sized messages respectively. The hardware > supports that by assigning windows [0] and [1,2] to each protocol. > However, I don't think the driver can support that. Or does it? > Correct, this version of the driver does not support mixing-and-matching protocols for an MHU device. Given the current use-cases for the driver, we do not currently see a need for this functionality. However, as you mention, the hardware does not restrict this and it would be possible to add in a future version. > Also I see problem with implementing "protocol modes" in the > controller driver - 'mhu-protocol' property should go away. And > 'mhu-frame' is unncessary - presence of interrupt property could imply > 'receiver', otherwise 'sender'. > > Cheers! > I agree that the 'mhu-frame' property can be removed and the frame type can be deduced from whether an interrupt property is present. In regards to 'mhu-protocol', i still see value in having it as a device tree property. As mentioned above, mixing protocols within an MHU is not currently supported. We decided to specify the protocol for an MHU in the device tree, given that the protocol influences how many mboxes it is allowed for a mailbox client to register with a controller, Thanks, Morten
On 8/7/19 1:17 PM, Tushar Khandelwal wrote: > > > On 02/08/2019, 11:59, "Sudeep Holla" <sudeep.holla@arm.com> wrote: > > On Sun, Jul 21, 2019 at 04:58:04PM -0500, Jassi Brar wrote: > > On Wed, Jul 17, 2019 at 2:26 PM Tushar Khandelwal > > <tushar.khandelwal@arm.com> wrote: > > > > > diff --git a/Documentation/devicetree/bindings/mailbox/arm,mhuv2.txt b/Documentation/devicetree/bindings/mailbox/arm,mhuv2.txt > > > new file mode 100644 > > > index 000000000000..3a05593414bc > > > --- /dev/null > > > +++ b/Documentation/devicetree/bindings/mailbox/arm,mhuv2.txt > > > @@ -0,0 +1,108 @@ > > > +Arm MHUv2 Mailbox Driver > > > +======================== > > > + > > > +The Arm Message-Handling-Unit (MHU) Version 2 is a mailbox controller that has > > > +between 1 and 124 channel windows to provide unidirectional communication with > > > +remote processor(s). > > > + > > > +Given the unidirectional nature of the device, an MHUv2 mailbox may only be > > > +written to or read from. If a pair of MHU devices is implemented between two > > > +processing elements to provide bidirectional communication, these must be > > > +specified as two separate mailboxes. > > > + > > > +A device tree node for an Arm MHUv2 device must specify either a receiver frame > > > +or a sender frame, indicating which end of the unidirectional MHU device which > > > +the device node entry describes. > > > + > > > +An MHU device must be specified with a transport protocol. The transport > > > +protocol of an MHU device determines the method of data transmission as well as > > > +the number of provided mailboxes. > > > +Following are the possible transport protocol types: > > > +- Single-word: An MHU device implements as many mailboxes as it > > > + provides channel windows. Data is transmitted through > > > + the MHU registers. > > > +- Multi-word: An MHU device implements a single mailbox. All channel windows > > > + will be used during transmission. Data is transmitted through > > > + the MHU registers. > > > +- Doorbell: An MHU device implements as many mailboxes as there are flag > > > + bits available in its channel windows. Optionally, data may > > > + be transmitted through a shared memory region, wherein the MHU > > > + is used strictly as an interrupt generation mechanism. > > > + > > > +Mailbox Device Node: > > > +==================== > > > + > > > +Required properties: > > > +-------------------- > > > +- compatible: Shall be "arm,mhuv2" & "arm,primecell" > > > +- reg: Contains the mailbox register address range (base > > > + address and length) > > > +- #mbox-cells Shall be 1 - the index of the channel needed. > > > +- mhu-frame Frame type of the device. > > > + Shall be either "sender" or "receiver" > > > +- mhu-protocol Transport protocol of the device. Shall be one of the > > > + following: "single-word", "multi-word", "doorbell" > > > + > > > +Required properties (receiver frame): > > > +------------------------------------- > > > +- interrupts: Contains the interrupt information corresponding to the > > > + combined interrupt of the receiver frame > > > + > > > +Example: > > > +-------- > > > + > > > + mbox_mw_tx: mhu@10000000 { > > > + compatible = "arm,mhuv2","arm,primecell"; > > > + reg = <0x10000000 0x1000>; > > > + clocks = <&refclk100mhz>; > > > + clock-names = "apb_pclk"; > > > + #mbox-cells = <1>; > > > + mhu-protocol = "multi-word"; > > > + mhu-frame = "sender"; > > > + }; > > > + > > > + mbox_sw_tx: mhu@10000000 { > > > + compatible = "arm,mhuv2","arm,primecell"; > > > + reg = <0x11000000 0x1000>; > > > + clocks = <&refclk100mhz>; > > > + clock-names = "apb_pclk"; > > > + #mbox-cells = <1>; > > > + mhu-protocol = "single-word"; > > > + mhu-frame = "sender"; > > > + }; > > > + > > > + mbox_db_rx: mhu@10000000 { > > > + compatible = "arm,mhuv2","arm,primecell"; > > > + reg = <0x12000000 0x1000>; > > > + clocks = <&refclk100mhz>; > > > + clock-names = "apb_pclk"; > > > + #mbox-cells = <1>; > > > + interrupts = <0 45 4>; > > > + interrupt-names = "mhu_rx"; > > > + mhu-protocol = "doorbell"; > > > + mhu-frame = "receiver"; > > > + }; > > > + > > > + mhu_client: scb@2e000000 { > > > + compatible = "fujitsu,mb86s70-scb-1.0"; > > > + reg = <0 0x2e000000 0x4000>; > > > + mboxes = > > > + // For multi-word frames, client may only instantiate a single > > > + // mailbox for a mailbox controller > > > + <&mbox_mw_tx 0>, > > > + > > > + // For single-word frames, client may instantiate as many > > > + // mailboxes as there are channel windows in the MHU > > > + <&mbox_sw_tx 0>, > > > + <&mbox_sw_tx 1>, > > > + <&mbox_sw_tx 2>, > > > + <&mbox_sw_tx 3>, > > > + > > > + // For doorbell frames, client may instantiate as many mailboxes > > > + // as there are bits available in the combined number of channel > > > + // windows ((channel windows * 32) mailboxes) > > > + <mbox_db_rx 0>, > > > + <mbox_db_rx 1>, > > > + ... > > > + <mbox_db_rx 17>; > > > + }; > > > > If the mhuv2 instance implements, say, 3 channel windows between > > sender (linux) and receiver (firmware), and Linux runs two protocols > > each requiring 1 and 2-word sized messages respectively. The hardware > > supports that by assigning windows [0] and [1,2] to each protocol. > > However, I don't think the driver can support that. Or does it? > > > > FWIW, the IP is designed to cover wide range of usecase from IoT to servers > with variable window length. I don't see the need to complicate the driver > supporting mix-n-match at the cost of latency. Each platform choose one > transport protocol for all it's use. > > The driver design is to address the most probable scenarios and not all. > Single-word : Client gets one 32-bit window > Doorbell : Client gets 32 data pointers (arm_message) > Multi-word: Client gets all channels available in the platform. > > --Tushar > To elaborate for better understanding; arm_message is used when a mailbox client is to transmit data through an MHUv2 mailbox (ie. in-band transmission), wherein the MHUv2 is in a single-word or multi-word protocol mode. arm_message allows for a mailbox client to transmit data with arbitrary length, without having to know the technicalities of underlying transport protocol, number of MHU channels etc. As such, the mailbox client driver code may remain unchanged, if the underlying transport protocol is changed from ie. single-word to multi-word, or if more channel-windows are added to an MHUv2 device in multi-word mode. Transmission of data as well as maximum utilization of the available channel windows (in multi-word mode) is solely job for the MHUv2 driver. Given the differences between using an MHUv2 mailbox in single- and multi-word mode compared to doorbell mode, it is however expected that mailbox client driver code must be changed if switching from single- or multi-word to doorbell. As per the MHUv2 spec, when in doorbell mode, it is expected that the receiver and transmitter has decided beforehand both where data is placed in shared memory, as well as the format of this data. Here we do not require that arm_message is used, given that all data is transmitted out-of-band, and the MHUv2 is only used as an interrupt generating mechanism. To give an example of how arm_message may be used; Say, a client-driver protocol has been written as follows: > struct { > int cmd; > int[4] args; > } foo_t; Now, a client driver may transmit this through a mailbox which has an MHUv2 as the controller - we do not need to know the underlying transport protocol, just that it has to be either single- or multi word. > // Create user-specific protocol struct > foo_t foo; > > /* Modify foo with the data to be transmitted... */ > > /* Wrap message into arm_message format, so the MHUv2 driver knows how > much data to send*/ > > arm_message msg; > msg.data = &foo; > msg.len = sizeof(foo); > > /* Transmit the arm_message */ > mbox_send_message(mbox, &msg); > On the receiver side, there should be some accompanying logic in the client driver which is aware of foo_t and from this may reconstruct the received message. Reconstruction of a received message is a task for the mailbox client driver. - Morten
From: Morten Borup Petersen <morten.petersen@arm.com> This patch series adds a driver for the Arm MHU v2 device, with support for the 2.1 minor hardware revision. The Arm Message-Handling-Unit (MHU) Version 2 is a mailbox controller which facilitate unidirectional communication between processing element(s). Unidirectionality ================= Given the unidirectional nature of the device, an MHUv2 mailbox may only be written to or read from. If a pair of MHU devices is implemented between two processing elements to provide bidirectional communication, these must be specified as two separate mailboxes. This stands in contrast to the arm_mhu driver, which assumes that MHU (v1) devices always come in pairs and thus may be grouped into a single mailbox (and device tree entry). While it is expected that MHUv2 devices in most cases will be provided in pairs, this is _not_ a requirement, and thus the driver must be able to handle such cases. Transport Protocols =================== As opposed to the MHUv1 driver, MHUv2 adds support for three distinct transport protocols. Transport protocols define the method of which information is transmitted through the device, in terms of how hardware resources (channel windows) are used. The transport protocol determines how many mailbox channels the mailbox controller will allocate. - Single Word: In single-word mode, the mailbox controller will provide a mailbox for each channel window available in the MHU device. Transmitting and receiving data through the mailbox framework in single-word mode is done through a struct arm_mbox_msg. - Multi Word: In multi word mode, the mailbox controller will provide a _single_ mailbox. It is required that the MHU device has at least 2 channel windows available for the MHU to function in multi word mode. - Doorbell: In doorbell mode, the mailbox controller will provide a mailbox for each flag bit available in the combined number of channel windows available within the MHU device. Combined Interrupt (v2.1) ========================= The driver adds support for the combined receiver interrupt, introduced in the 2.1 hardware revision. The combined interrupt status registers are used when in single-word and doorbell transport protocol mode, to more quickly identify a channel window containing non-zero data. The combined interrupt status registers are not used in multi word mode, given that only a single channel window may raise a receiver interrupt in this mode. Device Tree Changes =================== Compared to the device tree entry for an MHUv1 device, the following changes exists for an MHUv2 device: - Frame type: A device tree node for an Arm MHUv2 device must specify either a receiver frame or a sender frame, indicating which end of the unidirectional MHU device which the device node entry describes. - Transport protocol: While the transport protocol for an MHU is software defined, transport protocol configuration is static and should be specified in the device tree. - reg: Given the unidirectional nature of the device, MHUv2 mandates that only a single reg entry is provided. This is a change from MHUv1, which specified two reg entries for tx and rx respectively. - irq: The MHUv2 driver adds support for a single interrupt for receiver frames. Thus, no irq property should be specified for sender frames. struct arm_mbox_msg =================== The MHUv2 driver differs significantly in terms of its integration with the common mailbox framework compared to MHUv1. The common mailbox framework provides a void* to pass data between a mailbox client and controller, when sending and receiving data. In MHUv1, given that it only provided an implementation of the single-word message protocol, this void* was used to pass the actual data which was to be transmitted. This was possible given that the size of the STAT register within the MHU is 4 bytes, identical to the size of a void* on 32-bit systems. Given the introduction of different transport protocols - mainly multi-word - this method of passing data between client and controller is insufficient. This is given that multi-word makes sense when a higher bandwidth is desired, at the sacrifice of mailbox channels. To utilize this bandwidth, it should therefore be possible to pass a notion of data length to the mailbox controller, which may then utilize its available resources to efficiently transmit the message. The arm_mbox_msg structure is provided, which is used to pass data- and length information between a mailbox client and mailbox controller, through the provided void* of the common mailbox frameworks send- and receive APIs. No message protocol is enforced through this structure - a utilizing mailbox client driver shall implement its own message protocol, which may then be transmitted through an arm_mbox_msg. Testing ======= The driver has been tested using an Arm fixed virtual platform (FVP). The driver has not been tested on hardware. ======== Cheers, Morten Morten Borup Petersen (4): mailbox: arm_mhuv2: add device tree binding documentation mailbox: arm_mhuv2: add arm mhuv2 driver mailbox: arm_mhuv2: add doorbell transport protocol operations mailbox: arm_mhuv2: add multi word transport protocol operations .../devicetree/bindings/mailbox/arm,mhuv2.txt | 108 ++ drivers/mailbox/Kconfig | 7 + drivers/mailbox/Makefile | 2 + drivers/mailbox/arm_mhu_v2.c | 1068 +++++++++++++++++ include/linux/mailbox/arm-mbox-message.h | 37 + 5 files changed, 1222 insertions(+) create mode 100644 Documentation/devicetree/bindings/mailbox/arm,mhuv2.txt create mode 100644 drivers/mailbox/arm_mhu_v2.c create mode 100644 include/linux/mailbox/arm-mbox-message.h -- 2.17.1