Thanks Al, With respect to 0001-process-rules: “8. Immutability of Registered Property Set Definitions ------------------------------------------------------ All property set definitions, once registered and in the database [2], are immutable. It is not possible to remove existing content from the database or to modify any of it in place. It only is possible to add new content. The only way in which one property set can be superseded by another one is to register a new revision of the property set in question. Moreover, when creating a new revision of a property set, it is invalid to redefine property keys (that is, associate them with different data types or give them different meaning). New revisions can only add properties to the set or remove them from it. If one of the properties in the current (most recent) revision of a property set is to be deprecated in the next revision, the correct way to do that is to remove it from the set entirely and define a new property with a new key as a replacement for it. … “ The wording “…or remove them from it” is problematic. In order to ensure backward compatibility, we need to ensure that new revisions do not remove required properties from previous revisions. The goal is for an older OS/driver that only knows about revision 1 to continue to function with revision 2 by using all the required fields, and ignoring the additional fields added by later revisions. I’d recommend we strike “ or remove them from it” from section 8.

On 6/28/16, 1:02 PM, "DSD on behalf of Al Stone" <dsd-bounces(a)acpica.org on behalf of ahs3(a)redhat.com&gt; wrote: > Contributors: > Al Stone <ahs3(a)redhat.com&gt; > Charles Garcia-Tobin <charles.garcia-tobin(a)arm.com&gt; > Darren Hart <darren.hart(a)intel.com&gt; > David Woodhouse <david.woodhouse(a)intel.com&gt; > Rafael Wysocki <rjw.rjwysocki.net> > (apologies if we're missing someone that should be on this list...) Hi Al, Would you please add Rob and Mark who have both contributed significantly to this effort? Robert Gough <robert.gough(a)intel.com&gt; Doran, Mark <mark.doran(a)intel.com&gt;

On 6/28/16, 1:02 PM, "DSD on behalf of Al Stone" <dsd-bounces(a)acpica.org on behalf of ahs3(a)redhat.com&gt; wrote: > Contributors: > Al Stone <ahs3(a)redhat.com&gt; > Charles Garcia-Tobin <charles.garcia-tobin(a)arm.com&gt; > Darren Hart <darren.hart(a)intel.com&gt; > David Woodhouse <david.woodhouse(a)intel.com&gt; > Rafael Wysocki <rjw.rjwysocki.net> > (apologies if we're missing someone that should be on this list...) Hi Al, Would you please add Rob and Mark who have both contributed significantly to this effort? Robert Gough <robert.gough(a)intel.com&gt; Doran, Mark <mark.doran(a)intel.com&gt;

On Tue, Jun 28, 2016 at 02:02:02PM -0600, Al Stone wrote: > 4. Who Can Register Property Sets --------------------------------- > Since it is required to bind property sets to Device IDs, they can only > be registered by the owners of those Device IDs or by their authorized > representatives. > > A request to register a property set for a given Device ID is equivalent > to the statement: "I endorse the use of this set of properties with > devices identified by that Device ID". With my OS vendor hat on I would expect this to have a negative impact on the value of the database - it requires active engagement on the part of device vendors which (especially in the early stages of adoption) may not be forthcoming. The less likely an OS vendor is to look at the database the less likely people are to push things in so we might end up in a vicious cycle here. On the other hand I can see value in having vendor blessed bindings identified, perhaps we can have two databases here one for community contributed bindings and one for bindings that the vendor has blessed?

There also seems to be a bit of an issue with the unfortunate habit we see for device IDs to get assigned by board vendors rather than device vendors, the people registering the IDs may not be the people doing the software for the devices (look at all the random audio devices with Intel IDs for example).

> 4. Immutability of Registered Property Set Definitions > ------------------------------------------------------ All property set > definitions, once registered and in the database, are immutable. It is > not possible to remove existing content from the database or to modify > any of it in place. It only is possible to add new content. > The only way in which one property set can be superseded by another one > is to register a new revision of the property set in question and put it > into a new revision directory as described in above. > When creating a new revision of a property set, it is invalid to > redefine property keys (that is, associate them with different data types > or give them different meaning). New revisions can only add properties > to the set or remove them from it. A property set will be considered > deprecated if and only if the key no longer appears in the most recent > revision. This appears to preclude any kind of errata or clarification being added to an existing property which is something I can see people needing to do if for example a driver bug becomes widely relied upon in the wild. Perhaps we can have a modifiable place to put notes separately to the property set definitions themselves?

On Wed, Jun 29, 2016 at 01:18:19PM -0600, Al Stone wrote: > On 06/29/2016 11:25 AM, Mark Brown wrote: >> On Tue, Jun 28, 2016 at 02:02:02PM -0600, Al Stone wrote: > Would it be sufficient to be able to mark a property set as either: (a) > approved in the proper manner, or (b) approved by an OS vendor, or (c) > discovered by chance? There may be other classes in there somewhere. Works for me. >> There also seems to be a bit of an issue with the unfortunate habit we see >> for device IDs to get assigned by board vendors rather than device >> vendors, the people registering the IDs may not be the people doing the >> software for the devices (look at all the random audio devices with Intel >> IDs for example). > Hrm. I agree this is a problem. Can we solve it, however? Or, what can > we do to encourage things to head in the direction we would like? Perhaps allow silicon vendors to always define bindings for their devices? That seems to be the main case here. >>> 4. Immutability of Registered Property Set Definitions >>> ------------------------------------------------------ All property set >>> definitions, once registered and in the database, are immutable. It is >>> not possible to remove existing content from the database or to modify >>> any of it in place. It only is possible to add new content. >>> The only way in which one property set can be superseded by another one >>> is to register a new revision of the property set in question and put it >>> into a new revision directory as described in above. >>> When creating a new revision of a property set, it is invalid to >>> redefine property keys (that is, associate them with different data types >>> or give them different meaning). New revisions can only add properties >>> to the set or remove them from it. A property set will be considered >>> deprecated if and only if the key no longer appears in the most recent >>> revision. >> This appears to preclude any kind of errata or clarification being added >> to an existing property which is something I can see people needing to do > I believe the thinking was that changes would imply a new version, regardless of > what the changes were -- new features, errata, succumbing to a misinterpretation > of what the property was supposed to be, or whatever the situation. Is that too > clunky? OTOH, perhaps we could figure out some sort of annotation of existing > entries that's relatively straightforward -- some sort of minor version, vs a > major version or something. My reading of the text is that new versions are not allowed to modify existing properties at all (which come to think of it would also be an issue for things like adding new values to an enumeration).

On Fri, Jul 01, 2016 at 02:18:41AM +0200, Rafael J. Wysocki wrote: > The text clearly doesn't cover the cases when properties are defined along > with some limitations on the valid values (like a list of possible values, > bounds, ranges etc). Of course, it would make sense to allow changes of > those limitations to happen in new revisions of a property set, but that's > much different from redefining a property with a new data type. Right, that would be reasonable and sensible but the text needs to be clarified to say that since right now it looks like it prohibits any modification at all.

On 7/1/16, 8:04 AM, "DSD on behalf of Mark Brown" <dsd-bounces(a)acpica.org on behalf of broonie(a)kernel.org&gt; wrote:

>Right, that would be reasonable and sensible but the text needs to be >clarified to say that since right now it looks like it prohibits any >modification at all.

I’d argue it only makes sense to allow for restricting the data validation in new revisions, but not to extend it. Otherwise, old drivers may fail as they will expect the data to fit the previous revision’s validation rules.

On 7/7/16, 1:46 AM, "Mark Brown" <broonie(a)kernel.org&gt; wrote: > On Wed, Jul 06, 2016 at 05:47:13PM +0000, Hart, Darren wrote: >> On 7/1/16, 8:04 AM, "DSD on behalf of Mark Brown" <dsd-bounces(a)acpica.org on behalf of broonie(a)kernel.org&gt; wrote: > >>> Right, that would be reasonable and sensible but the text needs to be >>> clarified to say that since right now it looks like it prohibits any >>> modification at all. > >> I’d argue it only makes sense to allow for restricting the data >> validation in new revisions, but not to extend it. Otherwise, old >> drivers may fail as they will expect the data to fit the previous >> revision’s validation rules. > > That does seem like something which can be a guideline rather than a > strong rule, Am I the only one that read that in a pirate voice? ;-)

> depending on what the property is it might be possible to > cope fine if it's ignored - things like features that can improve > performance but aren't required for correctness. It does also seem like > it should be reasonable for people to require that new hardware has a > minimum OS version run on it if they're willing to take that hit. > > In general it'd be better to avoid changes of course but I'm not sure we > want to be that strict as the workarounds might be worse. I suppose the meaning of guideline vs. rule should be discussed. Ultimately, nothing we do here will prevent a vendor from shipping whatever they want if they choose to ignore these documents, and we’ll end up documenting it as a discovered property set even if they don’t submit it. In that sense, everything here is a guideline. When there is a high likelihood of breaking compatibility, we should make a strong recommendation against it – which is about as close to a rule as I think we can get.

On 7/7/16, 11:34 AM, "Al Stone" <al.stone(a)linaro.org&gt; wrote: > On 07/07/2016 11:12 AM, Hart, Darren wrote: >> >> On 7/7/16, 1:46 AM, "Mark Brown" <broonie(a)kernel.org&gt; wrote: >> >>> On Wed, Jul 06, 2016 at 05:47:13PM +0000, Hart, Darren wrote: >>>> On 7/1/16, 8:04 AM, "DSD on behalf of Mark Brown" <dsd-bounces(a)acpica.org on behalf of broonie(a)kernel.org&gt; wrote: >>> >>>>> Right, that would be reasonable and sensible but the text needs to be >>>>> clarified to say that since right now it looks like it prohibits any >>>>> modification at all. >>> >>>> I’d argue it only makes sense to allow for restricting the data >>>> validation in new revisions, but not to extend it. Otherwise, old >>>> drivers may fail as they will expect the data to fit the previous >>>> revision’s validation rules. >>> >>> That does seem like something which can be a guideline rather than a >>> strong rule, >> >> Am I the only one that read that in a pirate voice? ;-) > > Yes, but maybe you just have better meds than the rest of us :-D. > >>> depending on what the property is it might be possible to >>> cope fine if it's ignored - things like features that can improve >>> performance but aren't required for correctness. It does also seem like >>> it should be reasonable for people to require that new hardware has a >>> minimum OS version run on it if they're willing to take that hit. >>> >>> In general it'd be better to avoid changes of course but I'm not sure we >>> want to be that strict as the workarounds might be worse. >> >> I suppose the meaning of guideline vs. rule should be discussed. Ultimately, >> nothing we do here will prevent a vendor from shipping whatever they want if >> they choose to ignore these documents, and we’ll end up documenting it as a >> discovered property set even if they don’t submit it. In that sense, everything >> here is a guideline. When there is a high likelihood of breaking compatibility, >> we should make a strong recommendation against it – which is about as close >> to a rule as I think we can get. > > Correct, the nihilistic point of view is that we cannot force anything to > happen :). I think of this sort of documentation as describing what we will > accept as reasonable, and there will always be exceptions. As in: you can do > whatever you want, Mr/Ms Firmware Writer Person, but don't expect us to pat you > on the back and shake your hand if you give us junk. > > That being said, let me see if I can paraphrase where this part of the > discussion has concluded, and what the amendments to the text need to say: > > (1) *No* changes to an accepted property set is too strict. > > (2) Changes to a property set are only allowed in new revisions. > > (3) Changes to an accepted property set are allowed if either: > > (a) The change is an obvious typographical error, or, > > (b) The change is an erratum, meant to correct the property set > so that it accurately reflects shipping firmware, or, > > (c) The change extends the range of possible values for a property, > but does not change the types of values, or impose a smaller > range of values. > > Is that the gist of what the re-write of this paragraph/section should say? > c) could be construed in a couple of ways, with the last clause is a can-do or a can’t do.

