Contents

Description

The "Device Tree" is a relatively new (for ARM Linux) framework
for specifying the hardware configuration of a board to the Linux Kernel.
See the Device Tree page for more details.

New device drivers for many embedded products are always being
produced, and it is strongly encouraged that new drivers
and the board support for new ARM boards use device tree as part
of their driver configuration. However, some areas of the device
tree bindings are non-uniform and not well-documented.

This project would consist of documenting aspects of the device
tree system that would be useful for:

board support developers (board/platform developers)

device driver developers

kernel sub-system maintainers

Kernel sub-system maintainers would be well-served by a document
describing "rules", guidelines and best practices for device
tree bindings.

Many documents exist which describe the syntax of the device tree,
(such as the epar document, the device-tree wiki and the usage
document in the kernel Documentation directory). However, some
details are missing from these documents, and in some cases the
explicit practices for working with device tree in the Linux
kernel are different or have evolved from when these original
documents were written.

The output from this effort would be a readily-accessible document.
It would probably make sense to put the document in the kernel source
tree, under Documentation/devicetree. Failing that, the document
could be placed on the elinux wiki or the device tree wiki.

Issues

Some areas of device tree bindings (and driver infrastructure) are
in flux (e.g. pinctrl, dma). Would it be better to wait until
these areas have settled down?

Current device-tree documentation

The page BeagleBone and the 3.8 Kernel describes the issues of moving to devicetree
for the BeagleBone, and gives an excellent overview of devicetree, the structure changes
required for moving platform and driver support to it, and how BeagleBone board support
moved to it.

Some questions to answer

Here are some possible questions that this documentation could
address: (If these are already answered by the epar document, please
cite the section:)

1. What is a phandle? How is it used? What rules are there for
defining them? For referencing them?

2. How are #foo-cells used?

3. What are the rules for naming attributes? when should vendor
qualifiers be used and when not?

4. How does device-tree interact with device instantiation - when
is the device node created?, who creates it, when is the initcall
called? when is the probe function called?

5. How does device-tree interact with platform/bus instantiation?
Do buses instantiate their children device nodes, or does the probe
routine do this?

6. what is the kernel API for interacting with device-tree? What
things are parsed automatically, vs. require manual (coded) parsing?

Scope

A rough guess of the amount of work required for this document is
approximately 3 months (12 person-weeks).