Grant Likely | b1e253c | 2006-11-27 14:16:22 -0700 | [diff] [blame] | 1 | MPC52xx Device Tree Bindings |
| 2 | ---------------------------- |
| 3 | |
| 4 | (c) 2006 Secret Lab Technologies Ltd |
| 5 | Grant Likely <grant.likely at secretlab.ca> |
| 6 | |
| 7 | I - Introduction |
| 8 | ================ |
| 9 | Boards supported by the arch/powerpc architecture require device tree be |
| 10 | passed by the boot loader to the kernel at boot time. The device tree |
| 11 | describes what devices are present on the board and how they are |
| 12 | connected. The device tree can either be passed as a binary blob (as |
| 13 | described in Documentation/powerpc/booting-without-of.txt), or passed |
| 14 | by Open Firmare (IEEE 1275) compatible firmware using an OF compatible |
| 15 | client interface API. |
| 16 | |
| 17 | This document specifies the requirements on the device-tree for mpc52xx |
| 18 | based boards. These requirements are above and beyond the details |
| 19 | specified in either the OpenFirmware spec or booting-without-of.txt |
| 20 | |
| 21 | All new mpc52xx-based boards are expected to match this document. In |
| 22 | cases where this document is not sufficient to support a new board port, |
| 23 | this document should be updated as part of adding the new board support. |
| 24 | |
| 25 | II - Philosophy |
| 26 | =============== |
| 27 | The core of this document is naming convention. The whole point of |
| 28 | defining this convention is to reduce or eliminate the number of |
| 29 | special cases required to support a 52xx board. If all 52xx boards |
| 30 | follow the same convention, then generic 52xx support code will work |
| 31 | rather than coding special cases for each new board. |
| 32 | |
| 33 | This section tries to capture the thought process behind why the naming |
| 34 | convention is what it is. |
| 35 | |
| 36 | 1. Node names |
| 37 | ------------- |
| 38 | There is strong convention/requirements already established for children |
| 39 | of the root node. 'cpus' describes the processor cores, 'memory' |
| 40 | describes memory, and 'chosen' provides boot configuration. Other nodes |
| 41 | are added to describe devices attached to the processor local bus. |
| 42 | Following convention already established with other system-on-chip |
| 43 | processors, MPC52xx boards must have an 'soc5200' node as a child of the |
| 44 | root node. |
| 45 | |
| 46 | The soc5200 node holds child nodes for all on chip devices. Child nodes |
| 47 | are typically named after the configured function. ie. the FEC node is |
| 48 | named 'ethernet', and a PSC in uart mode is named 'serial'. |
| 49 | |
| 50 | 2. device_type property |
| 51 | ----------------------- |
| 52 | similar to the node name convention above; the device_type reflects the |
| 53 | configured function of a device. ie. 'serial' for a uart and 'spi' for |
| 54 | an spi controller. However, while node names *should* reflect the |
| 55 | configured function, device_type *must* match the configured function |
| 56 | exactly. |
| 57 | |
| 58 | 3. compatible property |
| 59 | ---------------------- |
| 60 | Since device_type isn't enough to match devices to drivers, there also |
| 61 | needs to be a naming convention for the compatible property. Compatible |
| 62 | is an list of device descriptions sorted from specific to generic. For |
| 63 | the mpc52xx, the required format for each compatible value is |
| 64 | <chip>-<device>[-<mode>]. At the minimum, the list shall contain two |
| 65 | items; the first specifying the exact chip, and the second specifying |
| 66 | mpc52xx for the chip. |
| 67 | |
| 68 | ie. ethernet on mpc5200b: compatible = "mpc5200b-ethernet\0mpc52xx-ethernet" |
| 69 | |
| 70 | The idea here is that most drivers will match to the most generic field |
| 71 | in the compatible list (mpc52xx-*), but can also test the more specific |
| 72 | field for enabling bug fixes or extra features. |
| 73 | |
| 74 | Modal devices, like PSCs, also append the configured function to the |
| 75 | end of the compatible field. ie. A PSC in i2s mode would specify |
| 76 | "mpc52xx-psc-i2s", not "mpc52xx-i2s". This convention is chosen to |
| 77 | avoid naming conflicts with non-psc devices providing the same |
| 78 | function. For example, "mpc52xx-spi" and "mpc52xx-psc-spi" describe |
| 79 | the mpc5200 simple spi device and a PSC spi mode respectively. |
| 80 | |
| 81 | If the soc device is more generic and present on other SOCs, the |
| 82 | compatible property can specify the more generic device type also. |
| 83 | |
| 84 | ie. mscan: compatible = "mpc5200-mscan\0mpc52xx-mscan\0fsl,mscan"; |
| 85 | |
| 86 | At the time of writing, exact chip may be either 'mpc5200' or |
| 87 | 'mpc5200b'. |
| 88 | |
| 89 | Device drivers should always try to match as generically as possible. |
| 90 | |
| 91 | III - Structure |
| 92 | =============== |
| 93 | The device tree for an mpc52xx board follows the structure defined in |
| 94 | booting-without-of.txt with the following additional notes: |
| 95 | |
| 96 | 0) the root node |
| 97 | ---------------- |
| 98 | Typical root description node; see booting-without-of |
| 99 | |
| 100 | 1) The cpus node |
| 101 | ---------------- |
| 102 | The cpus node follows the basic layout described in booting-without-of. |
| 103 | The bus-frequency property holds the XLB bus frequency |
| 104 | The clock-frequency property holds the core frequency |
| 105 | |
| 106 | 2) The memory node |
| 107 | ------------------ |
| 108 | Typical memory description node; see booting-without-of. |
| 109 | |
| 110 | 3) The soc5200 node |
| 111 | ------------------- |
| 112 | This node describes the on chip SOC peripherals. Every mpc52xx based |
| 113 | board will have this node, and as such there is a common naming |
| 114 | convention for SOC devices. |
| 115 | |
| 116 | Required properties: |
| 117 | name type description |
| 118 | ---- ---- ----------- |
| 119 | device_type string must be "soc" |
| 120 | ranges int should be <0 baseaddr baseaddr+10000> |
| 121 | reg int must be <baseaddr 10000> |
| 122 | |
| 123 | Recommended properties: |
| 124 | name type description |
| 125 | ---- ---- ----------- |
| 126 | compatible string should be "<chip>-soc\0mpc52xx-soc" |
| 127 | ie. "mpc5200b-soc\0mpc52xx-soc" |
| 128 | #interrupt-cells int must be <3>. If it is not defined |
| 129 | here then it must be defined in every |
| 130 | soc device node. |
| 131 | bus-frequency int IPB bus frequency in HZ. Clock rate |
| 132 | used by most of the soc devices. |
| 133 | Defining it here avoids needing it |
| 134 | added to every device node. |
| 135 | |
| 136 | 4) soc5200 child nodes |
| 137 | ---------------------- |
| 138 | Any on chip SOC devices available to Linux must appear as soc5200 child nodes. |
| 139 | |
| 140 | Note: in the tables below, '*' matches all <chip> values. ie. |
| 141 | *-pic would translate to "mpc5200-pic\0mpc52xx-pic" |
| 142 | |
| 143 | Required soc5200 child nodes: |
| 144 | name device_type compatible Description |
| 145 | ---- ----------- ---------- ----------- |
| 146 | cdm@<addr> cdm *-cmd Clock Distribution |
| 147 | pic@<addr> interrupt-controller *-pic need an interrupt |
| 148 | controller to boot |
| 149 | bestcomm@<addr> dma-controller *-bestcomm 52xx pic also requires |
| 150 | the bestcomm device |
| 151 | |
| 152 | Recommended soc5200 child nodes; populate as needed for your board |
| 153 | name device_type compatible Description |
| 154 | ---- ----------- ---------- ----------- |
| 155 | gpt@<addr> gpt *-gpt General purpose timers |
| 156 | rtc@<addr> rtc *-rtc Real time clock |
| 157 | mscan@<addr> mscan *-mscan CAN bus controller |
| 158 | pci@<addr> pci *-pci PCI bridge |
| 159 | serial@<addr> serial *-psc-uart PSC in serial mode |
| 160 | i2s@<addr> i2s *-psc-i2s PSC in i2s mode |
| 161 | ac97@<addr> ac97 *-psc-ac97 PSC in ac97 mode |
| 162 | spi@<addr> spi *-psc-spi PSC in spi mode |
| 163 | irda@<addr> irda *-psc-irda PSC in IrDA mode |
| 164 | spi@<addr> spi *-spi MPC52xx spi device |
| 165 | ethernet@<addr> network *-fec MPC52xx ethernet device |
| 166 | ata@<addr> ata *-ata IDE ATA interface |
| 167 | i2c@<addr> i2c *-i2c I2C controller |
| 168 | usb@<addr> usb-ohci-be *-ohci,ohci-be USB controller |
| 169 | xlb@<addr> xlb *-xlb XLB arbritrator |
| 170 | |
| 171 | IV - Extra Notes |
| 172 | ================ |
| 173 | |
| 174 | 1. Interrupt mapping |
| 175 | -------------------- |
| 176 | The mpc52xx pic driver splits hardware IRQ numbers into two levels. The |
| 177 | split reflects the layout of the PIC hardware itself, which groups |
| 178 | interrupts into one of three groups; CRIT, MAIN or PERP. Also, the |
| 179 | Bestcomm dma engine has it's own set of interrupt sources which are |
| 180 | cascaded off of peripheral interrupt 0, which the driver interprets as a |
| 181 | fourth group, SDMA. |
| 182 | |
| 183 | The interrupts property for device nodes using the mpc52xx pic consists |
| 184 | of three cells; <L1 L2 level> |
| 185 | |
| 186 | L1 := [CRIT=0, MAIN=1, PERP=2, SDMA=3] |
| 187 | L2 := interrupt number; directly mapped from the value in the |
| 188 | "ICTL PerStat, MainStat, CritStat Encoded Register" |
| 189 | level := [LEVEL_HIGH=0, EDGE_RISING=1, EDGE_FALLING=2, LEVEL_LOW=3] |