Difference between revisions of "Device-tree documentation project"

From eLinux.org
Jump to: navigation, search
(partial creation of this page)
 
(show that Frank is the contractor for this)
 
(13 intermediate revisions by 3 users not shown)
Line 1: Line 1:
Device-tree documentation project
 
 
 
; Summary: Device-tree documentation project
 
; Summary: Device-tree documentation project
 
 
; Proposer: Tim Bird, Sony Mobile
 
; Proposer: Tim Bird, Sony Mobile
 +
; Status: Selected to be sponsored by the CE Workgroup
  
 
== Description ==
 
== Description ==
The [[Device Tree]] is a relatively new (for ARM Linux) framework
+
The "Device Tree" is a relatively new (for ARM Linux) framework
for specifying hardware that a Linux kernel should support for a
+
for specifying the hardware configuration of a board to the Linux Kernel.
particular board.  New device drivers for many embedded products
+
See the [[Device Tree|Device Tree page]] for more details.
are being produced, and it is strongly encouraged that new drivers
+
 
 +
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
 
and the board support for new ARM boards use device tree as part
 
of their driver configuration.  However, some areas of the device
 
of their driver configuration.  However, some areas of the device
Line 25: Line 25:
  
 
Many documents exist which describe the syntax of the device tree,
 
Many documents exist which describe the syntax of the device tree,
(such as the epar document).
+
(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.
 
The output from this effort would be a readily-accessible document.
 
It would probably make sense to put the document in the kernel source
 
It would probably make sense to put the document in the kernel source
tree, under Documentation/devicetree.
+
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?
 +
 +
Does throwing money at this project dis-incent volunteer effort?
  
 
== Related work ==
 
== Related work ==
* http://devicetree.org/Device_Tree_Usage
+
* http://elinux.org/Device_Tree_Usage
*  
+
* https://www.power.org/documentation/power-org-standard-for-embedded-power-architecture-platform-requirements-epapr-v1-1-2/ - open-firmware device tree specification
* Add links to any other resources which might be helpful
+
* Some 2013 kernel summit discussion entries:
** (talks, articles, mail list messages, etc.)
+
** 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
 +
** http://lists.linuxfoundation.org/pipermail/ksummit-2013-discuss/2013-July/000785.html
 +
*** Olof Johansson announces ARM kernel summit, with device tree as a possible focus
 +
 
 +
=== 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 ==
 
== Scope ==
A rough guess of the amount of work required for this document is approximately 3 months (12 person-weeks).
+
A rough guess of the amount of work required for this document is
 +
approximately 3 months (12 person-weeks).
 +
 
 +
== Contractor ==
 +
* Frank Rowand (device tree maintainer)
  
 
== Contractor Candidates ==
 
== Contractor Candidates ==
 
* Jonathan Corbet (output could also be part of LDD4??)
 
* Jonathan Corbet (output could also be part of LDD4??)
 
* Thomas Petazzoni - is presenting a tutorial on device tree at ELCE
 
* Thomas Petazzoni - is presenting a tutorial on device tree at ELCE
 +
* Pantelis Antoniou - who wrote: [[BeagleBone and the 3.8 Kernel]]
 
* one of the device-tree maintainers?  (Grant, Stephen, Mark, etc.)
 
* one of the device-tree maintainers?  (Grant, Stephen, Mark, etc.)
  
Line 49: Line 103:
  
 
[[Category:Project proposals 2013]]
 
[[Category:Project proposals 2013]]
 +
[[Category:Project proposals 2015]]

Latest revision as of 07:17, 26 April 2016

Summary
Device-tree documentation project
Proposer
Tim Bird, Sony Mobile
Status
Selected to be sponsored by the CE Workgroup

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?

Does throwing money at this project dis-incent volunteer effort?

Related work

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

Contractor

  • Frank Rowand (device tree maintainer)

Contractor Candidates

  • Jonathan Corbet (output could also be part of LDD4??)
  • Thomas Petazzoni - is presenting a tutorial on device tree at ELCE
  • Pantelis Antoniou - who wrote: BeagleBone and the 3.8 Kernel
  • one of the device-tree maintainers? (Grant, Stephen, Mark, etc.)

Comments