In the three documents that follow, we lay out a process for defining the use cases of device properties returned by the ACPI _DSD (Device Specific Data) object in Data Structures associated with the Device Properties UUID [0] and the Hierarchical Properties Extension UUID [1]. The term "_DSD device properties" below refers to the data formats associated with those two UUIDs only. All other UUIDs used with _DSD are outside the scope of what is described here. The goal of these documents is to: (1) make clear to OS vendors which of the use cases of _DSD device properties need to be supported; (2) be clear on what those use cases should mean to the OS; and, (3) have all OSs use the same definitions for those use cases. The first document describes basic context and essential terminology for the process of submitting a use case for the _DSD device properties to a central location so that it can be reviewed and tracked. The next document describes a database for storing the use cases of _DSD device properties that have been reviewed and agreed upon. The idea is to make this database publicly available so that OS developers and firmware creators can easily see what is already defined, what is in use, and what is not defined. The final document provides a formal language for describing the use cases of _DSD device properties. The goal is to make it relatively easy to define new use cases of the _DSD device properties, by stating clearly what those definitions must look like. This also makes building automated tools easier, allowing us to keep the process simpler, permit validation of the content, assist with documentation, and perform basic record keeping. A copy of the ChangeLog is also attached so that you can see what the primary changes were for this second version. Why should you care? If you write ACPI firmware, you may need to provide a _DSD object; if you decide to create your own UUID, you will need to clearly document the content returned by your _DSD UUID so that an OS can use it properly. However, if you need to use _DSD device properties, the documents here are intended to make it clear what needs to be done so that use cases are documented and consistent for all OSs. If you work with OS drivers using ACPI, you may need to consult one of the use cases of the _DSD device properties. What these documents lay out is a standard mechanism for describing these use cases, independent of OS, with a uniform way to determine what is available, and what their values are. Ideally, there would be no need to reverse engineer, or worse, guess at, the device properties available for a specific device. Finally, we hope to arrive at a time when OS changes requiring use cases in the _DSD device properties do not get accepted unless they have been registered and documented as described here. We want to get to the point where use cases of _DSD device properties are unambiguous, well documented, visible to all who need them, and usable across any number of OSs. If you have any comments, improvements or suggestions, let us know. We believe the basic content is sound, but more eyes are always better. We would also like to have this process up and running by August; it has been postponed far too long as it is. Comment here, or if you would rather, you can find the documents on github and suggest patches there: https://github.com/ahs3/dsd/tree/master/documentation Thanks. 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; Mark Doran <mark.doran(a)intel.com&gt; Rafael Wysocki <rafael.j.wysocki(a)intel.com&gt; Robert Gough <robert.gough(a)intel.com&gt; (...my apologies if anyone has not been mentioned...) References: [0] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-U UID.pdf [1] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-e xtension-UUID-v1.pdf -- ciao, al ----------------------------------- Al Stone Software Engineer Red Hat, Inc. ahs3(a)redhat.com -----------------------------------

I’ve reviewed the intervening commits on github and the changelog. All the changes look good to me. I do recall a discussion about coming up with a better way to discuss “inheritance” since the term is burdened with language specific semantics and will likely be a cause for confusion. Do you have a change in the works for that?

The revision string appears to be inconsistent. It states it must use a numeric value commonly used in the C language, but the example uses strings with multiple decimal points, such as 1.3.1… which to my knowledge is not valid C syntax (gcc concurs).

