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

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

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?