| Message ID | 1444342250-6196-2-git-send-email-ddaney.cavm@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Thu, Oct 8, 2015 at 5:10 PM, David Daney <ddaney.cavm@gmail.com> wrote: > From: Mark Rutland <mark.rutland@arm.com> > > 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> > Signed-off-by: Mark Rutland <mark.rutland@arm.com> > Signed-off-by: David Daney <david.daney@cavium.com> I acked v3. Please add it so I can stop paying attention. Rob > --- > 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 > index 0000000..9b3cc81 > --- /dev/null > +++ b/Documentation/devicetree/bindings/pci/pci-msi.txt > @@ -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 > +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>; > + }; > +}; > -- > 1.9.1 >
On 10/09/2015 06:20 AM, Rob Herring wrote: > On Thu, Oct 8, 2015 at 5:10 PM, David Daney <ddaney.cavm@gmail.com> wrote: >> From: Mark Rutland <mark.rutland@arm.com> >> >> 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> >> Signed-off-by: Mark Rutland <mark.rutland@arm.com> >> Signed-off-by: David Daney <david.daney@cavium.com> > > I acked v3. Please add it so I can stop paying attention. > My apologies for missing that. The Acked-by is now in my local tree. Can the MSI maintainer take it as is and add your Acked-by? If not, I can resend with this added. Thanks for taking the time to review it, David Daney
On Fri, Oct 9, 2015 at 11:12 AM, David Daney <ddaney@caviumnetworks.com> wrote: > On 10/09/2015 06:20 AM, Rob Herring wrote: >> >> On Thu, Oct 8, 2015 at 5:10 PM, David Daney <ddaney.cavm@gmail.com> wrote: >>> >>> From: Mark Rutland <mark.rutland@arm.com> >>> >>> 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> >>> Signed-off-by: Mark Rutland <mark.rutland@arm.com> >>> Signed-off-by: David Daney <david.daney@cavium.com> >> >> >> I acked v3. Please add it so I can stop paying attention. >> > > My apologies for missing that. > > The Acked-by is now in my local tree. Can the MSI maintainer take it as is > and add your Acked-by? If not, I can resend with this added. Usually they should pick up acks on the current version, but not previous versions. Given the discussion here though, that should be enough. IOW, don't resend stuff just to add acks. Rob
diff --git a/Documentation/devicetree/bindings/pci/pci-msi.txt b/Documentation/devicetree/bindings/pci/pci-msi.txt new file mode 100644 index 0000000..9b3cc81 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/pci-msi.txt @@ -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 +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>; + }; +};