1* Freescale Management Complex
2
3The Freescale Management Complex (fsl-mc) is a hardware resource
4manager that manages specialized hardware objects used in
5network-oriented packet processing applications. After the fsl-mc
6block is enabled, pools of hardware resources are available, such as
7queues, buffer pools, I/O interfaces. These resources are building
8blocks that can be used to create functional hardware objects/devices
9such as network interfaces, crypto accelerator instances, L2 switches,
10etc.
11
12For an overview of the DPAA2 architecture and fsl-mc bus see:
13Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst
14
15As described in the above overview, all DPAA2 objects in a DPRC share the
16same hardware "isolation context" and a 10-bit value called an ICID
17(isolation context id) is expressed by the hardware to identify
18the requester.
19
20The generic 'iommus' property is insufficient to describe the relationship
21between ICIDs and IOMMUs, so an iommu-map property is used to define
22the set of possible ICIDs under a root DPRC and how they map to
23an IOMMU.
24
25For generic IOMMU bindings, see
26Documentation/devicetree/bindings/iommu/iommu.txt.
27
28For arm-smmu binding, see:
29Documentation/devicetree/bindings/iommu/arm,smmu.yaml.
30
31The MSI writes are accompanied by sideband data which is derived from the ICID.
32The msi-map property is used to associate the devices with both the ITS
33controller and the sideband data which accompanies the writes.
34
35For generic MSI bindings, see
36Documentation/devicetree/bindings/interrupt-controller/msi.txt.
37
38For GICv3 and GIC ITS bindings, see:
39Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml.
40
41Required properties:
42
43    - compatible
44        Value type: <string>
45        Definition: Must be "fsl,qoriq-mc".  A Freescale Management Complex
46                    compatible with this binding must have Block Revision
47                    Registers BRR1 and BRR2 at offset 0x0BF8 and 0x0BFC in
48                    the MC control register region.
49
50    - reg
51        Value type: <prop-encoded-array>
52        Definition: A standard property.  Specifies one or two regions
53                    defining the MC's registers:
54
55                       -the first region is the command portal for the
56                        this machine and must always be present
57
58                       -the second region is the MC control registers. This
59                        region may not be present in some scenarios, such
60                        as in the device tree presented to a virtual machine.
61
62    - ranges
63        Value type: <prop-encoded-array>
64        Definition: A standard property.  Defines the mapping between the child
65                    MC address space and the parent system address space.
66
67                    The MC address space is defined by 3 components:
68                       <region type> <offset hi> <offset lo>
69
70                    Valid values for region type are
71                       0x0 - MC portals
72                       0x1 - QBMAN portals
73
74    - #address-cells
75        Value type: <u32>
76        Definition: Must be 3.  (see definition in 'ranges' property)
77
78    - #size-cells
79        Value type: <u32>
80        Definition: Must be 1.
81
82Sub-nodes:
83
84        The fsl-mc node may optionally have dpmac sub-nodes that describe
85        the relationship between the Ethernet MACs which belong to the MC
86        and the Ethernet PHYs on the system board.
87
88        The dpmac nodes must be under a node named "dpmacs" which contains
89        the following properties:
90
91            - #address-cells
92              Value type: <u32>
93              Definition: Must be present if dpmac sub-nodes are defined and must
94                          have a value of 1.
95
96            - #size-cells
97              Value type: <u32>
98              Definition: Must be present if dpmac sub-nodes are defined and must
99                          have a value of 0.
100
101        These nodes must have the following properties:
102
103            - compatible
104              Value type: <string>
105              Definition: Must be "fsl,qoriq-mc-dpmac".
106
107            - reg
108              Value type: <prop-encoded-array>
109              Definition: Specifies the id of the dpmac.
110
111            - phy-handle
112              Value type: <phandle>
113              Definition: Specifies the phandle to the PHY device node associated
114                          with the this dpmac.
115Optional properties:
116
117- iommu-map: Maps an ICID to an IOMMU and associated iommu-specifier
118  data.
119
120  The property is an arbitrary number of tuples of
121  (icid-base,iommu,iommu-base,length).
122
123  Any ICID i in the interval [icid-base, icid-base + length) is
124  associated with the listed IOMMU, with the iommu-specifier
125  (i - icid-base + iommu-base).
126
127- msi-map: Maps an ICID to a GIC ITS and associated msi-specifier
128  data.
129
130  The property is an arbitrary number of tuples of
131  (icid-base,gic-its,msi-base,length).
132
133  Any ICID in the interval [icid-base, icid-base + length) is
134  associated with the listed GIC ITS, with the msi-specifier
135  (i - icid-base + msi-base).
136
137Deprecated properties:
138
139    - msi-parent
140        Value type: <phandle>
141        Definition: Describes the MSI controller node handling message
142                    interrupts for the MC. When there is no translation
143                    between the ICID and deviceID this property can be used
144                    to describe the MSI controller used by the devices on the
145                    mc-bus.
146                    The use of this property for mc-bus is deprecated. Please
147                    use msi-map.
148
149Example:
150
151        smmu: iommu@5000000 {
152               compatible = "arm,mmu-500";
153               #iommu-cells = <1>;
154               stream-match-mask = <0x7C00>;
155               ...
156        };
157
158        gic: interrupt-controller@6000000 {
159               compatible = "arm,gic-v3";
160               ...
161        }
162        its: gic-its@6020000 {
163               compatible = "arm,gic-v3-its";
164               msi-controller;
165               ...
166        };
167
168        fsl_mc: fsl-mc@80c000000 {
169                compatible = "fsl,qoriq-mc";
170                reg = <0x00000008 0x0c000000 0 0x40>,    /* MC portal base */
171                      <0x00000000 0x08340000 0 0x40000>; /* MC control reg */
172                /* define map for ICIDs 23-64 */
173                iommu-map = <23 &smmu 23 41>;
174                /* define msi map for ICIDs 23-64 */
175                msi-map = <23 &its 23 41>;
176                #address-cells = <3>;
177                #size-cells = <1>;
178
179                /*
180                 * Region type 0x0 - MC portals
181                 * Region type 0x1 - QBMAN portals
182                 */
183                ranges = <0x0 0x0 0x0 0x8 0x0c000000 0x4000000
184                          0x1 0x0 0x0 0x8 0x18000000 0x8000000>;
185
186                dpmacs {
187                    #address-cells = <1>;
188                    #size-cells = <0>;
189
190                    dpmac@1 {
191                        compatible = "fsl,qoriq-mc-dpmac";
192                        reg = <1>;
193                        phy-handle = <&mdio0_phy0>;
194                    }
195                }
196        };
197