My position was that the document should state changes to existing properties data validation rules can only make them more strict to ensure backwards compatibility. To extend the data validation to accept more values would break older OSes that only knew about the previous schema. I agree with Charles’ interpretation that a new property should be introduced instead of extending the data validation. Mark B. points out that there may be cases where extending the property would not render the device non-functional, but perhaps only less performant, and in these cases, the backward compatibility argument is not as strong. I agree with both statements, but I believe it would be preferable to be more strict in the documentation so as to reduce the number of abuses that may occur if we over qualify the position. I’d be interested to hear from more people though.

On 7/7/2016 11:00 PM, Al Stone wrote: > On 07/07/2016 01:46 PM, Hart, Darren wrote: >> On 7/7/16, 11:34 AM, "Al Stone" <al.stone(a)linaro.org&gt; wrote: >> >>> On 07/07/2016 11:12 AM, Hart, Darren wrote: >>>> On 7/7/16, 1:46 AM, "Mark Brown" <broonie(a)kernel.org&gt; wrote: >>>> >>>>> On Wed, Jul 06, 2016 at 05:47:13PM +0000, Hart, Darren wrote: >>>>>> On 7/1/16, 8:04 AM, "DSD on behalf of Mark Brown" &gt;&gt;&gt;&gt;&gt;&gt;&lt;dsd-bounces(a)acpica.org on behalf of broonie(a)kernel.org&gt; wrote: >>>>>>> Right, that would be reasonable and sensible but the text needs >>>>>>>to be >>>>>>> clarified to say that since right now it looks like it prohibits >>>>>>>any >>>>>>> modification at all. >>>>>> I’d argue it only makes sense to allow for restricting the data >>>>>> validation in new revisions, but not to extend it. Otherwise, old >>>>>> drivers may fail as they will expect the data to fit the previous >>>>>> revision’s validation rules. >>>>> That does seem like something which can be a guideline rather than a >>>>> strong rule, >>>> Am I the only one that read that in a pirate voice? ;-) >>> Yes, but maybe you just have better meds than the rest of us :-D. >>> >>>>> depending on what the property is it might be possible to >>>>> cope fine if it's ignored - things like features that can improve >>>>> performance but aren't required for correctness. It does also seem >>>>>like >>>>> it should be reasonable for people to require that new hardware has >>>>>a >>>>> minimum OS version run on it if they're willing to take that hit. >>>>> >>>>> In general it'd be better to avoid changes of course but I'm not >>>>>sure we >>>>> want to be that strict as the workarounds might be worse. >>>> I suppose the meaning of guideline vs. rule should be discussed. >>>>Ultimately, >>>> nothing we do here will prevent a vendor from shipping whatever they >>>>want if >>>> they choose to ignore these documents, and we’ll end up documenting >>>>it as a >>>> discovered property set even if they don’t submit it. In that sense, >>>>everything >>>> here is a guideline. When there is a high likelihood of breaking >>>>compatibility, >>>> we should make a strong recommendation against it – which is about >>>>as close >>>> to a rule as I think we can get. >>> Correct, the nihilistic point of view is that we cannot force >>>anything to >>> happen :). I think of this sort of documentation as describing what >>>we will >>> accept as reasonable, and there will always be exceptions. As in: >>>you can do >>> whatever you want, Mr/Ms Firmware Writer Person, but don't expect us >>>to pat you >>> on the back and shake your hand if you give us junk. >>> >>> That being said, let me see if I can paraphrase where this part of the >>> discussion has concluded, and what the amendments to the text need to >>>say: >>> >>> (1) *No* changes to an accepted property set is too strict. >>> >>> (2) Changes to a property set are only allowed in new revisions. >>> >>> (3) Changes to an accepted property set are allowed if either: >>> >>> (a) The change is an obvious typographical error, or, >>> >>> (b) The change is an erratum, meant to correct the property set >>> so that it accurately reflects shipping firmware, or, >>> >>> (c) The change extends the range of possible values for a >>>property, >>> but does not change the types of values, or impose a >>>smaller >>> range of values. >>> >>> Is that the gist of what the re-write of this paragraph/section >>>should say? >>> >> c) could be construed in a couple of ways, with the last clause is a >>can-do or a can’t do. > Agreed. It needs some think time to be more precise. > >> My position was that the document should state changes to existing >>properties data validation rules can only make them more strict to >>ensure backwards compatibility. To extend the data validation to accept >>more values would break older OSes that only knew about the previous >>schema. I agree with Charles’ interpretation that a new property should >>be introduced instead of extending the data validation. >> >> Mark B. points out that there may be cases where extending the >>property would not render the device non-functional, but perhaps only >>less performant, and in these cases, the backward compatibility >>argument is not as strong. >> >> I agree with both statements, but I believe it would be preferable to >>be more strict in the documentation so as to reduce the number of >>abuses that may occur if we over qualify the position. I’d be >>interested to hear from more people though. >> > Okay. That's sort of why I paraphrased; I was hearing agreement on both > statements also -- and that's why (c) came out the way it did. > > Let's see what others say... > I agree with Darren.

