> 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?

_______________________________________________ DSD mailing list DSD(a)acpica.org https://lists.acpica.org/mailman/listinfo/dsd