In the three documents that follow, we lay out a process for defining the use cases of device properties returned by the ACPI _DSD (Device Specific Data) object in Data Structures associated with the Device Properties UUID [0] and the Hierarchical Properties Extension UUID [1]. The term "_DSD device properties" below refers to the data formats associated with those two UUIDs only. All other UUIDs used with _DSD are outside the scope of what is described here. The goal of these documents is to: (1) make clear to OS vendors which of the use cases of _DSD device properties need to be supported; (2) be clear on what those use cases should mean to the OS; and, (3) have all OSs use the same definitions for those use cases. The first document describes basic context and essential terminology for the process of submitting a use case for the _DSD device properties to a central location so that it can be reviewed and tracked. The next document describes a database for storing the use cases of _DSD device properties that have been reviewed and agreed upon. The idea is to make this database publicly available so that OS developers and firmware creators can easily see what is already defined, what is in use, and what is not defined. The final document provides a formal language for describing the use cases of _DSD device properties. The goal is to make it relatively easy to define new use cases of the _DSD device properties, by stating clearly what those definitions must look like. This also makes building automated tools easier, allowing us to keep the process simpler, permit validation of the content, assist with documentation, and perform basic record keeping. A copy of the ChangeLog is also attached so that you can see what the primary changes were for this second version. Why should you care? If you write ACPI firmware, you may need to provide a _DSD object; if you decide to create your own UUID, you will need to clearly document the content returned by your _DSD UUID so that an OS can use it properly. However, if you need to use _DSD device properties, the documents here are intended to make it clear what needs to be done so that use cases are documented and consistent for all OSs. If you work with OS drivers using ACPI, you may need to consult one of the use cases of the _DSD device properties. What these documents lay out is a standard mechanism for describing these use cases, independent of OS, with a uniform way to determine what is available, and what their values are. Ideally, there would be no need to reverse engineer, or worse, guess at, the device properties available for a specific device. Finally, we hope to arrive at a time when OS changes requiring use cases in the _DSD device properties do not get accepted unless they have been registered and documented as described here. We want to get to the point where use cases of _DSD device properties are unambiguous, well documented, visible to all who need them, and usable across any number of OSs. If you have any comments, improvements or suggestions, let us know. We believe the basic content is sound, but more eyes are always better. We would also like to have this process up and running by August; it has been postponed far too long as it is. Comment here, or if you would rather, you can find the documents on github and suggest patches there: https://github.com/ahs3/dsd/tree/master/documentation Thanks. 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; Mark Doran <mark.doran(a)intel.com&gt; Rafael Wysocki <rafael.j.wysocki(a)intel.com&gt; Robert Gough <robert.gough(a)intel.com&gt; (...my apologies if anyone has not been mentioned...) References: [0] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-... [1] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-... -- ciao, al ----------------------------------- Al Stone Software Engineer Red Hat, Inc. ahs3(a)redhat.com -----------------------------------

In the three documents that follow, we lay out a process for defining the use cases of device properties returned by the ACPI _DSD (Device Specific Data) object in Data Structures associated with the Device Properties UUID [0] and the Hierarchical Properties Extension UUID [1]. The term "_DSD device properties" below refers to the data formats associated with those two UUIDs only. All other UUIDs used with _DSD are outside the scope of what is described here. The goal of these documents is to: (1) make clear to OS vendors which of the use cases of _DSD device properties need to be supported; (2) be clear on what those use cases should mean to the OS; and, (3) have all OSs use the same definitions for those use cases. The first document describes basic context and essential terminology for the process of submitting a use case for the _DSD device properties to a central location so that it can be reviewed and tracked. The next document describes a database for storing the use cases of _DSD device properties that have been reviewed and agreed upon. The idea is to make this database publicly available so that OS developers and firmware creators can easily see what is already defined, what is in use, and what is not defined. The final document provides a formal language for describing the use cases of _DSD device properties. The goal is to make it relatively easy to define new use cases of the _DSD device properties, by stating clearly what those definitions must look like. This also makes building automated tools easier, allowing us to keep the process simpler, permit validation of the content, assist with documentation, and perform basic record keeping. A copy of the ChangeLog is also attached so that you can see what the primary changes were for this second version. Why should you care? If you write ACPI firmware, you may need to provide a _DSD object; if you decide to create your own UUID, you will need to clearly document the content returned by your _DSD UUID so that an OS can use it properly. However, if you need to use _DSD device properties, the documents here are intended to make it clear what needs to be done so that use cases are documented and consistent for all OSs. If you work with OS drivers using ACPI, you may need to consult one of the use cases of the _DSD device properties. What these documents lay out is a standard mechanism for describing these use cases, independent of OS, with a uniform way to determine what is available, and what their values are. Ideally, there would be no need to reverse engineer, or worse, guess at, the device properties available for a specific device. Finally, we hope to arrive at a time when OS changes requiring use cases in the _DSD device properties do not get accepted unless they have been registered and documented as described here. We want to get to the point where use cases of _DSD device properties are unambiguous, well documented, visible to all who need them, and usable across any number of OSs. If you have any comments, improvements or suggestions, let us know. We believe the basic content is sound, but more eyes are always better. We would also like to have this process up and running by August; it has been postponed far too long as it is. Comment here, or if you would rather, you can find the documents on github and suggest patches there: https://github.com/ahs3/dsd/tree/master/documentation Thanks. 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; Mark Doran <mark.doran(a)intel.com&gt; Rafael Wysocki <rafael.j.wysocki(a)intel.com&gt; Robert Gough <robert.gough(a)intel.com&gt; (...my apologies if anyone has not been mentioned...) References: [0] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-... [1] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-... -- ciao, al ----------------------------------- Al Stone Software Engineer Red Hat, Inc. ahs3(a)redhat.com -----------------------------------

