| Booting the Linux/ppc kernel without Open Firmware |
| -------------------------------------------------- |
| |
| (c) 2005 Benjamin Herrenschmidt <benh at kernel.crashing.org>, |
| IBM Corp. |
| (c) 2005 Becky Bruce <becky.bruce at freescale.com>, |
| Freescale Semiconductor, FSL SOC and 32-bit additions |
| (c) 2006 MontaVista Software, Inc. |
| Flash chip node definition |
| |
| Table of Contents |
| ================= |
| |
| I - Introduction |
| 1) Entry point for arch/powerpc |
| 2) Board support |
| |
| II - The DT block format |
| 1) Header |
| 2) Device tree generalities |
| 3) Device tree "structure" block |
| 4) Device tree "strings" block |
| |
| III - Required content of the device tree |
| 1) Note about cells and address representation |
| 2) Note about "compatible" properties |
| 3) Note about "name" properties |
| 4) Note about node and property names and character set |
| 5) Required nodes and properties |
| a) The root node |
| b) The /cpus node |
| c) The /cpus/* nodes |
| d) the /memory node(s) |
| e) The /chosen node |
| f) the /soc<SOCname> node |
| |
| IV - "dtc", the device tree compiler |
| |
| V - Recommendations for a bootloader |
| |
| VI - System-on-a-chip devices and nodes |
| 1) Defining child nodes of an SOC |
| 2) Representing devices without a current OF specification |
| a) MDIO IO device |
| b) Gianfar-compatible ethernet nodes |
| c) PHY nodes |
| d) Interrupt controllers |
| e) I2C |
| f) Freescale SOC USB controllers |
| g) Freescale SOC SEC Security Engines |
| h) Board Control and Status (BCSR) |
| i) Freescale QUICC Engine module (QE) |
| j) CFI or JEDEC memory-mapped NOR flash |
| k) Global Utilities Block |
| l) Freescale Communications Processor Module |
| m) Chipselect/Local Bus |
| n) 4xx/Axon EMAC ethernet nodes |
| o) Xilinx IP cores |
| p) Freescale Synchronous Serial Interface |
| q) USB EHCI controllers |
| r) Freescale Display Interface Unit |
| s) Freescale on board FPGA |
| t) Freescael MSI interrupt controller |
| u) Freescale General-purpose Timers Module |
| |
| VII - Marvell Discovery mv64[345]6x System Controller chips |
| 1) The /system-controller node |
| 2) Child nodes of /system-controller |
| a) Marvell Discovery MDIO bus |
| b) Marvell Discovery ethernet controller |
| c) Marvell Discovery PHY nodes |
| d) Marvell Discovery SDMA nodes |
| e) Marvell Discovery BRG nodes |
| f) Marvell Discovery CUNIT nodes |
| g) Marvell Discovery MPSCROUTING nodes |
| h) Marvell Discovery MPSCINTR nodes |
| i) Marvell Discovery MPSC nodes |
| j) Marvell Discovery Watch Dog Timer nodes |
| k) Marvell Discovery I2C nodes |
| l) Marvell Discovery PIC (Programmable Interrupt Controller) nodes |
| m) Marvell Discovery MPP (Multipurpose Pins) multiplexing nodes |
| n) Marvell Discovery GPP (General Purpose Pins) nodes |
| o) Marvell Discovery PCI host bridge node |
| p) Marvell Discovery CPU Error nodes |
| q) Marvell Discovery SRAM Controller nodes |
| r) Marvell Discovery PCI Error Handler nodes |
| s) Marvell Discovery Memory Controller nodes |
| |
| VIII - Specifying interrupt information for devices |
| 1) interrupts property |
| 2) interrupt-parent property |
| 3) OpenPIC Interrupt Controllers |
| 4) ISA Interrupt Controllers |
| |
| VIII - Specifying GPIO information for devices |
| 1) gpios property |
| 2) gpio-controller nodes |
| |
| Appendix A - Sample SOC node for MPC8540 |
| |
| |
| Revision Information |
| ==================== |
| |
| May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet. |
| |
| May 19, 2005: Rev 0.2 - Add chapter III and bits & pieces here or |
| clarifies the fact that a lot of things are |
| optional, the kernel only requires a very |
| small device tree, though it is encouraged |
| to provide an as complete one as possible. |
| |
| May 24, 2005: Rev 0.3 - Precise that DT block has to be in RAM |
| - Misc fixes |
| - Define version 3 and new format version 16 |
| for the DT block (version 16 needs kernel |
| patches, will be fwd separately). |
| String block now has a size, and full path |
| is replaced by unit name for more |
| compactness. |
| linux,phandle is made optional, only nodes |
| that are referenced by other nodes need it. |
| "name" property is now automatically |
| deduced from the unit name |
| |
| June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and |
| OF_DT_END_NODE in structure definition. |
| - Change version 16 format to always align |
| property data to 4 bytes. Since tokens are |
| already aligned, that means no specific |
| required alignment between property size |
| and property data. The old style variable |
| alignment would make it impossible to do |
| "simple" insertion of properties using |
| memmove (thanks Milton for |
| noticing). Updated kernel patch as well |
| - Correct a few more alignment constraints |
| - Add a chapter about the device-tree |
| compiler and the textural representation of |
| the tree that can be "compiled" by dtc. |
| |
| November 21, 2005: Rev 0.5 |
| - Additions/generalizations for 32-bit |
| - Changed to reflect the new arch/powerpc |
| structure |
| - Added chapter VI |
| |
| |
| ToDo: |
| - Add some definitions of interrupt tree (simple/complex) |
| - Add some definitions for PCI host bridges |
| - Add some common address format examples |
| - Add definitions for standard properties and "compatible" |
| names for cells that are not already defined by the existing |
| OF spec. |
| - Compare FSL SOC use of PCI to standard and make sure no new |
| node definition required. |
| - Add more information about node definitions for SOC devices |
| that currently have no standard, like the FSL CPM. |
| |
| |
| I - Introduction |
| ================ |
| |
| During the recent development of the Linux/ppc64 kernel, and more |
| specifically, the addition of new platform types outside of the old |
| IBM pSeries/iSeries pair, it was decided to enforce some strict rules |
| regarding the kernel entry and bootloader <-> kernel interfaces, in |
| order to avoid the degeneration that had become the ppc32 kernel entry |
| point and the way a new platform should be added to the kernel. The |
| legacy iSeries platform breaks those rules as it predates this scheme, |
| but no new board support will be accepted in the main tree that |
| doesn't follows them properly. In addition, since the advent of the |
| arch/powerpc merged architecture for ppc32 and ppc64, new 32-bit |
| platforms and 32-bit platforms which move into arch/powerpc will be |
| required to use these rules as well. |
| |
| The main requirement that will be defined in more detail below is |
| the presence of a device-tree whose format is defined after Open |
| Firmware specification. However, in order to make life easier |
| to embedded board vendors, the kernel doesn't require the device-tree |
| to represent every device in the system and only requires some nodes |
| and properties to be present. This will be described in detail in |
| section III, but, for example, the kernel does not require you to |
| create a node for every PCI device in the system. It is a requirement |
| to have a node for PCI host bridges in order to provide interrupt |
| routing informations and memory/IO ranges, among others. It is also |
| recommended to define nodes for on chip devices and other busses that |
| don't specifically fit in an existing OF specification. This creates a |
| great flexibility in the way the kernel can then probe those and match |
| drivers to device, without having to hard code all sorts of tables. It |
| also makes it more flexible for board vendors to do minor hardware |
| upgrades without significantly impacting the kernel code or cluttering |
| it with special cases. |
| |
| |
| 1) Entry point for arch/powerpc |
| ------------------------------- |
| |
| There is one and one single entry point to the kernel, at the start |
| of the kernel image. That entry point supports two calling |
| conventions: |
| |
| a) Boot from Open Firmware. If your firmware is compatible |
| with Open Firmware (IEEE 1275) or provides an OF compatible |
| client interface API (support for "interpret" callback of |
| forth words isn't required), you can enter the kernel with: |
| |
| r5 : OF callback pointer as defined by IEEE 1275 |
| bindings to powerpc. Only the 32-bit client interface |
| is currently supported |
| |
| r3, r4 : address & length of an initrd if any or 0 |
| |
| The MMU is either on or off; the kernel will run the |
| trampoline located in arch/powerpc/kernel/prom_init.c to |
| extract the device-tree and other information from open |
| firmware and build a flattened device-tree as described |
| in b). prom_init() will then re-enter the kernel using |
| the second method. This trampoline code runs in the |
| context of the firmware, which is supposed to handle all |
| exceptions during that time. |
| |
| b) Direct entry with a flattened device-tree block. This entry |
| point is called by a) after the OF trampoline and can also be |
| called directly by a bootloader that does not support the Open |
| Firmware client interface. It is also used by "kexec" to |
| implement "hot" booting of a new kernel from a previous |
| running one. This method is what I will describe in more |
| details in this document, as method a) is simply standard Open |
| Firmware, and thus should be implemented according to the |
| various standard documents defining it and its binding to the |
| PowerPC platform. The entry point definition then becomes: |
| |
| r3 : physical pointer to the device-tree block |
| (defined in chapter II) in RAM |
| |
| r4 : physical pointer to the kernel itself. This is |
| used by the assembly code to properly disable the MMU |
| in case you are entering the kernel with MMU enabled |
| and a non-1:1 mapping. |
| |
| r5 : NULL (as to differentiate with method a) |
| |
| Note about SMP entry: Either your firmware puts your other |
| CPUs in some sleep loop or spin loop in ROM where you can get |
| them out via a soft reset or some other means, in which case |
| you don't need to care, or you'll have to enter the kernel |
| with all CPUs. The way to do that with method b) will be |
| described in a later revision of this document. |
| |
| |
| 2) Board support |
| ---------------- |
| |
| 64-bit kernels: |
| |
| Board supports (platforms) are not exclusive config options. An |
| arbitrary set of board supports can be built in a single kernel |
| image. The kernel will "know" what set of functions to use for a |
| given platform based on the content of the device-tree. Thus, you |
| should: |
| |
| a) add your platform support as a _boolean_ option in |
| arch/powerpc/Kconfig, following the example of PPC_PSERIES, |
| PPC_PMAC and PPC_MAPLE. The later is probably a good |
| example of a board support to start from. |
| |
| b) create your main platform file as |
| "arch/powerpc/platforms/myplatform/myboard_setup.c" and add it |
| to the Makefile under the condition of your CONFIG_ |
| option. This file will define a structure of type "ppc_md" |
| containing the various callbacks that the generic code will |
| use to get to your platform specific code |
| |
| c) Add a reference to your "ppc_md" structure in the |
| "machines" table in arch/powerpc/kernel/setup_64.c if you are |
| a 64-bit platform. |
| |
| d) request and get assigned a platform number (see PLATFORM_* |
| constants in include/asm-powerpc/processor.h |
| |
| 32-bit embedded kernels: |
| |
| Currently, board support is essentially an exclusive config option. |
| The kernel is configured for a single platform. Part of the reason |
| for this is to keep kernels on embedded systems small and efficient; |
| part of this is due to the fact the code is already that way. In the |
| future, a kernel may support multiple platforms, but only if the |
| platforms feature the same core architecture. A single kernel build |
| cannot support both configurations with Book E and configurations |
| with classic Powerpc architectures. |
| |
| 32-bit embedded platforms that are moved into arch/powerpc using a |
| flattened device tree should adopt the merged tree practice of |
| setting ppc_md up dynamically, even though the kernel is currently |
| built with support for only a single platform at a time. This allows |
| unification of the setup code, and will make it easier to go to a |
| multiple-platform-support model in the future. |
| |
| NOTE: I believe the above will be true once Ben's done with the merge |
| of the boot sequences.... someone speak up if this is wrong! |
| |
| To add a 32-bit embedded platform support, follow the instructions |
| for 64-bit platforms above, with the exception that the Kconfig |
| option should be set up such that the kernel builds exclusively for |
| the platform selected. The processor type for the platform should |
| enable another config option to select the specific board |
| supported. |
| |
| NOTE: If Ben doesn't merge the setup files, may need to change this to |
| point to setup_32.c |
| |
| |
| I will describe later the boot process and various callbacks that |
| your platform should implement. |
| |
| |
| II - The DT block format |
| ======================== |
| |
| |
| This chapter defines the actual format of the flattened device-tree |
| passed to the kernel. The actual content of it and kernel requirements |
| are described later. You can find example of code manipulating that |
| format in various places, including arch/powerpc/kernel/prom_init.c |
| which will generate a flattened device-tree from the Open Firmware |
| representation, or the fs2dt utility which is part of the kexec tools |
| which will generate one from a filesystem representation. It is |
| expected that a bootloader like uboot provides a bit more support, |
| that will be discussed later as well. |
| |
| Note: The block has to be in main memory. It has to be accessible in |
| both real mode and virtual mode with no mapping other than main |
| memory. If you are writing a simple flash bootloader, it should copy |
| the block to RAM before passing it to the kernel. |
| |
| |
| 1) Header |
| --------- |
| |
| The kernel is entered with r3 pointing to an area of memory that is |
| roughly described in include/asm-powerpc/prom.h by the structure |
| boot_param_header: |
| |
| struct boot_param_header { |
| u32 magic; /* magic word OF_DT_HEADER */ |
| u32 totalsize; /* total size of DT block */ |
| u32 off_dt_struct; /* offset to structure */ |
| u32 off_dt_strings; /* offset to strings */ |
| u32 off_mem_rsvmap; /* offset to memory reserve map |
| */ |
| u32 version; /* format version */ |
| u32 last_comp_version; /* last compatible version */ |
| |
| /* version 2 fields below */ |
| u32 boot_cpuid_phys; /* Which physical CPU id we're |
| booting on */ |
| /* version 3 fields below */ |
| u32 size_dt_strings; /* size of the strings block */ |
| |
| /* version 17 fields below */ |
| u32 size_dt_struct; /* size of the DT structure block */ |
| }; |
| |
| Along with the constants: |
| |
| /* Definitions used by the flattened device tree */ |
| #define OF_DT_HEADER 0xd00dfeed /* 4: version, |
| 4: total size */ |
| #define OF_DT_BEGIN_NODE 0x1 /* Start node: full name |
| */ |
| #define OF_DT_END_NODE 0x2 /* End node */ |
| #define OF_DT_PROP 0x3 /* Property: name off, |
| size, content */ |
| #define OF_DT_END 0x9 |
| |
| All values in this header are in big endian format, the various |
| fields in this header are defined more precisely below. All |
| "offset" values are in bytes from the start of the header; that is |
| from the value of r3. |
| |
| - magic |
| |
| This is a magic value that "marks" the beginning of the |
| device-tree block header. It contains the value 0xd00dfeed and is |
| defined by the constant OF_DT_HEADER |
| |
| - totalsize |
| |
| This is the total size of the DT block including the header. The |
| "DT" block should enclose all data structures defined in this |
| chapter (who are pointed to by offsets in this header). That is, |
| the device-tree structure, strings, and the memory reserve map. |
| |
| - off_dt_struct |
| |
| This is an offset from the beginning of the header to the start |
| of the "structure" part the device tree. (see 2) device tree) |
| |
| - off_dt_strings |
| |
| This is an offset from the beginning of the header to the start |
| of the "strings" part of the device-tree |
| |
| - off_mem_rsvmap |
| |
| This is an offset from the beginning of the header to the start |
| of the reserved memory map. This map is a list of pairs of 64- |
| bit integers. Each pair is a physical address and a size. The |
| list is terminated by an entry of size 0. This map provides the |
| kernel with a list of physical memory areas that are "reserved" |
| and thus not to be used for memory allocations, especially during |
| early initialization. The kernel needs to allocate memory during |
| boot for things like un-flattening the device-tree, allocating an |
| MMU hash table, etc... Those allocations must be done in such a |
| way to avoid overriding critical things like, on Open Firmware |
| capable machines, the RTAS instance, or on some pSeries, the TCE |
| tables used for the iommu. Typically, the reserve map should |
| contain _at least_ this DT block itself (header,total_size). If |
| you are passing an initrd to the kernel, you should reserve it as |
| well. You do not need to reserve the kernel image itself. The map |
| should be 64-bit aligned. |
| |
| - version |
| |
| This is the version of this structure. Version 1 stops |
| here. Version 2 adds an additional field boot_cpuid_phys. |
| Version 3 adds the size of the strings block, allowing the kernel |
| to reallocate it easily at boot and free up the unused flattened |
| structure after expansion. Version 16 introduces a new more |
| "compact" format for the tree itself that is however not backward |
| compatible. Version 17 adds an additional field, size_dt_struct, |
| allowing it to be reallocated or moved more easily (this is |
| particularly useful for bootloaders which need to make |
| adjustments to a device tree based on probed information). You |
| should always generate a structure of the highest version defined |
| at the time of your implementation. Currently that is version 17, |
| unless you explicitly aim at being backward compatible. |
| |
| - last_comp_version |
| |
| Last compatible version. This indicates down to what version of |
| the DT block you are backward compatible. For example, version 2 |
| is backward compatible with version 1 (that is, a kernel build |
| for version 1 will be able to boot with a version 2 format). You |
| should put a 1 in this field if you generate a device tree of |
| version 1 to 3, or 16 if you generate a tree of version 16 or 17 |
| using the new unit name format. |
| |
| - boot_cpuid_phys |
| |
| This field only exist on version 2 headers. It indicate which |
| physical CPU ID is calling the kernel entry point. This is used, |
| among others, by kexec. If you are on an SMP system, this value |
| should match the content of the "reg" property of the CPU node in |
| the device-tree corresponding to the CPU calling the kernel entry |
| point (see further chapters for more informations on the required |
| device-tree contents) |
| |
| - size_dt_strings |
| |
| This field only exists on version 3 and later headers. It |
| gives the size of the "strings" section of the device tree (which |
| starts at the offset given by off_dt_strings). |
| |
| - size_dt_struct |
| |
| This field only exists on version 17 and later headers. It gives |
| the size of the "structure" section of the device tree (which |
| starts at the offset given by off_dt_struct). |
| |
| So the typical layout of a DT block (though the various parts don't |
| need to be in that order) looks like this (addresses go from top to |
| bottom): |
| |
| |
| ------------------------------ |
| r3 -> | struct boot_param_header | |
| ------------------------------ |
| | (alignment gap) (*) | |
| ------------------------------ |
| | memory reserve map | |
| ------------------------------ |
| | (alignment gap) | |
| ------------------------------ |
| | | |
| | device-tree structure | |
| | | |
| ------------------------------ |
| | (alignment gap) | |
| ------------------------------ |
| | | |
| | device-tree strings | |
| | | |
| -----> ------------------------------ |
| | |
| | |
| --- (r3 + totalsize) |
| |
| (*) The alignment gaps are not necessarily present; their presence |
| and size are dependent on the various alignment requirements of |
| the individual data blocks. |
| |
| |
| 2) Device tree generalities |
| --------------------------- |
| |
| This device-tree itself is separated in two different blocks, a |
| structure block and a strings block. Both need to be aligned to a 4 |
| byte boundary. |
| |
| First, let's quickly describe the device-tree concept before detailing |
| the storage format. This chapter does _not_ describe the detail of the |
| required types of nodes & properties for the kernel, this is done |
| later in chapter III. |
| |
| The device-tree layout is strongly inherited from the definition of |
| the Open Firmware IEEE 1275 device-tree. It's basically a tree of |
| nodes, each node having two or more named properties. A property can |
| have a value or not. |
| |
| It is a tree, so each node has one and only one parent except for the |
| root node who has no parent. |
| |
| A node has 2 names. The actual node name is generally contained in a |
| property of type "name" in the node property list whose value is a |
| zero terminated string and is mandatory for version 1 to 3 of the |
| format definition (as it is in Open Firmware). Version 16 makes it |
| optional as it can generate it from the unit name defined below. |
| |
| There is also a "unit name" that is used to differentiate nodes with |
| the same name at the same level, it is usually made of the node |
| names, the "@" sign, and a "unit address", which definition is |
| specific to the bus type the node sits on. |
| |
| The unit name doesn't exist as a property per-se but is included in |
| the device-tree structure. It is typically used to represent "path" in |
| the device-tree. More details about the actual format of these will be |
| below. |
| |
| The kernel powerpc generic code does not make any formal use of the |
| unit address (though some board support code may do) so the only real |
| requirement here for the unit address is to ensure uniqueness of |
| the node unit name at a given level of the tree. Nodes with no notion |
| of address and no possible sibling of the same name (like /memory or |
| /cpus) may omit the unit address in the context of this specification, |
| or use the "@0" default unit address. The unit name is used to define |
| a node "full path", which is the concatenation of all parent node |
| unit names separated with "/". |
| |
| The root node doesn't have a defined name, and isn't required to have |
| a name property either if you are using version 3 or earlier of the |
| format. It also has no unit address (no @ symbol followed by a unit |
| address). The root node unit name is thus an empty string. The full |
| path to the root node is "/". |
| |
| Every node which actually represents an actual device (that is, a node |
| which isn't only a virtual "container" for more nodes, like "/cpus" |
| is) is also required to have a "device_type" property indicating the |
| type of node . |
| |
| Finally, every node that can be referenced from a property in another |
| node is required to have a "linux,phandle" property. Real open |
| firmware implementations provide a unique "phandle" value for every |
| node that the "prom_init()" trampoline code turns into |
| "linux,phandle" properties. However, this is made optional if the |
| flattened device tree is used directly. An example of a node |
| referencing another node via "phandle" is when laying out the |
| interrupt tree which will be described in a further version of this |
| document. |
| |
| This "linux, phandle" property is a 32-bit value that uniquely |
| identifies a node. You are free to use whatever values or system of |
| values, internal pointers, or whatever to generate these, the only |
| requirement is that every node for which you provide that property has |
| a unique value for it. |
| |
| Here is an example of a simple device-tree. In this example, an "o" |
| designates a node followed by the node unit name. Properties are |
| presented with their name followed by their content. "content" |
| represents an ASCII string (zero terminated) value, while <content> |
| represents a 32-bit hexadecimal value. The various nodes in this |
| example will be discussed in a later chapter. At this point, it is |
| only meant to give you a idea of what a device-tree looks like. I have |
| purposefully kept the "name" and "linux,phandle" properties which |
| aren't necessary in order to give you a better idea of what the tree |
| looks like in practice. |
| |
| / o device-tree |
| |- name = "device-tree" |
| |- model = "MyBoardName" |
| |- compatible = "MyBoardFamilyName" |
| |- #address-cells = <2> |
| |- #size-cells = <2> |
| |- linux,phandle = <0> |
| | |
| o cpus |
| | | - name = "cpus" |
| | | - linux,phandle = <1> |
| | | - #address-cells = <1> |
| | | - #size-cells = <0> |
| | | |
| | o PowerPC,970@0 |
| | |- name = "PowerPC,970" |
| | |- device_type = "cpu" |
| | |- reg = <0> |
| | |- clock-frequency = <5f5e1000> |
| | |- 64-bit |
| | |- linux,phandle = <2> |
| | |
| o memory@0 |
| | |- name = "memory" |
| | |- device_type = "memory" |
| | |- reg = <00000000 00000000 00000000 20000000> |
| | |- linux,phandle = <3> |
| | |
| o chosen |
| |- name = "chosen" |
| |- bootargs = "root=/dev/sda2" |
| |- linux,phandle = <4> |
| |
| This tree is almost a minimal tree. It pretty much contains the |
| minimal set of required nodes and properties to boot a linux kernel; |
| that is, some basic model informations at the root, the CPUs, and the |
| physical memory layout. It also includes misc information passed |
| through /chosen, like in this example, the platform type (mandatory) |
| and the kernel command line arguments (optional). |
| |
| The /cpus/PowerPC,970@0/64-bit property is an example of a |
| property without a value. All other properties have a value. The |
| significance of the #address-cells and #size-cells properties will be |
| explained in chapter IV which defines precisely the required nodes and |
| properties and their content. |
| |
| |
| 3) Device tree "structure" block |
| |
| The structure of the device tree is a linearized tree structure. The |
| "OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE" |
| ends that node definition. Child nodes are simply defined before |
| "OF_DT_END_NODE" (that is nodes within the node). A 'token' is a 32 |
| bit value. The tree has to be "finished" with a OF_DT_END token |
| |
| Here's the basic structure of a single node: |
| |
| * token OF_DT_BEGIN_NODE (that is 0x00000001) |
| * for version 1 to 3, this is the node full path as a zero |
| terminated string, starting with "/". For version 16 and later, |
| this is the node unit name only (or an empty string for the |
| root node) |
| * [align gap to next 4 bytes boundary] |
| * for each property: |
| * token OF_DT_PROP (that is 0x00000003) |
| * 32-bit value of property value size in bytes (or 0 if no |
| value) |
| * 32-bit value of offset in string block of property name |
| * property value data if any |
| * [align gap to next 4 bytes boundary] |
| * [child nodes if any] |
| * token OF_DT_END_NODE (that is 0x00000002) |
| |
| So the node content can be summarized as a start token, a full path, |
| a list of properties, a list of child nodes, and an end token. Every |
| child node is a full node structure itself as defined above. |
| |
| NOTE: The above definition requires that all property definitions for |
| a particular node MUST precede any subnode definitions for that node. |
| Although the structure would not be ambiguous if properties and |
| subnodes were intermingled, the kernel parser requires that the |
| properties come first (up until at least 2.6.22). Any tools |
| manipulating a flattened tree must take care to preserve this |
| constraint. |
| |
| 4) Device tree "strings" block |
| |
| In order to save space, property names, which are generally redundant, |
| are stored separately in the "strings" block. This block is simply the |
| whole bunch of zero terminated strings for all property names |
| concatenated together. The device-tree property definitions in the |
| structure block will contain offset values from the beginning of the |
| strings block. |
| |
| |
| III - Required content of the device tree |
| ========================================= |
| |
| WARNING: All "linux,*" properties defined in this document apply only |
| to a flattened device-tree. If your platform uses a real |
| implementation of Open Firmware or an implementation compatible with |
| the Open Firmware client interface, those properties will be created |
| by the trampoline code in the kernel's prom_init() file. For example, |
| that's where you'll have to add code to detect your board model and |
| set the platform number. However, when using the flattened device-tree |
| entry point, there is no prom_init() pass, and thus you have to |
| provide those properties yourself. |
| |
| |
| 1) Note about cells and address representation |
| ---------------------------------------------- |
| |
| The general rule is documented in the various Open Firmware |
| documentations. If you choose to describe a bus with the device-tree |
| and there exist an OF bus binding, then you should follow the |
| specification. However, the kernel does not require every single |
| device or bus to be described by the device tree. |
| |
| In general, the format of an address for a device is defined by the |
| parent bus type, based on the #address-cells and #size-cells |
| properties. Note that the parent's parent definitions of #address-cells |
| and #size-cells are not inhereted so every node with children must specify |
| them. The kernel requires the root node to have those properties defining |
| addresses format for devices directly mapped on the processor bus. |
| |
| Those 2 properties define 'cells' for representing an address and a |
| size. A "cell" is a 32-bit number. For example, if both contain 2 |
| like the example tree given above, then an address and a size are both |
| composed of 2 cells, and each is a 64-bit number (cells are |
| concatenated and expected to be in big endian format). Another example |
| is the way Apple firmware defines them, with 2 cells for an address |
| and one cell for a size. Most 32-bit implementations should define |
| #address-cells and #size-cells to 1, which represents a 32-bit value. |
| Some 32-bit processors allow for physical addresses greater than 32 |
| bits; these processors should define #address-cells as 2. |
| |
| "reg" properties are always a tuple of the type "address size" where |
| the number of cells of address and size is specified by the bus |
| #address-cells and #size-cells. When a bus supports various address |
| spaces and other flags relative to a given address allocation (like |
| prefetchable, etc...) those flags are usually added to the top level |
| bits of the physical address. For example, a PCI physical address is |
| made of 3 cells, the bottom two containing the actual address itself |
| while the top cell contains address space indication, flags, and pci |
| bus & device numbers. |
| |
| For busses that support dynamic allocation, it's the accepted practice |
| to then not provide the address in "reg" (keep it 0) though while |
| providing a flag indicating the address is dynamically allocated, and |
| then, to provide a separate "assigned-addresses" property that |
| contains the fully allocated addresses. See the PCI OF bindings for |
| details. |
| |
| In general, a simple bus with no address space bits and no dynamic |
| allocation is preferred if it reflects your hardware, as the existing |
| kernel address parsing functions will work out of the box. If you |
| define a bus type with a more complex address format, including things |
| like address space bits, you'll have to add a bus translator to the |
| prom_parse.c file of the recent kernels for your bus type. |
| |
| The "reg" property only defines addresses and sizes (if #size-cells is |
| non-0) within a given bus. In order to translate addresses upward |
| (that is into parent bus addresses, and possibly into CPU physical |
| addresses), all busses must contain a "ranges" property. If the |
| "ranges" property is missing at a given level, it's assumed that |
| translation isn't possible, i.e., the registers are not visible on the |
| parent bus. The format of the "ranges" property for a bus is a list |
| of: |
| |
| bus address, parent bus address, size |
| |
| "bus address" is in the format of the bus this bus node is defining, |
| that is, for a PCI bridge, it would be a PCI address. Thus, (bus |
| address, size) defines a range of addresses for child devices. "parent |
| bus address" is in the format of the parent bus of this bus. For |
| example, for a PCI host controller, that would be a CPU address. For a |
| PCI<->ISA bridge, that would be a PCI address. It defines the base |
| address in the parent bus where the beginning of that range is mapped. |
| |
| For a new 64-bit powerpc board, I recommend either the 2/2 format or |
| Apple's 2/1 format which is slightly more compact since sizes usually |
| fit in a single 32-bit word. New 32-bit powerpc boards should use a |
| 1/1 format, unless the processor supports physical addresses greater |
| than 32-bits, in which case a 2/1 format is recommended. |
| |
| Alternatively, the "ranges" property may be empty, indicating that the |
| registers are visible on the parent bus using an identity mapping |
| translation. In other words, the parent bus address space is the same |
| as the child bus address space. |
| |
| 2) Note about "compatible" properties |
| ------------------------------------- |
| |
| These properties are optional, but recommended in devices and the root |
| node. The format of a "compatible" property is a list of concatenated |
| zero terminated strings. They allow a device to express its |
| compatibility with a family of similar devices, in some cases, |
| allowing a single driver to match against several devices regardless |
| of their actual names. |
| |
| 3) Note about "name" properties |
| ------------------------------- |
| |
| While earlier users of Open Firmware like OldWorld macintoshes tended |
| to use the actual device name for the "name" property, it's nowadays |
| considered a good practice to use a name that is closer to the device |
| class (often equal to device_type). For example, nowadays, ethernet |
| controllers are named "ethernet", an additional "model" property |
| defining precisely the chip type/model, and "compatible" property |
| defining the family in case a single driver can driver more than one |
| of these chips. However, the kernel doesn't generally put any |
| restriction on the "name" property; it is simply considered good |
| practice to follow the standard and its evolutions as closely as |
| possible. |
| |
| Note also that the new format version 16 makes the "name" property |
| optional. If it's absent for a node, then the node's unit name is then |
| used to reconstruct the name. That is, the part of the unit name |
| before the "@" sign is used (or the entire unit name if no "@" sign |
| is present). |
| |
| 4) Note about node and property names and character set |
| ------------------------------------------------------- |
| |
| While open firmware provides more flexible usage of 8859-1, this |
| specification enforces more strict rules. Nodes and properties should |
| be comprised only of ASCII characters 'a' to 'z', '0' to |
| '9', ',', '.', '_', '+', '#', '?', and '-'. Node names additionally |
| allow uppercase characters 'A' to 'Z' (property names should be |
| lowercase. The fact that vendors like Apple don't respect this rule is |
| irrelevant here). Additionally, node and property names should always |
| begin with a character in the range 'a' to 'z' (or 'A' to 'Z' for node |
| names). |
| |
| The maximum number of characters for both nodes and property names |
| is 31. In the case of node names, this is only the leftmost part of |
| a unit name (the pure "name" property), it doesn't include the unit |
| address which can extend beyond that limit. |
| |
| |
| 5) Required nodes and properties |
| -------------------------------- |
| These are all that are currently required. However, it is strongly |
| recommended that you expose PCI host bridges as documented in the |
| PCI binding to open firmware, and your interrupt tree as documented |
| in OF interrupt tree specification. |
| |
| a) The root node |
| |
| The root node requires some properties to be present: |
| |
| - model : this is your board name/model |
| - #address-cells : address representation for "root" devices |
| - #size-cells: the size representation for "root" devices |
| - device_type : This property shouldn't be necessary. However, if |
| you decide to create a device_type for your root node, make sure it |
| is _not_ "chrp" unless your platform is a pSeries or PAPR compliant |
| one for 64-bit, or a CHRP-type machine for 32-bit as this will |
| matched by the kernel this way. |
| |
| Additionally, some recommended properties are: |
| |
| - compatible : the board "family" generally finds its way here, |
| for example, if you have 2 board models with a similar layout, |
| that typically get driven by the same platform code in the |
| kernel, you would use a different "model" property but put a |
| value in "compatible". The kernel doesn't directly use that |
| value but it is generally useful. |
| |
| The root node is also generally where you add additional properties |
| specific to your board like the serial number if any, that sort of |
| thing. It is recommended that if you add any "custom" property whose |
| name may clash with standard defined ones, you prefix them with your |
| vendor name and a comma. |
| |
| b) The /cpus node |
| |
| This node is the parent of all individual CPU nodes. It doesn't |
| have any specific requirements, though it's generally good practice |
| to have at least: |
| |
| #address-cells = <00000001> |
| #size-cells = <00000000> |
| |
| This defines that the "address" for a CPU is a single cell, and has |
| no meaningful size. This is not necessary but the kernel will assume |
| that format when reading the "reg" properties of a CPU node, see |
| below |
| |
| c) The /cpus/* nodes |
| |
| So under /cpus, you are supposed to create a node for every CPU on |
| the machine. There is no specific restriction on the name of the |
| CPU, though It's common practice to call it PowerPC,<name>. For |
| example, Apple uses PowerPC,G5 while IBM uses PowerPC,970FX. |
| |
| Required properties: |
| |
| - device_type : has to be "cpu" |
| - reg : This is the physical CPU number, it's a single 32-bit cell |
| and is also used as-is as the unit number for constructing the |
| unit name in the full path. For example, with 2 CPUs, you would |
| have the full path: |
| /cpus/PowerPC,970FX@0 |
| /cpus/PowerPC,970FX@1 |
| (unit addresses do not require leading zeroes) |
| - d-cache-block-size : one cell, L1 data cache block size in bytes (*) |
| - i-cache-block-size : one cell, L1 instruction cache block size in |
| bytes |
| - d-cache-size : one cell, size of L1 data cache in bytes |
| - i-cache-size : one cell, size of L1 instruction cache in bytes |
| |
| (*) The cache "block" size is the size on which the cache management |
| instructions operate. Historically, this document used the cache |
| "line" size here which is incorrect. The kernel will prefer the cache |
| block size and will fallback to cache line size for backward |
| compatibility. |
| |
| Recommended properties: |
| |
| - timebase-frequency : a cell indicating the frequency of the |
| timebase in Hz. This is not directly used by the generic code, |
| but you are welcome to copy/paste the pSeries code for setting |
| the kernel timebase/decrementer calibration based on this |
| value. |
| - clock-frequency : a cell indicating the CPU core clock frequency |
| in Hz. A new property will be defined for 64-bit values, but if |
| your frequency is < 4Ghz, one cell is enough. Here as well as |
| for the above, the common code doesn't use that property, but |
| you are welcome to re-use the pSeries or Maple one. A future |
| kernel version might provide a common function for this. |
| - d-cache-line-size : one cell, L1 data cache line size in bytes |
| if different from the block size |
| - i-cache-line-size : one cell, L1 instruction cache line size in |
| bytes if different from the block size |
| |
| You are welcome to add any property you find relevant to your board, |
| like some information about the mechanism used to soft-reset the |
| CPUs. For example, Apple puts the GPIO number for CPU soft reset |
| lines in there as a "soft-reset" property since they start secondary |
| CPUs by soft-resetting them. |
| |
| |
| d) the /memory node(s) |
| |
| To define the physical memory layout of your board, you should |
| create one or more memory node(s). You can either create a single |
| node with all memory ranges in its reg property, or you can create |
| several nodes, as you wish. The unit address (@ part) used for the |
| full path is the address of the first range of memory defined by a |
| given node. If you use a single memory node, this will typically be |
| @0. |
| |
| Required properties: |
| |
| - device_type : has to be "memory" |
| - reg : This property contains all the physical memory ranges of |
| your board. It's a list of addresses/sizes concatenated |
| together, with the number of cells of each defined by the |
| #address-cells and #size-cells of the root node. For example, |
| with both of these properties being 2 like in the example given |
| earlier, a 970 based machine with 6Gb of RAM could typically |
| have a "reg" property here that looks like: |
| |
| 00000000 00000000 00000000 80000000 |
| 00000001 00000000 00000001 00000000 |
| |
| That is a range starting at 0 of 0x80000000 bytes and a range |
| starting at 0x100000000 and of 0x100000000 bytes. You can see |
| that there is no memory covering the IO hole between 2Gb and |
| 4Gb. Some vendors prefer splitting those ranges into smaller |
| segments, but the kernel doesn't care. |
| |
| e) The /chosen node |
| |
| This node is a bit "special". Normally, that's where open firmware |
| puts some variable environment information, like the arguments, or |
| the default input/output devices. |
| |
| This specification makes a few of these mandatory, but also defines |
| some linux-specific properties that would be normally constructed by |
| the prom_init() trampoline when booting with an OF client interface, |
| but that you have to provide yourself when using the flattened format. |
| |
| Recommended properties: |
| |
| - bootargs : This zero-terminated string is passed as the kernel |
| command line |
| - linux,stdout-path : This is the full path to your standard |
| console device if any. Typically, if you have serial devices on |
| your board, you may want to put the full path to the one set as |
| the default console in the firmware here, for the kernel to pick |
| it up as its own default console. If you look at the function |
| set_preferred_console() in arch/ppc64/kernel/setup.c, you'll see |
| that the kernel tries to find out the default console and has |
| knowledge of various types like 8250 serial ports. You may want |
| to extend this function to add your own. |
| |
| Note that u-boot creates and fills in the chosen node for platforms |
| that use it. |
| |
| (Note: a practice that is now obsolete was to include a property |
| under /chosen called interrupt-controller which had a phandle value |
| that pointed to the main interrupt controller) |
| |
| f) the /soc<SOCname> node |
| |
| This node is used to represent a system-on-a-chip (SOC) and must be |
| present if the processor is a SOC. The top-level soc node contains |
| information that is global to all devices on the SOC. The node name |
| should contain a unit address for the SOC, which is the base address |
| of the memory-mapped register set for the SOC. The name of an soc |
| node should start with "soc", and the remainder of the name should |
| represent the part number for the soc. For example, the MPC8540's |
| soc node would be called "soc8540". |
| |
| Required properties: |
| |
| - device_type : Should be "soc" |
| - ranges : Should be defined as specified in 1) to describe the |
| translation of SOC addresses for memory mapped SOC registers. |
| - bus-frequency: Contains the bus frequency for the SOC node. |
| Typically, the value of this field is filled in by the boot |
| loader. |
| |
| |
| Recommended properties: |
| |
| - reg : This property defines the address and size of the |
| memory-mapped registers that are used for the SOC node itself. |
| It does not include the child device registers - these will be |
| defined inside each child node. The address specified in the |
| "reg" property should match the unit address of the SOC node. |
| - #address-cells : Address representation for "soc" devices. The |
| format of this field may vary depending on whether or not the |
| device registers are memory mapped. For memory mapped |
| registers, this field represents the number of cells needed to |
| represent the address of the registers. For SOCs that do not |
| use MMIO, a special address format should be defined that |
| contains enough cells to represent the required information. |
| See 1) above for more details on defining #address-cells. |
| - #size-cells : Size representation for "soc" devices |
| - #interrupt-cells : Defines the width of cells used to represent |
| interrupts. Typically this value is <2>, which includes a |
| 32-bit number that represents the interrupt number, and a |
| 32-bit number that represents the interrupt sense and level. |
| This field is only needed if the SOC contains an interrupt |
| controller. |
| |
| The SOC node may contain child nodes for each SOC device that the |
| platform uses. Nodes should not be created for devices which exist |
| on the SOC but are not used by a particular platform. See chapter VI |
| for more information on how to specify devices that are part of a SOC. |
| |
| Example SOC node for the MPC8540: |
| |
| soc8540@e0000000 { |
| #address-cells = <1>; |
| #size-cells = <1>; |
| #interrupt-cells = <2>; |
| device_type = "soc"; |
| ranges = <00000000 e0000000 00100000> |
| reg = <e0000000 00003000>; |
| bus-frequency = <0>; |
| } |
| |
| |
| |
| IV - "dtc", the device tree compiler |
| ==================================== |
| |
| |
| dtc source code can be found at |
| <http://ozlabs.org/~dgibson/dtc/dtc.tar.gz> |
| |
| WARNING: This version is still in early development stage; the |
| resulting device-tree "blobs" have not yet been validated with the |
| kernel. The current generated bloc lacks a useful reserve map (it will |
| be fixed to generate an empty one, it's up to the bootloader to fill |
| it up) among others. The error handling needs work, bugs are lurking, |
| etc... |
| |
| dtc basically takes a device-tree in a given format and outputs a |
| device-tree in another format. The currently supported formats are: |
| |
| Input formats: |
| ------------- |
| |
| - "dtb": "blob" format, that is a flattened device-tree block |
| with |
| header all in a binary blob. |
| - "dts": "source" format. This is a text file containing a |
| "source" for a device-tree. The format is defined later in this |
| chapter. |
| - "fs" format. This is a representation equivalent to the |
| output of /proc/device-tree, that is nodes are directories and |
| properties are files |
| |
| Output formats: |
| --------------- |
| |
| - "dtb": "blob" format |
| - "dts": "source" format |
| - "asm": assembly language file. This is a file that can be |
| sourced by gas to generate a device-tree "blob". That file can |
| then simply be added to your Makefile. Additionally, the |
| assembly file exports some symbols that can be used. |
| |
| |
| The syntax of the dtc tool is |
| |
| dtc [-I <input-format>] [-O <output-format>] |
| [-o output-filename] [-V output_version] input_filename |
| |
| |
| The "output_version" defines what version of the "blob" format will be |
| generated. Supported versions are 1,2,3 and 16. The default is |
| currently version 3 but that may change in the future to version 16. |
| |
| Additionally, dtc performs various sanity checks on the tree, like the |
| uniqueness of linux, phandle properties, validity of strings, etc... |
| |
| The format of the .dts "source" file is "C" like, supports C and C++ |
| style comments. |
| |
| / { |
| } |
| |
| The above is the "device-tree" definition. It's the only statement |
| supported currently at the toplevel. |
| |
| / { |
| property1 = "string_value"; /* define a property containing a 0 |
| * terminated string |
| */ |
| |
| property2 = <1234abcd>; /* define a property containing a |
| * numerical 32-bit value (hexadecimal) |
| */ |
| |
| property3 = <12345678 12345678 deadbeef>; |
| /* define a property containing 3 |
| * numerical 32-bit values (cells) in |
| * hexadecimal |
| */ |
| property4 = [0a 0b 0c 0d de ea ad be ef]; |
| /* define a property whose content is |
| * an arbitrary array of bytes |
| */ |
| |
| childnode@addresss { /* define a child node named "childnode" |
| * whose unit name is "childnode at |
| * address" |
| */ |
| |
| childprop = "hello\n"; /* define a property "childprop" of |
| * childnode (in this case, a string) |
| */ |
| }; |
| }; |
| |
| Nodes can contain other nodes etc... thus defining the hierarchical |
| structure of the tree. |
| |
| Strings support common escape sequences from C: "\n", "\t", "\r", |
| "\(octal value)", "\x(hex value)". |
| |
| It is also suggested that you pipe your source file through cpp (gcc |
| preprocessor) so you can use #include's, #define for constants, etc... |
| |
| Finally, various options are planned but not yet implemented, like |
| automatic generation of phandles, labels (exported to the asm file so |
| you can point to a property content and change it easily from whatever |
| you link the device-tree with), label or path instead of numeric value |
| in some cells to "point" to a node (replaced by a phandle at compile |
| time), export of reserve map address to the asm file, ability to |
| specify reserve map content at compile time, etc... |
| |
| We may provide a .h include file with common definitions of that |
| proves useful for some properties (like building PCI properties or |
| interrupt maps) though it may be better to add a notion of struct |
| definitions to the compiler... |
| |
| |
| V - Recommendations for a bootloader |
| ==================================== |
| |
| |
| Here are some various ideas/recommendations that have been proposed |
| while all this has been defined and implemented. |
| |
| - The bootloader may want to be able to use the device-tree itself |
| and may want to manipulate it (to add/edit some properties, |
| like physical memory size or kernel arguments). At this point, 2 |
| choices can be made. Either the bootloader works directly on the |
| flattened format, or the bootloader has its own internal tree |
| representation with pointers (similar to the kernel one) and |
| re-flattens the tree when booting the kernel. The former is a bit |
| more difficult to edit/modify, the later requires probably a bit |
| more code to handle the tree structure. Note that the structure |
| format has been designed so it's relatively easy to "insert" |
| properties or nodes or delete them by just memmoving things |
| around. It contains no internal offsets or pointers for this |
| purpose. |
| |
| - An example of code for iterating nodes & retrieving properties |
| directly from the flattened tree format can be found in the kernel |
| file arch/ppc64/kernel/prom.c, look at scan_flat_dt() function, |
| its usage in early_init_devtree(), and the corresponding various |
| early_init_dt_scan_*() callbacks. That code can be re-used in a |
| GPL bootloader, and as the author of that code, I would be happy |
| to discuss possible free licensing to any vendor who wishes to |
| integrate all or part of this code into a non-GPL bootloader. |
| |
| |
| |
| VI - System-on-a-chip devices and nodes |
| ======================================= |
| |
| Many companies are now starting to develop system-on-a-chip |
| processors, where the processor core (CPU) and many peripheral devices |
| exist on a single piece of silicon. For these SOCs, an SOC node |
| should be used that defines child nodes for the devices that make |
| up the SOC. While platforms are not required to use this model in |
| order to boot the kernel, it is highly encouraged that all SOC |
| implementations define as complete a flat-device-tree as possible to |
| describe the devices on the SOC. This will allow for the |
| genericization of much of the kernel code. |
| |
| |
| 1) Defining child nodes of an SOC |
| --------------------------------- |
| |
| Each device that is part of an SOC may have its own node entry inside |
| the SOC node. For each device that is included in the SOC, the unit |
| address property represents the address offset for this device's |
| memory-mapped registers in the parent's address space. The parent's |
| address space is defined by the "ranges" property in the top-level soc |
| node. The "reg" property for each node that exists directly under the |
| SOC node should contain the address mapping from the child address space |
| to the parent SOC address space and the size of the device's |
| memory-mapped register file. |
| |
| For many devices that may exist inside an SOC, there are predefined |
| specifications for the format of the device tree node. All SOC child |
| nodes should follow these specifications, except where noted in this |
| document. |
| |
| See appendix A for an example partial SOC node definition for the |
| MPC8540. |
| |
| |
| 2) Representing devices without a current OF specification |
| ---------------------------------------------------------- |
| |
| Currently, there are many devices on SOCs that do not have a standard |
| representation pre-defined as part of the open firmware |
| specifications, mainly because the boards that contain these SOCs are |
| not currently booted using open firmware. This section contains |
| descriptions for the SOC devices for which new nodes have been |
| defined; this list will expand as more and more SOC-containing |
| platforms are moved over to use the flattened-device-tree model. |
| |
| a) MDIO IO device |
| |
| The MDIO is a bus to which the PHY devices are connected. For each |
| device that exists on this bus, a child node should be created. See |
| the definition of the PHY node below for an example of how to define |
| a PHY. |
| |
| Required properties: |
| - reg : Offset and length of the register set for the device |
| - compatible : Should define the compatible device type for the |
| mdio. Currently, this is most likely to be "fsl,gianfar-mdio" |
| |
| Example: |
| |
| mdio@24520 { |
| reg = <24520 20>; |
| compatible = "fsl,gianfar-mdio"; |
| |
| ethernet-phy@0 { |
| ...... |
| }; |
| }; |
| |
| |
| b) Gianfar-compatible ethernet nodes |
| |
| Required properties: |
| |
| - device_type : Should be "network" |
| - model : Model of the device. Can be "TSEC", "eTSEC", or "FEC" |
| - compatible : Should be "gianfar" |
| - reg : Offset and length of the register set for the device |
| - mac-address : List of bytes representing the ethernet address of |
| this controller |
| - interrupts : <a b> where a is the interrupt number and b is a |
| field that represents an encoding of the sense and level |
| information for the interrupt. This should be encoded based on |
| the information in section 2) depending on the type of interrupt |
| controller you have. |
| - interrupt-parent : the phandle for the interrupt controller that |
| services interrupts for this device. |
| - phy-handle : The phandle for the PHY connected to this ethernet |
| controller. |
| - fixed-link : <a b c d e> where a is emulated phy id - choose any, |
| but unique to the all specified fixed-links, b is duplex - 0 half, |
| 1 full, c is link speed - d#10/d#100/d#1000, d is pause - 0 no |
| pause, 1 pause, e is asym_pause - 0 no asym_pause, 1 asym_pause. |
| |
| Recommended properties: |
| |
| - phy-connection-type : a string naming the controller/PHY interface type, |
| i.e., "mii" (default), "rmii", "gmii", "rgmii", "rgmii-id", "sgmii", |
| "tbi", or "rtbi". This property is only really needed if the connection |
| is of type "rgmii-id", as all other connection types are detected by |
| hardware. |
| |
| |
| Example: |
| |
| ethernet@24000 { |
| #size-cells = <0>; |
| device_type = "network"; |
| model = "TSEC"; |
| compatible = "gianfar"; |
| reg = <24000 1000>; |
| mac-address = [ 00 E0 0C 00 73 00 ]; |
| interrupts = <d 3 e 3 12 3>; |
| interrupt-parent = <40000>; |
| phy-handle = <2452000> |
| }; |
| |
| |
| |
| c) PHY nodes |
| |
| Required properties: |
| |
| - device_type : Should be "ethernet-phy" |
| - interrupts : <a b> where a is the interrupt number and b is a |
| field that represents an encoding of the sense and level |
| information for the interrupt. This should be encoded based on |
| the information in section 2) depending on the type of interrupt |
| controller you have. |
| - interrupt-parent : the phandle for the interrupt controller that |
| services interrupts for this device. |
| - reg : The ID number for the phy, usually a small integer |
| - linux,phandle : phandle for this node; likely referenced by an |
| ethernet controller node. |
| |
| |
| Example: |
| |
| ethernet-phy@0 { |
| linux,phandle = <2452000> |
| interrupt-parent = <40000>; |
| interrupts = <35 1>; |
| reg = <0>; |
| device_type = "ethernet-phy"; |
| }; |
| |
| |
| d) Interrupt controllers |
| |
| Some SOC devices contain interrupt controllers that are different |
| from the standard Open PIC specification. The SOC device nodes for |
| these types of controllers should be specified just like a standard |
| OpenPIC controller. Sense and level information should be encoded |
| as specified in section 2) of this chapter for each device that |
| specifies an interrupt. |
| |
| Example : |
| |
| pic@40000 { |
| linux,phandle = <40000>; |
| interrupt-controller; |
| #address-cells = <0>; |
| reg = <40000 40000>; |
| compatible = "chrp,open-pic"; |
| device_type = "open-pic"; |
| }; |
| |
| |
| e) I2C |
| |
| Required properties : |
| |
| - device_type : Should be "i2c" |
| - reg : Offset and length of the register set for the device |
| |
| Recommended properties : |
| |
| - compatible : Should be "fsl-i2c" for parts compatible with |
| Freescale I2C specifications. |
| - interrupts : <a b> where a is the interrupt number and b is a |
| field that represents an encoding of the sense and level |
| information for the interrupt. This should be encoded based on |
| the information in section 2) depending on the type of interrupt |
| controller you have. |
| - interrupt-parent : the phandle for the interrupt controller that |
| services interrupts for this device. |
| - dfsrr : boolean; if defined, indicates that this I2C device has |
| a digital filter sampling rate register |
| - fsl5200-clocking : boolean; if defined, indicated that this device |
| uses the FSL 5200 clocking mechanism. |
| |
| Example : |
| |
| i2c@3000 { |
| interrupt-parent = <40000>; |
| interrupts = <1b 3>; |
| reg = <3000 18>; |
| device_type = "i2c"; |
| compatible = "fsl-i2c"; |
| dfsrr; |
| }; |
| |
| |
| f) Freescale SOC USB controllers |
| |
| The device node for a USB controller that is part of a Freescale |
| SOC is as described in the document "Open Firmware Recommended |
| Practice : Universal Serial Bus" with the following modifications |
| and additions : |
| |
| Required properties : |
| - compatible : Should be "fsl-usb2-mph" for multi port host USB |
| controllers, or "fsl-usb2-dr" for dual role USB controllers |
| - phy_type : For multi port host USB controllers, should be one of |
| "ulpi", or "serial". For dual role USB controllers, should be |
| one of "ulpi", "utmi", "utmi_wide", or "serial". |
| - reg : Offset and length of the register set for the device |
| - port0 : boolean; if defined, indicates port0 is connected for |
| fsl-usb2-mph compatible controllers. Either this property or |
| "port1" (or both) must be defined for "fsl-usb2-mph" compatible |
| controllers. |
| - port1 : boolean; if defined, indicates port1 is connected for |
| fsl-usb2-mph compatible controllers. Either this property or |
| "port0" (or both) must be defined for "fsl-usb2-mph" compatible |
| controllers. |
| - dr_mode : indicates the working mode for "fsl-usb2-dr" compatible |
| controllers. Can be "host", "peripheral", or "otg". Default to |
| "host" if not defined for backward compatibility. |
| |
| Recommended properties : |
| - interrupts : <a b> where a is the interrupt number and b is a |
| field that represents an encoding of the sense and level |
| information for the interrupt. This should be encoded based on |
| the information in section 2) depending on the type of interrupt |
| controller you have. |
| - interrupt-parent : the phandle for the interrupt controller that |
| services interrupts for this device. |
| |
| Example multi port host USB controller device node : |
| usb@22000 { |
| compatible = "fsl-usb2-mph"; |
| reg = <22000 1000>; |
| #address-cells = <1>; |
| #size-cells = <0>; |
| interrupt-parent = <700>; |
| interrupts = <27 1>; |
| phy_type = "ulpi"; |
| port0; |
| port1; |
| }; |
| |
| Example dual role USB controller device node : |
| usb@23000 { |
| compatible = "fsl-usb2-dr"; |
| reg = <23000 1000>; |
| #address-cells = <1>; |
| #size-cells = <0>; |
| interrupt-parent = <700>; |
| interrupts = <26 1>; |
| dr_mode = "otg"; |
| phy = "ulpi"; |
| }; |
| |
| |
| g) Freescale SOC SEC Security Engines |
| |
| Required properties: |
| |
| - device_type : Should be "crypto" |
| - model : Model of the device. Should be "SEC1" or "SEC2" |
| - compatible : Should be "talitos" |
| - reg : Offset and length of the register set for the device |
| - interrupts : <a b> where a is the interrupt number and b is a |
| field that represents an encoding of the sense and level |
| information for the interrupt. This should be encoded based on |
| the information in section 2) depending on the type of interrupt |
| controller you have. |
| - interrupt-parent : the phandle for the interrupt controller that |
| services interrupts for this device. |
| - num-channels : An integer representing the number of channels |
| available. |
| - channel-fifo-len : An integer representing the number of |
| descriptor pointers each channel fetch fifo can hold. |
| - exec-units-mask : The bitmask representing what execution units |
| (EUs) are available. It's a single 32-bit cell. EU information |
| should be encoded following the SEC's Descriptor Header Dword |
| EU_SEL0 field documentation, i.e. as follows: |
| |
| bit 0 = reserved - should be 0 |
| bit 1 = set if SEC has the ARC4 EU (AFEU) |
| bit 2 = set if SEC has the DES/3DES EU (DEU) |
| bit 3 = set if SEC has the message digest EU (MDEU) |
| bit 4 = set if SEC has the random number generator EU (RNG) |
| bit 5 = set if SEC has the public key EU (PKEU) |
| bit 6 = set if SEC has the AES EU (AESU) |
| bit 7 = set if SEC has the Kasumi EU (KEU) |
| |
| bits 8 through 31 are reserved for future SEC EUs. |
| |
| - descriptor-types-mask : The bitmask representing what descriptors |
| are available. It's a single 32-bit cell. Descriptor type |
| information should be encoded following the SEC's Descriptor |
| Header Dword DESC_TYPE field documentation, i.e. as follows: |
| |
| bit 0 = set if SEC supports the aesu_ctr_nonsnoop desc. type |
| bit 1 = set if SEC supports the ipsec_esp descriptor type |
| bit 2 = set if SEC supports the common_nonsnoop desc. type |
| bit 3 = set if SEC supports the 802.11i AES ccmp desc. type |
| bit 4 = set if SEC supports the hmac_snoop_no_afeu desc. type |
| bit 5 = set if SEC supports the srtp descriptor type |
| bit 6 = set if SEC supports the non_hmac_snoop_no_afeu desc.type |
| bit 7 = set if SEC supports the pkeu_assemble descriptor type |
| bit 8 = set if SEC supports the aesu_key_expand_output desc.type |
| bit 9 = set if SEC supports the pkeu_ptmul descriptor type |
| bit 10 = set if SEC supports the common_nonsnoop_afeu desc. type |
| bit 11 = set if SEC supports the pkeu_ptadd_dbl descriptor type |
| |
| ..and so on and so forth. |
| |
| Example: |
| |
| /* MPC8548E */ |
| crypto@30000 { |
| device_type = "crypto"; |
| model = "SEC2"; |
| compatible = "talitos"; |
| reg = <30000 10000>; |
| interrupts = <1d 3>; |
| interrupt-parent = <40000>; |
| num-channels = <4>; |
| channel-fifo-len = <18>; |
| exec-units-mask = <000000fe>; |
| descriptor-types-mask = <012b0ebf>; |
| }; |
| |
| h) Board Control and Status (BCSR) |
| |
| Required properties: |
| |
| - device_type : Should be "board-control" |
| - reg : Offset and length of the register set for the device |
| |
| Example: |
| |
| bcsr@f8000000 { |
| device_type = "board-control"; |
| reg = <f8000000 8000>; |
| }; |
| |
| i) Freescale QUICC Engine module (QE) |
| This represents qe module that is installed on PowerQUICC II Pro. |
| |
| NOTE: This is an interim binding; it should be updated to fit |
| in with the CPM binding later in this document. |
| |
| Basically, it is a bus of devices, that could act more or less |
| as a complete entity (UCC, USB etc ). All of them should be siblings on |
| the "root" qe node, using the common properties from there. |
| The description below applies to the qe of MPC8360 and |
| more nodes and properties would be extended in the future. |
| |
| i) Root QE device |
| |
| Required properties: |
| - compatible : should be "fsl,qe"; |
| - model : precise model of the QE, Can be "QE", "CPM", or "CPM2" |
| - reg : offset and length of the device registers. |
| - bus-frequency : the clock frequency for QUICC Engine. |
| |
| Recommended properties |
| - brg-frequency : the internal clock source frequency for baud-rate |
| generators in Hz. |
| |
| Example: |
| qe@e0100000 { |
| #address-cells = <1>; |
| #size-cells = <1>; |
| #interrupt-cells = <2>; |
| compatible = "fsl,qe"; |
| ranges = <0 e0100000 00100000>; |
| reg = <e0100000 480>; |
| brg-frequency = <0>; |
| bus-frequency = <179A7B00>; |
| } |
| |
| |
| ii) SPI (Serial Peripheral Interface) |
| |
| Required properties: |
| - cell-index : SPI controller index. |
| - compatible : should be "fsl,spi". |
| - mode : the SPI operation mode, it can be "cpu" or "cpu-qe". |
| - reg : Offset and length of the register set for the device |
| - interrupts : <a b> where a is the interrupt number and b is a |
| field that represents an encoding of the sense and level |
| information for the interrupt. This should be encoded based on |
| the information in section 2) depending on the type of interrupt |
| controller you have. |
| - interrupt-parent : the phandle for the interrupt controller that |
| services interrupts for this device. |
| |
| Example: |
| spi@4c0 { |
| cell-index = <0>; |
| compatible = "fsl,spi"; |
| reg = <4c0 40>; |
| interrupts = <82 0>; |
| interrupt-parent = <700>; |
| mode = "cpu"; |
| }; |
| |
| |
| iii) USB (Universal Serial Bus Controller) |
| |
| Required properties: |
| - compatible : could be "qe_udc" or "fhci-hcd". |
| - mode : the could be "host" or "slave". |
| - reg : Offset and length of the register set for the device |
| - interrupts : <a b> where a is the interrupt number and b is a |
| field that represents an encoding of the sense and level |
| information for the interrupt. This should be encoded based on |
| the information in section 2) depending on the type of interrupt |
| controller you have. |
| - interrupt-parent : the phandle for the interrupt controller that |
| services interrupts for this device. |
| |
| Example(slave): |
| usb@6c0 { |
| compatible = "qe_udc"; |
| reg = <6c0 40>; |
| interrupts = <8b 0>; |
| interrupt-parent = <700>; |
| mode = "slave"; |
| }; |
| |
| |
| iv) UCC (Unified Communications Controllers) |
| |
| Required properties: |
| - device_type : should be "network", "hldc", "uart", "transparent" |
| "bisync", "atm", or "serial". |
| - compatible : could be "ucc_geth" or "fsl_atm" and so on. |
| - cell-index : the ucc number(1-8), corresponding to UCCx in UM. |
| - reg : Offset and length of the register set for the device |
| - interrupts : <a b> where a is the interrupt number and b is a |
| field that represents an encoding of the sense and level |
| information for the interrupt. This should be encoded based on |
| the information in section 2) depending on the type of interrupt |
| controller you have. |
| - interrupt-parent : the phandle for the interrupt controller that |
| services interrupts for this device. |
| - pio-handle : The phandle for the Parallel I/O port configuration. |
| - port-number : for UART drivers, the port number to use, between 0 and 3. |
| This usually corresponds to the /dev/ttyQE device, e.g. <0> = /dev/ttyQE0. |
| The port number is added to the minor number of the device. Unlike the |
| CPM UART driver, the port-number is required for the QE UART driver. |
| - soft-uart : for UART drivers, if specified this means the QE UART device |
| driver should use "Soft-UART" mode, which is needed on some SOCs that have |
| broken UART hardware. Soft-UART is provided via a microcode upload. |
| - rx-clock-name: the UCC receive clock source |
| "none": clock source is disabled |
| "brg1" through "brg16": clock source is BRG1-BRG16, respectively |
| "clk1" through "clk24": clock source is CLK1-CLK24, respectively |
| - tx-clock-name: the UCC transmit clock source |
| "none": clock source is disabled |
| "brg1" through "brg16": clock source is BRG1-BRG16, respectively |
| "clk1" through "clk24": clock source is CLK1-CLK24, respectively |
| The following two properties are deprecated. rx-clock has been replaced |
| with rx-clock-name, and tx-clock has been replaced with tx-clock-name. |
| Drivers that currently use the deprecated properties should continue to |
| do so, in order to support older device trees, but they should be updated |
| to check for the new properties first. |
| - rx-clock : represents the UCC receive clock source. |
| 0x00 : clock source is disabled; |
| 0x1~0x10 : clock source is BRG1~BRG16 respectively; |
| 0x11~0x28: clock source is QE_CLK1~QE_CLK24 respectively. |
| - tx-clock: represents the UCC transmit clock source; |
| 0x00 : clock source is disabled; |
| 0x1~0x10 : clock source is BRG1~BRG16 respectively; |
| 0x11~0x28: clock source is QE_CLK1~QE_CLK24 respectively. |
| |
| Required properties for network device_type: |
| - mac-address : list of bytes representing the ethernet address. |
| - phy-handle : The phandle for the PHY connected to this controller. |
| |
| Recommended properties: |
| - phy-connection-type : a string naming the controller/PHY interface type, |
| i.e., "mii" (default), "rmii", "gmii", "rgmii", "rgmii-id" (Internal |
| Delay), "rgmii-txid" (delay on TX only), "rgmii-rxid" (delay on RX only), |
| "tbi", or "rtbi". |
| |
| Example: |
| ucc@2000 { |
| device_type = "network"; |
| compatible = "ucc_geth"; |
| cell-index = <1>; |
| reg = <2000 200>; |
| interrupts = <a0 0>; |
| interrupt-parent = <700>; |
| mac-address = [ 00 04 9f 00 23 23 ]; |
| rx-clock = "none"; |
| tx-clock = "clk9"; |
| phy-handle = <212000>; |
| phy-connection-type = "gmii"; |
| pio-handle = <140001>; |
| }; |
| |
| |
| v) Parallel I/O Ports |
| |
| This node configures Parallel I/O ports for CPUs with QE support. |
| The node should reside in the "soc" node of the tree. For each |
| device that using parallel I/O ports, a child node should be created. |
| See the definition of the Pin configuration nodes below for more |
| information. |
| |
| Required properties: |
| - device_type : should be "par_io". |
| - reg : offset to the register set and its length. |
| - num-ports : number of Parallel I/O ports |
| |
| Example: |
| par_io@1400 { |
| reg = <1400 100>; |
| #address-cells = <1>; |
| #size-cells = <0>; |
| device_type = "par_io"; |
| num-ports = <7>; |
| ucc_pin@01 { |
| ...... |
| }; |
| |
| |
| vi) Pin configuration nodes |
| |
| Required properties: |
| - linux,phandle : phandle of this node; likely referenced by a QE |
| device. |
| - pio-map : array of pin configurations. Each pin is defined by 6 |
| integers. The six numbers are respectively: port, pin, dir, |
| open_drain, assignment, has_irq. |
| - port : port number of the pin; 0-6 represent port A-G in UM. |
| - pin : pin number in the port. |
| - dir : direction of the pin, should encode as follows: |
| |
| 0 = The pin is disabled |
| 1 = The pin is an output |
| 2 = The pin is an input |
| 3 = The pin is I/O |
| |
| - open_drain : indicates the pin is normal or wired-OR: |
| |
| 0 = The pin is actively driven as an output |
| 1 = The pin is an open-drain driver. As an output, the pin is |
| driven active-low, otherwise it is three-stated. |
| |
| - assignment : function number of the pin according to the Pin Assignment |
| tables in User Manual. Each pin can have up to 4 possible functions in |
| QE and two options for CPM. |
| - has_irq : indicates if the pin is used as source of external |
| interrupts. |
| |
| Example: |
| ucc_pin@01 { |
| linux,phandle = <140001>; |
| pio-map = < |
| /* port pin dir open_drain assignment has_irq */ |
| 0 3 1 0 1 0 /* TxD0 */ |
| 0 4 1 0 1 0 /* TxD1 */ |
| 0 5 1 0 1 0 /* TxD2 */ |
| 0 6 1 0 1 0 /* TxD3 */ |
| 1 6 1 0 3 0 /* TxD4 */ |
| 1 7 1 0 1 0 /* TxD5 */ |
| 1 9 1 0 2 0 /* TxD6 */ |
| 1 a 1 0 2 0 /* TxD7 */ |
| 0 9 2 0 1 0 /* RxD0 */ |
| 0 a 2 0 1 0 /* RxD1 */ |
| 0 b 2 0 1 0 /* RxD2 */ |
| 0 c 2 0 1 0 /* RxD3 */ |
| 0 d 2 0 1 0 /* RxD4 */ |
| 1 1 2 0 2 0 /* RxD5 */ |
| 1 0 2 0 2 0 /* RxD6 */ |
| 1 4 2 0 2 0 /* RxD7 */ |
| 0 7 1 0 1 0 /* TX_EN */ |
| 0 8 1 0 1 0 /* TX_ER */ |
| 0 f 2 0 1 0 /* RX_DV */ |
| 0 10 2 0 1 0 /* RX_ER */ |
| 0 0 2 0 1 0 /* RX_CLK */ |
| 2 9 1 0 3 0 /* GTX_CLK - CLK10 */ |
| 2 8 2 0 1 0>; /* GTX125 - CLK9 */ |
| }; |
| |
| vii) Multi-User RAM (MURAM) |
| |
| Required properties: |
| - compatible : should be "fsl,qe-muram", "fsl,cpm-muram". |
| - mode : the could be "host" or "slave". |
| - ranges : Should be defined as specified in 1) to describe the |
| translation of MURAM addresses. |
| - data-only : sub-node which defines the address area under MURAM |
| bus that can be allocated as data/parameter |
| |
| Example: |
| |
| muram@10000 { |
| compatible = "fsl,qe-muram", "fsl,cpm-muram"; |
| ranges = <0 00010000 0000c000>; |
| |
| data-only@0{ |
| compatible = "fsl,qe-muram-data", |
| "fsl,cpm-muram-data"; |
| reg = <0 c000>; |
| }; |
| }; |
| |
| viii) Uploaded QE firmware |
| |
| If a new firwmare has been uploaded to the QE (usually by the |
| boot loader), then a 'firmware' child node should be added to the QE |
| node. This node provides information on the uploaded firmware that |
| device drivers may need. |
| |
| Required properties: |
| - id: The string name of the firmware. This is taken from the 'id' |
| member of the qe_firmware structure of the uploaded firmware. |
| Device drivers can search this string to determine if the |
| firmware they want is already present. |
| - extended-modes: The Extended Modes bitfield, taken from the |
| firmware binary. It is a 64-bit number represented |
| as an array of two 32-bit numbers. |
| - virtual-traps: The virtual traps, taken from the firmware binary. |
| It is an array of 8 32-bit numbers. |
| |
| Example: |
| |
| firmware { |
| id = "Soft-UART"; |
| extended-modes = <0 0>; |
| virtual-traps = <0 0 0 0 0 0 0 0>; |
| } |
| |
| j) CFI or JEDEC memory-mapped NOR flash |
| |
| Flash chips (Memory Technology Devices) are often used for solid state |
| file systems on embedded devices. |
| |
| - compatible : should contain the specific model of flash chip(s) |
| used, if known, followed by either "cfi-flash" or "jedec-flash" |
| - reg : Address range of the flash chip |
| - bank-width : Width (in bytes) of the flash bank. Equal to the |
| device width times the number of interleaved chips. |
| - device-width : (optional) Width of a single flash chip. If |
| omitted, assumed to be equal to 'bank-width'. |
| - #address-cells, #size-cells : Must be present if the flash has |
| sub-nodes representing partitions (see below). In this case |
| both #address-cells and #size-cells must be equal to 1. |
| |
| For JEDEC compatible devices, the following additional properties |
| are defined: |
| |
| - vendor-id : Contains the flash chip's vendor id (1 byte). |
| - device-id : Contains the flash chip's device id (1 byte). |
| |
| In addition to the information on the flash bank itself, the |
| device tree may optionally contain additional information |
| describing partitions of the flash address space. This can be |
| used on platforms which have strong conventions about which |
| portions of the flash are used for what purposes, but which don't |
| use an on-flash partition table such as RedBoot. |
| |
| Each partition is represented as a sub-node of the flash device. |
| Each node's name represents the name of the corresponding |
| partition of the flash device. |
| |
| Flash partitions |
| - reg : The partition's offset and size within the flash bank. |
| - label : (optional) The label / name for this flash partition. |
| If omitted, the label is taken from the node name (excluding |
| the unit address). |
| - read-only : (optional) This parameter, if present, is a hint to |
| Linux that this flash partition should only be mounted |
| read-only. This is usually used for flash partitions |
| containing early-boot firmware images or data which should not |
| be clobbered. |
| |
| Example: |
| |
| flash@ff000000 { |
| compatible = "amd,am29lv128ml", "cfi-flash"; |
| reg = <ff000000 01000000>; |
| bank-width = <4>; |
| device-width = <1>; |
| #address-cells = <1>; |
| #size-cells = <1>; |
| fs@0 { |
| label = "fs"; |
| reg = <0 f80000>; |
| }; |
| firmware@f80000 { |
| label ="firmware"; |
| reg = <f80000 80000>; |
| read-only; |
| }; |
| }; |
| |
| k) Global Utilities Block |
| |
| The global utilities block controls power management, I/O device |
| enabling, power-on-reset configuration monitoring, general-purpose |
| I/O signal configuration, alternate function selection for multiplexed |
| signals, and clock control. |
| |
| Required properties: |
| |
| - compatible : Should define the compatible device type for |
| global-utilities. |
| - reg : Offset and length of the register set for the device. |
| |
| Recommended properties: |
| |
| - fsl,has-rstcr : Indicates that the global utilities register set |
| contains a functioning "reset control register" (i.e. the board |
| is wired to reset upon setting the HRESET_REQ bit in this register). |
| |
| Example: |
| |
| global-utilities@e0000 { /* global utilities block */ |
| compatible = "fsl,mpc8548-guts"; |
| reg = <e0000 1000>; |
| fsl,has-rstcr; |
| }; |
| |
| l) Freescale Communications Processor Module |
| |
| NOTE: This is an interim binding, and will likely change slightly, |
| as more devices are supported. The QE bindings especially are |
| incomplete. |
| |
| i) Root CPM node |
| |
| Properties: |
| - compatible : "fsl,cpm1", "fsl,cpm2", or "fsl,qe". |
| - reg : A 48-byte region beginning with CPCR. |
| |
| Example: |
| cpm@119c0 { |
| #address-cells = <1>; |
| #size-cells = <1>; |
| #interrupt-cells = <2>; |
| compatible = "fsl,mpc8272-cpm", "fsl,cpm2"; |
| reg = <119c0 30>; |
| } |
| |
| ii) Properties common to mulitple CPM/QE devices |
| |
| - fsl,cpm-command : This value is ORed with the opcode and command flag |
| to specify the device on which a CPM command operates. |
| |
| - fsl,cpm-brg : Indicates which baud rate generator the device |
| is associated with. If absent, an unused BRG |
| should be dynamically allocated. If zero, the |
| device uses an external clock rather than a BRG. |
| |
| - reg : Unless otherwise specified, the first resource represents the |
| scc/fcc/ucc registers, and the second represents the device's |
| parameter RAM region (if it has one). |
| |
| iii) Serial |
| |
| Currently defined compatibles: |
| - fsl,cpm1-smc-uart |
| - fsl,cpm2-smc-uart |
| - fsl,cpm1-scc-uart |
| - fsl,cpm2-scc-uart |
| - fsl,qe-uart |
| |
| Example: |
| |
| serial@11a00 { |
| device_type = "serial"; |
| compatible = "fsl,mpc8272-scc-uart", |
| "fsl,cpm2-scc-uart"; |
| reg = <11a00 20 8000 100>; |
| interrupts = <28 8>; |
| interrupt-parent = <&PIC>; |
| fsl,cpm-brg = <1>; |
| fsl,cpm-command = <00800000>; |
| }; |
| |
| iii) Network |
| |
| Currently defined compatibles: |
| - fsl,cpm1-scc-enet |
| - fsl,cpm2-scc-enet |
| - fsl,cpm1-fec-enet |
| - fsl,cpm2-fcc-enet (third resource is GFEMR) |
| - fsl,qe-enet |
| |
| Example: |
| |
| ethernet@11300 { |
| device_type = "network"; |
| compatible = "fsl,mpc8272-fcc-enet", |
| "fsl,cpm2-fcc-enet"; |
| reg = <11300 20 8400 100 11390 1>; |
| local-mac-address = [ 00 00 00 00 00 00 ]; |
| interrupts = <20 8>; |
| interrupt-parent = <&PIC>; |
| phy-handle = <&PHY0>; |
| fsl,cpm-command = <12000300>; |
| }; |
| |
| iv) MDIO |
| |
| Currently defined compatibles: |
| fsl,pq1-fec-mdio (reg is same as first resource of FEC device) |
| fsl,cpm2-mdio-bitbang (reg is port C registers) |
| |
| Properties for fsl,cpm2-mdio-bitbang: |
| fsl,mdio-pin : pin of port C controlling mdio data |
| fsl,mdc-pin : pin of port C controlling mdio clock |
| |
| Example: |
| |
| mdio@10d40 { |
| device_type = "mdio"; |
| compatible = "fsl,mpc8272ads-mdio-bitbang", |
| "fsl,mpc8272-mdio-bitbang", |
| "fsl,cpm2-mdio-bitbang"; |
| reg = <10d40 14>; |
| #address-cells = <1>; |
| #size-cells = <0>; |
| fsl,mdio-pin = <12>; |
| fsl,mdc-pin = <13>; |
| }; |
| |
| v) Baud Rate Generators |
| |
| Currently defined compatibles: |
| fsl,cpm-brg |
| fsl,cpm1-brg |
| fsl,cpm2-brg |
| |
| Properties: |
| - reg : There may be an arbitrary number of reg resources; BRG |
| numbers are assigned to these in order. |
| - clock-frequency : Specifies the base frequency driving |
| the BRG. |
| |
| Example: |
| |
| brg@119f0 { |
| compatible = "fsl,mpc8272-brg", |
| "fsl,cpm2-brg", |
| "fsl,cpm-brg"; |
| reg = <119f0 10 115f0 10>; |
| clock-frequency = <d#25000000>; |
| }; |
| |
| vi) Interrupt Controllers |
| |
| Currently defined compatibles: |
| - fsl,cpm1-pic |
| - only one interrupt cell |
| - fsl,pq1-pic |
| - fsl,cpm2-pic |
| - second interrupt cell is level/sense: |
| - 2 is falling edge |
| - 8 is active low |
| |
| Example: |
| |
| interrupt-controller@10c00 { |
| #interrupt-cells = <2>; |
| interrupt-controller; |
| reg = <10c00 80>; |
| compatible = "mpc8272-pic", "fsl,cpm2-pic"; |
| }; |
| |
| vii) USB (Universal Serial Bus Controller) |
| |
| Properties: |
| - compatible : "fsl,cpm1-usb", "fsl,cpm2-usb", "fsl,qe-usb" |
| |
| Example: |
| usb@11bc0 { |
| #address-cells = <1>; |
| #size-cells = <0>; |
| compatible = "fsl,cpm2-usb"; |
| reg = <11b60 18 8b00 100>; |
| interrupts = <b 8>; |
| interrupt-parent = <&PIC>; |
| fsl,cpm-command = <2e600000>; |
| }; |
| |
| viii) Multi-User RAM (MURAM) |
| |
| The multi-user/dual-ported RAM is expressed as a bus under the CPM node. |
| |
| Ranges must be set up subject to the following restrictions: |
| |
| - Children's reg nodes must be offsets from the start of all muram, even |
| if the user-data area does not begin at zero. |
| - If multiple range entries are used, the difference between the parent |
| address and the child address must be the same in all, so that a single |
| mapping can cover them all while maintaining the ability to determine |
| CPM-side offsets with pointer subtraction. It is recommended that |
| multiple range entries not be used. |
| - A child address of zero must be translatable, even if no reg resources |
| contain it. |
| |
| A child "data" node must exist, compatible with "fsl,cpm-muram-data", to |
| indicate the portion of muram that is usable by the OS for arbitrary |
| purposes. The data node may have an arbitrary number of reg resources, |
| all of which contribute to the allocatable muram pool. |
| |
| Example, based on mpc8272: |
| |
| muram@0 { |
| #address-cells = <1>; |
| #size-cells = <1>; |
| ranges = <0 0 10000>; |
| |
| data@0 { |
| compatible = "fsl,cpm-muram-data"; |
| reg = <0 2000 9800 800>; |
| }; |
| }; |
| |
| m) Chipselect/Local Bus |
| |
| Properties: |
| - name : Should be localbus |
| - #address-cells : Should be either two or three. The first cell is the |
| chipselect number, and the remaining cells are the |
| offset into the chipselect. |
| - #size-cells : Either one or two, depending on how large each chipselect |
| can be. |
| - ranges : Each range corresponds to a single chipselect, and cover |
| the entire access window as configured. |
| |
| Example: |
| localbus@f0010100 { |
| compatible = "fsl,mpc8272-localbus", |
| "fsl,pq2-localbus"; |
| #address-cells = <2>; |
| #size-cells = <1>; |
| reg = <f0010100 40>; |
| |
| ranges = <0 0 fe000000 02000000 |
| 1 0 f4500000 00008000>; |
| |
| flash@0,0 { |
| compatible = "jedec-flash"; |
| reg = <0 0 2000000>; |
| bank-width = <4>; |
| device-width = <1>; |
| }; |
| |
| board-control@1,0 { |
| reg = <1 0 20>; |
| compatible = "fsl,mpc8272ads-bcsr"; |
| }; |
| }; |
| |
| |
| n) 4xx/Axon EMAC ethernet nodes |
| |
| The EMAC ethernet controller in IBM and AMCC 4xx chips, and also |
| the Axon bridge. To operate this needs to interact with a ths |
| special McMAL DMA controller, and sometimes an RGMII or ZMII |
| interface. In addition to the nodes and properties described |
| below, the node for the OPB bus on which the EMAC sits must have a |
| correct clock-frequency property. |
| |
| i) The EMAC node itself |
| |
| Required properties: |
| - device_type : "network" |
| |
| - compatible : compatible list, contains 2 entries, first is |
| "ibm,emac-CHIP" where CHIP is the host ASIC (440gx, |
| 405gp, Axon) and second is either "ibm,emac" or |
| "ibm,emac4". For Axon, thus, we have: "ibm,emac-axon", |
| "ibm,emac4" |
| - interrupts : <interrupt mapping for EMAC IRQ and WOL IRQ> |
| - interrupt-parent : optional, if needed for interrupt mapping |
| - reg : <registers mapping> |
| - local-mac-address : 6 bytes, MAC address |
| - mal-device : phandle of the associated McMAL node |
| - mal-tx-channel : 1 cell, index of the tx channel on McMAL associated |
| with this EMAC |
| - mal-rx-channel : 1 cell, index of the rx channel on McMAL associated |
| with this EMAC |
| - cell-index : 1 cell, hardware index of the EMAC cell on a given |
| ASIC (typically 0x0 and 0x1 for EMAC0 and EMAC1 on |
| each Axon chip) |
| - max-frame-size : 1 cell, maximum frame size supported in bytes |
| - rx-fifo-size : 1 cell, Rx fifo size in bytes for 10 and 100 Mb/sec |
| operations. |
| For Axon, 2048 |
| - tx-fifo-size : 1 cell, Tx fifo size in bytes for 10 and 100 Mb/sec |
| operations. |
| For Axon, 2048. |
| - fifo-entry-size : 1 cell, size of a fifo entry (used to calculate |
| thresholds). |
| For Axon, 0x00000010 |
| - mal-burst-size : 1 cell, MAL burst size (used to calculate thresholds) |
| in bytes. |
| For Axon, 0x00000100 (I think ...) |
| - phy-mode : string, mode of operations of the PHY interface. |
| Supported values are: "mii", "rmii", "smii", "rgmii", |
| "tbi", "gmii", rtbi", "sgmii". |
| For Axon on CAB, it is "rgmii" |
| - mdio-device : 1 cell, required iff using shared MDIO registers |
| (440EP). phandle of the EMAC to use to drive the |
| MDIO lines for the PHY used by this EMAC. |
| - zmii-device : 1 cell, required iff connected to a ZMII. phandle of |
| the ZMII device node |
| - zmii-channel : 1 cell, required iff connected to a ZMII. Which ZMII |
| channel or 0xffffffff if ZMII is only used for MDIO. |
| - rgmii-device : 1 cell, required iff connected to an RGMII. phandle |
| of the RGMII device node. |
| For Axon: phandle of plb5/plb4/opb/rgmii |
| - rgmii-channel : 1 cell, required iff connected to an RGMII. Which |
| RGMII channel is used by this EMAC. |
| Fox Axon: present, whatever value is appropriate for each |
| EMAC, that is the content of the current (bogus) "phy-port" |
| property. |
| |
| Optional properties: |
| - phy-address : 1 cell, optional, MDIO address of the PHY. If absent, |
| a search is performed. |
| - phy-map : 1 cell, optional, bitmap of addresses to probe the PHY |
| for, used if phy-address is absent. bit 0x00000001 is |
| MDIO address 0. |
| For Axon it can be absent, thouugh my current driver |
| doesn't handle phy-address yet so for now, keep |
| 0x00ffffff in it. |
| - rx-fifo-size-gige : 1 cell, Rx fifo size in bytes for 1000 Mb/sec |
| operations (if absent the value is the same as |
| rx-fifo-size). For Axon, either absent or 2048. |
| - tx-fifo-size-gige : 1 cell, Tx fifo size in bytes for 1000 Mb/sec |
| operations (if absent the value is the same as |
| tx-fifo-size). For Axon, either absent or 2048. |
| - tah-device : 1 cell, optional. If connected to a TAH engine for |
| offload, phandle of the TAH device node. |
| - tah-channel : 1 cell, optional. If appropriate, channel used on the |
| TAH engine. |
| |
| Example: |
| |
| EMAC0: ethernet@40000800 { |
| device_type = "network"; |
| compatible = "ibm,emac-440gp", "ibm,emac"; |
| interrupt-parent = <&UIC1>; |
| interrupts = <1c 4 1d 4>; |
| reg = <40000800 70>; |
| local-mac-address = [00 04 AC E3 1B 1E]; |
| mal-device = <&MAL0>; |
| mal-tx-channel = <0 1>; |
| mal-rx-channel = <0>; |
| cell-index = <0>; |
| max-frame-size = <5dc>; |
| rx-fifo-size = <1000>; |
| tx-fifo-size = <800>; |
| phy-mode = "rmii"; |
| phy-map = <00000001>; |
| zmii-device = <&ZMII0>; |
| zmii-channel = <0>; |
| }; |
| |
| ii) McMAL node |
| |
| Required properties: |
| - device_type : "dma-controller" |
| - compatible : compatible list, containing 2 entries, first is |
| "ibm,mcmal-CHIP" where CHIP is the host ASIC (like |
| emac) and the second is either "ibm,mcmal" or |
| "ibm,mcmal2". |
| For Axon, "ibm,mcmal-axon","ibm,mcmal2" |
| - interrupts : <interrupt mapping for the MAL interrupts sources: |
| 5 sources: tx_eob, rx_eob, serr, txde, rxde>. |
| For Axon: This is _different_ from the current |
| firmware. We use the "delayed" interrupts for txeob |
| and rxeob. Thus we end up with mapping those 5 MPIC |
| interrupts, all level positive sensitive: 10, 11, 32, |
| 33, 34 (in decimal) |
| - dcr-reg : < DCR registers range > |
| - dcr-parent : if needed for dcr-reg |
| - num-tx-chans : 1 cell, number of Tx channels |
| - num-rx-chans : 1 cell, number of Rx channels |
| |
| iii) ZMII node |
| |
| Required properties: |
| - compatible : compatible list, containing 2 entries, first is |
| "ibm,zmii-CHIP" where CHIP is the host ASIC (like |
| EMAC) and the second is "ibm,zmii". |
| For Axon, there is no ZMII node. |
| - reg : <registers mapping> |
| |
| iv) RGMII node |
| |
| Required properties: |
| - compatible : compatible list, containing 2 entries, first is |
| "ibm,rgmii-CHIP" where CHIP is the host ASIC (like |
| EMAC) and the second is "ibm,rgmii". |
| For Axon, "ibm,rgmii-axon","ibm,rgmii" |
| - reg : <registers mapping> |
| - revision : as provided by the RGMII new version register if |
| available. |
| For Axon: 0x0000012a |
| |
| o) Xilinx IP cores |
| |
| The Xilinx EDK toolchain ships with a set of IP cores (devices) for use |
| in Xilinx Spartan and Virtex FPGAs. The devices cover the whole range |
| of standard device types (network, serial, etc.) and miscellanious |
| devices (gpio, LCD, spi, etc). Also, since these devices are |
| implemented within the fpga fabric every instance of the device can be |
| synthesised with different options that change the behaviour. |
| |
| Each IP-core has a set of parameters which the FPGA designer can use to |
| control how the core is synthesized. Historically, the EDK tool would |
| extract the device parameters relevant to device drivers and copy them |
| into an 'xparameters.h' in the form of #define symbols. This tells the |
| device drivers how the IP cores are configured, but it requres the kernel |
| to be recompiled every time the FPGA bitstream is resynthesized. |
| |
| The new approach is to export the parameters into the device tree and |
| generate a new device tree each time the FPGA bitstream changes. The |
| parameters which used to be exported as #defines will now become |
| properties of the device node. In general, device nodes for IP-cores |
| will take the following form: |
| |
| (name): (generic-name)@(base-address) { |
| compatible = "xlnx,(ip-core-name)-(HW_VER)" |
| [, (list of compatible devices), ...]; |
| reg = <(baseaddr) (size)>; |
| interrupt-parent = <&interrupt-controller-phandle>; |
| interrupts = < ... >; |
| xlnx,(parameter1) = "(string-value)"; |
| xlnx,(parameter2) = <(int-value)>; |
| }; |
| |
| (generic-name): an open firmware-style name that describes the |
| generic class of device. Preferably, this is one word, such |
| as 'serial' or 'ethernet'. |
| (ip-core-name): the name of the ip block (given after the BEGIN |
| directive in system.mhs). Should be in lowercase |
| and all underscores '_' converted to dashes '-'. |
| (name): is derived from the "PARAMETER INSTANCE" value. |
| (parameter#): C_* parameters from system.mhs. The C_ prefix is |
| dropped from the parameter name, the name is converted |
| to lowercase and all underscore '_' characters are |
| converted to dashes '-'. |
| (baseaddr): the baseaddr parameter value (often named C_BASEADDR). |
| (HW_VER): from the HW_VER parameter. |
| (size): the address range size (often C_HIGHADDR - C_BASEADDR + 1). |
| |
| Typically, the compatible list will include the exact IP core version |
| followed by an older IP core version which implements the same |
| interface or any other device with the same interface. |
| |
| 'reg', 'interrupt-parent' and 'interrupts' are all optional properties. |
| |
| For example, the following block from system.mhs: |
| |
| BEGIN opb_uartlite |
| PARAMETER INSTANCE = opb_uartlite_0 |
| PARAMETER HW_VER = 1.00.b |
| PARAMETER C_BAUDRATE = 115200 |
| PARAMETER C_DATA_BITS = 8 |
| PARAMETER C_ODD_PARITY = 0 |
| PARAMETER C_USE_PARITY = 0 |
| PARAMETER C_CLK_FREQ = 50000000 |
| PARAMETER C_BASEADDR = 0xEC100000 |
| PARAMETER C_HIGHADDR = 0xEC10FFFF |
| BUS_INTERFACE SOPB = opb_7 |
| PORT OPB_Clk = CLK_50MHz |
| PORT Interrupt = opb_uartlite_0_Interrupt |
| PORT RX = opb_uartlite_0_RX |
| PORT TX = opb_uartlite_0_TX |
| PORT OPB_Rst = sys_bus_reset_0 |
| END |
| |
| becomes the following device tree node: |
| |
| opb_uartlite_0: serial@ec100000 { |
| device_type = "serial"; |
| compatible = "xlnx,opb-uartlite-1.00.b"; |
| reg = <ec100000 10000>; |
| interrupt-parent = <&opb_intc_0>; |
| interrupts = <1 0>; // got this from the opb_intc parameters |
| current-speed = <d#115200>; // standard serial device prop |
| clock-frequency = <d#50000000>; // standard serial device prop |
| xlnx,data-bits = <8>; |
| xlnx,odd-parity = <0>; |
| xlnx,use-parity = <0>; |
| }; |
| |
| Some IP cores actually implement 2 or more logical devices. In |
| this case, the device should still describe the whole IP core with |
| a single node and add a child node for each logical device. The |
| ranges property can be used to translate from parent IP-core to the |
| registers of each device. In addition, the parent node should be |
| compatible with the bus type 'xlnx,compound', and should contain |
| #address-cells and #size-cells, as with any other bus. (Note: this |
| makes the assumption that both logical devices have the same bus |
| binding. If this is not true, then separate nodes should be used |
| for each logical device). The 'cell-index' property can be used to |
| enumerate logical devices within an IP core. For example, the |
| following is the system.mhs entry for the dual ps2 controller found |
| on the ml403 reference design. |
| |
| BEGIN opb_ps2_dual_ref |
| PARAMETER INSTANCE = opb_ps2_dual_ref_0 |
| PARAMETER HW_VER = 1.00.a |
| PARAMETER C_BASEADDR = 0xA9000000 |
| PARAMETER C_HIGHADDR = 0xA9001FFF |
| BUS_INTERFACE SOPB = opb_v20_0 |
| PORT Sys_Intr1 = ps2_1_intr |
| PORT Sys_Intr2 = ps2_2_intr |
| PORT Clkin1 = ps2_clk_rx_1 |
| PORT Clkin2 = ps2_clk_rx_2 |
| PORT Clkpd1 = ps2_clk_tx_1 |
| PORT Clkpd2 = ps2_clk_tx_2 |
| PORT Rx1 = ps2_d_rx_1 |
| PORT Rx2 = ps2_d_rx_2 |
| PORT Txpd1 = ps2_d_tx_1 |
| PORT Txpd2 = ps2_d_tx_2 |
| END |
| |
| It would result in the following device tree nodes: |
| |
| opb_ps2_dual_ref_0: opb-ps2-dual-ref@a9000000 { |
| #address-cells = <1>; |
| #size-cells = <1>; |
| compatible = "xlnx,compound"; |
| ranges = <0 a9000000 2000>; |
| // If this device had extra parameters, then they would |
| // go here. |
| ps2@0 { |
| compatible = "xlnx,opb-ps2-dual-ref-1.00.a"; |
| reg = <0 40>; |
| interrupt-parent = <&opb_intc_0>; |
| interrupts = <3 0>; |
| cell-index = <0>; |
| }; |
| ps2@1000 { |
| compatible = "xlnx,opb-ps2-dual-ref-1.00.a"; |
| reg = <1000 40>; |
| interrupt-parent = <&opb_intc_0>; |
| interrupts = <3 0>; |
| cell-index = <0>; |
| }; |
| }; |
| |
| Also, the system.mhs file defines bus attachments from the processor |
| to the devices. The device tree structure should reflect the bus |
| attachments. Again an example; this system.mhs fragment: |
| |
| BEGIN ppc405_virtex4 |
| PARAMETER INSTANCE = ppc405_0 |
| PARAMETER HW_VER = 1.01.a |
| BUS_INTERFACE DPLB = plb_v34_0 |
| BUS_INTERFACE IPLB = plb_v34_0 |
| END |
| |
| BEGIN opb_intc |
| PARAMETER INSTANCE = opb_intc_0 |
| PARAMETER HW_VER = 1.00.c |
| PARAMETER C_BASEADDR = 0xD1000FC0 |
| PARAMETER C_HIGHADDR = 0xD1000FDF |
| BUS_INTERFACE SOPB = opb_v20_0 |
| END |
| |
| BEGIN opb_uart16550 |
| PARAMETER INSTANCE = opb_uart16550_0 |
| PARAMETER HW_VER = 1.00.d |
| PARAMETER C_BASEADDR = 0xa0000000 |
| PARAMETER C_HIGHADDR = 0xa0001FFF |
| BUS_INTERFACE SOPB = opb_v20_0 |
| END |
| |
| BEGIN plb_v34 |
| PARAMETER INSTANCE = plb_v34_0 |
| PARAMETER HW_VER = 1.02.a |
| END |
| |
| BEGIN plb_bram_if_cntlr |
| PARAMETER INSTANCE = plb_bram_if_cntlr_0 |
| PARAMETER HW_VER = 1.00.b |
| PARAMETER C_BASEADDR = 0xFFFF0000 |
| PARAMETER C_HIGHADDR = 0xFFFFFFFF |
| BUS_INTERFACE SPLB = plb_v34_0 |
| END |
| |
| BEGIN plb2opb_bridge |
| PARAMETER INSTANCE = plb2opb_bridge_0 |
| PARAMETER HW_VER = 1.01.a |
| PARAMETER C_RNG0_BASEADDR = 0x20000000 |
| PARAMETER C_RNG0_HIGHADDR = 0x3FFFFFFF |
| PARAMETER C_RNG1_BASEADDR = 0x60000000 |
| PARAMETER C_RNG1_HIGHADDR = 0x7FFFFFFF |
| PARAMETER C_RNG2_BASEADDR = 0x80000000 |
| PARAMETER C_RNG2_HIGHADDR = 0xBFFFFFFF |
| PARAMETER C_RNG3_BASEADDR = 0xC0000000 |
| PARAMETER C_RNG3_HIGHADDR = 0xDFFFFFFF |
| BUS_INTERFACE SPLB = plb_v34_0 |
| BUS_INTERFACE MOPB = opb_v20_0 |
| END |
| |
| Gives this device tree (some properties removed for clarity): |
| |
| plb@0 { |
| #address-cells = <1>; |
| #size-cells = <1>; |
| compatible = "xlnx,plb-v34-1.02.a"; |
| device_type = "ibm,plb"; |
| ranges; // 1:1 translation |
| |
| plb_bram_if_cntrl_0: bram@ffff0000 { |
| reg = <ffff0000 10000>; |
| } |
| |
| opb@20000000 { |
| #address-cells = <1>; |
| #size-cells = <1>; |
| ranges = <20000000 20000000 20000000 |
| 60000000 60000000 20000000 |
| 80000000 80000000 40000000 |
| c0000000 c0000000 20000000>; |
| |
| opb_uart16550_0: serial@a0000000 { |
| reg = <a00000000 2000>; |
| }; |
| |
| opb_intc_0: interrupt-controller@d1000fc0 { |
| reg = <d1000fc0 20>; |
| }; |
| }; |
| }; |
| |
| That covers the general approach to binding xilinx IP cores into the |
| device tree. The following are bindings for specific devices: |
| |
| i) Xilinx ML300 Framebuffer |
| |
| Simple framebuffer device from the ML300 reference design (also on the |
| ML403 reference design as well as others). |
| |
| Optional properties: |
| - resolution = <xres yres> : pixel resolution of framebuffer. Some |
| implementations use a different resolution. |
| Default is <d#640 d#480> |
| - virt-resolution = <xvirt yvirt> : Size of framebuffer in memory. |
| Default is <d#1024 d#480>. |
| - rotate-display (empty) : rotate display 180 degrees. |
| |
| ii) Xilinx SystemACE |
| |
| The Xilinx SystemACE device is used to program FPGAs from an FPGA |
| bitstream stored on a CF card. It can also be used as a generic CF |
| interface device. |
| |
| Optional properties: |
| - 8-bit (empty) : Set this property for SystemACE in 8 bit mode |
| |
| iii) Xilinx EMAC and Xilinx TEMAC |
| |
| Xilinx Ethernet devices. In addition to general xilinx properties |
| listed above, nodes for these devices should include a phy-handle |
| property, and may include other common network device properties |
| like local-mac-address. |
| |
| iv) Xilinx Uartlite |
| |
| Xilinx uartlite devices are simple fixed speed serial ports. |
| |
| Requred properties: |
| - current-speed : Baud rate of uartlite |
| |
| v) Xilinx hwicap |
| |
| Xilinx hwicap devices provide access to the configuration logic |
| of the FPGA through the Internal Configuration Access Port |
| (ICAP). The ICAP enables partial reconfiguration of the FPGA, |
| readback of the configuration information, and some control over |
| 'warm boots' of the FPGA fabric. |
| |
| Required properties: |
| - xlnx,family : The family of the FPGA, necessary since the |
| capabilities of the underlying ICAP hardware |
| differ between different families. May be |
| 'virtex2p', 'virtex4', or 'virtex5'. |
| |
| vi) Xilinx Uart 16550 |
| |
| Xilinx UART 16550 devices are very similar to the NS16550 but with |
| different register spacing and an offset from the base address. |
| |
| Requred properties: |
| - clock-frequency : Frequency of the clock input |
| - reg-offset : A value of 3 is required |
| - reg-shift : A value of 2 is required |
| |
| |
| p) Freescale Synchronous Serial Interface |
| |
| The SSI is a serial device that communicates with audio codecs. It can |
| be programmed in AC97, I2S, left-justified, or right-justified modes. |
| |
| Required properties: |
| - compatible : compatible list, containing "fsl,ssi" |
| - cell-index : the SSI, <0> = SSI1, <1> = SSI2, and so on |
| - reg : offset and length of the register set for the device |
| - interrupts : <a b> where a is the interrupt number and b is a |
| field that represents an encoding of the sense and |
| level information for the interrupt. This should be |
| encoded based on the information in section 2) |
| depending on the type of interrupt controller you |
| have. |
| - interrupt-parent : the phandle for the interrupt controller that |
| services interrupts for this device. |
| - fsl,mode : the operating mode for the SSI interface |
| "i2s-slave" - I2S mode, SSI is clock slave |
| "i2s-master" - I2S mode, SSI is clock master |
| "lj-slave" - left-justified mode, SSI is clock slave |
| "lj-master" - l.j. mode, SSI is clock master |
| "rj-slave" - right-justified mode, SSI is clock slave |
| "rj-master" - r.j., SSI is clock master |
| "ac97-slave" - AC97 mode, SSI is clock slave |
| "ac97-master" - AC97 mode, SSI is clock master |
| |
| Optional properties: |
| - codec-handle : phandle to a 'codec' node that defines an audio |
| codec connected to this SSI. This node is typically |
| a child of an I2C or other control node. |
| |
| Child 'codec' node required properties: |
| - compatible : compatible list, contains the name of the codec |
| |
| Child 'codec' node optional properties: |
| - clock-frequency : The frequency of the input clock, which typically |
| comes from an on-board dedicated oscillator. |
| |
| * Freescale 83xx DMA Controller |
| |
| Freescale PowerPC 83xx have on chip general purpose DMA controllers. |
| |
| Required properties: |
| |
| - compatible : compatible list, contains 2 entries, first is |
| "fsl,CHIP-dma", where CHIP is the processor |
| (mpc8349, mpc8360, etc.) and the second is |
| "fsl,elo-dma" |
| - reg : <registers mapping for DMA general status reg> |
| - ranges : Should be defined as specified in 1) to describe the |
| DMA controller channels. |
| - cell-index : controller index. 0 for controller @ 0x8100 |
| - interrupts : <interrupt mapping for DMA IRQ> |
| - interrupt-parent : optional, if needed for interrupt mapping |
| |
| |
| - DMA channel nodes: |
| - compatible : compatible list, contains 2 entries, first is |
| "fsl,CHIP-dma-channel", where CHIP is the processor |
| (mpc8349, mpc8350, etc.) and the second is |
| "fsl,elo-dma-channel" |
| - reg : <registers mapping for channel> |
| - cell-index : dma channel index starts at 0. |
| |
| Optional properties: |
| - interrupts : <interrupt mapping for DMA channel IRQ> |
| (on 83xx this is expected to be identical to |
| the interrupts property of the parent node) |
| - interrupt-parent : optional, if needed for interrupt mapping |
| |
| Example: |
| dma@82a8 { |
| #address-cells = <1>; |
| #size-cells = <1>; |
| compatible = "fsl,mpc8349-dma", "fsl,elo-dma"; |
| reg = <82a8 4>; |
| ranges = <0 8100 1a4>; |
| interrupt-parent = <&ipic>; |
| interrupts = <47 8>; |
| cell-index = <0>; |
| dma-channel@0 { |
| compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel"; |
| cell-index = <0>; |
| reg = <0 80>; |
| }; |
| dma-channel@80 { |
| compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel"; |
| cell-index = <1>; |
| reg = <80 80>; |
| }; |
| dma-channel@100 { |
| compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel"; |
| cell-index = <2>; |
| reg = <100 80>; |
| }; |
| dma-channel@180 { |
| compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel"; |
| cell-index = <3>; |
| reg = <180 80>; |
| }; |
| }; |
| |
| * Freescale 85xx/86xx DMA Controller |
| |
| Freescale PowerPC 85xx/86xx have on chip general purpose DMA controllers. |
| |
| Required properties: |
| |
| - compatible : compatible list, contains 2 entries, first is |
| "fsl,CHIP-dma", where CHIP is the processor |
| (mpc8540, mpc8540, etc.) and the second is |
| "fsl,eloplus-dma" |
| - reg : <registers mapping for DMA general status reg> |
| - cell-index : controller index. 0 for controller @ 0x21000, |
| 1 for controller @ 0xc000 |
| - ranges : Should be defined as specified in 1) to describe the |
| DMA controller channels. |
| |
| - DMA channel nodes: |
| - compatible : compatible list, contains 2 entries, first is |
| "fsl,CHIP-dma-channel", where CHIP is the processor |
| (mpc8540, mpc8560, etc.) and the second is |
| "fsl,eloplus-dma-channel" |
| - cell-index : dma channel index starts at 0. |
| - reg : <registers mapping for channel> |
| - interrupts : <interrupt mapping for DMA channel IRQ> |
| - interrupt-parent : optional, if needed for interrupt mapping |
| |
| Example: |
| dma@21300 { |
| #address-cells = <1>; |
| #size-cells = <1>; |
| compatible = "fsl,mpc8540-dma", "fsl,eloplus-dma"; |
| reg = <21300 4>; |
| ranges = <0 21100 200>; |
| cell-index = <0>; |
| dma-channel@0 { |
| compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel"; |
| reg = <0 80>; |
| cell-index = <0>; |
| interrupt-parent = <&mpic>; |
| interrupts = <14 2>; |
| }; |
| dma-channel@80 { |
| compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel"; |
| reg = <80 80>; |
| cell-index = <1>; |
| interrupt-parent = <&mpic>; |
| interrupts = <15 2>; |
| }; |
| dma-channel@100 { |
| compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel"; |
| reg = <100 80>; |
| cell-index = <2>; |
| interrupt-parent = <&mpic>; |
| interrupts = <16 2>; |
| }; |
| dma-channel@180 { |
| compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel"; |
| reg = <180 80>; |
| cell-index = <3>; |
| interrupt-parent = <&mpic>; |
| interrupts = <17 2>; |
| }; |
| }; |
| |
| * Freescale 8xxx/3.0 Gb/s SATA nodes |
| |
| SATA nodes are defined to describe on-chip Serial ATA controllers. |
| Each SATA port should have its own node. |
| |
| Required properties: |
| - compatible : compatible list, contains 2 entries, first is |
| "fsl,CHIP-sata", where CHIP is the processor |
| (mpc8315, mpc8379, etc.) and the second is |
| "fsl,pq-sata" |
| - interrupts : <interrupt mapping for SATA IRQ> |
| - cell-index : controller index. |
| 1 for controller @ 0x18000 |
| 2 for controller @ 0x19000 |
| 3 for controller @ 0x1a000 |
| 4 for controller @ 0x1b000 |
| |
| Optional properties: |
| - interrupt-parent : optional, if needed for interrupt mapping |
| - reg : <registers mapping> |
| |
| Example: |
| |
| sata@18000 { |
| compatible = "fsl,mpc8379-sata", "fsl,pq-sata"; |
| reg = <0x18000 0x1000>; |
| cell-index = <1>; |
| interrupts = <2c 8>; |
| interrupt-parent = < &ipic >; |
| }; |
| |
| q) USB EHCI controllers |
| |
| Required properties: |
| - compatible : should be "usb-ehci". |
| - reg : should contain at least address and length of the standard EHCI |
| register set for the device. Optional platform-dependent registers |
| (debug-port or other) can be also specified here, but only after |
| definition of standard EHCI registers. |
| - interrupts : one EHCI interrupt should be described here. |
| If device registers are implemented in big endian mode, the device |
| node should have "big-endian-regs" property. |
| If controller implementation operates with big endian descriptors, |
| "big-endian-desc" property should be specified. |
| If both big endian registers and descriptors are used by the controller |
| implementation, "big-endian" property can be specified instead of having |
| both "big-endian-regs" and "big-endian-desc". |
| |
| Example (Sequoia 440EPx): |
| ehci@e0000300 { |
| compatible = "ibm,usb-ehci-440epx", "usb-ehci"; |
| interrupt-parent = <&UIC0>; |
| interrupts = <1a 4>; |
| reg = <0 e0000300 90 0 e0000390 70>; |
| big-endian; |
| }; |
| |
| r) Freescale Display Interface Unit |
| |
| The Freescale DIU is a LCD controller, with proper hardware, it can also |
| drive DVI monitors. |
| |
| Required properties: |
| - compatible : should be "fsl-diu". |
| - reg : should contain at least address and length of the DIU register |
| set. |
| - Interrupts : one DIU interrupt should be describe here. |
| |
| Example (MPC8610HPCD) |
| display@2c000 { |
| compatible = "fsl,diu"; |
| reg = <0x2c000 100>; |
| interrupts = <72 2>; |
| interrupt-parent = <&mpic>; |
| }; |
| |
| s) Freescale on board FPGA |
| |
| This is the memory-mapped registers for on board FPGA. |
| |
| Required properities: |
| - compatible : should be "fsl,fpga-pixis". |
| - reg : should contain the address and the lenght of the FPPGA register |
| set. |
| |
| Example (MPC8610HPCD) |
| board-control@e8000000 { |
| compatible = "fsl,fpga-pixis"; |
| reg = <0xe8000000 32>; |
| }; |
| |
| t) Freescale MSI interrupt controller |
| |
| Reguired properities: |
| - compatible : compatible list, contains 2 entries, |
| first is "fsl,CHIP-msi", where CHIP is the processor(mpc8610, mpc8572, |
| etc.) and the second is "fsl,mpic-msi" or "fsl,ipic-msi" depending on |
| the parent type. |
| - reg : should contain the address and the length of the shared message |
| interrupt register set. |
| - msi-available-ranges: use <start count> style section to define which |
| msi interrupt can be used in the 256 msi interrupts. This property is |
| optional, without this, all the 256 MSI interrupts can be used. |
| - interrupts : each one of the interrupts here is one entry per 32 MSIs, |
| and routed to the host interrupt controller. the interrupts should |
| be set as edge sensitive. |
| - interrupt-parent: the phandle for the interrupt controller |
| that services interrupts for this device. for 83xx cpu, the interrupts |
| are routed to IPIC, and for 85xx/86xx cpu the interrupts are routed |
| to MPIC. |
| |
| Example |
| msi@41600 { |
| compatible = "fsl,mpc8610-msi", "fsl,mpic-msi"; |
| reg = <0x41600 0x80>; |
| msi-available-ranges = <0 0x100>; |
| interrupts = < |
| 0xe0 0 |
| 0xe1 0 |
| 0xe2 0 |
| 0xe3 0 |
| 0xe4 0 |
| 0xe5 0 |
| 0xe6 0 |
| 0xe7 0>; |
| interrupt-parent = <&mpic>; |
| }; |
| |
| u) Freescale General-purpose Timers Module |
| |
| Required properties: |
| - compatible : should be |
| "fsl,<chip>-gtm", "fsl,gtm" for SOC GTMs |
| "fsl,<chip>-qe-gtm", "fsl,qe-gtm", "fsl,gtm" for QE GTMs |
| "fsl,<chip>-cpm2-gtm", "fsl,cpm2-gtm", "fsl,gtm" for CPM2 GTMs |
| - reg : should contain gtm registers location and length (0x40). |
| - interrupts : should contain four interrupts. |
| - interrupt-parent : interrupt source phandle. |
| - clock-frequency : specifies the frequency driving the timer. |
| |
| Example: |
| |
| timer@500 { |
| compatible = "fsl,mpc8360-gtm", "fsl,gtm"; |
| reg = <0x500 0x40>; |
| interrupts = <90 8 78 8 84 8 72 8>; |
| interrupt-parent = <&ipic>; |
| /* filled by u-boot */ |
| clock-frequency = <0>; |
| }; |
| |
| timer@440 { |
| compatible = "fsl,mpc8360-qe-gtm", "fsl,qe-gtm", "fsl,gtm"; |
| reg = <0x440 0x40>; |
| interrupts = <12 13 14 15>; |
| interrupt-parent = <&qeic>; |
| /* filled by u-boot */ |
| clock-frequency = <0>; |
| }; |
| |
| VII - Marvell Discovery mv64[345]6x System Controller chips |
| =========================================================== |
| |
| The Marvell mv64[345]60 series of system controller chips contain |
| many of the peripherals needed to implement a complete computer |
| system. In this section, we define device tree nodes to describe |
| the system controller chip itself and each of the peripherals |
| which it contains. Compatible string values for each node are |
| prefixed with the string "marvell,", for Marvell Technology Group Ltd. |
| |
| 1) The /system-controller node |
| |
| This node is used to represent the system-controller and must be |
| present when the system uses a system contller chip. The top-level |
| system-controller node contains information that is global to all |
| devices within the system controller chip. The node name begins |
| with "system-controller" followed by the unit address, which is |
| the base address of the memory-mapped register set for the system |
| controller chip. |
| |
| Required properties: |
| |
| - ranges : Describes the translation of system controller addresses |
| for memory mapped registers. |
| - clock-frequency: Contains the main clock frequency for the system |
| controller chip. |
| - reg : This property defines the address and size of the |
| memory-mapped registers contained within the system controller |
| chip. The address specified in the "reg" property should match |
| the unit address of the system-controller node. |
| - #address-cells : Address representation for system controller |
| devices. This field represents the number of cells needed to |
| represent the address of the memory-mapped registers of devices |
| within the system controller chip. |
| - #size-cells : Size representation for for the memory-mapped |
| registers within the system controller chip. |
| - #interrupt-cells : Defines the width of cells used to represent |
| interrupts. |
| |
| Optional properties: |
| |
| - model : The specific model of the system controller chip. Such |
| as, "mv64360", "mv64460", or "mv64560". |
| - compatible : A string identifying the compatibility identifiers |
| of the system controller chip. |
| |
| The system-controller node contains child nodes for each system |
| controller device that the platform uses. Nodes should not be created |
| for devices which exist on the system controller chip but are not used |
| |
| Example Marvell Discovery mv64360 system-controller node: |
| |
| system-controller@f1000000 { /* Marvell Discovery mv64360 */ |
| #address-cells = <1>; |
| #size-cells = <1>; |
| model = "mv64360"; /* Default */ |
| compatible = "marvell,mv64360"; |
| clock-frequency = <133333333>; |
| reg = <0xf1000000 0x10000>; |
| virtual-reg = <0xf1000000>; |
| ranges = <0x88000000 0x88000000 0x1000000 /* PCI 0 I/O Space */ |
| 0x80000000 0x80000000 0x8000000 /* PCI 0 MEM Space */ |
| 0xa0000000 0xa0000000 0x4000000 /* User FLASH */ |
| 0x00000000 0xf1000000 0x0010000 /* Bridge's regs */ |
| 0xf2000000 0xf2000000 0x0040000>;/* Integrated SRAM */ |
| |
| [ child node definitions... ] |
| } |
| |
| 2) Child nodes of /system-controller |
| |
| a) Marvell Discovery MDIO bus |
| |
| The MDIO is a bus to which the PHY devices are connected. For each |
| device that exists on this bus, a child node should be created. See |
| the definition of the PHY node below for an example of how to define |
| a PHY. |
| |
| Required properties: |
| - #address-cells : Should be <1> |
| - #size-cells : Should be <0> |
| - device_type : Should be "mdio" |
| - compatible : Should be "marvell,mv64360-mdio" |
| |
| Example: |
| |
| mdio { |
| #address-cells = <1>; |
| #size-cells = <0>; |
| device_type = "mdio"; |
| compatible = "marvell,mv64360-mdio"; |
| |
| ethernet-phy@0 { |
| ...... |
| }; |
| }; |
| |
| |
| b) Marvell Discovery ethernet controller |
| |
| The Discover ethernet controller is described with two levels |
| of nodes. The first level describes an ethernet silicon block |
| and the second level describes up to 3 ethernet nodes within |
| that block. The reason for the multiple levels is that the |
| registers for the node are interleaved within a single set |
| of registers. The "ethernet-block" level describes the |
| shared register set, and the "ethernet" nodes describe ethernet |
| port-specific properties. |
| |
| Ethernet block node |
| |
| Required properties: |
| - #address-cells : <1> |
| - #size-cells : <0> |
| - compatible : "marvell,mv64360-eth-block" |
| - reg : Offset and length of the register set for this block |
| |
| Example Discovery Ethernet block node: |
| ethernet-block@2000 { |
| #address-cells = <1>; |
| #size-cells = <0>; |
| compatible = "marvell,mv64360-eth-block"; |
| reg = <0x2000 0x2000>; |
| ethernet@0 { |
| ....... |
| }; |
| }; |
| |
| Ethernet port node |
| |
| Required properties: |
| - device_type : Should be "network". |
| - compatible : Should be "marvell,mv64360-eth". |
| - reg : Should be <0>, <1>, or <2>, according to which registers |
| within the silicon block the device uses. |
| - interrupts : <a> where a is the interrupt number for the port. |
| - interrupt-parent : the phandle for the interrupt controller |
| that services interrupts for this device. |
| - phy : the phandle for the PHY connected to this ethernet |
| controller. |
| - local-mac-address : 6 bytes, MAC address |
| |
| Example Discovery Ethernet port node: |
| ethernet@0 { |
| device_type = "network"; |
| compatible = "marvell,mv64360-eth"; |
| reg = <0>; |
| interrupts = <32>; |
| interrupt-parent = <&PIC>; |
| phy = <&PHY0>; |
| local-mac-address = [ 00 00 00 00 00 00 ]; |
| }; |
| |
| |
| |
| c) Marvell Discovery PHY nodes |
| |
| Required properties: |
| - device_type : Should be "ethernet-phy" |
| - interrupts : <a> where a is the interrupt number for this phy. |
| - interrupt-parent : the phandle for the interrupt controller that |
| services interrupts for this device. |
| - reg : The ID number for the phy, usually a small integer |
| |
| Example Discovery PHY node: |
| ethernet-phy@1 { |
| device_type = "ethernet-phy"; |
| compatible = "broadcom,bcm5421"; |
| interrupts = <76>; /* GPP 12 */ |
| interrupt-parent = <&PIC>; |
| reg = <1>; |
| }; |
| |
| |
| d) Marvell Discovery SDMA nodes |
| |
| Represent DMA hardware associated with the MPSC (multiprotocol |
| serial controllers). |
| |
| Required properties: |
| - compatible : "marvell,mv64360-sdma" |
| - reg : Offset and length of the register set for this device |
| - interrupts : <a> where a is the interrupt number for the DMA |
| device. |
| - interrupt-parent : the phandle for the interrupt controller |
| that services interrupts for this device. |
| |
| Example Discovery SDMA node: |
| sdma@4000 { |
| compatible = "marvell,mv64360-sdma"; |
| reg = <0x4000 0xc18>; |
| virtual-reg = <0xf1004000>; |
| interrupts = <36>; |
| interrupt-parent = <&PIC>; |
| }; |
| |
| |
| e) Marvell Discovery BRG nodes |
| |
| Represent baud rate generator hardware associated with the MPSC |
| (multiprotocol serial controllers). |
| |
| Required properties: |
| - compatible : "marvell,mv64360-brg" |
| - reg : Offset and length of the register set for this device |
| - clock-src : A value from 0 to 15 which selects the clock |
| source for the baud rate generator. This value corresponds |
| to the CLKS value in the BRGx configuration register. See |
| the mv64x60 User's Manual. |
| - clock-frequence : The frequency (in Hz) of the baud rate |
| generator's input clock. |
| - current-speed : The current speed setting (presumably by |
| firmware) of the baud rate generator. |
| |
| Example Discovery BRG node: |
| brg@b200 { |
| compatible = "marvell,mv64360-brg"; |
| reg = <0xb200 0x8>; |
| clock-src = <8>; |
| clock-frequency = <133333333>; |
| current-speed = <9600>; |
| }; |
| |
| |
| f) Marvell Discovery CUNIT nodes |
| |
| Represent the Serial Communications Unit device hardware. |
| |
| Required properties: |
| - reg : Offset and length of the register set for this device |
| |
| Example Discovery CUNIT node: |
| cunit@f200 { |
| reg = <0xf200 0x200>; |
| }; |
| |
| |
| g) Marvell Discovery MPSCROUTING nodes |
| |
| Represent the Discovery's MPSC routing hardware |
| |
| Required properties: |
| - reg : Offset and length of the register set for this device |
| |
| Example Discovery CUNIT node: |
| mpscrouting@b500 { |
| reg = <0xb400 0xc>; |
| }; |
| |
| |
| h) Marvell Discovery MPSCINTR nodes |
| |
| Represent the Discovery's MPSC DMA interrupt hardware registers |
| (SDMA cause and mask registers). |
| |
| Required properties: |
| - reg : Offset and length of the register set for this device |
| |
| Example Discovery MPSCINTR node: |
| mpsintr@b800 { |
| reg = <0xb800 0x100>; |
| }; |
| |
| |
| i) Marvell Discovery MPSC nodes |
| |
| Represent the Discovery's MPSC (Multiprotocol Serial Controller) |
| serial port. |
| |
| Required properties: |
| - device_type : "serial" |
| - compatible : "marvell,mv64360-mpsc" |
| - reg : Offset and length of the register set for this device |
| - sdma : the phandle for the SDMA node used by this port |
| - brg : the phandle for the BRG node used by this port |
| - cunit : the phandle for the CUNIT node used by this port |
| - mpscrouting : the phandle for the MPSCROUTING node used by this port |
| - mpscintr : the phandle for the MPSCINTR node used by this port |
| - cell-index : the hardware index of this cell in the MPSC core |
| - max_idle : value needed for MPSC CHR3 (Maximum Frame Length) |
| register |
| - interrupts : <a> where a is the interrupt number for the MPSC. |
| - interrupt-parent : the phandle for the interrupt controller |
| that services interrupts for this device. |
| |
| Example Discovery MPSCINTR node: |
| mpsc@8000 { |
| device_type = "serial"; |
| compatible = "marvell,mv64360-mpsc"; |
| reg = <0x8000 0x38>; |
| virtual-reg = <0xf1008000>; |
| sdma = <&SDMA0>; |
| brg = <&BRG0>; |
| cunit = <&CUNIT>; |
| mpscrouting = <&MPSCROUTING>; |
| mpscintr = <&MPSCINTR>; |
| cell-index = <0>; |
| max_idle = <40>; |
| interrupts = <40>; |
| interrupt-parent = <&PIC>; |
| }; |
| |
| |
| j) Marvell Discovery Watch Dog Timer nodes |
| |
| Represent the Discovery's watchdog timer hardware |
| |
| Required properties: |
| - compatible : "marvell,mv64360-wdt" |
| - reg : Offset and length of the register set for this device |
| |
| Example Discovery Watch Dog Timer node: |
| wdt@b410 { |
| compatible = "marvell,mv64360-wdt"; |
| reg = <0xb410 0x8>; |
| }; |
| |
| |
| k) Marvell Discovery I2C nodes |
| |
| Represent the Discovery's I2C hardware |
| |
| Required properties: |
| - device_type : "i2c" |
| - compatible : "marvell,mv64360-i2c" |
| - reg : Offset and length of the register set for this device |
| - interrupts : <a> where a is the interrupt number for the I2C. |
| - interrupt-parent : the phandle for the interrupt controller |
| that services interrupts for this device. |
| |
| Example Discovery I2C node: |
| compatible = "marvell,mv64360-i2c"; |
| reg = <0xc000 0x20>; |
| virtual-reg = <0xf100c000>; |
| interrupts = <37>; |
| interrupt-parent = <&PIC>; |
| }; |
| |
| |
| l) Marvell Discovery PIC (Programmable Interrupt Controller) nodes |
| |
| Represent the Discovery's PIC hardware |
| |
| Required properties: |
| - #interrupt-cells : <1> |
| - #address-cells : <0> |
| - compatible : "marvell,mv64360-pic" |
| - reg : Offset and length of the register set for this device |
| - interrupt-controller |
| |
| Example Discovery PIC node: |
| pic { |
| #interrupt-cells = <1>; |
| #address-cells = <0>; |
| compatible = "marvell,mv64360-pic"; |
| reg = <0x0 0x88>; |
| interrupt-controller; |
| }; |
| |
| |
| m) Marvell Discovery MPP (Multipurpose Pins) multiplexing nodes |
| |
| Represent the Discovery's MPP hardware |
| |
| Required properties: |
| - compatible : "marvell,mv64360-mpp" |
| - reg : Offset and length of the register set for this device |
| |
| Example Discovery MPP node: |
| mpp@f000 { |
| compatible = "marvell,mv64360-mpp"; |
| reg = <0xf000 0x10>; |
| }; |
| |
| |
| n) Marvell Discovery GPP (General Purpose Pins) nodes |
| |
| Represent the Discovery's GPP hardware |
| |
| Required properties: |
| - compatible : "marvell,mv64360-gpp" |
| - reg : Offset and length of the register set for this device |
| |
| Example Discovery GPP node: |
| gpp@f000 { |
| compatible = "marvell,mv64360-gpp"; |
| reg = <0xf100 0x20>; |
| }; |
| |
| |
| o) Marvell Discovery PCI host bridge node |
| |
| Represents the Discovery's PCI host bridge device. The properties |
| for this node conform to Rev 2.1 of the PCI Bus Binding to IEEE |
| 1275-1994. A typical value for the compatible property is |
| "marvell,mv64360-pci". |
| |
| Example Discovery PCI host bridge node |
| pci@80000000 { |
| #address-cells = <3>; |
| #size-cells = <2>; |
| #interrupt-cells = <1>; |
| device_type = "pci"; |
| compatible = "marvell,mv64360-pci"; |
| reg = <0xcf8 0x8>; |
| ranges = <0x01000000 0x0 0x0 |
| 0x88000000 0x0 0x01000000 |
| 0x02000000 0x0 0x80000000 |
| 0x80000000 0x0 0x08000000>; |
| bus-range = <0 255>; |
| clock-frequency = <66000000>; |
| interrupt-parent = <&PIC>; |
| interrupt-map-mask = <0xf800 0x0 0x0 0x7>; |
| interrupt-map = < |
| /* IDSEL 0x0a */ |
| 0x5000 0 0 1 &PIC 80 |
| 0x5000 0 0 2 &PIC 81 |
| 0x5000 0 0 3 &PIC 91 |
| 0x5000 0 0 4 &PIC 93 |
| |
| /* IDSEL 0x0b */ |
| 0x5800 0 0 1 &PIC 91 |
| 0x5800 0 0 2 &PIC 93 |
| 0x5800 0 0 3 &PIC 80 |
| 0x5800 0 0 4 &PIC 81 |
| |
| /* IDSEL 0x0c */ |
| 0x6000 0 0 1 &PIC 91 |
| 0x6000 0 0 2 &PIC 93 |
| 0x6000 0 0 3 &PIC 80 |
| 0x6000 0 0 4 &PIC 81 |
| |
| /* IDSEL 0x0d */ |
| 0x6800 0 0 1 &PIC 93 |
| 0x6800 0 0 2 &PIC 80 |
| 0x6800 0 0 3 &PIC 81 |
| 0x6800 0 0 4 &PIC 91 |
| >; |
| }; |
| |
| |
| p) Marvell Discovery CPU Error nodes |
| |
| Represent the Discovery's CPU error handler device. |
| |
| Required properties: |
| - compatible : "marvell,mv64360-cpu-error" |
| - reg : Offset and length of the register set for this device |
| - interrupts : the interrupt number for this device |
| - interrupt-parent : the phandle for the interrupt controller |
| that services interrupts for this device. |
| |
| Example Discovery CPU Error node: |
| cpu-error@0070 { |
| compatible = "marvell,mv64360-cpu-error"; |
| reg = <0x70 0x10 0x128 0x28>; |
| interrupts = <3>; |
| interrupt-parent = <&PIC>; |
| }; |
| |
| |
| q) Marvell Discovery SRAM Controller nodes |
| |
| Represent the Discovery's SRAM controller device. |
| |
| Required properties: |
| - compatible : "marvell,mv64360-sram-ctrl" |
| - reg : Offset and length of the register set for this device |
| - interrupts : the interrupt number for this device |
| - interrupt-parent : the phandle for the interrupt controller |
| that services interrupts for this device. |
| |
| Example Discovery SRAM Controller node: |
| sram-ctrl@0380 { |
| compatible = "marvell,mv64360-sram-ctrl"; |
| reg = <0x380 0x80>; |
| interrupts = <13>; |
| interrupt-parent = <&PIC>; |
| }; |
| |
| |
| r) Marvell Discovery PCI Error Handler nodes |
| |
| Represent the Discovery's PCI error handler device. |
| |
| Required properties: |
| - compatible : "marvell,mv64360-pci-error" |
| - reg : Offset and length of the register set for this device |
| - interrupts : the interrupt number for this device |
| - interrupt-parent : the phandle for the interrupt controller |
| that services interrupts for this device. |
| |
| Example Discovery PCI Error Handler node: |
| pci-error@1d40 { |
| compatible = "marvell,mv64360-pci-error"; |
| reg = <0x1d40 0x40 0xc28 0x4>; |
| interrupts = <12>; |
| interrupt-parent = <&PIC>; |
| }; |
| |
| |
| s) Marvell Discovery Memory Controller nodes |
| |
| Represent the Discovery's memory controller device. |
| |
| Required properties: |
| - compatible : "marvell,mv64360-mem-ctrl" |
| - reg : Offset and length of the register set for this device |
| - interrupts : the interrupt number for this device |
| - interrupt-parent : the phandle for the interrupt controller |
| that services interrupts for this device. |
| |
| Example Discovery Memory Controller node: |
| mem-ctrl@1400 { |
| compatible = "marvell,mv64360-mem-ctrl"; |
| reg = <0x1400 0x60>; |
| interrupts = <17>; |
| interrupt-parent = <&PIC>; |
| }; |
| |
| |
| VIII - Specifying interrupt information for devices |
| =================================================== |
| |
| The device tree represents the busses and devices of a hardware |
| system in a form similar to the physical bus topology of the |
| hardware. |
| |
| In addition, a logical 'interrupt tree' exists which represents the |
| hierarchy and routing of interrupts in the hardware. |
| |
| The interrupt tree model is fully described in the |
| document "Open Firmware Recommended Practice: Interrupt |
| Mapping Version 0.9". The document is available at: |
| <http://playground.sun.com/1275/practice>. |
| |
| 1) interrupts property |
| ---------------------- |
| |
| Devices that generate interrupts to a single interrupt controller |
| should use the conventional OF representation described in the |
| OF interrupt mapping documentation. |
| |
| Each device which generates interrupts must have an 'interrupt' |
| property. The interrupt property value is an arbitrary number of |
| of 'interrupt specifier' values which describe the interrupt or |
| interrupts for the device. |
| |
| The encoding of an interrupt specifier is determined by the |
| interrupt domain in which the device is located in the |
| interrupt tree. The root of an interrupt domain specifies in |
| its #interrupt-cells property the number of 32-bit cells |
| required to encode an interrupt specifier. See the OF interrupt |
| mapping documentation for a detailed description of domains. |
| |
| For example, the binding for the OpenPIC interrupt controller |
| specifies an #interrupt-cells value of 2 to encode the interrupt |
| number and level/sense information. All interrupt children in an |
| OpenPIC interrupt domain use 2 cells per interrupt in their interrupts |
| property. |
| |
| The PCI bus binding specifies a #interrupt-cell value of 1 to encode |
| which interrupt pin (INTA,INTB,INTC,INTD) is used. |
| |
| 2) interrupt-parent property |
| ---------------------------- |
| |
| The interrupt-parent property is specified to define an explicit |
| link between a device node and its interrupt parent in |
| the interrupt tree. The value of interrupt-parent is the |
| phandle of the parent node. |
| |
| If the interrupt-parent property is not defined for a node, it's |
| interrupt parent is assumed to be an ancestor in the node's |
| _device tree_ hierarchy. |
| |
| 3) OpenPIC Interrupt Controllers |
| -------------------------------- |
| |
| OpenPIC interrupt controllers require 2 cells to encode |
| interrupt information. The first cell defines the interrupt |
| number. The second cell defines the sense and level |
| information. |
| |
| Sense and level information should be encoded as follows: |
| |
| 0 = low to high edge sensitive type enabled |
| 1 = active low level sensitive type enabled |
| 2 = active high level sensitive type enabled |
| 3 = high to low edge sensitive type enabled |
| |
| 4) ISA Interrupt Controllers |
| ---------------------------- |
| |
| ISA PIC interrupt controllers require 2 cells to encode |
| interrupt information. The first cell defines the interrupt |
| number. The second cell defines the sense and level |
| information. |
| |
| ISA PIC interrupt controllers should adhere to the ISA PIC |
| encodings listed below: |
| |
| 0 = active low level sensitive type enabled |
| 1 = active high level sensitive type enabled |
| 2 = high to low edge sensitive type enabled |
| 3 = low to high edge sensitive type enabled |
| |
| VIII - Specifying GPIO information for devices |
| ============================================== |
| |
| 1) gpios property |
| ----------------- |
| |
| Nodes that makes use of GPIOs should define them using `gpios' property, |
| format of which is: <&gpio-controller1-phandle gpio1-specifier |
| &gpio-controller2-phandle gpio2-specifier |
| 0 /* holes are permitted, means no GPIO 3 */ |
| &gpio-controller4-phandle gpio4-specifier |
| ...>; |
| |
| Note that gpio-specifier length is controller dependent. |
| |
| gpio-specifier may encode: bank, pin position inside the bank, |
| whether pin is open-drain and whether pin is logically inverted. |
| |
| Example of the node using GPIOs: |
| |
| node { |
| gpios = <&qe_pio_e 18 0>; |
| }; |
| |
| In this example gpio-specifier is "18 0" and encodes GPIO pin number, |
| and empty GPIO flags as accepted by the "qe_pio_e" gpio-controller. |
| |
| 2) gpio-controller nodes |
| ------------------------ |
| |
| Every GPIO controller node must have #gpio-cells property defined, |
| this information will be used to translate gpio-specifiers. |
| |
| Example of two SOC GPIO banks defined as gpio-controller nodes: |
| |
| qe_pio_a: gpio-controller@1400 { |
| #gpio-cells = <2>; |
| compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank"; |
| reg = <0x1400 0x18>; |
| gpio-controller; |
| }; |
| |
| qe_pio_e: gpio-controller@1460 { |
| #gpio-cells = <2>; |
| compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; |
| reg = <0x1460 0x18>; |
| gpio-controller; |
| }; |
| |
| Appendix A - Sample SOC node for MPC8540 |
| ======================================== |
| |
| Note that the #address-cells and #size-cells for the SoC node |
| in this example have been explicitly listed; these are likely |
| not necessary as they are usually the same as the root node. |
| |
| soc8540@e0000000 { |
| #address-cells = <1>; |
| #size-cells = <1>; |
| #interrupt-cells = <2>; |
| device_type = "soc"; |
| ranges = <00000000 e0000000 00100000> |
| reg = <e0000000 00003000>; |
| bus-frequency = <0>; |
| |
| mdio@24520 { |
| reg = <24520 20>; |
| device_type = "mdio"; |
| compatible = "gianfar"; |
| |
| ethernet-phy@0 { |
| linux,phandle = <2452000> |
| interrupt-parent = <40000>; |
| interrupts = <35 1>; |
| reg = <0>; |
| device_type = "ethernet-phy"; |
| }; |
| |
| ethernet-phy@1 { |
| linux,phandle = <2452001> |
| interrupt-parent = <40000>; |
| interrupts = <35 1>; |
| reg = <1>; |
| device_type = "ethernet-phy"; |
| }; |
| |
| ethernet-phy@3 { |
| linux,phandle = <2452002> |
| interrupt-parent = <40000>; |
| interrupts = <35 1>; |
| reg = <3>; |
| device_type = "ethernet-phy"; |
| }; |
| |
| }; |
| |
| ethernet@24000 { |
| #size-cells = <0>; |
| device_type = "network"; |
| model = "TSEC"; |
| compatible = "gianfar"; |
| reg = <24000 1000>; |
| mac-address = [ 00 E0 0C 00 73 00 ]; |
| interrupts = <d 3 e 3 12 3>; |
| interrupt-parent = <40000>; |
| phy-handle = <2452000>; |
| }; |
| |
| ethernet@25000 { |
| #address-cells = <1>; |
| #size-cells = <0>; |
| device_type = "network"; |
| model = "TSEC"; |
| compatible = "gianfar"; |
| reg = <25000 1000>; |
| mac-address = [ 00 E0 0C 00 73 01 ]; |
| interrupts = <13 3 14 3 18 3>; |
| interrupt-parent = <40000>; |
| phy-handle = <2452001>; |
| }; |
| |
| ethernet@26000 { |
| #address-cells = <1>; |
| #size-cells = <0>; |
| device_type = "network"; |
| model = "FEC"; |
| compatible = "gianfar"; |
| reg = <26000 1000>; |
| mac-address = [ 00 E0 0C 00 73 02 ]; |
| interrupts = <19 3>; |
| interrupt-parent = <40000>; |
| phy-handle = <2452002>; |
| }; |
| |
| serial@4500 { |
| device_type = "serial"; |
| compatible = "ns16550"; |
| reg = <4500 100>; |
| clock-frequency = <0>; |
| interrupts = <1a 3>; |
| interrupt-parent = <40000>; |
| }; |
| |
| pic@40000 { |
| linux,phandle = <40000>; |
| interrupt-controller; |
| #address-cells = <0>; |
| reg = <40000 40000>; |
| compatible = "chrp,open-pic"; |
| device_type = "open-pic"; |
| }; |
| |
| i2c@3000 { |
| interrupt-parent = <40000>; |
| interrupts = <1b 3>; |
| reg = <3000 18>; |
| device_type = "i2c"; |
| compatible = "fsl-i2c"; |
| dfsrr; |
| }; |
| |
| }; |