ARM,SoC: About the use DT-defined properties by 3rd-party drivers

ARM,SoC: About the use DT-defined properties by 3rd-party drivers

[Sebastian Frias]

Hi,

Given a SoC and its SDK, 3rd party users of said SoC (customers of the SoC's
manufacturer) may need/want to write kernel modules.
Since the DT describes the HW, it would make sense to expose some HW properties
through the DT, and have 3rd party users rely on them to write their drivers in
a generic way.
However, it seems that one is not allowed to upstream DT bindings and
properties without a driver, is that right?

If true, that hampers DT usage by out-of-tree drivers (or in this case,
drivers that are not written yet) and limits the usage of DT properties as an
API.

We can understand that DT maintainers want to know what goes upstream,
make sure that the bindings are documented, that there are no conflicts with
other bindings or generic strings, etc.
However, it is hard to see why there is not a "relaxed" upstreaming path
for SoC-specific properties (i.e.: that do not affect DT API nor other
SoCs).

As an example, we would like to add some properties to /soc/ like:

   soc {
       compatible = "simple-bus";
       ...
       sigma-register-layout-version = <2>;
       sigma-has-XYZ-capability;

and so on.

If this is really not possible, it forces the SoC manufacturer to expose
those properties in a different way, thus wasting a (seemingly) perfectly
fine way of doing so: the DT and its documentation.

Thoughts?

By the way, what about properties generated on-the-fly by the bootloader?

Thanks in advance.
Best regards,

Sebastian

Re: ARM,SoC: About the use DT-defined properties by 3rd-party drivers

[Timur Tabi]

On Wed, Aug 24, 2016 at 9:29 AM, Sebastian Frias <sf84@laposte.net> wrote:
>
> If this is really not possible, it forces the SoC manufacturer to expose
> those properties in a different way, thus wasting a (seemingly) perfectly
> fine way of doing so: the DT and its documentation.

When you submit a new driver upstream, that patch also includes the
new device tree nodes and documentation for those nodes.  Everything
is peer-reviewed together.  I don't understand what you think the
problem is.

Re: ARM,SoC: About the use DT-defined properties by 3rd-party drivers

[Sebastian Frias]

Hi Timur,

On 08/28/2016 10:36 PM, Timur Tabi wrote:
> On Wed, Aug 24, 2016 at 9:29 AM, Sebastian Frias <sf84@laposte.net> wrote:
>>
>> If this is really not possible, it forces the SoC manufacturer to expose
>> those properties in a different way, thus wasting a (seemingly) perfectly
>> fine way of doing so: the DT and its documentation.
> 
> When you submit a new driver upstream, that patch also includes the
> new device tree nodes and documentation for those nodes.  Everything
> is peer-reviewed together.  I don't understand what you think the
> problem is.
> 

Thanks for your comment and sorry for the late reply.

My question is about submitting DT properties/nodes (describing some HW) for
which there is no Linux driver. Like register addresses for HW blocks,
including HW capabilities of said HW blocks, which may or may not be setup
by Linux directly.

The idea being that since DT describes the HW and is usually shared with the
bootloader (yet stored in the Linux kernel tree), all layers of the stack
could use the same DT and each layer would use relevant properties. So the
DT would describe the whole SoC even if not all HW blocks have a Linux
driver.

3rd party users of said SoC could then write kernel modules for such HW
blocks using the DT description. The DT would thus become the authoritative
source of information regarding register programming for the SoC.

Currently, HW blocks for which there is no public driver (that it is
accessed through user-mode libraries or firmware) require a separate
HW description (be it Documentation, headers, etc.)

Since the DT describes the HW, it would make sense to expose the HW through
DT, that would centralise the HW description.

However, after discussing over IRC, it looks like there was no guidance on
this. Some people think submitting DT properties/nodes without a corresponding
Linux driver is frowned upon, while others thought it was an odd limitation
and suggested asking here.

Does that clarifies the scope of the question?

Best regards,

Sebastian

Re: ARM,SoC: About the use DT-defined properties by 3rd-party drivers

[Mark Rutland]

On Mon, Sep 12, 2016 at 02:29:37PM +0200, Sebastian Frias wrote:
> My question is about submitting DT properties/nodes (describing some HW) for
> which there is no Linux driver. Like register addresses for HW blocks,
> including HW capabilities of said HW blocks, which may or may not be setup
> by Linux directly.
> 
> The idea being that since DT describes the HW and is usually shared with the
> bootloader (yet stored in the Linux kernel tree), all layers of the stack
> could use the same DT and each layer would use relevant properties. So the
> DT would describe the whole SoC even if not all HW blocks have a Linux
> driver.
> 
> 3rd party users of said SoC could then write kernel modules for such HW
> blocks using the DT description. The DT would thus become the authoritative
> source of information regarding register programming for the SoC.

I don't follow this part entirely. Why are you expecting thrid parties
to write a driver for those blocks rather than upstreaming a driver for
them?

> Currently, HW blocks for which there is no public driver (that it is
> accessed through user-mode libraries or firmware) require a separate
> HW description (be it Documentation, headers, etc.)
> 
> Since the DT describes the HW, it would make sense to expose the HW through
> DT, that would centralise the HW description.

I would generally agree that the hardware should be described in DT.
The difficulty is that without a 'real' user it's not always possible to
tell if we're describing the thing correctly.

Putting smoething together that's only sufficient to support some
out-of-tree driver with implicit assumptions that we are not aware of is
far from fantastic.

> However, after discussing over IRC, it looks like there was no guidance on
> this. Some people think submitting DT properties/nodes without a corresponding
> Linux driver is frowned upon, while others thought it was an odd limitation
> and suggested asking here.

Unfortunately, I think that the area is sufficiently vague that there
simply is no clear and general answer.

For the sake of discussion, an example of a particular block, along with
what you expect/need to describe would be helpful.

Thanks,
Mark.

Re: ARM,SoC: About the use DT-defined properties by 3rd-party drivers

[Sebastian Frias]

Hi Mark,

On 09/12/2016 02:38 PM, Mark Rutland wrote:
>>
>> 3rd party users of said SoC could then write kernel modules for such HW
>> blocks using the DT description. The DT would thus become the authoritative
>> source of information regarding register programming for the SoC.
> 
> I don't follow this part entirely. Why are you expecting thrid parties
> to write a driver for those blocks rather than upstreaming a driver for
> them?

3rd parties could choose to write a driver (as opposed to use say, a user-mode
library) if it fits their programming model better, if they think they would
have better performance, or other reasons.

The main idea is to make DT the authoritative source of HW description.

> 
>> Currently, HW blocks for which there is no public driver (that it is
>> accessed through user-mode libraries or firmware) require a separate
>> HW description (be it Documentation, headers, etc.)
>>
>> Since the DT describes the HW, it would make sense to expose the HW through
>> DT, that would centralise the HW description.
> 
> I would generally agree that the hardware should be described in DT.
> The difficulty is that without a 'real' user it's not always possible to
> tell if we're describing the thing correctly.
> 

That may be true, but so far we are not discussing changing DT's API so it
should not have big ramifications.
Besides, what "makes sense now" may "not make sense tomorrow" depending on
how the HW is modified.
We have somehow learned the hard-way that "le mieux est l'ennemi du bien"
(the better is the enemy of the good) and we are trying to take a more
practical (and flexible) approach.

> Putting smoething together that's only sufficient to support some
> out-of-tree driver with implicit assumptions that we are not aware of is
> far from fantastic.

That does not seem very positive and it is not the case anyway, otherwise we
would not be consulting here :-)
Agreed, right now this whole thing seems like a really hypothetical question,
but the intention is good.

Actually, I think it would encourage more SoC manufacturers to use DT as a way
to document their HW, which is a good thing.

> 
>> However, after discussing over IRC, it looks like there was no guidance on
>> this. Some people think submitting DT properties/nodes without a corresponding
>> Linux driver is frowned upon, while others thought it was an odd limitation
>> and suggested asking here.
> 
> Unfortunately, I think that the area is sufficiently vague that there
> simply is no clear and general answer.
> 
> For the sake of discussion, an example of a particular block, along with
> what you expect/need to describe would be helpful.

I don't have a more concrete example now.

As I stated, right now HW description is not centralised, and thus different
bits of information are cherry-picked by hand from HW description into DT for
bootloader, DT for Linux, Documentation/headers for 3rd-parties, etc.

But if I understood correctly your comment, you are basically saying that
without an example is hard to say.
Since the question seems understood, do you have an example of other SoC's
doing something similar?

I've seen some big DT descriptions, but it is difficult to know if we are the
first ones trying to use the DT in this way.

