From: Al Stone [mailto:firstname.lastname@example.org]
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:email@example.com] 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
>> [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
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 184.108.40.206, 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
From the correspondences, sounds like option a) is chosen. There is a
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
>>> 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,
>> 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.
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
I agree with your points that the db should only contain device
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?
Red Hat, Inc.