Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml

Source file repositories/reference/linux-study-clean/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml

File Facts

System
Linux kernel
Corpus path
Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml
Extension
.yaml
Size
10012 bytes
Lines
225
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: configuration, schema, or hardware description
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

# 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

Annotation

Implementation Notes