Best regards,

Sebastian

Re: ARM,SoC: About the use DT-defined properties by 3rd-party drivers

[Timur Tabi]

Sebastian Frias wrote:
> 3rd parties could choose to write a driver (as opposed to use say, a user-mode
> library) if it fits their programming model better, if they think they would
> have better performance, or other reasons.
>
> The main idea is to make DT the authoritative source of HW description.

Do you really expect the open-source community to make a serious effort 
to support out-of-tree drivers written by developers who have no 
intention of upstreaming?

There's a process for writing a Linux kernel driver with a DT binding. 
That process is not broken.

>> >Putting smoething together that's only sufficient to support some
>> >out-of-tree driver with implicit assumptions that we are not aware of is
>> >far from fantastic.
> That does not seem very positive and it is not the case anyway, otherwise we
> would not be consulting here:-)

Mark is correct.  Trying to create a device tree binding, and getting it 
correct 100% the first time, without an actual drivers is just 
impossible.  To even attempt that is folly.

> Agreed, right now this whole thing seems like a really hypothetical question,

Yes, it is.

> but the intention is good.

I'm not sure I agree with that.

> Actually, I think it would encourage more SoC manufacturers to use DT as a way
> to document their HW, which is a good thing.

No it isn't.  SOC manufacturers should just release the documentation 
they have.

> But if I understood correctly your comment, you are basically saying that
> without an example is hard to say.
> Since the question seems understood, do you have an example of other SoC's
> doing something similar?

Similar to what?  Every upstream driver today is written the way we're 
talking about -- submit the driver with the binding, and both are 
reviewed together.

> I've seen some big DT descriptions, but it is difficult to know if we are the
> first ones trying to use the DT in this way.

Hopefully, you'll be the last.

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Mark Rutland]

Hi,

On Mon, Sep 12, 2016 at 03:15:00PM +0200, Sebastian Frias wrote:
> On 09/12/2016 02:38 PM, Mark Rutland wrote:
> >>
> >> 3rd party users of said SoC could then write kernel modules for such HW
> >> blocks using the DT description. The DT would thus become the authoritative
> >> source of information regarding register programming for the SoC.
> > 
> > I don't follow this part entirely. Why are you expecting thrid parties
> > to write a driver for those blocks rather than upstreaming a driver for
> > them?
> 
> 3rd parties could choose to write a driver (as opposed to use say, a user-mode
> library) if it fits their programming model better, if they think they would
> have better performance, or other reasons.

A vendor can always choose to "add value" in this manner. The general
expectation of *some* driver being upstreamed remains.

> > I would generally agree that the hardware should be described in DT.
> > The difficulty is that without a 'real' user it's not always possible to
> > tell if we're describing the thing correctly.
> 
> That may be true, but so far we are not discussing changing DT's API so it
> should not have big ramifications.

You're not changing the code, but you are creating a binding. Bindings
are intended to be stable (i.e. a working DTB from today should continue
to work in future), and thus there are ramifications.

Few devices these says are entirely independent, and most devices can be
instantiated multiple times (even if there happens to only be a single
instance in practice). For the example of a userspace driver there are
very real ABI concerns, such as how the device(s) are discovered, how
any related components like regulators and clocks are controlled, etc.

There are ramifications here, and it's a dangerous over simplification
to say that this doesn't matter because we're not changing kernel code.

> Besides, what "makes sense now" may "not make sense tomorrow" depending on
> how the HW is modified.

That's always the case when a new generation of hardware comes out, so I
don't think that's relevant to the topic at hand.

> We have somehow learned the hard-way that "le mieux est l'ennemi du bien"
> (the better is the enemy of the good) and we are trying to take a more
> practical (and flexible) approach.
> 
> > Putting smoething together that's only sufficient to support some
> > out-of-tree driver with implicit assumptions that we are not aware of is
> > far from fantastic.
> 
> That does not seem very positive and it is not the case anyway, otherwise we
> would not be consulting here :-)
> Agreed, right now this whole thing seems like a really hypothetical question,
> but the intention is good.
> 
> Actually, I think it would encourage more SoC manufacturers to use DT as a way
> to document their HW, which is a good thing.

Writing and reviewing bindings is a very tricky topic, as it can require
fairly intimate knowledge of a piece of hardware. I've repeatedly found
that binding descriptions did not match the realities of the hardware,
and I've only managed to do so by looking at accompanying driver code.

Given that manuals and other information on devices are often not freely
available (if they exist at all), the proposal effectively limits myself
and others to spot common (anti)patterns, which is far less than ideal,
and will result in more mistakes.

As it stands, the proposal asks for effort for the community (in terms
of review and maintenance of bindings), with no benefit to the kernel
community, and a number of pitfalls that we would rather avoid.

In an ideal world, writing and reviewing bindings would be a simple
affair, and this could happen separately from work on any particular OS.
In practice, things are sufficiently complicated that you need *some*
demonstration that a binding is suitable, which is what I'm personally
after when I ask for a Linux driver.

> >> However, after discussing over IRC, it looks like there was no guidance on
> >> this. Some people think submitting DT properties/nodes without a corresponding
> >> Linux driver is frowned upon, while others thought it was an odd limitation
> >> and suggested asking here.
> > 
> > Unfortunately, I think that the area is sufficiently vague that there
> > simply is no clear and general answer.
> > 
> > For the sake of discussion, an example of a particular block, along with
> > what you expect/need to describe would be helpful.
> 
> I don't have a more concrete example now.

For this discussion to go somewhere, we need an example. Otherwise we're
all coming at this with differing implicit assumptions and no clear
evidence for any assertions.

> As I stated, right now HW description is not centralised, and thus different
> bits of information are cherry-picked by hand from HW description into DT for
> bootloader, DT for Linux, Documentation/headers for 3rd-parties, etc.
> 
> But if I understood correctly your comment, you are basically saying that
> without an example is hard to say.
> Since the question seems understood, do you have an example of other SoC's
> doing something similar?

I do not have an example. I know that others are using DT for data
beyond what Linux or another OS requires, but it's my understanding that
that is typically in a separate DTB.

Thanks,
Mark.

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Warner Losh]

On Mon, Sep 12, 2016 at 8:01 AM, Mark Rutland <mark.rutland@arm.com> wrote:
>> Since the question seems understood, do you have an example of other SoC's
>> doing something similar?
>
> I do not have an example. I know that others are using DT for data
> beyond what Linux or another OS requires, but it's my understanding that
> that is typically in a separate DTB.

Just to clarify: FreeBSD uses, for the most part, the DTB's that the
'vendor' ships, which is quite often the same ones included in Linux.
There's some exceptions where the bindings weren't really hardware
independent, or where the abstraction model was really Linux specific
(for things like the HDMI stack).

However, with the advent of overlays, one would think that a vendor
could easily include an overlay with the DTB data for the devices they
don't wish to, or cannot for other reasons release. It seems like the
perfect mechanism to comply with the rules about inclusion of nodes in
the DTS. Vendors are free to document these nodes and don't require
the Linux kernel include them in the Documents directory to do so.
There have been recent efforts to move this documentation to a third
party to maintain.

Warner

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Sebastian Frias]

Hi Warner,

On 09/12/2016 04:26 PM, Warner Losh wrote:
> On Mon, Sep 12, 2016 at 8:01 AM, Mark Rutland <mark.rutland@arm.com> wrote:
>>> Since the question seems understood, do you have an example of other SoC's
>>> doing something similar?
>>
>> I do not have an example. I know that others are using DT for data
>> beyond what Linux or another OS requires, but it's my understanding that
>> that is typically in a separate DTB.
> 
> Just to clarify: FreeBSD uses, for the most part, the DTB's that the
> 'vendor' ships, which is quite often the same ones included in Linux.
> There's some exceptions where the bindings weren't really hardware
> independent, or where the abstraction model was really Linux specific
> (for things like the HDMI stack).
> 
> However, with the advent of overlays, one would think that a vendor
> could easily include an overlay with the DTB data for the devices they
> don't wish to, or cannot for other reasons release. It seems like the
> perfect mechanism to comply with the rules about inclusion of nodes in
> the DTS. Vendors are free to document these nodes and don't require
> the Linux kernel include them in the Documents directory to do so.
> There have been recent efforts to move this documentation to a third
> party to maintain.

This is very interesting, do you have a more concrete example of such
usage?

The overlay technique could be a solution, but so is forking and
distributing a non-documented DT. That's why I'd put this solution a
little bit lower than just exposing the entire HW description through
the DT.

Best regards,

Sebastian

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Warner Losh]

