Documentation/devicetree/bindings/interrupt-controller/msi.txt

Source file repositories/reference/linux-study-clean/Documentation/devicetree/bindings/interrupt-controller/msi.txt

File Facts

System
Linux kernel
Corpus path
Documentation/devicetree/bindings/interrupt-controller/msi.txt
Extension
.txt
Size
3852 bytes
Lines
136
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
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

This document describes the generic device tree binding for MSI controllers and
their master(s).

Message Signaled Interrupts (MSIs) are a class of interrupts generated by a
write to an MMIO address.

MSIs were originally specified by PCI (and are used with PCIe), but may also be
used with other busses, and hence a mechanism is required to relate devices on
those busses to the MSI controllers which they are capable of using,
potentially including additional information.

MSIs are distinguished by some combination of:

- The doorbell (the MMIO address written to).
  
  Devices may be configured by software to write to arbitrary doorbells which
  they can address. An MSI controller may feature a number of doorbells.

- The payload (the value written to the doorbell).
  
  Devices may be configured to write an arbitrary payload chosen by software.
  MSI controllers may have restrictions on permitted payloads.

- Sideband information accompanying the write.
  
  Typically this is neither configurable nor probeable, and depends on the path
  taken through the memory system (i.e. it is a property of the combination of
  MSI controller and device rather than a property of either in isolation).


MSI controllers:
================

An MSI controller signals interrupts to a CPU when a write is made to an MMIO
address by some master. An MSI controller may feature a number of doorbells.

Required properties:
--------------------

- msi-controller: Identifies the node as an MSI controller.

Optional properties:
--------------------

- #msi-cells: The number of cells in an msi-specifier, required if not zero.

  Typically this will encode information related to sideband data, and will
  not encode doorbells or payloads as these can be configured dynamically.

  The meaning of the msi-specifier is defined by the device tree binding of
  the specific MSI controller. 


MSI clients
===========

MSI clients are devices which generate MSIs. For each MSI they wish to
generate, the doorbell and payload may be configured, though sideband
information may not be configurable.

Required properties:
--------------------

- msi-parent: A list of phandle + msi-specifier pairs, one for each MSI
  controller which the device is capable of using.

  This property is unordered, and MSIs may be allocated from any combination of
  MSI controllers listed in the msi-parent property.

  If a device has restrictions on the allocation of MSIs, these restrictions

Annotation

Implementation Notes