Device-tree documentation project

Device-tree documentation project


 * Summary: Device-tree documentation project


 * Proposer: Tim Bird, Sony Mobile

Description
The Device Tree is a relatively new (for ARM Linux) framework for specifying hardware that a Linux kernel should support for a particular board. New device drivers for many embedded products are 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 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.

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?

Related work

 * http://devicetree.org/Device_Tree_Usage - this is part of the device tree wiki
 * http://www.power.org/resources/downloads/Power_ePAPR_APPROVED_v1.0.pdf - open-firmware device tree specification (requires registration?)
 * Some 2013 kernel summit discussion entries:
 * http://lists.linuxfoundation.org/pipermail/ksummit-2013-discuss/2013-July/000127.html
 * Jonathan Corbet asks about the need for discussion and/or a document on device tree
 * http://lists.linuxfoundation.org/pipermail/ksummit-2013-discuss/2013-July/000129.html
 * Greg KH would like a document
 * http://lists.linuxfoundation.org/pipermail/ksummit-2013-discuss/2013-July/000599.html
 * Stephen Warren recommends a reviewer's checklist for new bindings

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?

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?

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

Contractor Candidates

 * Jonathan Corbet (output could also be part of LDD4??)
 * Thomas Petazzoni - is presenting a tutorial on device tree at ELCE
 * one of the device-tree maintainers? (Grant, Stephen, Mark, etc.)