On Mon, Sep 12, 2016 at 10:29 AM, Sebastian Frias <sf84@laposte.net> wrote:
> Hi Warner,
>
> On 09/12/2016 04:26 PM, Warner Losh wrote:
>> On Mon, Sep 12, 2016 at 8:01 AM, Mark Rutland <mark.rutland@arm.com> wrote:
>>>> Since the question seems understood, do you have an example of other SoC's
>>>> doing something similar?
>>>
>>> I do not have an example. I know that others are using DT for data
>>> beyond what Linux or another OS requires, but it's my understanding that
>>> that is typically in a separate DTB.
>>
>> Just to clarify: FreeBSD uses, for the most part, the DTB's that the
>> 'vendor' ships, which is quite often the same ones included in Linux.
>> There's some exceptions where the bindings weren't really hardware
>> independent, or where the abstraction model was really Linux specific
>> (for things like the HDMI stack).
>>
>> However, with the advent of overlays, one would think that a vendor
>> could easily include an overlay with the DTB data for the devices they
>> don't wish to, or cannot for other reasons release. It seems like the
>> perfect mechanism to comply with the rules about inclusion of nodes in
>> the DTS. Vendors are free to document these nodes and don't require
>> the Linux kernel include them in the Documents directory to do so.
>> There have been recent efforts to move this documentation to a third
>> party to maintain.
>
> This is very interesting, do you have a more concrete example of such
> usage?

Using overlays to layer in a proprietary device blob for a proprietary driver?
No. I don't. It just seems like a natural solution. Do I have more examples
where FreeBSD has to deviate because the DT is actually Linux
specific and does a poor job of modeling the hardware and instead
reflects the Linux driver model? I have plenty of those...

Warner

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Timur Tabi]

Warner Losh wrote:
> Do I have more examples
> where FreeBSD has to deviate because the DT is actually Linux
> specific and does a poor job of modeling the hardware and instead
> reflects the Linux driver model? I have plenty of those...

I think it would be a great idea if the FreeBSD and Linux DT maintainers 
collaborated on cleaning up the DT bindings so that this problem no 
longer occurs (or at least, not normally).

I would love to see some of those examples.

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Mark Rutland]

On Mon, Sep 12, 2016 at 11:49:07AM -0500, Timur Tabi wrote:
> Warner Losh wrote:
> >Do I have more examples
> >where FreeBSD has to deviate because the DT is actually Linux
> >specific and does a poor job of modeling the hardware and instead
> >reflects the Linux driver model? I have plenty of those...
> 
> I think it would be a great idea if the FreeBSD and Linux DT
> maintainers collaborated on cleaning up the DT bindings so that this
> problem no longer occurs (or at least, not normally).

Indeed. Theoretically/hopefully, the devicetree.org stuff creates a more
inclusive forum for this.

Thanks,
Mark.

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Mark Rutland]

Hi,

On Mon, Sep 12, 2016 at 10:45:37AM -0600, Warner Losh wrote:
> Do I have more examples where FreeBSD has to deviate because the DT is
> actually Linux specific and does a poor job of modeling the hardware
> and instead reflects the Linux driver model? I have plenty of those...

I guess you don't actually have those written down, but on the
off-chance, would you be able to share any major pain points?

We do try (admittedly far from perfectly) to avoid implementation
details in bindings, but driver mdoel details are fairly difficult to
pin down either way. It would be nice to be more aware.

Thanks,
Mark.

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Sebastian Frias]

Hi Mark,

On 09/12/2016 04:01 PM, Mark Rutland wrote:
>> 3rd parties could choose to write a driver (as opposed to use say, a user-mode
>> library) if it fits their programming model better, if they think they would
>> have better performance, or other reasons.
> 
> A vendor can always choose to "add value" in this manner. The general
> expectation of *some* driver being upstreamed remains.

Yes, that's the idea.

>>
>> That may be true, but so far we are not discussing changing DT's API so it
>> should not have big ramifications.
> 
> You're not changing the code, but you are creating a binding. Bindings
> are intended to be stable (i.e. a working DTB from today should continue
> to work in future), and thus there are ramifications.

Ok, but who is responsible for such guarantee?
How is it enforced and verified?

> 
> Few devices these says are entirely independent, and most devices can be
> instantiated multiple times (even if there happens to only be a single
> instance in practice). For the example of a userspace driver there are
> very real ABI concerns, such as how the device(s) are discovered, how
> any related components like regulators and clocks are controlled, etc.
> 
> There are ramifications here, and it's a dangerous over simplification
> to say that this doesn't matter because we're not changing kernel code.
> 
>> Besides, what "makes sense now" may "not make sense tomorrow" depending on
>> how the HW is modified.
> 
> That's always the case when a new generation of hardware comes out, so I
> don't think that's relevant to the topic at hand.

Exactly, that's why to I'm having trouble to understand why there is so much
insistence on "getting the DT 100% right", since a HW change could imply
that what made 100% sense yesterday, does not today.
Since that is a possibility we have to live with, then the "100% right" goal
is most likely unachievable.
That's different from "backwards compatibility" for which some technique,
like alternate descriptions, can be put in place.

Maybe I will get a better understanding of this once my previous question
about who and how guarantees the stability of a given DT blob.

>>
>> Actually, I think it would encourage more SoC manufacturers to use DT as a way
>> to document their HW, which is a good thing.
> 
> Writing and reviewing bindings is a very tricky topic, as it can require
> fairly intimate knowledge of a piece of hardware. I've repeatedly found
> that binding descriptions did not match the realities of the hardware,
> and I've only managed to do so by looking at accompanying driver code.
> 
> Given that manuals and other information on devices are often not freely
> available (if they exist at all), the proposal effectively limits myself
> and others to spot common (anti)patterns, which is far less than ideal,
> and will result in more mistakes.
> 
> As it stands, the proposal asks for effort for the community (in terms
> of review and maintenance of bindings), with no benefit to the kernel
> community, and a number of pitfalls that we would rather avoid.

Could you be more precise on those two issues? Namely:
"the effort" and the "lack of benefit for the community"?

I can understand the effort it takes to review a binding and some
driver, but if there's no driver, why would it matter if the DT binding is
100% right? Hence, why would it take more effort?
Furthermore, if there's no driver, there's no backward compatibility to
guarantee. Shouldn't it require less effort?

Also, what sort of "benefits" does the community expects or requires?
Because the idea behind the proposal is to put the HW description in DT, so
basically the HW would be documented. Maybe there wouldn't be a driver right
away, but the HW description would allow for drivers to exist.

> 
> In an ideal world, writing and reviewing bindings would be a simple
> affair, and this could happen separately from work on any particular OS.
> In practice, things are sufficiently complicated that you need *some*
> demonstration that a binding is suitable, which is what I'm personally
> after when I ask for a Linux driver.
> 
>>>> However, after discussing over IRC, it looks like there was no guidance on
>>>> this. Some people think submitting DT properties/nodes without a corresponding
>>>> Linux driver is frowned upon, while others thought it was an odd limitation
>>>> and suggested asking here.
>>>
>>> Unfortunately, I think that the area is sufficiently vague that there
>>> simply is no clear and general answer.
>>>
>>> For the sake of discussion, an example of a particular block, along with
>>> what you expect/need to describe would be helpful.
>>
>> I don't have a more concrete example now.
> 
> For this discussion to go somewhere, we need an example. Otherwise we're
> all coming at this with differing implicit assumptions and no clear
> evidence for any assertions.

Ok, I'll try to come up with some example.

>> But if I understood correctly your comment, you are basically saying that
>> without an example is hard to say.
>> Since the question seems understood, do you have an example of other SoC's
>> doing something similar?
> 
> I do not have an example. I know that others are using DT for data
> beyond what Linux or another OS requires, but it's my understanding that
> that is typically in a separate DTB.
> 

I see, although I don't understand how accepting such solution (i.e.: having the
information in a different DT) benefits the open-source community, since it
basically means that the open-source community settles for less information.

Best regards,

Sebastian

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Timur Tabi]

Sebastian Frias wrote:
>> You're not changing the code, but you are creating a binding.
>> Bindings
>>> are intended to be stable (i.e. a working DTB from today should
>>> continue to work in future), and thus there are ramifications.

> Ok, but who is responsible for such guarantee?

The developers who create the driver and modify it.  Only upstream 
contributions count.

> How is it enforced and verified?

The upstream reviewers verify it, and if they see a problem, they reject 
the patch.

> Exactly, that's why to I'm having trouble to understand why there is
>  so much insistence on "getting the DT 100% right", since a HW change
>  could imply that what made 100% sense yesterday, does not today.

