diff options
Diffstat (limited to 'Documentation/powerpc/mpc52xx-device-tree-bindings.txt')
| -rw-r--r-- | Documentation/powerpc/mpc52xx-device-tree-bindings.txt | 277 |
1 files changed, 277 insertions, 0 deletions
diff --git a/Documentation/powerpc/mpc52xx-device-tree-bindings.txt b/Documentation/powerpc/mpc52xx-device-tree-bindings.txt new file mode 100644 index 0000000..6f12f1c --- /dev/null +++ b/Documentation/powerpc/mpc52xx-device-tree-bindings.txt @@ -0,0 +1,277 @@ +MPC5200 Device Tree Bindings +---------------------------- + +(c) 2006-2007 Secret Lab Technologies Ltd +Grant Likely <grant.likely at secretlab.ca> + +********** DRAFT *********** +* WARNING: Do not depend on the stability of these bindings just yet. +* The MPC5200 device tree conventions are still in flux +* Keep an eye on the linuxppc-dev mailing list for more details +********** DRAFT *********** + +I - Introduction +================ +Boards supported by the arch/powerpc architecture require device tree be +passed by the boot loader to the kernel at boot time. The device tree +describes what devices are present on the board and how they are +connected. The device tree can either be passed as a binary blob (as +described in Documentation/powerpc/booting-without-of.txt), or passed +by Open Firmware (IEEE 1275) compatible firmware using an OF compatible +client interface API. + +This document specifies the requirements on the device-tree for mpc5200 +based boards. These requirements are above and beyond the details +specified in either the Open Firmware spec or booting-without-of.txt + +All new mpc5200-based boards are expected to match this document. In +cases where this document is not sufficient to support a new board port, +this document should be updated as part of adding the new board support. + +II - Philosophy +=============== +The core of this document is naming convention. The whole point of +defining this convention is to reduce or eliminate the number of +special cases required to support a 5200 board. If all 5200 boards +follow the same convention, then generic 5200 support code will work +rather than coding special cases for each new board. + +This section tries to capture the thought process behind why the naming +convention is what it is. + +1. names +--------- +There is strong convention/requirements already established for children +of the root node. 'cpus' describes the processor cores, 'memory' +describes memory, and 'chosen' provides boot configuration. Other nodes +are added to describe devices attached to the processor local bus. + +Following convention already established with other system-on-chip +processors, 5200 device trees should use the name 'soc5200' for the +parent node of on chip devices, and the root node should be its parent. + +Child nodes are typically named after the configured function. ie. +the FEC node is named 'ethernet', and a PSC in uart mode is named 'serial'. + +2. device_type property +----------------------- +similar to the node name convention above; the device_type reflects the +configured function of a device. ie. 'serial' for a uart and 'spi' for +an spi controller. However, while node names *should* reflect the +configured function, device_type *must* match the configured function +exactly. + +3. compatible property +---------------------- +Since device_type isn't enough to match devices to drivers, there also +needs to be a naming convention for the compatible property. Compatible +is an list of device descriptions sorted from specific to generic. For +the mpc5200, the required format for each compatible value is +<chip>-<device>[-<mode>]. The OS should be able to match a device driver +to the device based solely on the compatible value. If two drivers +match on the compatible list; the 'most compatible' driver should be +selected. + +The split between the MPC5200 and the MPC5200B leaves a bit of a +conundrum. How should the compatible property be set up to provide +maximum compatibility information; but still accurately describe the +chip? For the MPC5200; the answer is easy. Most of the SoC devices +originally appeared on the MPC5200. Since they didn't exist anywhere +else; the 5200 compatible properties will contain only one item; +"mpc5200-<device>". + +The 5200B is almost the same as the 5200, but not quite. It fixes +silicon bugs and it adds a small number of enhancements. Most of the +devices either provide exactly the same interface as on the 5200. A few +devices have extra functions but still have a backwards compatible mode. +To express this information as completely as possible, 5200B device trees +should have two items in the compatible list; +"mpc5200b-<device>\0mpc5200-<device>". It is *strongly* recommended +that 5200B device trees follow this convention (instead of only listing +the base mpc5200 item). + +If another chip appear on the market with one of the mpc5200 SoC +devices, then the compatible list should include mpc5200-<device>. + +ie. ethernet on mpc5200: compatible = "mpc5200-ethernet" + ethernet on mpc5200b: compatible = "mpc5200b-ethernet\0mpc5200-ethernet" + +Modal devices, like PSCs, also append the configured function to the +end of the compatible field. ie. A PSC in i2s mode would specify +"mpc5200-psc-i2s", not "mpc5200-i2s". This convention is chosen to +avoid naming conflicts with non-psc devices providing the same +function. For example, "mpc5200-spi" and "mpc5200-psc-spi" describe +the mpc5200 simple spi device and a PSC spi mode respectively. + +If the soc device is more generic and present on other SOCs, the +compatible property can specify the more generic device type also. + +ie. mscan: compatible = "mpc5200-mscan\0fsl,mscan"; + +At the time of writing, exact chip may be either 'mpc5200' or +'mpc5200b'. + +Device drivers should always try to match as generically as possible. + +III - Structure +=============== +The device tree for an mpc5200 board follows the structure defined in +booting-without-of.txt with the following additional notes: + +0) the root node +---------------- +Typical root description node; see booting-without-of + +1) The cpus node +---------------- +The cpus node follows the basic layout described in booting-without-of. +The bus-frequency property holds the XLB bus frequency +The clock-frequency property holds the core frequency + +2) The memory node +------------------ +Typical memory description node; see booting-without-of. + +3) The soc5200 node +------------------- +This node describes the on chip SOC peripherals. Every mpc5200 based +board will have this node, and as such there is a common naming +convention for SOC devices. + +Required properties: +name type description +---- ---- ----------- +device_type string must be "soc" +ranges int should be <0 baseaddr baseaddr+10000> +reg int must be <baseaddr 10000> +compatible string mpc5200: "mpc5200-soc" + mpc5200b: "mpc5200b-soc\0mpc5200-soc" +system-frequency int Fsystem frequency; source of all + other clocks. +bus-frequency int IPB bus frequency in HZ. Clock rate + used by most of the soc devices. +#interrupt-cells int must be <3>. + +Recommended properties: +name type description +---- ---- ----------- +model string Exact model of the chip; + ie: model="fsl,mpc5200" +revision string Silicon revision of chip + ie: revision="M08A" + +The 'model' and 'revision' properties are *strongly* recommended. Having +them presence acts as a bit of a safety net for working around as yet +undiscovered bugs on one version of silicon. For example, device drivers +can use the model and revision properties to decide if a bug fix should +be turned on. + +4) soc5200 child nodes +---------------------- +Any on chip SOC devices available to Linux must appear as soc5200 child nodes. + +Note: The tables below show the value for the mpc5200. A mpc5200b device +tree should use the "mpc5200b-<device>\0mpc5200-<device> form. + +Required soc5200 child nodes: +name device_type compatible Description +---- ----------- ---------- ----------- +cdm@<addr> cdm mpc5200-cmd Clock Distribution +pic@<addr> interrupt-controller mpc5200-pic need an interrupt + controller to boot +bestcomm@<addr> dma-controller mpc5200-bestcomm 5200 pic also requires + the bestcomm device + +Recommended soc5200 child nodes; populate as needed for your board +name device_type compatible Description +---- ----------- ---------- ----------- +gpt@<addr> gpt fsl,mpc5200-gpt General purpose timers +gpt@<addr> gpt fsl,mpc5200-gpt-gpio General purpose + timers in GPIO mode +gpio@<addr> fsl,mpc5200-gpio MPC5200 simple gpio + controller +gpio@<addr> fsl,mpc5200-gpio-wkup MPC5200 wakeup gpio + controller +rtc@<addr> rtc mpc5200-rtc Real time clock +mscan@<addr> mscan mpc5200-mscan CAN bus controller +pci@<addr> pci mpc5200-pci PCI bridge +serial@<addr> serial mpc5200-psc-uart PSC in serial mode +i2s@<addr> sound mpc5200-psc-i2s PSC in i2s mode +ac97@<addr> sound mpc5200-psc-ac97 PSC in ac97 mode +spi@<addr> spi mpc5200-psc-spi PSC in spi mode +irda@<addr> irda mpc5200-psc-irda PSC in IrDA mode +spi@<addr> spi mpc5200-spi MPC5200 spi device +ethernet@<addr> network mpc5200-fec MPC5200 ethernet device +ata@<addr> ata mpc5200-ata IDE ATA interface +i2c@<addr> i2c mpc5200-i2c I2C controller +usb@<addr> usb-ohci-be mpc5200-ohci,ohci-be USB controller +xlb@<addr> xlb mpc5200-xlb XLB arbitrator + +Important child node properties +name type description +---- ---- ----------- +cell-index int When multiple devices are present, is the + index of the device in the hardware (ie. There + are 6 PSC on the 5200 numbered PSC1 to PSC6) + PSC1 has 'cell-index = <0>' + PSC4 has 'cell-index = <3>' + +5) General Purpose Timer nodes (child of soc5200 node) +On the mpc5200 and 5200b, GPT0 has a watchdog timer function. If the board +design supports the internal wdt, then the device node for GPT0 should +include the empty property 'fsl,has-wdt'. + +6) PSC nodes (child of soc5200 node) +PSC nodes can define the optional 'port-number' property to force assignment +order of serial ports. For example, PSC5 might be physically connected to +the port labeled 'COM1' and PSC1 wired to 'COM1'. In this case, PSC5 would +have a "port-number = <0>" property, and PSC1 would have "port-number = <1>". + +PSC in i2s mode: The mpc5200 and mpc5200b PSCs are not compatible when in +i2s mode. An 'mpc5200b-psc-i2s' node cannot include 'mpc5200-psc-i2s' in the +compatible field. + +7) GPIO controller nodes +Each GPIO controller node should have the empty property gpio-controller and +#gpio-cells set to 2. First cell is the GPIO number which is interpreted +according to the bit numbers in the GPIO control registers. The second cell +is for flags which is currently unsused. + +8) FEC nodes +The FEC node can specify one of the following properties to configure +the MII link: +"fsl,7-wire-mode" - An empty property that specifies the link uses 7-wire + mode instead of MII +"current-speed" - Specifies that the MII should be configured for a fixed + speed. This property should contain two cells. The + first cell specifies the speed in Mbps and the second + should be '0' for half duplex and '1' for full duplex +"phy-handle" - Contains a phandle to an Ethernet PHY. + +IV - Extra Notes +================ + +1. Interrupt mapping +-------------------- +The mpc5200 pic driver splits hardware IRQ numbers into two levels. The +split reflects the layout of the PIC hardware itself, which groups +interrupts into one of three groups; CRIT, MAIN or PERP. Also, the +Bestcomm dma engine has it's own set of interrupt sources which are +cascaded off of peripheral interrupt 0, which the driver interprets as a +fourth group, SDMA. + +The interrupts property for device nodes using the mpc5200 pic consists +of three cells; <L1 L2 level> + + L1 := [CRIT=0, MAIN=1, PERP=2, SDMA=3] + L2 := interrupt number; directly mapped from the value in the + "ICTL PerStat, MainStat, CritStat Encoded Register" + level := [LEVEL_HIGH=0, EDGE_RISING=1, EDGE_FALLING=2, LEVEL_LOW=3] + +2. Shared registers +------------------- +Some SoC devices share registers between them. ie. the i2c devices use +a single clock control register, and almost all device are affected by +the port_config register. Devices which need to manipulate shared regs +should look to the parent SoC node. The soc node is responsible +for arbitrating all shared register access. |
