aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2009-02-02 22:26:44 -0500
committerLinus Torvalds <torvalds@linux-foundation.org>2009-02-02 22:26:44 -0500
commit93bfbd71db4d2e01c05e219f285249a74808b1d4 (patch)
tree43f38899aaa2af9169146b6523d094be299ccc60 /Documentation
parent31c952dcf83d5b0fd57b514cbe8a1664647c26e7 (diff)
parent7fbb7cadd062baf299fd8b26a80ea99da0c3fe01 (diff)
Merge branch 'merge' of git://git.kernel.org/pub/scm/linux/kernel/git/benh/powerpc
* 'merge' of git://git.kernel.org/pub/scm/linux/kernel/git/benh/powerpc: fbdev/atyfb: Fix DSP config on some PowerMacs & PowerBooks powerpc: Fix oops on some machines due to incorrect pr_debug() powerpc/ps3: Printing fixups for l64 to ll64 convserion drivers/net powerpc/5200: update device tree binding documentation powerpc/5200: Bugfix for PCI mapping of memory and IMMR powerpc/5200: update defconfigs
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/powerpc/dts-bindings/fsl/mpc5200.txt180
-rw-r--r--Documentation/powerpc/mpc52xx-device-tree-bindings.txt277
2 files changed, 180 insertions, 277 deletions
diff --git a/Documentation/powerpc/dts-bindings/fsl/mpc5200.txt b/Documentation/powerpc/dts-bindings/fsl/mpc5200.txt
new file mode 100644
index 000000000000..8447fd7090d0
--- /dev/null
+++ b/Documentation/powerpc/dts-bindings/fsl/mpc5200.txt
@@ -0,0 +1,180 @@
1MPC5200 Device Tree Bindings
2----------------------------
3
4(c) 2006-2009 Secret Lab Technologies Ltd
5Grant Likely <grant.likely@secretlab.ca>
6
7Naming conventions
8------------------
9For mpc5200 on-chip devices, the format for each compatible value is
10<chip>-<device>[-<mode>]. The OS should be able to match a device driver
11to the device based solely on the compatible value. If two drivers
12match on the compatible list; the 'most compatible' driver should be
13selected.
14
15The split between the MPC5200 and the MPC5200B leaves a bit of a
16conundrum. How should the compatible property be set up to provide
17maximum compatibility information; but still accurately describe the
18chip? For the MPC5200; the answer is easy. Most of the SoC devices
19originally appeared on the MPC5200. Since they didn't exist anywhere
20else; the 5200 compatible properties will contain only one item;
21"fsl,mpc5200-<device>".
22
23The 5200B is almost the same as the 5200, but not quite. It fixes
24silicon bugs and it adds a small number of enhancements. Most of the
25devices either provide exactly the same interface as on the 5200. A few
26devices have extra functions but still have a backwards compatible mode.
27To express this information as completely as possible, 5200B device trees
28should have two items in the compatible list:
29 compatible = "fsl,mpc5200b-<device>","fsl,mpc5200-<device>";
30
31It is *strongly* recommended that 5200B device trees follow this convention
32(instead of only listing the base mpc5200 item).
33
34ie. ethernet on mpc5200: compatible = "fsl,mpc5200-fec";
35 ethernet on mpc5200b: compatible = "fsl,mpc5200b-fec", "fsl,mpc5200-fec";
36
37Modal devices, like PSCs, also append the configured function to the
38end of the compatible field. ie. A PSC in i2s mode would specify
39"fsl,mpc5200-psc-i2s", not "fsl,mpc5200-i2s". This convention is chosen to
40avoid naming conflicts with non-psc devices providing the same
41function. For example, "fsl,mpc5200-spi" and "fsl,mpc5200-psc-spi" describe
42the mpc5200 simple spi device and a PSC spi mode respectively.
43
44At the time of writing, exact chip may be either 'fsl,mpc5200' or
45'fsl,mpc5200b'.
46
47The soc node
48------------
49This node describes the on chip SOC peripherals. Every mpc5200 based
50board will have this node, and as such there is a common naming
51convention for SOC devices.
52
53Required properties:
54name description
55---- -----------
56ranges Memory range of the internal memory mapped registers.
57 Should be <0 [baseaddr] 0xc000>
58reg Should be <[baseaddr] 0x100>
59compatible mpc5200: "fsl,mpc5200-immr"
60 mpc5200b: "fsl,mpc5200b-immr"
61system-frequency 'fsystem' frequency in Hz; XLB, IPB, USB and PCI
62 clocks are derived from the fsystem clock.
63bus-frequency IPB bus frequency in Hz. Clock rate
64 used by most of the soc devices.
65
66soc child nodes
67---------------
68Any on chip SOC devices available to Linux must appear as soc5200 child nodes.
69
70Note: The tables below show the value for the mpc5200. A mpc5200b device
71tree should use the "fsl,mpc5200b-<device>","fsl,mpc5200-<device>" form.
72
73Required soc5200 child nodes:
74name compatible Description
75---- ---------- -----------
76cdm@<addr> fsl,mpc5200-cdm Clock Distribution
77interrupt-controller@<addr> fsl,mpc5200-pic need an interrupt
78 controller to boot
79bestcomm@<addr> fsl,mpc5200-bestcomm Bestcomm DMA controller
80
81Recommended soc5200 child nodes; populate as needed for your board
82name compatible Description
83---- ---------- -----------
84timer@<addr> fsl,mpc5200-gpt General purpose timers
85gpio@<addr> fsl,mpc5200-gpio MPC5200 simple gpio controller
86gpio@<addr> fsl,mpc5200-gpio-wkup MPC5200 wakeup gpio controller
87rtc@<addr> fsl,mpc5200-rtc Real time clock
88mscan@<addr> fsl,mpc5200-mscan CAN bus controller
89pci@<addr> fsl,mpc5200-pci PCI bridge
90serial@<addr> fsl,mpc5200-psc-uart PSC in serial mode
91i2s@<addr> fsl,mpc5200-psc-i2s PSC in i2s mode
92ac97@<addr> fsl,mpc5200-psc-ac97 PSC in ac97 mode
93spi@<addr> fsl,mpc5200-psc-spi PSC in spi mode
94irda@<addr> fsl,mpc5200-psc-irda PSC in IrDA mode
95spi@<addr> fsl,mpc5200-spi MPC5200 spi device
96ethernet@<addr> fsl,mpc5200-fec MPC5200 ethernet device
97ata@<addr> fsl,mpc5200-ata IDE ATA interface
98i2c@<addr> fsl,mpc5200-i2c I2C controller
99usb@<addr> fsl,mpc5200-ohci,ohci-be USB controller
100xlb@<addr> fsl,mpc5200-xlb XLB arbitrator
101
102fsl,mpc5200-gpt nodes
103---------------------
104On the mpc5200 and 5200b, GPT0 has a watchdog timer function. If the board
105design supports the internal wdt, then the device node for GPT0 should
106include the empty property 'fsl,has-wdt'.
107
108An mpc5200-gpt can be used as a single line GPIO controller. To do so,
109add the following properties to the gpt node:
110 gpio-controller;
111 #gpio-cells = <2>;
112When referencing the GPIO line from another node, the first cell must always
113be zero and the second cell represents the gpio flags and described in the
114gpio device tree binding.
115
116An mpc5200-gpt can be used as a single line edge sensitive interrupt
117controller. To do so, add the following properties to the gpt node:
118 interrupt-controller;
119 #interrupt-cells = <1>;
120When referencing the IRQ line from another node, the cell represents the
121sense mode; 1 for edge rising, 2 for edge falling.
122
123fsl,mpc5200-psc nodes
124---------------------
125The PSCs should include a cell-index which is the index of the PSC in
126hardware. cell-index is used to determine which shared SoC registers to
127use when setting up PSC clocking. cell-index number starts at '0'. ie:
128 PSC1 has 'cell-index = <0>'
129 PSC4 has 'cell-index = <3>'
130
131PSC in i2s mode: The mpc5200 and mpc5200b PSCs are not compatible when in
132i2s mode. An 'mpc5200b-psc-i2s' node cannot include 'mpc5200-psc-i2s' in the
133compatible field.
134
135
136fsl,mpc5200-gpio and fsl,mpc5200-gpio-wkup nodes
137------------------------------------------------
138Each GPIO controller node should have the empty property gpio-controller and
139#gpio-cells set to 2. First cell is the GPIO number which is interpreted
140according to the bit numbers in the GPIO control registers. The second cell
141is for flags which is currently unused.
142
143fsl,mpc5200-fec nodes
144---------------------
145The FEC node can specify one of the following properties to configure
146the MII link:
147- fsl,7-wire-mode - An empty property that specifies the link uses 7-wire
148 mode instead of MII
149- current-speed - Specifies that the MII should be configured for a fixed
150 speed. This property should contain two cells. The
151 first cell specifies the speed in Mbps and the second
152 should be '0' for half duplex and '1' for full duplex
153- phy-handle - Contains a phandle to an Ethernet PHY.
154
155Interrupt controller (fsl,mpc5200-pic) node
156-------------------------------------------
157The mpc5200 pic binding splits hardware IRQ numbers into two levels. The
158split reflects the layout of the PIC hardware itself, which groups
159interrupts into one of three groups; CRIT, MAIN or PERP. Also, the
160Bestcomm dma engine has it's own set of interrupt sources which are
161cascaded off of peripheral interrupt 0, which the driver interprets as a
162fourth group, SDMA.
163
164The interrupts property for device nodes using the mpc5200 pic consists
165of three cells; <L1 L2 level>
166
167 L1 := [CRIT=0, MAIN=1, PERP=2, SDMA=3]
168 L2 := interrupt number; directly mapped from the value in the
169 "ICTL PerStat, MainStat, CritStat Encoded Register"
170 level := [LEVEL_HIGH=0, EDGE_RISING=1, EDGE_FALLING=2, LEVEL_LOW=3]
171
172For external IRQs, use the following interrupt property values (how to
173specify external interrupts is a frequently asked question):
174External interrupts:
175 external irq0: interrupts = <0 0 n>;
176 external irq1: interrupts = <1 1 n>;
177 external irq2: interrupts = <1 2 n>;
178 external irq3: interrupts = <1 3 n>;
179'n' is sense (0: level high, 1: edge rising, 2: edge falling 3: level low)
180
diff --git a/Documentation/powerpc/mpc52xx-device-tree-bindings.txt b/Documentation/powerpc/mpc52xx-device-tree-bindings.txt
deleted file mode 100644
index 6f12f1c79c0c..000000000000
--- a/Documentation/powerpc/mpc52xx-device-tree-bindings.txt
+++ /dev/null
@@ -1,277 +0,0 @@
1MPC5200 Device Tree Bindings
2----------------------------
3
4(c) 2006-2007 Secret Lab Technologies Ltd
5Grant Likely <grant.likely at secretlab.ca>
6
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
13I - Introduction
14================
15Boards supported by the arch/powerpc architecture require device tree be
16passed by the boot loader to the kernel at boot time. The device tree
17describes what devices are present on the board and how they are
18connected. The device tree can either be passed as a binary blob (as
19described in Documentation/powerpc/booting-without-of.txt), or passed
20by Open Firmware (IEEE 1275) compatible firmware using an OF compatible
21client interface API.
22
23This document specifies the requirements on the device-tree for mpc5200
24based boards. These requirements are above and beyond the details
25specified in either the Open Firmware spec or booting-without-of.txt
26
27All new mpc5200-based boards are expected to match this document. In
28cases where this document is not sufficient to support a new board port,
29this document should be updated as part of adding the new board support.
30
31II - Philosophy
32===============
33The core of this document is naming convention. The whole point of
34defining this convention is to reduce or eliminate the number of
35special cases required to support a 5200 board. If all 5200 boards
36follow the same convention, then generic 5200 support code will work
37rather than coding special cases for each new board.
38
39This section tries to capture the thought process behind why the naming
40convention is what it is.
41
421. names
43---------
44There is strong convention/requirements already established for children
45of the root node. 'cpus' describes the processor cores, 'memory'
46describes memory, and 'chosen' provides boot configuration. Other nodes
47are added to describe devices attached to the processor local bus.
48
49Following convention already established with other system-on-chip
50processors, 5200 device trees should use the name 'soc5200' for the
51parent node of on chip devices, and the root node should be its parent.
52
53Child nodes are typically named after the configured function. ie.
54the FEC node is named 'ethernet', and a PSC in uart mode is named 'serial'.
55
562. device_type property
57-----------------------
58similar to the node name convention above; the device_type reflects the
59configured function of a device. ie. 'serial' for a uart and 'spi' for
60an spi controller. However, while node names *should* reflect the
61configured function, device_type *must* match the configured function
62exactly.
63
643. compatible property
65----------------------
66Since device_type isn't enough to match devices to drivers, there also
67needs to be a naming convention for the compatible property. Compatible
68is an list of device descriptions sorted from specific to generic. For
69the mpc5200, the required format for each compatible value is
70<chip>-<device>[-<mode>]. The OS should be able to match a device driver
71to the device based solely on the compatible value. If two drivers
72match on the compatible list; the 'most compatible' driver should be
73selected.
74
75The split between the MPC5200 and the MPC5200B leaves a bit of a
76conundrum. How should the compatible property be set up to provide
77maximum compatibility information; but still accurately describe the
78chip? For the MPC5200; the answer is easy. Most of the SoC devices
79originally appeared on the MPC5200. Since they didn't exist anywhere
80else; the 5200 compatible properties will contain only one item;
81"mpc5200-<device>".
82
83The 5200B is almost the same as the 5200, but not quite. It fixes
84silicon bugs and it adds a small number of enhancements. Most of the
85devices either provide exactly the same interface as on the 5200. A few
86devices have extra functions but still have a backwards compatible mode.
87To express this information as completely as possible, 5200B device trees
88should have two items in the compatible list;
89"mpc5200b-<device>\0mpc5200-<device>". It is *strongly* recommended
90that 5200B device trees follow this convention (instead of only listing
91the base mpc5200 item).
92
93If another chip appear on the market with one of the mpc5200 SoC
94devices, then the compatible list should include mpc5200-<device>.
95
96ie. ethernet on mpc5200: compatible = "mpc5200-ethernet"
97 ethernet on mpc5200b: compatible = "mpc5200b-ethernet\0mpc5200-ethernet"
98
99Modal devices, like PSCs, also append the configured function to the
100end of the compatible field. ie. A PSC in i2s mode would specify
101"mpc5200-psc-i2s", not "mpc5200-i2s". This convention is chosen to
102avoid naming conflicts with non-psc devices providing the same
103function. For example, "mpc5200-spi" and "mpc5200-psc-spi" describe
104the mpc5200 simple spi device and a PSC spi mode respectively.
105
106If the soc device is more generic and present on other SOCs, the
107compatible property can specify the more generic device type also.
108
109ie. mscan: compatible = "mpc5200-mscan\0fsl,mscan";
110
111At the time of writing, exact chip may be either 'mpc5200' or
112'mpc5200b'.
113
114Device drivers should always try to match as generically as possible.
115
116III - Structure
117===============
118The device tree for an mpc5200 board follows the structure defined in
119booting-without-of.txt with the following additional notes:
120
1210) the root node
122----------------
123Typical root description node; see booting-without-of
124
1251) The cpus node
126----------------
127The cpus node follows the basic layout described in booting-without-of.
128The bus-frequency property holds the XLB bus frequency
129The clock-frequency property holds the core frequency
130
1312) The memory node
132------------------
133Typical memory description node; see booting-without-of.
134
1353) The soc5200 node
136-------------------
137This node describes the on chip SOC peripherals. Every mpc5200 based
138board will have this node, and as such there is a common naming
139convention for SOC devices.
140
141Required properties:
142name type description
143---- ---- -----------
144device_type string must be "soc"
145ranges int should be <0 baseaddr baseaddr+10000>
146reg int must be <baseaddr 10000>
147compatible string mpc5200: "mpc5200-soc"
148 mpc5200b: "mpc5200b-soc\0mpc5200-soc"
149system-frequency int Fsystem frequency; source of all
150 other clocks.
151bus-frequency int IPB bus frequency in HZ. Clock rate
152 used by most of the soc devices.
153#interrupt-cells int must be <3>.
154
155Recommended properties:
156name type description
157---- ---- -----------
158model string Exact model of the chip;
159 ie: model="fsl,mpc5200"
160revision string Silicon revision of chip
161 ie: revision="M08A"
162
163The 'model' and 'revision' properties are *strongly* recommended. Having
164them presence acts as a bit of a safety net for working around as yet
165undiscovered bugs on one version of silicon. For example, device drivers
166can use the model and revision properties to decide if a bug fix should
167be turned on.
168
1694) soc5200 child nodes
170----------------------
171Any on chip SOC devices available to Linux must appear as soc5200 child nodes.
172
173Note: The tables below show the value for the mpc5200. A mpc5200b device
174tree should use the "mpc5200b-<device>\0mpc5200-<device> form.
175
176Required soc5200 child nodes:
177name device_type compatible Description
178---- ----------- ---------- -----------
179cdm@<addr> cdm mpc5200-cmd Clock Distribution
180pic@<addr> interrupt-controller mpc5200-pic need an interrupt
181 controller to boot
182bestcomm@<addr> dma-controller mpc5200-bestcomm 5200 pic also requires
183 the bestcomm device
184
185Recommended soc5200 child nodes; populate as needed for your board
186name device_type compatible Description
187---- ----------- ---------- -----------
188gpt@<addr> gpt fsl,mpc5200-gpt General purpose timers
189gpt@<addr> gpt fsl,mpc5200-gpt-gpio General purpose
190 timers in GPIO mode
191gpio@<addr> fsl,mpc5200-gpio MPC5200 simple gpio
192 controller
193gpio@<addr> fsl,mpc5200-gpio-wkup MPC5200 wakeup gpio
194 controller
195rtc@<addr> rtc mpc5200-rtc Real time clock
196mscan@<addr> mscan mpc5200-mscan CAN bus controller
197pci@<addr> pci mpc5200-pci PCI bridge
198serial@<addr> serial mpc5200-psc-uart PSC in serial mode
199i2s@<addr> sound mpc5200-psc-i2s PSC in i2s mode
200ac97@<addr> sound mpc5200-psc-ac97 PSC in ac97 mode
201spi@<addr> spi mpc5200-psc-spi PSC in spi mode
202irda@<addr> irda mpc5200-psc-irda PSC in IrDA mode
203spi@<addr> spi mpc5200-spi MPC5200 spi device
204ethernet@<addr> network mpc5200-fec MPC5200 ethernet device
205ata@<addr> ata mpc5200-ata IDE ATA interface
206i2c@<addr> i2c mpc5200-i2c I2C controller
207usb@<addr> usb-ohci-be mpc5200-ohci,ohci-be USB controller
208xlb@<addr> xlb mpc5200-xlb XLB arbitrator
209
210Important child node properties
211name type description
212---- ---- -----------
213cell-index int When multiple devices are present, is the
214 index of the device in the hardware (ie. There
215 are 6 PSC on the 5200 numbered PSC1 to PSC6)
216 PSC1 has 'cell-index = <0>'
217 PSC4 has 'cell-index = <3>'
218
2195) General Purpose Timer nodes (child of soc5200 node)
220On the mpc5200 and 5200b, GPT0 has a watchdog timer function. If the board
221design supports the internal wdt, then the device node for GPT0 should
222include the empty property 'fsl,has-wdt'.
223
2246) PSC nodes (child of soc5200 node)
225PSC nodes can define the optional 'port-number' property to force assignment
226order of serial ports. For example, PSC5 might be physically connected to
227the port labeled 'COM1' and PSC1 wired to 'COM1'. In this case, PSC5 would
228have a "port-number = <0>" property, and PSC1 would have "port-number = <1>".
229
230PSC in i2s mode: The mpc5200 and mpc5200b PSCs are not compatible when in
231i2s mode. An 'mpc5200b-psc-i2s' node cannot include 'mpc5200-psc-i2s' in the
232compatible field.
233
2347) GPIO controller nodes
235Each GPIO controller node should have the empty property gpio-controller and
236#gpio-cells set to 2. First cell is the GPIO number which is interpreted
237according to the bit numbers in the GPIO control registers. The second cell
238is for flags which is currently unsused.
239
2408) FEC nodes
241The FEC node can specify one of the following properties to configure
242the MII link:
243"fsl,7-wire-mode" - An empty property that specifies the link uses 7-wire
244 mode instead of MII
245"current-speed" - Specifies that the MII should be configured for a fixed
246 speed. This property should contain two cells. The
247 first cell specifies the speed in Mbps and the second
248 should be '0' for half duplex and '1' for full duplex
249"phy-handle" - Contains a phandle to an Ethernet PHY.
250
251IV - Extra Notes
252================
253
2541. Interrupt mapping
255--------------------
256The mpc5200 pic driver splits hardware IRQ numbers into two levels. The
257split reflects the layout of the PIC hardware itself, which groups
258interrupts into one of three groups; CRIT, MAIN or PERP. Also, the
259Bestcomm dma engine has it's own set of interrupt sources which are
260cascaded off of peripheral interrupt 0, which the driver interprets as a
261fourth group, SDMA.
262
263The interrupts property for device nodes using the mpc5200 pic consists
264of three cells; <L1 L2 level>
265
266 L1 := [CRIT=0, MAIN=1, PERP=2, SDMA=3]
267 L2 := interrupt number; directly mapped from the value in the
268 "ICTL PerStat, MainStat, CritStat Encoded Register"
269 level := [LEVEL_HIGH=0, EDGE_RISING=1, EDGE_FALLING=2, LEVEL_LOW=3]
270
2712. Shared registers
272-------------------
273Some SoC devices share registers between them. ie. the i2c devices use
274a single clock control register, and almost all device are affected by
275the port_config register. Devices which need to manipulate shared regs
276should look to the parent SoC node. The soc node is responsible
277for arbitrating all shared register access.