[PATCH v4] dt: update PSCI binding documentation for v0.2

On Wed, Sep 25, 2013 at 2:34 PM, Olof Johansson [off-list ref] wrote:

On Wed, Sep 25, 2013 at 12:20 PM, Rob Herring [off-list ref] wrote:

quoted

On Wed, Sep 25, 2013 at 12:15 PM, Olof Johansson [off-list ref] wrote:

quoted

On Fri, Sep 20, 2013 at 3:20 AM, Mark Rutland [off-list ref] wrote:

quoted

On Fri, Sep 20, 2013 at 05:36:51AM +0100, Olof Johansson wrote:

quoted

Hi,

Hi Olof,

quoted

Just a quick drive-by. Sorry, I don't know the history of previous
review cycles.


On Thu, Sep 19, 2013 at 2:24 PM, Rob Herring [off-list ref] wrote:

quoted

 Main node optional properties:

- - cpu_suspend   : Function ID for CPU_SUSPEND operation
+ - cpu_suspend[-<32|64]   : Function ID for CPU_SUSPEND operation
+
+ - cpu_off                : Function ID for CPU_OFF operation
+
+ - cpu_on[-<32|64]        : Function ID for CPU_ON operation
+
+ - affinity_info[-<32|64] : Function ID for AFFINITY_INFO operation

- - cpu_off       : Function ID for CPU_OFF operation
+ - migrate[-<32|64]       : Function ID for MIGRATE operation

- - cpu_on        : Function ID for CPU_ON operation
+ - migrate_info_type      : Function ID for MIGRATE_INFO_TYPE operation

- - migrate       : Function ID for MIGRATE operation
+ - migrate_info_up_cpu[-<32|64] : Function ID for MIGRATE_INFO_UP_CPU operation

+ - system_reset           : Function ID for SYSTEM_RESET operation
+
+ - system_off             : Function ID for SYSTEM_OFF operation

All of these should use dashes instead of underscores.

I also don't like the underscores, but they're an unfortunate historical
artifact that we can't get rid of (at least for cpu_on, cpu_off, and
cpu_suspend).

We need to keep those three old ones supported in the driver, but the
newer binding can use dashes instead, as long as the kernel also
handles the old binding.

quoted

Both Xen and kvmtool are already passing DTs to guests which have
underscores in the property names, so it's both a boot ABI and a
userspace ABI.

Again, as mentioned on IRC: We've said that bindings are not yet
stable until we lock them down, so we will need to adjust accordingly.
Once we lock them down, they are stable and part of ABI. But we really
don't want to deal with the bad bindings that people came up with
without much review, and that's what the whole idea behind cleaning up
and then locking them down is all about.

For some of us, bindings are already in production. Until we have some
way to document stable vs. unstable, it is not up to anyone but the
users of a binding to define the stability. If the users of a binding
can tolerate the change, then it is unstable and can change.

Ok, so why review bindings at all then? Just implement what you want,
ship it and force it on the rest of us for ever.

Dealing with 2 versions of PSCI bindings rather than simply extending
the existing binding will be more pain for the kernel, kvmtool, qemu
and xen than any benefit of using a hyphen will provide.

This binding was written by Will Deacon and acked by Arnd and Nicolas
not to mention the follow-up patches to use it over the last 9 months.
Hardly a bunch of newbies that don't understand DT. That binding had 3
postings. No one complained about the underscores then. It is
precisely because it has been reviewed that I don't think we should be
changing it. I don't see simply adding additional function ids as
grounds for redoing the binding. The 32/64 bit calling convention
handling may be a different discussion which is fine with me. Dealing
with that was not my goal here.

quoted

All this boils down to using '_' vs. '-', right? Come on. I'm all for
consistency, but let's be practical. There are plenty of documented
examples that use '_' starting with device_type.

Next property I add will be called Device_Type then, if we're willing
to not give a shit about best practices any more. Thanks for setting
the direction and holding the bar high, Rob!

That's fine, just mark it unstable and we can change it later. I'll
sit quiet for 9 months first and then complain about it. I'll be
waiting for your patch to change all the '_' to '-' in all the binding
docs and dts files. Since everything is unstable, that shouldn't be a
problem to change. :)

Rob