Commit | Line | Data |
---|---|---|
05cbbc69 | 1 | MPC5200 Device Tree Bindings |
b1e253c4 GL |
2 | ---------------------------- |
3 | ||
05cbbc69 | 4 | (c) 2006-2007 Secret Lab Technologies Ltd |
b1e253c4 GL |
5 | Grant Likely <grant.likely at secretlab.ca> |
6 | ||
121361f7 GL |
7 | ********** DRAFT *********** |
8 | * WARNING: Do not depend on the stability of these bindings just yet. | |
9 | * The MPC5200 device tree conventions are still in flux | |
10 | * Keep an eye on the linuxppc-dev mailing list for more details | |
11 | ********** DRAFT *********** | |
12 | ||
b1e253c4 GL |
13 | I - Introduction |
14 | ================ | |
15 | Boards supported by the arch/powerpc architecture require device tree be | |
16 | passed by the boot loader to the kernel at boot time. The device tree | |
17 | describes what devices are present on the board and how they are | |
18 | connected. The device tree can either be passed as a binary blob (as | |
19 | described in Documentation/powerpc/booting-without-of.txt), or passed | |
01dd2fbf | 20 | by Open Firmware (IEEE 1275) compatible firmware using an OF compatible |
b1e253c4 GL |
21 | client interface API. |
22 | ||
05cbbc69 | 23 | This document specifies the requirements on the device-tree for mpc5200 |
b1e253c4 | 24 | based boards. These requirements are above and beyond the details |
01dd2fbf | 25 | specified in either the Open Firmware spec or booting-without-of.txt |
b1e253c4 | 26 | |
05cbbc69 | 27 | All new mpc5200-based boards are expected to match this document. In |
b1e253c4 GL |
28 | cases where this document is not sufficient to support a new board port, |
29 | this document should be updated as part of adding the new board support. | |
30 | ||
31 | II - Philosophy | |
32 | =============== | |
33 | The core of this document is naming convention. The whole point of | |
34 | defining this convention is to reduce or eliminate the number of | |
05cbbc69 GL |
35 | special cases required to support a 5200 board. If all 5200 boards |
36 | follow the same convention, then generic 5200 support code will work | |
b1e253c4 GL |
37 | rather than coding special cases for each new board. |
38 | ||
39 | This section tries to capture the thought process behind why the naming | |
40 | convention is what it is. | |
41 | ||
05cbbc69 GL |
42 | 1. names |
43 | --------- | |
b1e253c4 GL |
44 | There is strong convention/requirements already established for children |
45 | of the root node. 'cpus' describes the processor cores, 'memory' | |
46 | describes memory, and 'chosen' provides boot configuration. Other nodes | |
47 | are added to describe devices attached to the processor local bus. | |
05cbbc69 | 48 | |
b1e253c4 | 49 | Following convention already established with other system-on-chip |
05cbbc69 GL |
50 | processors, 5200 device trees should use the name 'soc5200' for the |
51 | parent node of on chip devices, and the root node should be its parent. | |
b1e253c4 | 52 | |
05cbbc69 GL |
53 | Child nodes are typically named after the configured function. ie. |
54 | the FEC node is named 'ethernet', and a PSC in uart mode is named 'serial'. | |
b1e253c4 GL |
55 | |
56 | 2. device_type property | |
57 | ----------------------- | |
58 | similar to the node name convention above; the device_type reflects the | |
59 | configured function of a device. ie. 'serial' for a uart and 'spi' for | |
60 | an spi controller. However, while node names *should* reflect the | |
61 | configured function, device_type *must* match the configured function | |
62 | exactly. | |
63 | ||
64 | 3. compatible property | |
65 | ---------------------- | |
66 | Since device_type isn't enough to match devices to drivers, there also | |
67 | needs to be a naming convention for the compatible property. Compatible | |
68 | is an list of device descriptions sorted from specific to generic. For | |
05cbbc69 GL |
69 | the mpc5200, the required format for each compatible value is |
70 | <chip>-<device>[-<mode>]. The OS should be able to match a device driver | |
71 | to the device based solely on the compatible value. If two drivers | |
72 | match on the compatible list; the 'most compatible' driver should be | |
73 | selected. | |
74 | ||
75 | The split between the MPC5200 and the MPC5200B leaves a bit of a | |
01dd2fbf ML |
76 | conundrum. How should the compatible property be set up to provide |
77 | maximum compatibility information; but still accurately describe the | |
05cbbc69 GL |
78 | chip? For the MPC5200; the answer is easy. Most of the SoC devices |
79 | originally appeared on the MPC5200. Since they didn't exist anywhere | |
80 | else; the 5200 compatible properties will contain only one item; | |
81 | "mpc5200-<device>". | |
82 | ||
83 | The 5200B is almost the same as the 5200, but not quite. It fixes | |
84 | silicon bugs and it adds a small number of enhancements. Most of the | |
85 | devices either provide exactly the same interface as on the 5200. A few | |
86 | devices have extra functions but still have a backwards compatible mode. | |
01dd2fbf | 87 | To express this information as completely as possible, 5200B device trees |
05cbbc69 GL |
88 | should have two items in the compatible list; |
89 | "mpc5200b-<device>\0mpc5200-<device>". It is *strongly* recommended | |
90 | that 5200B device trees follow this convention (instead of only listing | |
91 | the base mpc5200 item). | |
92 | ||
93 | If another chip appear on the market with one of the mpc5200 SoC | |
94 | devices, then the compatible list should include mpc5200-<device>. | |
95 | ||
96 | ie. ethernet on mpc5200: compatible = "mpc5200-ethernet" | |
97 | ethernet on mpc5200b: compatible = "mpc5200b-ethernet\0mpc5200-ethernet" | |
b1e253c4 GL |
98 | |
99 | Modal devices, like PSCs, also append the configured function to the | |
100 | end of the compatible field. ie. A PSC in i2s mode would specify | |
05cbbc69 | 101 | "mpc5200-psc-i2s", not "mpc5200-i2s". This convention is chosen to |
b1e253c4 | 102 | avoid naming conflicts with non-psc devices providing the same |
05cbbc69 | 103 | function. For example, "mpc5200-spi" and "mpc5200-psc-spi" describe |
b1e253c4 GL |
104 | the mpc5200 simple spi device and a PSC spi mode respectively. |
105 | ||
106 | If the soc device is more generic and present on other SOCs, the | |
107 | compatible property can specify the more generic device type also. | |
108 | ||
05cbbc69 | 109 | ie. mscan: compatible = "mpc5200-mscan\0fsl,mscan"; |
b1e253c4 GL |
110 | |
111 | At the time of writing, exact chip may be either 'mpc5200' or | |
112 | 'mpc5200b'. | |
113 | ||
114 | Device drivers should always try to match as generically as possible. | |
115 | ||
116 | III - Structure | |
117 | =============== | |
05cbbc69 | 118 | The device tree for an mpc5200 board follows the structure defined in |
b1e253c4 GL |
119 | booting-without-of.txt with the following additional notes: |
120 | ||
121 | 0) the root node | |
122 | ---------------- | |
123 | Typical root description node; see booting-without-of | |
124 | ||
125 | 1) The cpus node | |
126 | ---------------- | |
127 | The cpus node follows the basic layout described in booting-without-of. | |
128 | The bus-frequency property holds the XLB bus frequency | |
129 | The clock-frequency property holds the core frequency | |
130 | ||
131 | 2) The memory node | |
132 | ------------------ | |
133 | Typical memory description node; see booting-without-of. | |
134 | ||
135 | 3) The soc5200 node | |
136 | ------------------- | |
05cbbc69 | 137 | This node describes the on chip SOC peripherals. Every mpc5200 based |
b1e253c4 GL |
138 | board will have this node, and as such there is a common naming |
139 | convention for SOC devices. | |
140 | ||
141 | Required properties: | |
142 | name type description | |
143 | ---- ---- ----------- | |
144 | device_type string must be "soc" | |
145 | ranges int should be <0 baseaddr baseaddr+10000> | |
146 | reg int must be <baseaddr 10000> | |
05cbbc69 GL |
147 | compatible string mpc5200: "mpc5200-soc" |
148 | mpc5200b: "mpc5200b-soc\0mpc5200-soc" | |
149 | system-frequency int Fsystem frequency; source of all | |
150 | other clocks. | |
151 | bus-frequency int IPB bus frequency in HZ. Clock rate | |
152 | used by most of the soc devices. | |
153 | #interrupt-cells int must be <3>. | |
b1e253c4 GL |
154 | |
155 | Recommended properties: | |
156 | name type description | |
157 | ---- ---- ----------- | |
05cbbc69 GL |
158 | model string Exact model of the chip; |
159 | ie: model="fsl,mpc5200" | |
160 | revision string Silicon revision of chip | |
161 | ie: revision="M08A" | |
162 | ||
163 | The 'model' and 'revision' properties are *strongly* recommended. Having | |
164 | them presence acts as a bit of a safety net for working around as yet | |
165 | undiscovered bugs on one version of silicon. For example, device drivers | |
166 | can use the model and revision properties to decide if a bug fix should | |
167 | be turned on. | |
b1e253c4 GL |
168 | |
169 | 4) soc5200 child nodes | |
170 | ---------------------- | |
171 | Any on chip SOC devices available to Linux must appear as soc5200 child nodes. | |
172 | ||
05cbbc69 GL |
173 | Note: The tables below show the value for the mpc5200. A mpc5200b device |
174 | tree should use the "mpc5200b-<device>\0mpc5200-<device> form. | |
b1e253c4 GL |
175 | |
176 | Required soc5200 child nodes: | |
177 | name device_type compatible Description | |
178 | ---- ----------- ---------- ----------- | |
05cbbc69 GL |
179 | cdm@<addr> cdm mpc5200-cmd Clock Distribution |
180 | pic@<addr> interrupt-controller mpc5200-pic need an interrupt | |
b1e253c4 | 181 | controller to boot |
05cbbc69 GL |
182 | bestcomm@<addr> dma-controller mpc5200-bestcomm 5200 pic also requires |
183 | the bestcomm device | |
b1e253c4 GL |
184 | |
185 | Recommended soc5200 child nodes; populate as needed for your board | |
05cbbc69 GL |
186 | name device_type compatible Description |
187 | ---- ----------- ---------- ----------- | |
d24bc314 | 188 | gpt@<addr> gpt fsl,mpc5200-gpt General purpose timers |
05cbbc69 GL |
189 | rtc@<addr> rtc mpc5200-rtc Real time clock |
190 | mscan@<addr> mscan mpc5200-mscan CAN bus controller | |
191 | pci@<addr> pci mpc5200-pci PCI bridge | |
192 | serial@<addr> serial mpc5200-psc-uart PSC in serial mode | |
193 | i2s@<addr> sound mpc5200-psc-i2s PSC in i2s mode | |
194 | ac97@<addr> sound mpc5200-psc-ac97 PSC in ac97 mode | |
195 | spi@<addr> spi mpc5200-psc-spi PSC in spi mode | |
196 | irda@<addr> irda mpc5200-psc-irda PSC in IrDA mode | |
197 | spi@<addr> spi mpc5200-spi MPC5200 spi device | |
198 | ethernet@<addr> network mpc5200-fec MPC5200 ethernet device | |
199 | ata@<addr> ata mpc5200-ata IDE ATA interface | |
200 | i2c@<addr> i2c mpc5200-i2c I2C controller | |
201 | usb@<addr> usb-ohci-be mpc5200-ohci,ohci-be USB controller | |
01dd2fbf | 202 | xlb@<addr> xlb mpc5200-xlb XLB arbitrator |
05cbbc69 GL |
203 | |
204 | Important child node properties | |
205 | name type description | |
206 | ---- ---- ----------- | |
207 | cell-index int When multiple devices are present, is the | |
208 | index of the device in the hardware (ie. There | |
209 | are 6 PSC on the 5200 numbered PSC1 to PSC6) | |
210 | PSC1 has 'cell-index = <0>' | |
211 | PSC4 has 'cell-index = <3>' | |
212 | ||
213 | 5) General Purpose Timer nodes (child of soc5200 node) | |
214 | On the mpc5200 and 5200b, GPT0 has a watchdog timer function. If the board | |
215 | design supports the internal wdt, then the device node for GPT0 should | |
d24bc314 | 216 | include the empty property 'fsl,has-wdt'. |
05cbbc69 GL |
217 | |
218 | 6) PSC nodes (child of soc5200 node) | |
219 | PSC nodes can define the optional 'port-number' property to force assignment | |
220 | order of serial ports. For example, PSC5 might be physically connected to | |
221 | the port labeled 'COM1' and PSC1 wired to 'COM1'. In this case, PSC5 would | |
222 | have a "port-number = <0>" property, and PSC1 would have "port-number = <1>". | |
223 | ||
224 | PSC in i2s mode: The mpc5200 and mpc5200b PSCs are not compatible when in | |
225 | i2s mode. An 'mpc5200b-psc-i2s' node cannot include 'mpc5200-psc-i2s' in the | |
226 | compatible field. | |
b1e253c4 GL |
227 | |
228 | IV - Extra Notes | |
229 | ================ | |
230 | ||
231 | 1. Interrupt mapping | |
232 | -------------------- | |
05cbbc69 | 233 | The mpc5200 pic driver splits hardware IRQ numbers into two levels. The |
b1e253c4 GL |
234 | split reflects the layout of the PIC hardware itself, which groups |
235 | interrupts into one of three groups; CRIT, MAIN or PERP. Also, the | |
236 | Bestcomm dma engine has it's own set of interrupt sources which are | |
237 | cascaded off of peripheral interrupt 0, which the driver interprets as a | |
238 | fourth group, SDMA. | |
239 | ||
05cbbc69 | 240 | The interrupts property for device nodes using the mpc5200 pic consists |
b1e253c4 GL |
241 | of three cells; <L1 L2 level> |
242 | ||
243 | L1 := [CRIT=0, MAIN=1, PERP=2, SDMA=3] | |
244 | L2 := interrupt number; directly mapped from the value in the | |
245 | "ICTL PerStat, MainStat, CritStat Encoded Register" | |
246 | level := [LEVEL_HIGH=0, EDGE_RISING=1, EDGE_FALLING=2, LEVEL_LOW=3] | |
05cbbc69 GL |
247 | |
248 | 2. Shared registers | |
249 | ------------------- | |
250 | Some SoC devices share registers between them. ie. the i2c devices use | |
251 | a single clock control register, and almost all device are affected by | |
252 | the port_config register. Devices which need to manipulate shared regs | |
253 | should look to the parent SoC node. The soc node is responsible | |
254 | for arbitrating all shared register access. |