Realistically, if I'm a driver and I receive an unexpected value for a property otherwise known to me, I'll be inclined to either ignore the property (if I can do without it) or bail out with an error. It is hard to say in principle which will be more prevalent, so to be on the safe side, the docs should assume the worse possibility. That is, "drivers will likely refuse to work in that case, so don't do that". Thanks, Rafael _______________________________________________ DSD mailing list DSD(a)acpica.org https://lists.acpica.org/mailman/listinfo/dsd

On Fri, Jul 08, 2016 at 09:00:38AM +0100, Charles Garcia-Tobin wrote: > On 07/07/2016 23:33, "DSD on behalf of Rafael J. Wysocki" >> On 7/7/2016 11:00 PM, Al Stone wrote: >>> On 07/07/2016 01:46 PM, Hart, Darren wrote: >>>> Mark B. points out that there may be cases where extending the >>>> property would not render the device non-functional, but perhaps >>>> only less performant, and in these cases, the backward >>>> compatibility argument is not as strong. Well, and also that there may be cases where a vendor makes a considered and reasonable decision that they don't want to support older software (this is something that people already do by for example upping the base version of the ACPI spec they need). >> I agree with Darren. > Ditto Having said that I do broadly agree as well, this is more of a thing I expect to practically happen and need handling after the fact rather than something I particularly think is a great idea. I think I'd only really support things like extensible enums if they were explicitly documented as such when created and some comment made about how to handle extensions.