I'm not sure what you're getting at. Everything is best-effort. The 
binding for a given device is supposed to accurately, but minimally, 
describe the hardware so that the driver can program the device 
properly. Specific properties are added to the binding to handle 
specific cases. If a binding includes a description of properties that 
are not used by the driver, the developer is typically asked to remove 
those.

So I don't understand the "100% right" comment.

> Could you be more precise on those two issues? Namely: "the effort"
> and the "lack of benefit for the community"?

1) The effort = the effort by upstream developers to review the binding.

2) lack of benefit = proprietary and out-of-tree drivers do not benefit 
the community.

> I can understand the effort it takes to review a binding and some
> driver, but if there's no driver, why would it matter if the DT
> binding is 100% right?

Why bother creating a binding if there's no driver to use it?

 > Hence, why would it take more effort?
> Furthermore, if there's no driver, there's no backward compatibility
>  to guarantee. Shouldn't it require less effort?

If a developer creates a binding without a driver, then it's very hard 
to know if that binding is correct.  That's like creating a recipe 
without attempting to make the food.  How do you know it actually tastes 
good?  No one would ever ask a chef to create a "technically correct" 
recipe without cooking it first and tasting it.

> Also, what sort of "benefits" does the community expects or
> requires? Because the idea behind the proposal is to put the HW
> description in DT, so basically the HW would be documented. Maybe
> there wouldn't be a driver right away, but the HW description would
> allow for drivers to exist.

I'm not sure how many times we need to repeat this, but the idea that 
the DT binding documentation can be used as official documentation for 
the hardware is absurd.  What's wrong with the ACTUAL hardware 
documentation provided by the manufacturer in PDF format?  The DT 
binding has no value without an actual driver.

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Sebastian Frias]

On 09/12/2016 06:07 PM, Sebastian Frias wrote:
> Hi Mark,
> 
> On 09/12/2016 04:01 PM, Mark Rutland wrote:
>>> 3rd parties could choose to write a driver (as opposed to use say, a user-mode
>>> library) if it fits their programming model better, if they think they would
>>> have better performance, or other reasons.
>>
>> A vendor can always choose to "add value" in this manner. The general
>> expectation of *some* driver being upstreamed remains.
> 
> Yes, that's the idea.

Just to clarify, what I meant is that, using the DT as the authoritative
source of HW description is a way to "add value" to everybody, because both,
3rd-parties and the open-source community get the same information.
This creates the conditions for drivers to exist, with the expectation that
eventually said drivers would be upstreamed.

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Mark Rutland]

On Mon, Sep 12, 2016 at 06:07:05PM +0200, Sebastian Frias wrote:
> On 09/12/2016 04:01 PM, Mark Rutland wrote:
> > Few devices these says are entirely independent, and most devices can be
> > instantiated multiple times (even if there happens to only be a single
> > instance in practice). For the example of a userspace driver there are
> > very real ABI concerns, such as how the device(s) are discovered, how
> > any related components like regulators and clocks are controlled, etc.
> > 
> > There are ramifications here, and it's a dangerous over simplification
> > to say that this doesn't matter because we're not changing kernel code.
> > 
> >> Besides, what "makes sense now" may "not make sense tomorrow" depending on
> >> how the HW is modified.
> > 
> > That's always the case when a new generation of hardware comes out, so I
> > don't think that's relevant to the topic at hand.
> 
> Exactly, that's why to I'm having trouble to understand why there is so much
> insistence on "getting the DT 100% right", since a HW change could imply
> that what made 100% sense yesterday, does not today.
> Since that is a possibility we have to live with, then the "100% right" goal
> is most likely unachievable.
> That's different from "backwards compatibility" for which some technique,
> like alternate descriptions, can be put in place.

I'm not on about "100% right", but more "a reasonable chance of being
good enough". The latter is extremely difficult to judge when you just
get a binding document with little or no additional context.

Backwards compatibility is with regards to new software supporting old
bindings. If new HW comes out, we can create new bindings. Old bindings
should remain supported regardless.

> >> Actually, I think it would encourage more SoC manufacturers to use DT as a way
> >> to document their HW, which is a good thing.
> > 
> > Writing and reviewing bindings is a very tricky topic, as it can require
> > fairly intimate knowledge of a piece of hardware. I've repeatedly found
> > that binding descriptions did not match the realities of the hardware,
> > and I've only managed to do so by looking at accompanying driver code.
> > 
> > Given that manuals and other information on devices are often not freely
> > available (if they exist at all), the proposal effectively limits myself
> > and others to spot common (anti)patterns, which is far less than ideal,
> > and will result in more mistakes.
> > 
> > As it stands, the proposal asks for effort for the community (in terms
> > of review and maintenance of bindings), with no benefit to the kernel
> > community, and a number of pitfalls that we would rather avoid.
> 
> Could you be more precise on those two issues? Namely:
> "the effort" and the "lack of benefit for the community"?

As above, reviewing is tricky. One has to spend the time gaining an
understanding of a particular piece of hardware, the class of hardware
it falls in, and also the bigger picture that it fits in. Once you have
that, you have to review the binding in that context, and that takes
time and effort.

As things evolve, perhaps mistakes or inconsistencies are found, or new
ways to generalise things. As that occurs, there is a maintenance burden
for existing bindings.

All of that takes time and effort.

If, at the end of that, a proprietary vendor driver is using a different
version of the binding anyway, because "there's no backward
compatibility to guarantee", then there is no benefit to the document.

Even if that proprietary driver does remain stable, the Linux community
will have done work that only benefits the authors of that driver. We
would prefer that the results of our efforts are open, and benefit all.

> I can understand the effort it takes to review a binding and some
> driver, but if there's no driver, why would it matter if the DT binding is
> 100% right? Hence, why would it take more effort?
> Furthermore, if there's no driver, there's no backward compatibility to
> guarantee. Shouldn't it require less effort?

I don't follow. If there's no compatibility to guarantee, why do you
want a binding?

A binding is a form of contract -- if you describe the HW this way, then
some software will understand it. You can extend a binding over time,
certainly, but if the baseline of that binding is a moving target, that
benefits nobody.

[...]

> >> But if I understood correctly your comment, you are basically saying that
> >> without an example is hard to say.
> >> Since the question seems understood, do you have an example of other SoC's
> >> doing something similar?
> > 
> > I do not have an example. I know that others are using DT for data
> > beyond what Linux or another OS requires, but it's my understanding that
> > that is typically in a separate DTB.
> 
> I see, although I don't understand how accepting such solution (i.e.: having the
> information in a different DT) benefits the open-source community, since it
> basically means that the open-source community settles for less information.

As with all things, it depends on context. If someone's using a DT to
describe details of the secure world of a platform with trustzone to a
secure OS, then not all of that information is relevant to Linux.
Likewise if configuration details specific to FW are embedded.

If there's information relevant to a general purpose OS, then I would
expect it to be described. By the same token, I would expect a general
purpose OS to actually be making use of the information. In practice,
we've used Linux as the benchmark for that. That needn't necessarily be
the case if another OS can demonstrate that the binding is worthwhile --
ideally we'd have multiple OSs using bindings so as to "keep us honest"
and free from implementation details.

As I mentioned before, an example would help. The theoretical envelope
is very large and likely far beyond what you envisage. We need something
to focus on, or we're arguing about what we conceive differently.

Thanks,
Mark.

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Sebastian Frias]

Hi Mark,

On 09/12/2016 06:56 PM, Mark Rutland wrote:
>> Exactly, that's why to I'm having trouble to understand why there is so much
>> insistence on "getting the DT 100% right", since a HW change could imply
>> that what made 100% sense yesterday, does not today.
>> Since that is a possibility we have to live with, then the "100% right" goal
>> is most likely unachievable.
>> That's different from "backwards compatibility" for which some technique,
>> like alternate descriptions, can be put in place.
> 
> I'm not on about "100% right", but more "a reasonable chance of being
> good enough". 

Ok.

> The latter is extremely difficult to judge when you just
> get a binding document with little or no additional context.

Exactly, that is why I was thinking it would take less "review" time.
Indeed, if there is no driver, why would it matter what those bindings
are?

> Backwards compatibility is with regards to new software supporting old
> bindings. If new HW comes out, we can create new bindings. Old bindings
> should remain supported regardless.

Indeed. So you agree that without a driver, there is no backward compatibility
to maintain (because nothing could break).
Could we then say that in that case, it should not matter that much (if at all)
if the bindings have "a reasonable chance of being good enough"?

Because I'm trying to understand why/how would the "open-source community" be
affected by some DT properties/nodes that are not used by upstream Linux drivers.

