##(see the SpecSpec for an explanation)

 * '''Launchpad Entry''': UbuntuSpec:kernel-devicetree-quirks
 * '''Created''': 2009-12-02
 * '''Contributors''':
 * '''Packages affected''': kernel

== Summary ==

There are a large range of audio devices we need to support, and often there are small modifications in layout between otherwise-similar devices. This specification is based on using a device-tree type format to describe hardware (particularly audio devices) to facilitate device discovery and support.

== Release Note ==

Usage should be transparent to the user, but we will be adding system-level interfaces to manage device-tree handling.

== Rationale ==

With the growing number of hardware platforms supported by ubuntu, we're seeing a larger range of devices requiring 

== User stories ==

 * Alice has a new laptop (released after the latest version of Ubuntu), but audio doesn't work. Luckily, the hardware is fairly similar to that of an existing laptop, so it's possible to support it with a (run-time) device-tree update, rather than a full kernel release. She's happy to test the new device tree, and report working/not-working status to the kernel team. Once a working device-tree update is found, the kernel team can add the (non-invasive) update to the official kernel package.

 * Bob has the same hardware, but isn't willing to test new device trees. Bob receives the device tree update that Alice has tested through the regular update process, and audio starts working.

== Assumptions ==

No assumptions at present

== Design ==

 * Interface added to handle a device-tree-like structure for particular devices. A full DT will not be necessary for this support.
 * Drivers modified to parse hardware-specific information from the device-tree fragment for the device.
 * Facility to be provided to update the device tree (via sysfs?) at run time. We may also need to force a reinit of the device (perhaps via module reload).

== Implementation ==

To do.

=== Code Changes ===

To do.

== Test/Demo Plan ==


== Unresolved issues ==

This should highlight any issues that should be addressed in further specifications, and not problems with the specification itself; since any specification with problems cannot be approved.

== BoF agenda and discussion ==

How quirks can be handled with device tree

brief talk of device tree
dealing with quirks


=== brief talk of device tree ===

Data structure for describing hardware
Simple tree structure of nodes
	- nodes have named properties and subnodes
	- properties are name:value pairs
		- value is arbitrary blob
		- maybe empty
	- names are strings
	- secondary links between nodes
Usage model adopted from Open Firmware
Binary Tokenized from text representation

Example (text description of hardware)
	- even have label and phandle to link between nodes
	- e.g. codec connected to I2C and I2S
	
The quirks talked in Audio session

Q: what if links in nodes form a loop?
A: not recursive, used for data retrieving, not a problem

Use of device tree to describe the codec internal and make the kernel
driver generic. There are corner cases where code is inevitable, e.g.
JACK detection with GPIO.

We still need some other method to handle the run-time configurations.

Device tree is a whole hardware description, discuss with dynamic loading Device tree.

== Actions ==

NOTE: Current and up to date action list and status in the whiteboard for the blueprint.

ACTION:
 * look at alsa git history for info about current quirks (sconklin)
 * initial work on audio codec/etc bindings in DT format (jk)
  * start from alsa-soc?
 * design runtime update interface for DT (sysfs?)



----
CategorySpec