123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277 |
- 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.
|