On 8/13/2016 1:31 AM, Hart, Darren wrote: > One more comment for 0002-database-rules (and I’ll send a patch at least to the TODO file for these two I have outstanding). > > Section 2.2 Inheritance is problematic in my opinion. > > On the one hand, it says : > > “However, if two > or more base sets contain a property with the same key, the derived set > inherits the property from the first base set listed in the definition > of the property.” > > But goes on to say: > > “Direct definitions of properties in the derived set cannot override > any properties inherited from the base sets.” > > But the workaround to this is to simply include a set that has the override you want. > > Instead of (this doesn’t follow the formal language, but gives the idea): > > A: > foo=”bar” > > C: > Inherit A > foo=Package{1,2,3,4} > > Where A also defines foo, so C is illegally override it, you would do: > > B: > foo=Package{1,2,3,4} > > C: > Inherit A > Inherit B > > Now C overrides Apple from A. So the rules do a poor job of enforcing the intent. > > I suggest we either: > > 1) Forbid overriding, inheritance must be of disjoint property sets (no overlapping properties), which in turn means that order of inclusion no longer matters. > 2) Allow overriding in the property set definition itself and change the rules to use the LAST definition of a property, rather than the first. > > I personally prefer #1. It’s simpler. That's correct, but it may be practically inconvenient, for example when two sets you want to inherit have one property in common. That may be addressed, though, by requiring that any overlapping properties in the inherited sets must be identical. > It also matches what will happen with the OS driver (unless we want to see a host of quirks for every overridden property of a common set). > > I’d appreciate your thoughts everyone before I submit the TODO patch. > I think we can go for #1 with the above modification, unless you see a problem with it.

On 08/12/2016 05:51 PM, Hart, Darren wrote: > > On 8/12/16, 4:39 PM, "Wysocki, Rafael J" <rafael.j.wysocki(a)intel.com&gt; wrote: > >> On 8/13/2016 1:31 AM, Hart, Darren wrote: >>> One more comment for 0002-database-rules (and I’ll send a patch at least to the TODO file for these two I have outstanding). >>> >>> Section 2.2 Inheritance is problematic in my opinion. >>> >>> On the one hand, it says : >>> >>> “However, if two >>> or more base sets contain a property with the same key, the derived set >>> inherits the property from the first base set listed in the definition >>> of the property.” >>> >>> But goes on to say: >>> >>> “Direct definitions of properties in the derived set cannot override >>> any properties inherited from the base sets.” >>> >>> But the workaround to this is to simply include a set that has the override you want. >>> >>> Instead of (this doesn’t follow the formal language, but gives the idea): >>> >>> A: >>> foo=”bar” >>> >>> C: >>> Inherit A >>> foo=Package{1,2,3,4} >>> >>> Where A also defines foo, so C is illegally override it, you would do: >>> >>> B: >>> foo=Package{1,2,3,4} >>> >>> C: >>> Inherit A >>> Inherit B >>> >>> Now C overrides Apple from A. So the rules do a poor job of enforcing the intent. >>> >>> I suggest we either: >>> >>> 1) Forbid overriding, inheritance must be of disjoint property sets (no overlapping properties), which in turn means that order of inclusion no longer matters. >>> 2) Allow overriding in the property set definition itself and change the rules to use the LAST definition of a property, rather than the first. >>> >>> I personally prefer #1. It’s simpler. >> >> That's correct, but it may be practically inconvenient, for example when >> two sets you want to inherit have one property in common. >> >> That may be addressed, though, by requiring that any overlapping >> properties in the inherited sets must be identical. >> >>> It also matches what will happen with the OS driver (unless we want to see a host of quirks for every overridden property of a common set). >>> >>> I’d appreciate your thoughts everyone before I submit the TODO patch. >>> >> >> I think we can go for #1 with the above modification, unless you see a >> problem with it. > > That seems reasonable to me. > Sorry for the delayed reply.... I'd prefer #1 also. Whether or not that is practical is a different question, and I think some experience with this over time will provide us the right answer. But, let's try it for now and see if becomes a limitation or not.