Warner proposed 'overlays' to deal with the "open-source community" reticence to
accept such bindings.
Whereas it may be simpler to just find a way to accommodate the integration of
such bindings in a way that everybody wins.
That could take the form of a "staging" DT area, so that the 'overlay' is public.
Just for the sake and benefit of everybody, 3rd parties and open-source community.

>> Could you be more precise on those two issues? Namely:
>> "the effort" and the "lack of benefit for the community"?
> 
> As above, reviewing is tricky. One has to spend the time gaining an
> understanding of a particular piece of hardware, the class of hardware
> it falls in, and also the bigger picture that it fits in. Once you have
> that, you have to review the binding in that context, and that takes
> time and effort.

Yes, but this is based on a binding for which there's a driver.
If there's no driver it should not take that much time, right?

> As things evolve, perhaps mistakes or inconsistencies are found, or new
> ways to generalise things. As that occurs, there is a maintenance burden
> for existing bindings.
> 
> All of that takes time and effort.

Only for bindings for which there is a driver.

Think about this:
- a binding with no driver is submitted and ends up in the tree
(it could be on a staging area if necessary)

- if at a later point somebody attempts to upstream a driver using those
'staging' bindings, the reviewers could say "you are using 'staging' bindings,
please add compatibility with 'staging' and 'standard' bindings", even if that
includes the discussion and review of newly created 'standard' bindings
corresponding to the 'staging' bindings.

- the submitter may even say "there's no need for compatibility for 'staging'
bindings, because they were never used (or other valid reasons)".

What would you think of something like that?

> If, at the end of that, a proprietary vendor driver is using a different
> version of the binding anyway, because "there's no backward
> compatibility to guarantee", then there is no benefit to the document.

No, it would not use a "different version of the binding", because the
binding would be public, i.e.: everything would be on the public DT.

> Even if that proprietary driver does remain stable, the Linux community
> will have done work that only benefits the authors of that driver. We
> would prefer that the results of our efforts are open, and benefit all.

Do you have an example of a binding *not used by Linux* that created enormous
amount of work for the Linux community?

>> I can understand the effort it takes to review a binding and some
>> driver, but if there's no driver, why would it matter if the DT binding is
>> 100% right? Hence, why would it take more effort?
>> Furthermore, if there's no driver, there's no backward compatibility to
>> guarantee. Shouldn't it require less effort?
> 
> I don't follow. If there's no compatibility to guarantee, why do you
> want a binding?

Let's make an abstraction of the word 'binding', 'create a binding', etc. and
just focus on this:
- Somebody submits a DT file that contains properties and nodes that are
*not used* by any Linux driver.
- Said properties and nodes serve as HW description for HW blocks for which
*there is no* Linux driver.

The goal of the above is to use the DT as the authoritative (and single)
source of HW definition.

An alternate solution, as proposed by Warner, is to use 'binary overlays' for
the DT.

> A binding is a form of contract -- if you describe the HW this way, then
> some software will understand it. You can extend a binding over time,
> certainly, but if the baseline of that binding is a moving target, that
> benefits nobody.
> 

The benefit is that in one case (the case where the whole SoC is described
in the DT, regardless of the existence of a Linux driver or not) there is more
information available publicly.

>> I see, although I don't understand how accepting such solution (i.e.: having the
>> information in a different DT) benefits the open-source community, since it
>> basically means that the open-source community settles for less information.
> 
> As with all things, it depends on context. If someone's using a DT to
> describe details of the secure world of a platform with trustzone to a
> secure OS, then not all of that information is relevant to Linux.
> Likewise if configuration details specific to FW are embedded.

Ok, so if the information is not relevant to Linux do you agree that it
should not affect it, and then we could imagine such details being present on
the DT anyway?

> If there's information relevant to a general purpose OS, then I would
> expect it to be described. By the same token, I would expect a general
> purpose OS to actually be making use of the information. In practice,
> we've used Linux as the benchmark for that. That needn't necessarily be
> the case if another OS can demonstrate that the binding is worthwhile --
> ideally we'd have multiple OSs using bindings so as to "keep us honest"
> and free from implementation details.

You mention the case of another OS.
What is the definition of OS in this case?
Because one could say that "FW" or "secure world" could fit that definition,
right?
Or when you talk about "another OS" you think only about other open-source
mainstream OSs, like FreeBSD?

> As I mentioned before, an example would help. The theoretical envelope
> is very large and likely far beyond what you envisage. We need something
> to focus on, or we're arguing about what we conceive differently.
> 

I think we've made progress :-)
Indeed, to me it is clear that what we conceive "differently", is that
"the effort", "lack of benefit for the community", "Old bindings should
remain supported regardless" and "backward compatibility" are considered
with respect to DT *plus* driver, yet the idea is to have DT describe
HW for which there's no upstream driver yet.
Hence most of those considerations should not apply, right?

Best regards,

Sebastian

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Timur Tabi]

Sebastian Frias wrote:
> Let's make an abstraction of the word 'binding', 'create a binding', etc. and
> just focus on this:
> - Somebody submits a DT file that contains properties and nodes that are
> *not used*  by any Linux driver.
> - Said properties and nodes serve as HW description for HW blocks for which
> *there is no*  Linux driver.
>
> The goal of the above is to use the DT as the authoritative (and single)
> source of HW definition.

No.

I've grown weary of this discussion.  We have explained multiple times 
why this is impractical.  Using the DT to document hardware makes no 
sense.  No one is going to do that, and anyone who attempts to submit a 
DT binding without an actual driver will get rejected.

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Mark Rutland]

Hi Timur,

On Tue, Sep 13, 2016 at 06:37:16AM -0500, Timur Tabi wrote:
> Sebastian Frias wrote:
> >Let's make an abstraction of the word 'binding', 'create a binding', etc. and
> >just focus on this:
> >- Somebody submits a DT file that contains properties and nodes that are
> >*not used*  by any Linux driver.
> >- Said properties and nodes serve as HW description for HW blocks for which
> >*there is no*  Linux driver.
> >
> >The goal of the above is to use the DT as the authoritative (and single)
> >source of HW definition.
> 
> No.
> 
> I've grown weary of this discussion.  We have explained multiple
> times why this is impractical.  Using the DT to document hardware
> makes no sense.  No one is going to do that, and anyone who attempts
> to submit a DT binding without an actual driver will get rejected.

Please don't make the same mistake of trivialising this in either
direction.

While we appear to be going in circles, in general there are potentially
valid cases to consider -- there may be system properties/devices that
don't happen to matter to Linux, but are generic, well-defined, and
matter to others. Bindings for those should be considered.

In the absence of any example, as with this thread, there is nothing to
consider, however.

Thanks,
Mark.

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Mark Rutland]

On Tue, Sep 13, 2016 at 12:04:07PM +0200, Sebastian Frias wrote:
> Hi Mark,
> 
> On 09/12/2016 06:56 PM, Mark Rutland wrote:
> > The latter is extremely difficult to judge when you just
> > get a binding document with little or no additional context.
> 
> Exactly, that is why I was thinking it would take less "review" time.
> Indeed, if there is no driver, why would it matter what those bindings
> are?

If you believe that the bindings don't matter, then there is absolutely
no reason for them to exist in the first place.

If those binding matter to *anyone*, then those collating the bindings
have some responsibility of stewardship, and that includes
review/maintenance/etc.

Hence, the Linux community cares as stewards of those bindings, and
don't accept bindings they don't understand, for which there is no
obvious user, nor for which the authors claim stability does not matter.
Those go against the aims of DT, and against out responsiblities as
stewards.

I cannot put that any clearer. 

> >> Could you be more precise on those two issues? Namely:
> >> "the effort" and the "lack of benefit for the community"?
> > 
> > As above, reviewing is tricky. One has to spend the time gaining an
> > understanding of a particular piece of hardware, the class of hardware
> > it falls in, and also the bigger picture that it fits in. Once you have
> > that, you have to review the binding in that context, and that takes
> > time and effort.
> 
> Yes, but this is based on a binding for which there's a driver.
> If there's no driver it should not take that much time, right?
> 
> > As things evolve, perhaps mistakes or inconsistencies are found, or new
> > ways to generalise things. As that occurs, there is a maintenance burden
> > for existing bindings.
> > 
> > All of that takes time and effort.
> 
> Only for bindings for which there is a driver.

This is not true for all but the most trivial of hardware, as I stated
previously.

Go and take a look at all the effort that went into sorting out generic
IOMMU bindings, when driver support was written after a large amount of
review to sort out fundamental concepts. We had to sort out fundamentals
before prototype driver code could be written, and while we knew drivers
were coming, an awful lot of review effort came first.


