Hi Mark,
On 23/07/15 17:52, Mark Rutland wrote:
> Currently msi-parent is used in a couple of drivers 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.
>
> While MSIs are primarily distinguished by doorbell and payload, some MSI
> controllers (e.g. the GICv3 ITS) also use side-band information
> accompanying the write to identify the master which originated the MSI,
> to allow for sandboxing. This sideband information is non-probeable and
> needs to be described in the DT. Other MSI controllers may have
> additional configuration details which need to be described per-master.
>
> This patch adds a generic msi-parent binding document, extending the
> de-facto standard with a new (optional) #msi-cells which can be used to
> express any per-master configuration and/or sideband data. This is
> sufficient to describe non-hotpluggable devices.
>
> For busses where sideband data may be derived from some bus-specific
> master ID scheme, other properties will be required to describe the
> mapping.
>
> Signed-off-by: Mark Rutland <mark.rutland@xxxxxxx>
> ---
> .../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@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 = <0xb 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>;
> + };
> +};
>
This looks quite good for the non-PCI stuff. Should you also cover the
PCI usage of msi-parent? I'm can't really see the meaning of #msi-cells
in that context. Should it be entirely ignored? OR did you have some
specific usage in mind?
Thanks,
M.
--
Jazz is not dead. It just smells funny...
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
