Master-aware devices and sideband ID data

[Will Deacon]

On Thu, Jul 16, 2015 at 02:34:41PM +0100, Mark Rutland wrote:
> Hi Will,

Hi Mark,

[adding David, since he's working on PCI/ITS stuff atm]

> The below is an attempt at an MSI binding, derived from my original
> example. It extends msi-parent inoto a phandle+(optional args) style
> property.
> 
> I haven't yet managed to come up with a sane way of describing
> the Bus-ID/BDF -> {iommu,msi}-cells translation, but this should
> hopefully cover the platform device case.
> 
> For the Bus-ID translation case I'm not sure it's sane to attempt to use
> msi-parent, given that the transformation description will necessarily
> have to describe the parents anyway.

We probably want a separate property on the RC node describing the
transformation (i.e. offsetting) in a similar way to ranges or
interrupt-map (potentially replacing msi-parent altogether). Maybe you
could propose something so that David could have a crack at describing
his RequesterID -> DeviceID mapping, which seems to map nicely onto a
per-RC offset IIUC.

David -- does that sound ok to you?

Will

> ---->8----
> From 429dca4bba98732c492e95bdf395aa2ccc634e69 Mon Sep 17 00:00:00 2001
> From: Mark Rutland <mark.rutland at arm.com>
> Date: Thu, 9 Jul 2015 17:53:00 +0100
> Subject: [PATCH] Documentation: dt: add generic MSI bindings
> 
> Currently msi-parent is in use in a couple of drviers despite being
> fairly underspecified. This patch adds a generic binding for MSIs
> (including the existing msi-parent property) enabling the description of
> platform devices capable of using MSIs.
> 
> This binding does not yet cover the general case. Currently the binding
> does not cover the relationship between bus IDs (e.g. PCIe BDF) and
> sideband data.
> 
> Signed-off-by: Mark Rutland <mark.rutland at arm.com>
> ---
>  .../bindings/interrupt-controller/msi.txt          | 135 +++++++++++++++++++++
>  1 file changed, 135 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/interrupt-controller/msi.txt
> 
> diff --git a/Documentation/devicetree/bindings/interrupt-controller/msi.txt b/Documentation/devicetree/bindings/interrupt-controller/msi.txt
> new file mode 100644
> index 0000000..c60c034
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/interrupt-controller/msi.txt
> @@ -0,0 +1,135 @@
> +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 at a {
> +		reg = <0xa 0xf00>;
> +		compatible = "vendor-a,some-controller";
> +		msi-controller;
> +		/* No sideband data, so #msi-cells omitted */
> +	};
> +
> +	msi_b: msi-controller at b {
> +		reg = <0xb 0xf00>;
> +		compatible = "vendor-b,another-controller";
> +		msi-controller;
> +		/* Each device has some unique ID */
> +		#msi-cells = <1>;
> +	};
> +
> +	msi_c: msi-controller at c {
> +		reg = <0xb 0xf00>;
> +		compatible = "vendor-b,another-controller";
> +		msi-controller;
> +		/* Each device has some unique ID */
> +		#msi-cells = <1>;
> +	};
> +
> +	dev at 0 {
> +		reg = <0x0 0xf00>;
> +		compatible = "vendor-c,some-device";
> +
> +		/* Can only generate MSIs to msi_a */
> +		msi-parent = <&msi_a>;
> +	};
> +
> +	dev at 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 at 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>;
> +	};
> +};
> -- 
> 1.9.1
>