136 lines
3.8 KiB
Plaintext
Executable file
136 lines
3.8 KiB
Plaintext
Executable file
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
|
|
must be described with additional properties.
|
|
|
|
When #msi-cells is non-zero, busses with an msi-parent will require
|
|
additional properties to describe the relationship between devices on the bus
|
|
and the set of MSIs they can potentially generate.
|
|
|
|
|
|
Example
|
|
=======
|
|
|
|
/ {
|
|
#address-cells = <1>;
|
|
#size-cells = <1>;
|
|
|
|
msi_a: msi-controller@a {
|
|
reg = <0xa 0xf00>;
|
|
compatible = "vendor-a,some-controller";
|
|
msi-controller;
|
|
/* No sideband data, so #msi-cells omitted */
|
|
};
|
|
|
|
msi_b: msi-controller@b {
|
|
reg = <0xb 0xf00>;
|
|
compatible = "vendor-b,another-controller";
|
|
msi-controller;
|
|
/* Each device has some unique ID */
|
|
#msi-cells = <1>;
|
|
};
|
|
|
|
msi_c: msi-controller@c {
|
|
reg = <0xb 0xf00>;
|
|
compatible = "vendor-b,another-controller";
|
|
msi-controller;
|
|
/* Each device has some unique ID */
|
|
#msi-cells = <1>;
|
|
};
|
|
|
|
dev@0 {
|
|
reg = <0x0 0xf00>;
|
|
compatible = "vendor-c,some-device";
|
|
|
|
/* Can only generate MSIs to msi_a */
|
|
msi-parent = <&msi_a>;
|
|
};
|
|
|
|
dev@1 {
|
|
reg = <0x1 0xf00>;
|
|
compatible = "vendor-c,some-device";
|
|
|
|
/*
|
|
* Can generate MSIs to either A or B.
|
|
*/
|
|
msi-parent = <&msi_a>, <&msi_b 0x17>;
|
|
};
|
|
|
|
dev@2 {
|
|
reg = <0x2 0xf00>;
|
|
compatible = "vendor-c,some-device";
|
|
/*
|
|
* Has different IDs at each MSI controller.
|
|
* Can generate MSIs to all of the MSI controllers.
|
|
*/
|
|
msi-parent = <&msi_a>, <&msi_b 0x17>, <&msi_c 0x53>;
|
|
};
|
|
};
|