[RFC] Device Tree Overlays Proposal (Was Re: capebus moving omap_devices to mach-omap2)

[Russ Dill]

On Mon, Nov 12, 2012 at 3:23 AM, Pantelis Antoniou
<panto at antoniou-consulting.com> wrote:
> Hi Grant,
>
> Sorry for the late comments, travelling...
>
> On Nov 9, 2012, at 6:28 PM, Grant Likely wrote:
>
>> On Tue, Nov 6, 2012 at 10:37 PM, Stephen Warren <swarren at wwwdotorg.org> wrote:
>>> On 11/05/2012 01:40 PM, Grant Likely wrote:
>>>> Hey folks,
>>>>
>>>> As promised, here is my early draft to try and capture what device
>>>> tree overlays need to do and how to get there. Comments and
>>>> suggestions greatly appreciated.
>>>
>>> Interesting. This just came up internally at NVIDIA within the last
>>> couple weeks, and was discussed on the U-Boot mailing list very recently
>>> too:
>>>
>>> http://lists.denx.de/pipermail/u-boot/2012-October/thread.html#138227
>>> (it spills into the November archive too)
>>>
>>>> For these cases it is proposed to implement an overlay feature for the
>>>> so that the initial device tree data can be modified by userspace at
>>>
>>> I don't know if you're maintaining this as a document and taking patches
>>> to it, but if so:
>>
>> Sure, why not...
>>
>> http://git.secretlab.ca/?p=devicetree-overlays.git;a=summary
>>
>>>
>>> "for the so" split across those two lines.
>>
>> fixed
>>
>>>>  - SHOULD reliably handle changes between different underlying overlays
>>>>    (ie. what happens to existing .dtb overly files if the structure of
>>>>    the dtb it is layered over changes. If not possible, then SHALL
>>>>    detect when the base tree doesn't match and refuse to apply the
>>>>    overlay.
>>>
>>> Perhaps use (versioned) DT bindings to represent the interface between
>>> the two .dts files? See the links to the U-Boot mailing list discussions
>>> below?
>>
>> Implementing versioning is conceptually a lot more complex than plain
>> overlays since it means either the kernel or u-boot needs to start
>> filtering the data that it's given. This can get really complex in a
>> hurry. Mitch makes a valid point later in this thread that when it
>> comes to manipulating the data depending on the board then the data
>> overlay model alone doesn't handle it well.
>>
>> I'm not actually opposed to it, but it needs to be done in an elegant
>> way. The DT data model already imposes more of a conceptual learning
>> curve than I wish it did and I don't want to make that worse with a
>> versioning model that is difficult to get ones head around.
>>
>> Suggestions and proposals are definitely welcome here.
>>
>
> I didn't find versioning all that difficult TBH.
>
> Making the property access functions work sanely with versioning
> should cover most (if not all) kernel users.
> Keep non versioned property access function available to possibly
> users with a prefix for those that need it.
>
>>>
>>>> - What is the model for overlays?
>>>>  - Can an overlay modify existing properties?
>>>>  - Can an overlay add new properties to existing nodes?
>>>>  - Can an overlay delete existing nodes/properties?
>>>
>>> This proposal is very oriented at an overlay-based approach. I'm not
>>> totally convinced that a pure overlay approach (as in how dtc does
>>> overlayed DT nodes) will be flexible enough, but would love to be
>>> persuaded. Again see below.
>>
>> The way I'm currently thinking about the overlay approach is as a
>> discrete set of changes that all can be applied at once.* That
>> certainly doesn't preclude the change being generated with a script or
>> other tool in either firmware or userspace. For most changes it works
>> really well. Of the scenarios that don't work well, I can think of
>> two. The first is it moving or renaming existing nodes, and the second
>> is if the structure of the base tree changes (say due to a firmware
>> update). Although the second limitation is specifically with binary
>> .dtb overlays. Recompiling the dts overlay against the new tree would
>> work fine.**
>>
>
> Atomicity should be handled correctly. I can't imagine how hard would
> be to back out a semi-applied overlay without some kind of core DT
> tracking support. Leaving it to the driver/user is too difficult to get
> right.
>
> About moving and renaming nodes, I can't think of a user-case today that
> needs it. Perhaps it can be handled by removal & re-insertion?
>
>> *with the caveat that not all types of changes are a good idea and we
>> may disallow. For example, is changing properties in existing nodes a
>> good idea?
>
> Yes, changing properties is something that we need. One such change is
> the change of the bus controller 'status' properties to enabled upon
> insertion of a child device node, and change back to 'on-demand' when
> all the child device nodes are gone.

Some devices will probably have to support on the fly changes that
they may not have otherwise supported. An example of a driver that
needs to modify it's device based on DT would be an I²C bus speed
change.