> Think about this:
> - a binding with no driver is submitted and ends up in the tree
> (it could be on a staging area if necessary)
> 
> - if at a later point somebody attempts to upstream a driver using those
> 'staging' bindings, the reviewers could say "you are using 'staging' bindings,
> please add compatibility with 'staging' and 'standard' bindings", even if that
> includes the discussion and review of newly created 'standard' bindings
> corresponding to the 'staging' bindings.
> 
> - the submitter may even say "there's no need for compatibility for 'staging'
> bindings, because they were never used (or other valid reasons)".
> 
> What would you think of something like that?

As above, if they were never used, and potentially wrong, why did they
exist?

Trying to upstream a binding with no user comees with no immediate
benefit, and potentially creates longer-term pain, whereas you can defer
upstreaming a binding until the driver is ready.

Note that I've repeatedly pointed out that the user of the binding
doesn't necessarily have to be linux. However, there does need to be
some demonstration, and commitment to maintaining the principles DT aims
towards (e.g. stability).

> Let's make an abstraction of the word 'binding', 'create a binding', etc. and
> just focus on this:
> - Somebody submits a DT file that contains properties and nodes that are
> *not used* by any Linux driver.
> - Said properties and nodes serve as HW description for HW blocks for which
> *there is no* Linux driver.
> 
> The goal of the above is to use the DT as the authoritative (and single)
> source of HW definition.

I understand that goal, and I've asked for a specific example, as this
is not clear-cut. e.g. there has been work on describing secure devices
for QEMU, but this isn't necessarily something we want to expose Linux
to in general.

> > As with all things, it depends on context. If someone's using a DT to
> > describe details of the secure world of a platform with trustzone to a
> > secure OS, then not all of that information is relevant to Linux.
> > Likewise if configuration details specific to FW are embedded.
> 
> Ok, so if the information is not relevant to Linux do you agree that it
> should not affect it, and then we could imagine such details being present on
> the DT anyway?

Perhaps, or perhaps not. It depends on a number of details, and as I've
said previously I cannot give you a general answer, because there is
none. You must provide a specific case.

> You mention the case of another OS.
> What is the definition of OS in this case?

Generally, I am considering a general purpose OS (e.g. Linux, FreeBSD),
and not a secure-world trusted OS nor firmware (as typically these are
very strongly tied to the platform, and have very different strtuctures
and requirements when compared to a general purpose OS).

That's the conext in which bindings are developed.

> Because one could say that "FW" or "secure world" could fit that definition,
> right?

There's been work on describing things about the secure world in DT for
QEMU. Firmware is typically so device-specific that an upstream/common
DT doesn't really make sense.

Perhaps you have an example of the specific use-case you care about?

> Indeed, to me it is clear that what we conceive "differently", is that
> "the effort", "lack of benefit for the community", "Old bindings should
> remain supported regardless" and "backward compatibility" are considered
> with respect to DT *plus* driver, yet the idea is to have DT describe
> HW for which there's no upstream driver yet.
> Hence most of those considerations should not apply, right?

No.

Bindings themselves should remain stable over time in that they must be
evolved so as to allow software to handle them in a stable fashion,
supporting old and new DTBs.

While a lot of that effort is taken by code, care must also be taken wit
the bindings themselves, and those considerations apply.

Thanks,
Mark.

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Sebastian Frias]

Hi Mark,

On 09/13/2016 03:12 PM, Mark Rutland wrote:
>> Exactly, that is why I was thinking it would take less "review" time.
>> Indeed, if there is no driver, why would it matter what those bindings
>> are?
> 
> If you believe that the bindings don't matter, then there is absolutely
> no reason for them to exist in the first place.

Again, they would be there serving as HW description. Like documentation.
3rd parties and the open-source community could then use them to write
drivers.

Also, it would avoid having multiple DTs (bootloader, Linux, etc.) or
using 'binary DT overlays'.

In one case the nodes/properties would be made public, most likely with
documentation (even if there's no driver for them), in the other case
undocumented 'binary DT overlays' are used.

> 
> If those binding matter to *anyone*, then those collating the bindings
> have some responsibility of stewardship, and that includes
> review/maintenance/etc.
> 
> Hence, the Linux community cares as stewards of those bindings, and
> don't accept bindings they don't understand, for which there is no
> obvious user, nor for which the authors claim stability does not matter.
> Those go against the aims of DT, and against out responsiblities as
> stewards.
> 
> I cannot put that any clearer. 

I understand that.
However, it does not looks crazy to add some sort of 'staging', actually,
I found this:

$ find . -name 'stag*'
./Documentation/devicetree/bindings/staging
./drivers/staging
...
$ ls -1R ./Documentation/devicetree/bindings/staging
./Documentation/devicetree/bindings/staging:
iio
ion

./Documentation/devicetree/bindings/staging/iio:
adc

./Documentation/devicetree/bindings/staging/iio/adc:
lpc32xx-adc.txt
spear-adc.txt

./Documentation/devicetree/bindings/staging/ion:
hi6220-ion.txt

$ ls -1R ./drivers/staging | wc -l
2134

Isn't that a similar use to the one discussed in this thread?

>> Only for bindings for which there is a driver.
> 
> This is not true for all but the most trivial of hardware, as I stated
> previously.
> 
> Go and take a look at all the effort that went into sorting out generic
> IOMMU bindings, when driver support was written after a large amount of
> review to sort out fundamental concepts. We had to sort out fundamentals
> before prototype driver code could be written, and while we knew drivers
> were coming, an awful lot of review effort came first.

Again, you are talking about drivers, but it is not the case at hand.

DT seems essentially free-form, like XML.
One could imagine that some tool could then be used to guarantee that
some parts of DT conform to a given XML schema, including backwards
compatibility, while at the same time ignoring 'staging' stuff.

>> Think about this:
>> - a binding with no driver is submitted and ends up in the tree
>> (it could be on a staging area if necessary)
>>
>> - if at a later point somebody attempts to upstream a driver using those
>> 'staging' bindings, the reviewers could say "you are using 'staging' bindings,
>> please add compatibility with 'staging' and 'standard' bindings", even if that
>> includes the discussion and review of newly created 'standard' bindings
>> corresponding to the 'staging' bindings.
>>
>> - the submitter may even say "there's no need for compatibility for 'staging'
>> bindings, because they were never used (or other valid reasons)".
>>
>> What would you think of something like that?
> 
> As above, if they were never used, and potentially wrong, why did they
> exist?

The last step of my description, where the 'staging' bindings may not have
been used, was listed only for the sake of completeness since it is just a
possibility.
The hope is that they would be eventually used (most likely as is, but
there is also the possibility of having to rethink the bindings when
moving them from 'staging' to 'stable').

> Trying to upstream a binding with no user comees with no immediate
> benefit, and potentially creates longer-term pain, whereas you can defer
> upstreaming a binding until the driver is ready.

The immediate benefit is complete HW description, which, if generalised and
done properly would amount to HW documentation, isn't that good?

> Note that I've repeatedly pointed out that the user of the binding
> doesn't necessarily have to be linux. However, there does need to be
> some demonstration, and commitment to maintaining the principles DT aims
> towards (e.g. stability).

The commitment to stability can be enforced later, since changes would be
reviewed.

If the "user of the binding" is not Linux, under what circumstances
could "Linux" have the legitimacy of guaranteeing or enforcing any Linux-
specific commitment?

>> Let's make an abstraction of the word 'binding', 'create a binding', etc. and
>> just focus on this:
>> - Somebody submits a DT file that contains properties and nodes that are
>> *not used* by any Linux driver.
>> - Said properties and nodes serve as HW description for HW blocks for which
>> *there is no* Linux driver.
>>
>> The goal of the above is to use the DT as the authoritative (and single)
>> source of HW definition.
> 
> I understand that goal, and I've asked for a specific example, as this
> is not clear-cut. e.g. there has been work on describing secure devices
> for QEMU, but this isn't necessarily something we want to expose Linux
> to in general.

Interesting, do you know where in QEMU's code should I look for that?

Because the example I had in mind is something like (totally out of my
imagination):

   /sigma/ {
       audio_decoder_0: {
          version  = <2>;
          revision = <1>;
          program-memory = <0x20100000 0x1000>;
          data-memory    = <0x20101000 0x1000>;
          hwbug-list = <33, 57, 11>;
          arch = <DSP32>;
          mutex-id = <12>;
          irq-line = <9>;
          mbus-read-channels  = <2, 3>;
          mbus-write-channels = <12, 13>;
          has-AAC-support = <1>;
          has-DTS-support = <1>;
          has-SPDIF-output = <1>;
          ...
       };
       audio_decoder_1: {
          version  = <1>;
          revision = <0>;
          program-memory = <0x20200000 0x1000>;
          data-memory    = <0x20201000 0x1000>;
          hwbug-list = <33, 57>;
          arch = <DSP16>;
          mutex-id = <11>;
          irq-line = <8>;
          mbus-read-channels = <4>;
          mbus-write-channels = <14>;
          has-AAC-support = <1>;
          has-DTS-support = <0>;
          has-SPDIF-output = <0>;
          ...
       };
       ethernet: {
          mac-address = [ 00 11 22 33 44 55 ];
          hwbug-list = <23>;
       };
       video_decoder: {
          version = <4>;
          revision = <0>;
          memory = <0x20300000 0x10000>;
          arch = <MIPS4K>;
          mutex-id = <12>;
          irq-line = <7>;
          has-H264-support = <1>;
          ...
       };
   ...
   };

We could even imagine a section like:

   boot: {
      verify-images = <1>;
      boot-order = <NAND, SD, SATA>;
      enable-uart = <0>;
      debug-level = <1>;
   };

>> Ok, so if the information is not relevant to Linux do you agree that it
>> should not affect it, and then we could imagine such details being present on
>> the DT anyway?
> 
> Perhaps, or perhaps not. It depends on a number of details, and as I've
> said previously I cannot give you a general answer, because there is
> none. You must provide a specific case.

I gave one above, but I still don't understand why would it matter.
I mean, it should be easy:
- is the node/property used by a Linux driver?
  - YES => you must submit both DT+driver
  - NO  => we don't care

>> You mention the case of another OS.
>> What is the definition of OS in this case?
> 
> Generally, I am considering a general purpose OS (e.g. Linux, FreeBSD),
> and not a secure-world trusted OS nor firmware (as typically these are
> very strongly tied to the platform, and have very different strtuctures
> and requirements when compared to a general purpose OS).
> 
> That's the conext in which bindings are developed.
> 

I see, thanks.

>> Because one could say that "FW" or "secure world" could fit that definition,
>> right?
> 
> There's been work on describing things about the secure world in DT for
> QEMU. Firmware is typically so device-specific that an upstream/common
> DT doesn't really make sense.
> 
> Perhaps you have an example of the specific use-case you care about?

Like I said, this started like an hypothetical question as a way to centralise
all HW description in a single place.
Currently it is spread over multiple places and it is very error prone, not
to mention that not everybody gets all the information at once.
Also, DT is meant to be shared by at least Bootloader and Linux, so it would
be better if it was unique.

Anyway, I tried to make a more concrete example further above.
Hopefully it serves to illustrate more the idea.

>> Indeed, to me it is clear that what we conceive "differently", is that
>> "the effort", "lack of benefit for the community", "Old bindings should
>> remain supported regardless" and "backward compatibility" are considered
>> with respect to DT *plus* driver, yet the idea is to have DT describe
>> HW for which there's no upstream driver yet.
>> Hence most of those considerations should not apply, right?
> 
> No.
> 
> Bindings themselves should remain stable over time in that they must be
> evolved so as to allow software to handle them in a stable fashion,
> supporting old and new DTBs.

Yes, but "must be evolved so as to allow software to handle them in a stable
fashion, supporting old and new DTBs." makes sense for Linux drivers, or
from Linux's perspective.

Project independence rules should allow for projects to cooperate without
interfering with each other.

> 
> While a lot of that effort is taken by code, care must also be taken wit
> the bindings themselves, and those considerations apply.

IMHO, they apply only when there's a Linux driver, or any other public
user of such bindings. But if there's no user, it seems like an unnecessary
constraint.

Best regards,

Sebastian

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Mark Rutland]

