2722 строки
100 KiB
Plaintext
2722 строки
100 KiB
Plaintext
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) Xilinx IP cores
|
|
|
|
VII - Specifying interrupt information for devices
|
|
1) interrupts property
|
|
2) interrupt-parent property
|
|
3) OpenPIC Interrupt Controllers
|
|
4) ISA Interrupt Controllers
|
|
|
|
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
|
|
property. In the absence of such a property, the parent's parent
|
|
values are used, etc... 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. 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.
|
|
|
|
|
|
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
|
|
- device_type : Should be "mdio"
|
|
- compatible : Should define the compatible device type for the
|
|
mdio. Currently, this is most likely to be "gianfar"
|
|
|
|
Example:
|
|
|
|
mdio@24520 {
|
|
reg = <24520 20>;
|
|
device_type = "mdio";
|
|
compatible = "gianfar";
|
|
|
|
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.
|
|
|
|
Recommended properties:
|
|
|
|
- linux,network-index : This is the intended "index" of this
|
|
network device. This is used by the bootwrapper to interpret
|
|
MAC addresses passed by the firmware when no information other
|
|
than indices is available to associate an address with a device.
|
|
- 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>;
|
|
clock-frequency = <0>;
|
|
interrupt-controller;
|
|
#address-cells = <0>;
|
|
reg = <40000 40000>;
|
|
built-in;
|
|
compatible = "chrp,open-pic";
|
|
device_type = "open-pic";
|
|
big-endian;
|
|
};
|
|
|
|
|
|
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 {
|
|
device_type = "usb";
|
|
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 {
|
|
device_type = "usb";
|
|
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:
|
|
- device_type : should be "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>;
|
|
device_type = "qe";
|
|
model = "QE";
|
|
ranges = <0 e0100000 00100000>;
|
|
reg = <e0100000 480>;
|
|
brg-frequency = <0>;
|
|
bus-frequency = <179A7B00>;
|
|
}
|
|
|
|
|
|
ii) SPI (Serial Peripheral Interface)
|
|
|
|
Required properties:
|
|
- device_type : should be "spi".
|
|
- 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 {
|
|
device_type = "spi";
|
|
compatible = "fsl_spi";
|
|
reg = <4c0 40>;
|
|
interrupts = <82 0>;
|
|
interrupt-parent = <700>;
|
|
mode = "cpu";
|
|
};
|
|
|
|
|
|
iii) USB (Universal Serial Bus Controller)
|
|
|
|
Required properties:
|
|
- device_type : should be "usb".
|
|
- 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 {
|
|
device_type = "usb";
|
|
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" or "atm".
|
|
- compatible : could be "ucc_geth" or "fsl_atm" and so on.
|
|
- model : should be "UCC".
|
|
- device-id : 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.
|
|
- 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:
|
|
- linux,network-index : This is the intended "index" of this
|
|
network device. This is used by the bootwrapper to interpret
|
|
MAC addresses passed by the firmware when no information other
|
|
than indices is available to associate an address with a device.
|
|
- 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";
|
|
model = "UCC";
|
|
device-id = <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:
|
|
- device_type : should be "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 {
|
|
device_type = "muram";
|
|
ranges = <0 00010000 0000c000>;
|
|
|
|
data-only@0{
|
|
reg = <0 c000>;
|
|
};
|
|
};
|
|
|
|
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>;
|
|
linux,network-index = <0>;
|
|
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,mpc8272ads-localbus",
|
|
"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.
|
|
|
|
Recommended properties:
|
|
- linux,network-index : This is the intended "index" of this
|
|
network device. This is used by the bootwrapper to interpret
|
|
MAC addresses passed by the firmware when no information other
|
|
than indices is available to associate an address with a device.
|
|
|
|
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 {
|
|
linux,network-index = <0>;
|
|
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
|
|
|
|
l) 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)@(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)>;
|
|
};
|
|
|
|
(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 C_BASEADDR parameter.
|
|
(HW_VER): from the HW_VER parameter.
|
|
(size): equals 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@ec100000 {
|
|
device_type = "serial";
|
|
compatible = "xlnx,opb-uartlite-1.00.b";
|
|
reg = <ec100000 10000>;
|
|
interrupt-parent = <&opb-intc>;
|
|
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.
|
|
(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@a9000000 {
|
|
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>;
|
|
interrupts = <3 0>;
|
|
cell-index = <0>;
|
|
};
|
|
ps2@1000 {
|
|
compatible = "xlnx,opb-ps2-dual-ref-1.00.a";
|
|
reg = <1000 40>;
|
|
interrupt-parent = <&opb-intc>;
|
|
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-v34-0 {
|
|
#address-cells = <1>;
|
|
#size-cells = <1>;
|
|
device_type = "ibm,plb";
|
|
ranges; // 1:1 translation
|
|
|
|
plb-bram-if-cntrl-0@ffff0000 {
|
|
reg = <ffff0000 10000>;
|
|
}
|
|
|
|
opb-v20-0 {
|
|
#address-cells = <1>;
|
|
#size-cells = <1>;
|
|
ranges = <20000000 20000000 20000000
|
|
60000000 60000000 20000000
|
|
80000000 80000000 40000000
|
|
c0000000 c0000000 20000000>;
|
|
|
|
opb-uart16550-0@a0000000 {
|
|
reg = <a00000000 2000>;
|
|
};
|
|
|
|
opb-intc-0@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
|
|
|
|
More devices will be defined as this spec matures.
|
|
|
|
VII - 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
|
|
|
|
|
|
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>;
|
|
clock-frequency = <0>;
|
|
interrupt-controller;
|
|
#address-cells = <0>;
|
|
reg = <40000 40000>;
|
|
built-in;
|
|
compatible = "chrp,open-pic";
|
|
device_type = "open-pic";
|
|
big-endian;
|
|
};
|
|
|
|
i2c@3000 {
|
|
interrupt-parent = <40000>;
|
|
interrupts = <1b 3>;
|
|
reg = <3000 18>;
|
|
device_type = "i2c";
|
|
compatible = "fsl-i2c";
|
|
dfsrr;
|
|
};
|
|
|
|
};
|