We have been discussing this on the Intel side. We will have some material ready to help guide a discussion on this topic in next week's ASWG meeting. Thanks Vincent

On Aug 28, 2015, at 9:52 AM, Zhang, Jonathan Zhixiong <zjzhang(a)quicinc.com&gt; wrote: >> From: Al Stone [mailto:astone@redhat.com] >> Sent: Friday, August 28, 2015 8:34 AM >>> On 08/27/2015 06:38 PM, Rafael J. Wysocki wrote: >>>> On 8/28/2015 1:46 AM, Zhang, Jonathan Zhixiong wrote: >>>> >>>>> -----Original Message----- >>>>> From: aswg(a)uefi.org [mailto:aswg@uefi.org] On Behalf Of Al Stone >>>>> Sent: Monday, August 24, 2015 10:50 AM [...] Please see the git tree >>>>> at https://github.com/ahs3/dsd. This may or may not be the right >>>>> long term place to host it, but the README describes the idea -- >>>>> I've written a tool that uses simple YAML to describe device >>>>> properties. The tool can verify that all the right things are >>>>> documented, and allows one to build a data base -- of plain >>>>> human-readable ASCII YAML -- that anyone can visit, peruse, or offer >>>>> updates to. >>>>> >>>>> The YAML is probably not complete; however, the key thing is that >>>>> this is completely open source, under a very permissive license, and >>>>> easily seen or used by developers of any OS or any bit of firmware >>>>> -- the neutral location and open license means equal use and access >>>>> for Microsoft, Linux, and the firmware writers. Patches are of >>>>> course welcome -- to the tool, or even the data base of device property >> descriptions. >>>> [Jonathan] To make such YAML schema becomes THE de-facto one, it >>>> would be great to be able to translate/validate it from and into the >>>> local expressions, such as Linux documentation; and we could have >>>> such translation/validation happening on a frequent regular basis. >>> >>> I'm not sure what you mean really. >>> >>> Having a single definitive source of property bindings, why would we >>> need any extra documentation of them anywhere else? >> >> If one wanted a different format than YAML for some reason, it would be >> easy enough to do -- that's what the command "dsd simple-text" does, for >> example. >> That being said, though, I only see that as being useful in preparing other >> documentation of some sort -- perhaps for books or articles or something >> where YAML is not easily read -- and would expect the formal language to be >> the only authoritative form. >> >> The analogy in my mind is that I can tell you that www.google.com has an IP >> address of 216.58.217.36, which some may find easier to read than the more >> formal description in a BIND database. The former is easier to understand, >> perhaps, but the latter is authoritative. > There are two options for us to populate the DSD DB: > a). Only add property binding upon request to dsd(a)apcica.org and after approval. > b). In addition to option a, also add property bindings that either are existing (some > may come from DT bindings when makes sense), or have become the fact (for > example in Linux, the driver code supporting new property binding was accepted > in upstream). > > From the correspondences, sounds like option a) is chosen. There is a good chance > for option a) to work out, I certainly hope so and believe so. That being said, its success > depends on how well the process is socialized and accepted by the community. > Challenge for us is that how to convince "the community"; a portion of > "the community" are not in the discussion yet. > >>>>> So, if one sends the type of YAML expected to dsd(a)acpica.org, I can >>>>> easily pull it in, verify it, and push it back out to github, >>>>> assuming it's reasonably correct and usable. If we can agree that >>>>> all discussions about the acceptability of any particular device >>>>> property occurs on dsd(a)acpica.org, we can get this process moving >>>>> and documented, and change the discussion to be about specific >>>>> device properties instead. >>>> [Jonathan] Ditto! >>>> >>>>> [...] The dsd command uses basic YAML formatting (so, spaces for >>>>> indentation, then indentation for indicating structure) and >>>>> currently recognizes the following >>>>> keywords: >>>>> >>>>> property: <name> >>>>> >>>>> owner: <string> >>>>> >>>>> type: integer | >>>>> hexadecimal-integer | >>>>> hexadecimal-address-package | >>>>> string | >>>>> <type> <value-list> >>>>> >>>>> description: <free text> >>>>> >>>>> example: <free text> >>>> [Jonathan] In order to understand the status (proposed, adopted, >>>> deprecated, >>>> etc.) of a property, >>> >>> From experience, this is not practical. Once a binding is in the >>> database, we must assume that someone's using it and it has to be >>> supported going forward in any case. >>> >>>> I think it is good to add a "status" property. Likewise, what about a >>>> "compatibility" property documenting what version(s) of which OS >>>> supports it? >>> >>> That in turn is not practical for things like Linux, because it is a >>> moving target with a mainline release every 9-10 weeks, all of the >>> "stable" branches, enterprise vendor kernels end so on. >>> >>> Thanks, >>> Rafael >> >> I agree with Rafael here. I believe the process has to be that the description >> gets reviewed, and once accepted goes into the official db. Until then, it is >> not supported, but a topic under discussion. Adding info about what version >> of the OS supports the property or device is only really useful, IMHO, if it can >> be kept up-to-date; unfortunately, that seldom happens so the info >> becomes useless almost as soon as it is written down. The basic premise of >> this db of info is much more straightforward: if you are going to support the >> _DSD device property UUID, these are the device properties that need to be >> supported. > I agree with your points that the db should only contain device properties that > are currently agreed, Rafael/Al. I think we also need to solve following concerns: > > 1. As a driver developer, my driver already supports the _DSD device property > UUID. A new property is then added to my device in the DB and my code supporting it > Is not publicly available yet. How can FW developer know about this situation? > > 2. As a driver developer, my driver already supports the _DSD device property > UUID. An existing property of my device is then removed/renamed in the DB and my > code supporting the change is not publicly available yet. How can FW developer > know about this situation? >> >> -- >> ciao, >> al >> ----------------------------------- >> Al Stone >> Software Engineer >> Red Hat, Inc. >> ahs3(a)redhat.com >> -----------------------------------