Hi,

On Tue, Sep 13, 2016 at 04:22:09PM +0200, Sebastian Frias wrote:
> On 09/13/2016 03:12 PM, Mark Rutland wrote:

[context was deleted, TL;DR: binding review is necessary, and takes
effort, regardless of presence/absence of a driver]

> >> Only for bindings for which there is a driver.
> > 
> > This is not true for all but the most trivial of hardware, as I stated
> > previously.
> > 
> > Go and take a look at all the effort that went into sorting out generic
> > IOMMU bindings, when driver support was written after a large amount of
> > review to sort out fundamental concepts. We had to sort out fundamentals
> > before prototype driver code could be written, and while we knew drivers
> > were coming, an awful lot of review effort came first.
> 
> Again, you are talking about drivers, but it is not the case at hand.

No, I am not. Please do not presume to put words in my mouth.

I explicitly described a case where binding review took effort, and the
presence or absence of drivers was irrelevant. We later had drivers,
yes, but we had to understand the hardware to get the binding right
first.

If there's data which has no consumer, it has no value being in the DT.
Placing data with no consumer in the DT comes with a number of issues,
e.g.

a) Some DTS authors will ignore it, and not place data according to it
   in DTs. Hence there's no gain in consistency.

b) Though some accident (perhaps a typo, perhaps a misunderstanding of
   the binding), a DT will come to have erroneous data, yet this will go
   unnoticed, as there is no consumer. When later a consumer appears, it
   can't trust existing DTs, and has to either ignore the binding
   entirely, or bodge around each and every broken DT.

c) When a consumer eventually appears, it turned out we didn't capture
   details of the hardware sufficiently, and the binding turns out to be
   useless. At worst, this boils down to (b), at best, we require
   additional properties. In this case absolutely nothing is gained.

In all cases, all we end up doing is enlarging DTBs, and risk causing
even more work.

If there *is* going to be a consumer, and if information regarding that
will be provided, then matters are different, and we can consider a
binding on its own merit. We need a specific example for that.

> If the "user of the binding" is not Linux, under what circumstances
> could "Linux" have the legitimacy of guaranteeing or enforcing any Linux-
> specific commitment?

To at least the extent that if someone says they're not going to bother,
we clearly have no reason to bother supporting them.

Note that *nothing* stops you from using the DT container format for
your own purposes, in violation of every binding and rule we have.
However, for those cases we clearly won't document them as the standard
mechanism.

There are other things build atop of the DTB format, e.g. FIT, which
aren't quite devicetree in the usual sense.

> > I understand that goal, and I've asked for a specific example, as this
> > is not clear-cut. e.g. there has been work on describing secure devices
> > for QEMU, but this isn't necessarily something we want to expose Linux
> > to in general.
> 
> Interesting, do you know where in QEMU's code should I look for that?

Documentation/devicetree/bindings/arm/secure.txt for the basics.

Generally, I'd expect that even if the secure OS were using DT in this
fashion, the non-secure general purpose OS would be handed a DT
containing only the non-secure world portions.

> > While a lot of that effort is taken by code, care must also be taken wit
> > the bindings themselves, and those considerations apply.
> 
> IMHO, they apply only when there's a Linux driver, or any other public
> user of such bindings. But if there's no user, it seems like an unnecessary
> constraint.

If there's no user, there's no need for the binding.

If there's some user somewhere, and that user wants the binding
rubber-stamped as an "official" binding, they need to follow the usual
rules for bindings.

If there is a user, and they don't want to follow the usual rules,
there's no point trying to get the binding rubber-stamped.

Thanks,
Mark.

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Sebastian Frias]

Hi Mark,

On 09/13/2016 04:51 PM, Mark Rutland wrote:
> Hi,
> 
> On Tue, Sep 13, 2016 at 04:22:09PM +0200, Sebastian Frias wrote:
>> On 09/13/2016 03:12 PM, Mark Rutland wrote:
> 
> [context was deleted, TL;DR: binding review is necessary, and takes
> effort, regardless of presence/absence of a driver]

Ok, I see you deleted the part where I was asking about the 'staging' folders.

$ find . -name 'stag*'
./Documentation/devicetree/bindings/staging
./drivers/staging
...

I don't know if that was intended (since you said you did not read it) but
I think it would be interesting for the discussion to give a little overview
on that.
My understanding is that there's a 'staging' area for bindings, couldn't the
nodes/properties from my example be put in there?

>>> Go and take a look at all the effort that went into sorting out generic
>>> IOMMU bindings, when driver support was written after a large amount of
>>> review to sort out fundamental concepts. We had to sort out fundamentals
>>> before prototype driver code could be written, and while we knew drivers
>>> were coming, an awful lot of review effort came first.
>>
>> Again, you are talking about drivers, but it is not the case at hand.
> 
> No, I am not. Please do not presume to put words in my mouth.

I'm sorry, that was not my intention.
I just assumed that because your paragraph mentioned the word "driver" and
appears to have been Linux-only effort geared towards writing drivers:
   "...We had to sort out fundamentals before prototype driver code could be