There are a couple of items regarding the 0003-formal-language I’d like to address/discuss: 1) The <parent-sets> and <set-list> elements will need to define handing of circular references and multiple inclusion, maybe in a new section. What is the policy for

could be include the first time, ignore subsequent inclusions (like header

it to be invalid. Given we have minimal ability to change property sets, I

forgiving former definition, and to document best practice of avoiding circular

As for multiple includes (possibly through multiple inheritance): A is the base for B and C and D derives from B and C, A is included once, and B and C cannot otherwise

priority to resolve duplicate properties through inheritance since that is

a property type/data-validation, which we prohibit for backward-compatibility

2) There is no mention of hierarchical property sets in this document. I would recommend a directory for each, named with the key value. So for “Package(2) {“Alice”,

would be a subdirectory named “Alice”. However, this has a similar

as I’ve raised before, in that it’s possible that there is the possibility for

define DP0P to DPNP, each with the same set of properties. In this case,

in the property schema definition isn’t sufficient to document the 0-N usage.

On 7/7/2016 10:55 PM, Al Stone wrote: > On 07/06/2016 12:24 PM, Hart, Darren wrote: >> There are a couple of items regarding the 0003-formal-language I’d like to >> address/discuss: >> >> 1) The <parent-sets> and <set-list> elements will need to define handing of >> circular references >> and multiple inclusion, maybe in a new section. What is the policy for > circular inclusion? It >> could be include the first time, ignore subsequent inclusions (like header > gates) or we could define >> it to be invalid. Given we have minimal ability to change property sets, I > recommend the more >> forgiving former definition, and to document best practice of avoiding circular > includes. > > Interesting point. My inclination is to just ignore subsequent inclusions, and > mention that the circularity exists when found. I can't really see any use case > where doing more than that would be useful, but I am not omniscient, either. > >> As for multiple includes (possibly through multiple inheritance): A is the >> base for B and C and D >> derives from B and C, A is included once, and B and C cannot otherwise > conflict. We can’t use >> priority to resolve duplicate properties through inheritance since that is > equivalent to overriding >> a property type/data-validation, which we prohibit for backward-compatibility > reasons. > > I'm thinking "inheritance" may be the wrong term to use here; maybe we need > to rethink this part. > > I personally tend to overload "inheritance" with C++ or Python semantics, so > it's confusing to me. I think what we're really trying to do is define a > superset out of existing sets, so a better keyword may be "extends:" or, to > borrow from DT, "compatible:". > > Let me see if I can draw a little picture of the example so I can tell if I'm > understanding it properly: > > Set A > | > +-----+----+ <= derives-from: > | | > Set B Set C > | | > +-----+----+ <= derives-from: > | > Set D > > You can read this from top to bottom: Set D derives from B and C, which in > turn derive from A. I think the problem being described is that, if there > is a property "foo" in Set A, there is a "foo" in Set B and Set C. If Set D > derives from Sets B and C, which "foo" should be used? Is that the concern? The example need not be that complicated. It is sufficient if D derives from B and C and both define property "foo" (A is redundant).

> What we currently say in 0002-database-rules (section 2.2) for this case is > that Set D would use the first "foo" in the set list; for example: > > derives-from: B, C > > would use the foo from B, but: > > derives-from: C, B > > would use the foo from C. Further, the document currently says that if B, C > or D define "foo", those would override any existing definition. That feels > pretty messy for what we're trying to do -- especially the part about over- > riding the definition, so that part at least has to fixed in the doc. We seem to agree that the overriding part goes too far.

The ordering C, B vs B, C may be relevant, though. For one derived set, C may be the more important ancestor (in which case the "foo" from C should be present in that set), while for another one B may be more important. Basically, you can look at the B, C list as "I use all of the properties from B and also some (that are not in B) from C".

> So, apart from changing the terminology from inheritance to sets and extends, > which I recommend, we could clarify that everything is distinguished by full > path. If we do, then Set A defines A/foo, and Sets B and C have A/foo, too. > When Set D derives from A, there's no confusion since it just uses A/foo. When > providing the _DSD package ASL, maybe the full path is needed there, too. Well, what if B and C do not derive from a common ancestor and both define "foo"? Full paths don't help here I think.