mirror of
https://github.com/torvalds/linux.git
synced 2024-12-25 20:32:22 +00:00
b531566e4d
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 devices. 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 target. Acked-by: Marc Zyngier <marc.zyngier@arm.com> Acked-by: Rob Herring <robh@kernel.org> Signed-off-by: Mark Rutland <mark.rutland@arm.com> Signed-off-by: David Daney <david.daney@cavium.com> Signed-off-by: Marc Zyngier <marc.zyngier@arm.com>
221 lines
5.0 KiB
Plaintext
221 lines
5.0 KiB
Plaintext
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
|
|
Function number.
|
|
|
|
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
|
|
Documentation/devicetree/bindings/interrupt-controller/msi.txt.
|
|
|
|
|
|
PCI root complex
|
|
================
|
|
|
|
Optional properties
|
|
-------------------
|
|
|
|
- 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.
|
|
|
|
|
|
Example (1)
|
|
===========
|
|
|
|
/ {
|
|
#address-cells = <1>;
|
|
#size-cells = <1>;
|
|
|
|
msi: msi-controller@a {
|
|
reg = <0xa 0x1>;
|
|
compatible = "vendor,some-controller";
|
|
msi-controller;
|
|
#msi-cells = <1>;
|
|
};
|
|
|
|
pci: pci@f {
|
|
reg = <0xf 0x1>;
|
|
compatible = "vendor,pcie-root-complex";
|
|
device_type = "pci";
|
|
|
|
/*
|
|
* The sideband data provided to the MSI controller is
|
|
* the RID, identity-mapped.
|
|
*/
|
|
msi-map = <0x0 &msi_a 0x0 0x10000>,
|
|
};
|
|
};
|
|
|
|
|
|
Example (2)
|
|
===========
|
|
|
|
/ {
|
|
#address-cells = <1>;
|
|
#size-cells = <1>;
|
|
|
|
msi: msi-controller@a {
|
|
reg = <0xa 0x1>;
|
|
compatible = "vendor,some-controller";
|
|
msi-controller;
|
|
#msi-cells = <1>;
|
|
};
|
|
|
|
pci: pci@f {
|
|
reg = <0xf 0x1>;
|
|
compatible = "vendor,pcie-root-complex";
|
|
device_type = "pci";
|
|
|
|
/*
|
|
* The sideband data provided to the MSI controller is
|
|
* the RID, masked to only the device and function bits.
|
|
*/
|
|
msi-map = <0x0 &msi_a 0x0 0x100>,
|
|
msi-map-mask = <0xff>
|
|
};
|
|
};
|
|
|
|
|
|
Example (3)
|
|
===========
|
|
|
|
/ {
|
|
#address-cells = <1>;
|
|
#size-cells = <1>;
|
|
|
|
msi: msi-controller@a {
|
|
reg = <0xa 0x1>;
|
|
compatible = "vendor,some-controller";
|
|
msi-controller;
|
|
#msi-cells = <1>;
|
|
};
|
|
|
|
pci: pci@f {
|
|
reg = <0xf 0x1>;
|
|
compatible = "vendor,pcie-root-complex";
|
|
device_type = "pci";
|
|
|
|
/*
|
|
* The sideband data provided to the MSI controller is
|
|
* the RID, but the high bit of the bus number is
|
|
* ignored.
|
|
*/
|
|
msi-map = <0x0000 &msi 0x0000 0x8000>,
|
|
<0x8000 &msi 0x0000 0x8000>;
|
|
};
|
|
};
|
|
|
|
|
|
Example (4)
|
|
===========
|
|
|
|
/ {
|
|
#address-cells = <1>;
|
|
#size-cells = <1>;
|
|
|
|
msi: msi-controller@a {
|
|
reg = <0xa 0x1>;
|
|
compatible = "vendor,some-controller";
|
|
msi-controller;
|
|
#msi-cells = <1>;
|
|
};
|
|
|
|
pci: pci@f {
|
|
reg = <0xf 0x1>;
|
|
compatible = "vendor,pcie-root-complex";
|
|
device_type = "pci";
|
|
|
|
/*
|
|
* The sideband data provided to the MSI controller is
|
|
* the RID, but the high bit of the bus number is
|
|
* negated.
|
|
*/
|
|
msi-map = <0x0000 &msi 0x8000 0x8000>,
|
|
<0x8000 &msi 0x0000 0x8000>;
|
|
};
|
|
};
|
|
|
|
|
|
Example (5)
|
|
===========
|
|
|
|
/ {
|
|
#address-cells = <1>;
|
|
#size-cells = <1>;
|
|
|
|
msi_a: msi-controller@a {
|
|
reg = <0xa 0x1>;
|
|
compatible = "vendor,some-controller";
|
|
msi-controller;
|
|
#msi-cells = <1>;
|
|
};
|
|
|
|
msi_b: msi-controller@b {
|
|
reg = <0xb 0x1>;
|
|
compatible = "vendor,some-controller";
|
|
msi-controller;
|
|
#msi-cells = <1>;
|
|
};
|
|
|
|
msi_c: msi-controller@c {
|
|
reg = <0xc 0x1>;
|
|
compatible = "vendor,some-controller";
|
|
msi-controller;
|
|
#msi-cells = <1>;
|
|
};
|
|
|
|
pci: pci@c {
|
|
reg = <0xf 0x1>;
|
|
compatible = "vendor,pcie-root-complex";
|
|
device_type = "pci";
|
|
|
|
/*
|
|
* The sideband data provided to MSI controller a is the
|
|
* RID, but the high bit of the bus number is negated.
|
|
* The sideband data provided to MSI controller b is the
|
|
* RID, identity-mapped.
|
|
* MSI controller c is not addressable.
|
|
*/
|
|
msi-map = <0x0000 &msi_a 0x8000 0x08000>,
|
|
<0x8000 &msi_a 0x0000 0x08000>,
|
|
<0x0000 &msi_b 0x0000 0x10000>;
|
|
};
|
|
};
|