0001 This document describes the generic device tree binding for describing the
0002 relationship between PCI(e) devices and IOMMU(s).
0003
0004 Each PCI(e) device under a root complex is uniquely identified by its Requester
0005 ID (AKA RID). A Requester ID is a triplet of a Bus number, Device number, and
0006 Function number.
0007
0008 For the purpose of this document, when treated as a numeric value, a RID is
0009 formatted such that:
0010
0011 * Bits [15:8] are the Bus number.
0012 * Bits [7:3] are the Device number.
0013 * Bits [2:0] are the Function number.
0014 * Any other bits required for padding must be zero.
0015
0016 IOMMUs may distinguish PCI devices through sideband data derived from the
0017 Requester ID. While a given PCI device can only master through one IOMMU, a
0018 root complex may split masters across a set of IOMMUs (e.g. with one IOMMU per
0019 bus).
0020
0021 The generic 'iommus' property is insufficient to describe this relationship,
0022 and a mechanism is required to map from a PCI device to its IOMMU and sideband
0023 data.
0024
0025 For generic IOMMU bindings, see
0026 Documentation/devicetree/bindings/iommu/iommu.txt.
0027
0028
0029 PCI root complex
0030 ================
0031
0032 Optional properties
0033 -------------------
0034
0035 - iommu-map: Maps a Requester ID to an IOMMU and associated IOMMU specifier
0036 data.
0037
0038 The property is an arbitrary number of tuples of
0039 (rid-base,iommu,iommu-base,length).
0040
0041 Any RID r in the interval [rid-base, rid-base + length) is associated with
0042 the listed IOMMU, with the IOMMU specifier (r - rid-base + iommu-base).
0043
0044 - iommu-map-mask: A mask to be applied to each Requester ID prior to being
0045 mapped to an IOMMU specifier per the iommu-map property.
0046
0047
0048 Example (1)
0049 ===========
0050
0051 / {
0052 #address-cells = <1>;
0053 #size-cells = <1>;
0054
0055 iommu: iommu@a {
0056 reg = <0xa 0x1>;
0057 compatible = "vendor,some-iommu";
0058 #iommu-cells = <1>;
0059 };
0060
0061 pci: pci@f {
0062 reg = <0xf 0x1>;
0063 compatible = "vendor,pcie-root-complex";
0064 device_type = "pci";
0065
0066 /*
0067 * The sideband data provided to the IOMMU is the RID,
0068 * identity-mapped.
0069 */
0070 iommu-map = <0x0 &iommu 0x0 0x10000>;
0071 };
0072 };
0073
0074
0075 Example (2)
0076 ===========
0077
0078 / {
0079 #address-cells = <1>;
0080 #size-cells = <1>;
0081
0082 iommu: iommu@a {
0083 reg = <0xa 0x1>;
0084 compatible = "vendor,some-iommu";
0085 #iommu-cells = <1>;
0086 };
0087
0088 pci: pci@f {
0089 reg = <0xf 0x1>;
0090 compatible = "vendor,pcie-root-complex";
0091 device_type = "pci";
0092
0093 /*
0094 * The sideband data provided to the IOMMU is the RID with the
0095 * function bits masked out.
0096 */
0097 iommu-map = <0x0 &iommu 0x0 0x10000>;
0098 iommu-map-mask = <0xfff8>;
0099 };
0100 };
0101
0102
0103 Example (3)
0104 ===========
0105
0106 / {
0107 #address-cells = <1>;
0108 #size-cells = <1>;
0109
0110 iommu: iommu@a {
0111 reg = <0xa 0x1>;
0112 compatible = "vendor,some-iommu";
0113 #iommu-cells = <1>;
0114 };
0115
0116 pci: pci@f {
0117 reg = <0xf 0x1>;
0118 compatible = "vendor,pcie-root-complex";
0119 device_type = "pci";
0120
0121 /*
0122 * The sideband data provided to the IOMMU is the RID,
0123 * but the high bits of the bus number are flipped.
0124 */
0125 iommu-map = <0x0000 &iommu 0x8000 0x8000>,
0126 <0x8000 &iommu 0x0000 0x8000>;
0127 };
0128 };
0129
0130
0131 Example (4)
0132 ===========
0133
0134 / {
0135 #address-cells = <1>;
0136 #size-cells = <1>;
0137
0138 iommu_a: iommu@a {
0139 reg = <0xa 0x1>;
0140 compatible = "vendor,some-iommu";
0141 #iommu-cells = <1>;
0142 };
0143
0144 iommu_b: iommu@b {
0145 reg = <0xb 0x1>;
0146 compatible = "vendor,some-iommu";
0147 #iommu-cells = <1>;
0148 };
0149
0150 iommu_c: iommu@c {
0151 reg = <0xc 0x1>;
0152 compatible = "vendor,some-iommu";
0153 #iommu-cells = <1>;
0154 };
0155
0156 pci: pci@f {
0157 reg = <0xf 0x1>;
0158 compatible = "vendor,pcie-root-complex";
0159 device_type = "pci";
0160
0161 /*
0162 * Devices with bus number 0-127 are mastered via IOMMU
0163 * a, with sideband data being RID[14:0].
0164 * Devices with bus number 128-255 are mastered via
0165 * IOMMU b, with sideband data being RID[14:0].
0166 * No devices master via IOMMU c.
0167 */
0168 iommu-map = <0x0000 &iommu_a 0x0000 0x8000>,
0169 <0x8000 &iommu_b 0x0000 0x8000>;
0170 };
0171 };
