On 23/07/15 17:52, Mark Rutland wrote:
Currently msi-parent is used by a few bindings to describe the
relationship between a PCI root complex and a single MSI controller, but
this property does not have a generic binding document.
Additionally, msi-parent is insufficient to describe more complex
relationships between MSI controllers and devices under a root complex,
where devices may be able to target multiple MSI controllers, or where
MSI controllers use (non-probeable) sideband information to distinguish
This patch adds a generic binding for mapping PCI devices to MSI
controllers. This document covers msi-parent, and a new msi-map property
(specific to PCI*) which may be used to map devices (identified by their
Requester ID) to sideband data for each MSI controller that they may
Signed-off-by: Mark Rutland <mark.rutland@xxxxxxx>
Documentation/devicetree/bindings/pci/pci-msi.txt | 220 ++++++++++++++++++++++
1 file changed, 220 insertions(+)
create mode 100644 Documentation/devicetree/bindings/pci/pci-msi.txt
diff --git a/Documentation/devicetree/bindings/pci/pci-msi.txt b/Documentation/devicetree/bindings/pci/pci-msi.txt
new file mode 100644
@@ -0,0 +1,220 @@
+This document describes the generic device tree binding for describing the
+relationship between PCI devices and MSI controllers.
+Each PCI device under a root complex is uniquely identified by its Requester ID
+(AKA RID). A Requester ID is a triplet of a Bus number, Device number, and
+For the purpose of this document, when treated as a numeric value, a RID is
+formatted such that:
+* Bits [15:8] are the Bus number.
+* Bits [7:3] are the Device number.
+* Bits [2:0] are the Function number.
+* Any other bits required for padding must be zero.
+MSIs may be distinguished in part through the use of sideband data accompanying
+writes. In the case of PCI devices, this sideband data may be derived from the
+Requester ID. A mechanism is required to associate a device with both the MSI
+controllers it can address, and the sideband data that will be associated with
+its writes to those controllers.
+For generic MSI bindings, see
+PCI root complex
+- msi-map: Maps a Requester ID to an MSI controller and associated
+ msi-specifier data. The property is an arbitrary number of tuples of
+ (rid-base,msi-controller,msi-base,length), where:
+ * rid-base is a single cell describing the first RID matched by the entry.
+ * msi-controller is a single phandle to an MSI controller
+ * msi-base is an msi-specifier describing the msi-specifier produced for the
+ first RID matched by the entry.
+ * length is a single cell describing how many consecutive RIDs are matched
+ following the rid-base.
+ Any RID r in the interval [rid-base, rid-base + length) is associated with
+ the listed msi-controller, with the msi-specifier (r - rid-base + msi-base).
+- msi-map-mask: A mask to be applied to each Requester ID prior to being mapped
+ to an msi-specifier per the msi-map property.
+- msi-parent: Describes the MSI parent of the root complex itself. Where
+ the root complex and MSI controller do not pass sideband data with MSI
+ writes, this property may be used to describe the MSI controller(s)
+ used by PCI devices under the root complex, if defined as such in the
+ binding for the root complex.
Right, this is where I'd expect some details about #msi-cells. Is it
meant to be ignored? The lack of symmetry between the PCI and non-PCI
use cases feels a bit inelegant (not to mention that it precludes having
an unified parser for both cases).
This otherwise looks good to me.