mirror of https://github.com/Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
135 lines
3.8 KiB
135 lines
3.8 KiB
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 = <0xc 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>; |
|
}; |
|
};
|
|
|