written, and while we knew drivers were coming..."

Maybe I miss some more context on that example.

> 
> I explicitly described a case where binding review took effort, and the
> presence or absence of drivers was irrelevant. We later had drivers,
> yes, but we had to understand the hardware to get the binding right
> first.

I see.
So if I understood correctly, it was a cleanup, or a way to unify some
bindings, so that drivers could be written easier?

I can see that taking time, but the underlying idea of this discussion is
that the DT could be divided in different sections.

I think this would allow and encourage SoC manufacturers to publish more
details, since they could use them internally as well.

Obviously, this is not strictly necessary, and I'm sure SoC manufacturers
could choose to just avoid having to deal with the open-source community
entirely by using forks.

However, that does not benefit the community and allows a "one-way" street,
with companies "profiting" from open-source software (in this example,
they would profit unwillingly, yet out of the necessity to avoid dealing
with outside 'restrictions' perceived as unnecessary).

It seems it is a similar case to that of allowing or not binary
drivers/blobs.
If they were not allowed, less companies would choose Linux.
I don't want to go into that discussion, but it seems similar enough to
this one for it to be worth mentioning.

> If there's data which has no consumer, it has no value being in the DT.
> Placing data with no consumer in the DT comes with a number of issues,
> e.g.
> 
> a) Some DTS authors will ignore it, and not place data according to it
>    in DTs. Hence there's no gain in consistency.

Ok, but in this case the DT author (SoC manufacturer) would have interest
in using it.

> 
> b) Though some accident (perhaps a typo, perhaps a misunderstanding of
>    the binding), a DT will come to have erroneous data, yet this will go
>    unnoticed, as there is no consumer. When later a consumer appears, it
>    can't trust existing DTs, and has to either ignore the binding
>    entirely, or bodge around each and every broken DT.
> 

I think it is likely this has already happened, even with the current
constraints on review.

> c) When a consumer eventually appears, it turned out we didn't capture
>    details of the hardware sufficiently, and the binding turns out to be
>    useless. At worst, this boils down to (b), at best, we require
>    additional properties. In this case absolutely nothing is gained.

Case c) could happen even when a driver is provided, for example if the
driver writer got incomplete documentation.

At any rate, since there was no user, even if the bindings need amending,
it should be easy to do, since there's no backwards compatibility to keep.

> In all cases, all we end up doing is enlarging DTBs, and risk causing
> even more work.
> 
> If there *is* going to be a consumer, and if information regarding that
> will be provided, then matters are different, and we can consider a
> binding on its own merit. We need a specific example for that.
> 
>> If the "user of the binding" is not Linux, under what circumstances
>> could "Linux" have the legitimacy of guaranteeing or enforcing any Linux-
>> specific commitment?
> 
> To at least the extent that if someone says they're not going to bother,
> we clearly have no reason to bother supporting them.

I have the impression that this basically means that DT is Linux only.
Did I misunderstood?

What legitimacy does Linux expects to have when dealing with bindings whose
users are not Linux? For example, FreeBSD, U-Boot or others.
In other words, why would Linux usage and policies regarding DT have to affect
other users of DT?

That essentially limits DT usage;
Of course, it can be forked, etc. like you state below, but that is not the
best outcome for everybody, because this basically forces the use of
undocumented binary DT overlays.

> Note that *nothing* stops you from using the DT container format for
> your own purposes, in violation of every binding and rule we have.
> However, for those cases we clearly won't document them as the standard
> mechanism.

Yes, I'm aware of that possibility, but in that case we would not be having
this conversation :-)

Basically, IMHO there is no reason for this thing to be black or white when
it could be gray and have a win-win situation, that's all.

> There are other things build atop of the DTB format, e.g. FIT, which
> aren't quite devicetree in the usual sense.
> 
>>> I understand that goal, and I've asked for a specific example, as this
>>> is not clear-cut. e.g. there has been work on describing secure devices
>>> for QEMU, but this isn't necessarily something we want to expose Linux
>>> to in general.
>>
>> Interesting, do you know where in QEMU's code should I look for that?
> 
> Documentation/devicetree/bindings/arm/secure.txt for the basics.
> 
> Generally, I'd expect that even if the secure OS were using DT in this
> fashion, the non-secure general purpose OS would be handed a DT
> containing only the non-secure world portions.
> 

I see that you did not comment on my example, was that intended?

>> IMHO, they apply only when there's a Linux driver, or any other public
>> user of such bindings. But if there's no user, it seems like an unnecessary
>> constraint.
> 
> If there's no user, there's no need for the binding.

But you said earlier that bindings for users different from Linux are considered.
Did I miss something?

> If there's some user somewhere, and that user wants the binding
> rubber-stamped as an "official" binding, they need to follow the usual
> rules for bindings.
> 
> If there is a user, and they don't want to follow the usual rules,
> there's no point trying to get the binding rubber-stamped.

I understand, but nothing prevents the creation of DT 'sections':
- a section using rubber-stamped "official" bindings
- a section using 'staging' bindings
right?
What technical issues would this have?

Best regards,

Sebastian

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Sebastian Frias]

Hi Mark,

On 09/13/2016 03:12 PM, Mark Rutland wrote:
>> Exactly, that is why I was thinking it would take less "review" time.
>> Indeed, if there is no driver, why would it matter what those bindings
>> are?
> 
> If you believe that the bindings don't matter, then there is absolutely
> no reason for them to exist in the first place.
> 
> If those binding matter to *anyone*, then those collating the bindings
> have some responsibility of stewardship, and that includes
> review/maintenance/etc.

The thing is that right now it seems the "responsibility of stewardship"
lies only within "Linux", whereas DT is proposed as open for everybody,
Bootloaders, FreeBSD, etc.

In that case, shouldn't the "responsibility" be shared?
Alternatively, maybe 'borders' could be created, in order to enable the
allocation of responsibility of different sections to different parties,
right?
Obviously, moving properties/nodes from one 'section' to another crossing
responsibility 'borders' would require agreements.

Shouldn't that be something good to think about?

Best regards,

Sebastian

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Mark Rutland]

On Tue, Sep 13, 2016 at 04:55:59PM +0200, Sebastian Frias wrote:
> On 09/13/2016 03:12 PM, Mark Rutland wrote:
> >> Exactly, that is why I was thinking it would take less "review" time.
> >> Indeed, if there is no driver, why would it matter what those bindings
> >> are?
> > 
> > If you believe that the bindings don't matter, then there is absolutely
> > no reason for them to exist in the first place.
> > 
> > If those binding matter to *anyone*, then those collating the bindings
> > have some responsibility of stewardship, and that includes
> > review/maintenance/etc.
> 
> The thing is that right now it seems the "responsibility of stewardship"
> lies only within "Linux", whereas DT is proposed as open for everybody,
> Bootloaders, FreeBSD, etc.
> 
> In that case, shouldn't the "responsibility" be shared?

Ideally, yes.

Which is one of the reasons devicetree.org was set up as a common forum
for projects to collaborate on devicetree.

Thanks,
Mark.

Re: ARM, SoC: About the use DT-defined properties by 3rd-party drivers

[Sebastian Frias]

Hi Mark,

On 09/13/2016 05:47 PM, Mark Rutland wrote:
>>> If you believe that the bindings don't matter, then there is absolutely
>>> no reason for them to exist in the first place.
>>>
>>> If those binding matter to *anyone*, then those collating the bindings
>>> have some responsibility of stewardship, and that includes
>>> review/maintenance/etc.
>>
>> The thing is that right now it seems the "responsibility of stewardship"
>> lies only within "Linux", whereas DT is proposed as open for everybody,
>> Bootloaders, FreeBSD, etc.
>>
>> In that case, shouldn't the "responsibility" be shared?
> 
> Ideally, yes.
> 
> Which is one of the reasons devicetree.org was set up as a common forum
> for projects to collaborate on devicetree.

I see, what about using different 'sections' on a DT to allow different
parties be responsible for their 'section'?

- 'generic' sections (i.e.: those using bindings used by Linux drivers)
would be under stewardship of Linux.

- 'specific' sections (i.e.: my example, bindings *not used by Linux*, but
they could be bindings for other OSs as you said) would be under a
different stewardship.

DT seems essentially free-form, like XML.
One could imagine that some tool could then be used to guarantee that
some parts of DT conform to a given XML schema, including backwards
compatibility, while at the same time ignoring 'staging'/'specific' stuff.

NOTE: this appears to be possible using 'overlays' as Warner suggested, but
in that case not all parts are public, which limits public information.

Best regards,

Sebastian