[RFC DSD v2 00/04] How to Use the ACPI _DSD Device Properties UUIDs

[RFC DSD v2 00/04] How to Use the ACPI _DSD Device Properties UUIDs

[Al Stone]

[My apologies if this is a duplicate; operator error on my part]

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@redhat.com>
    Charles Garcia-Tobin <charles.garcia-tobin@arm.com>
    Darren Hart <darren.hart@intel.com>
    David Woodhouse <david.woodhouse@intel.com>
    Mark Doran <mark.doran@intel.com>
    Rafael Wysocki <rafael.j.wysocki@intel.com>
    Robert Gough <robert.gough@intel.com>
    (...my apologies if anyone has not been mentioned...)

References:
[0]
http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
[1]
http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.pdf


-- 
ciao,
al
-----------------------------------
Al Stone
Software Engineer
Red Hat, Inc.
ahs3@redhat.com
-----------------------------------

[RFC DSD v2 01/04] _DSD Property Registration Ruleset

[Al Stone]

_DSD Property Registration Ruleset
==================================
Dated:	2016-07-25
Status:	DRAFT


Contents
--------
1. Purpose
2. Properties, Property Sets and Property Subsets
3. What Can Be Registered
    3.1. Individual Properties Cannot Be Registered
    3.2. Device ID Requirement
    3.3. What Property Sets Are Eligible for Registration
4. Who Can Register Property Sets
5. How To Submit a Property Set for Registration
6. Review Process
7. Maintainers of the Database
8. Immutability of Registered Property Set Definitions
9. References
10. Contributors


1. Purpose
----------
This document specifies the rules regarding the registration and formal
definition of device properties to be used with the ACPI _DSD (Device
Specific Data) device configuration object along with the Device
Properties UUID, daffd814-6eba-4d8c-8a91-bc9bbf4aa301 [1].


2. Properties, Property Sets and Property Subsets
-------------------------------------------------
A device property is a data item consisting of a string key and a value
(of a specific type) associated with it.

In the ACPI _DSD context it is an element of the sub-package following
the Device Properties UUID in the _DSD return package as specified in
the Device Properties UUID definition document [1].

It also may be regarded as the definition of a key and the associated
data type that can be returned by _DSD in the Device Properties UUID
sub-package for a given device.  That is, what can be stored in the
database described for retaining a permanent record of these device
properties [2].

A property set is a collection of properties applicable to a hardware
entity like a device.  In the ACPI _DSD context it is the set of all
properties that can be returned in the Device Properties UUID sub-package
for the device in question.

Property subsets are nested collections of properties.  Each of them is
associated with an additional key (name) allowing the subset to be
referred to as a whole (and to be treated as a separate entity).  The
canonical representation of property subsets is via the mechanism
specified in the Hierarchical Properties Extension UUID definition
document [3].

Property sets may be hierarchical.  That is, a property set may contain
multiple property subsets that each may contain property subsets of its
own and so on.


3. What Can Be Registered
-------------------------
The goal of the registration of device properties is to make records of
what properties can be used with what devices.  That requires a way to
identify devices the properties are applicable to unambiguously and so
it implies that properties should be bound to Device IDs.

Moreover, in general, the interpretation of a single property may only
be meaningful if it is taken into consideration along with some other
properties applicable to the same device.  Thus every meaningful
property has to belong to a property set that can be related to a
specific device via its Device ID.

The above observations lead to the following rules:

3.1. Individual Properties Cannot Be Registered
-----------------------------------------------
The common device properties database [2] holds property sets, not
individual properties.

Even if the given property set consists of a single property, it still
has to be registered as a set.


3.2. Device ID Requirement
--------------------------
For every property set in the database, with the exception of property
sets created for the sole purpose of inheritance (see the section
entitled "Inheritance" below), there must be at least one Device ID
associated with it.  That can be a PNP or ACPI device ID, a device ID
that can be returned by the ACPI _CID object, a PCI Class Code that can
be returned by the ACPI _CLS object, or generally a device ID that can
be used by an Operating System to find a matching driver for the device.
In any case, it must be well defined in a way that is not OS-specific.


3.3. What Property Sets Are Eligible for Registration
-----------------------------------------------------
Property sets eligible for registration must follow the guidance given
by the Device Properties UUID definition document [1].

_DSD properties are intended to be used in addition to, and not instead
of, the existing mechanisms defined by the ACPI specification.
Therefore, as a rule, they should only be used if the ACPI specification
does not make direct provisions for handling the underlying use case.
Property sets that do not follow that rule generally cannot be registered.

[Note: Examples are given in [1].]


4. Who Can Register Property Sets
---------------------------------
Since it is required to bind property sets to Device IDs, they can only
be registered by the owners of those Device IDs or by their authorized
representatives.

A request to register a property set for a given Device ID is equivalent
to the statement: "I endorse the use of this set of properties with
devices identified by that Device ID".


5. How To Submit a Property Set for Registration
------------------------------------------------
Property sets are submitted for registration along with the Device IDs
they are associated with by sending an e-mail message to dsd@acpica.org
(public mailing list) and (optionally) to the maintainers of the common
device properties database [2].  The preferred format for the contents
of the e-mail message are described in [3].


6. Review Process
-----------------
The purpose of the device properties review process is to catch possible
problems with the submitted property sets before they are registered and
therefore avoid putting invalid content into the database [2].  This is
critical in light of the immutability of registered property sets as
described later in this document.

Submitted property sets can be reviewed by all of the subscribers of the
dsd@acpica.org mailing list and the reviewers' comments will only be taken
into consideration by the database maintainers if they are sent to that
list.

Generally, the comments should point out potential problems with the
submitted property set.  The only situation in which the submitter of a
property set may be requested to make changes to it is when there are
valid concerns about the material as submitted.  Review comments that
do not follow this rule will be discarded.

After a review period typically lasting between one to two weeks, the
database maintainers decide whether or not to include the property set
into the database and communicate their decision by sending an e-mail
message to the list.


7. Maintainers of The Database
------------------------------
The maintainership of the common database of device properties is a
service to the community of all of the existing users of it.

Maintainers are appointed by that community on a consensus basis.  They
must be generally trusted and possess sufficient industry experience to
be able to serve in their role effectively.


8. Immutability of Registered Property Set Definitions
------------------------------------------------------
All property set definitions, once registered and in the database [2],
are essentially immutable.  It is not allowed to remove existing content
from the database, and only a limited set of very specific modifications
may be made to an existing property set.

Changes to an accepted property set are only allowed if:

    1)  The change corrects an obvious typographical error, or

    2)  The change is an erratum, meant to correct the property set so
        that it accurately reflects shipping firmware, or

    3)  The change is to an existing data validation rule to make it
        stricter, which ensures that backward compatibility can be
	maintained.  The change cannot modify the types of values, or
	allow for a broader range of values.

The only way in which one property set can be superseded by another one
is to register a new revision of the property set in question.

Moreover, when creating a new revision of a property set, it is invalid
to redefine property keys (that is, associate them with different data
types or give them different meaning).  New revisions can only add
properties to the set.  If one of the properties in the current (most
recent) revision of a property set is to be deprecated in the next
revision, the correct way to do that is to remove it from the new set
entirely and define a new property with a new key as a replacement for
it.

If there are multiple revisions of a property set registered, platform
firmware is required to provide properties from the most recent one.
However, for the sake of backwards compatibility with existing Operating
Systems, it may also provide properties that are not present in the most
recent revision of the set, but were present in the previous revisions
of it.

Operating Systems are required to use properties from the most recent
revision of a property set they are aware of.  However, if those
properties are not provided by platform firmware, the OS may fall back
to using properties from the previous revisions of the property set that
are not present in the most recent one.


9. References
-------------
[1]
http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf

[2] See document entitled "_DSD Property Database Ruleset".

[3]
http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.pdf

[4] See document entitled "_DSD Formal Language Ruleset".


10. Contributors
----------------
In alphabetical order, by first name:

Al Stone <ahs3@redhat.com>
Charles Garcia-Tobin <charles.garcia-tobin@arm.com>
Darren Hart <darren.hart@intel.com>
David Woodhouse <david.woodhouse@intel.com>
Mark Doran <mark.doran@intel.com>
Rafael Wysocki <rafael.j.wysocki@intel.com>
Robert Gough <robert.gough@intel.com>

[RFC DSD v2 02/04] _DSD Property Database Ruleset

[Al Stone]

_DSD Property Database Ruleset
==============================
Dated:	2016-07-25
Status:	DRAFT


Contents
--------
1. Purpose
2. Database Structure
    2.1. Directory Tree Representation
    2.2. Inheritance
3. Content License
4. Immutability of Registered Property Set Definitions
5. References
6. Contributors


1. Purpose
----------
This document specifies the rules regarding the content and structure of
the common database of device properties to be used with the ACPI _DSD
(Device Specific Data) device configuration object along with the Device
Properties UUID, daffd814-6eba-4d8c-8a91-bc9bbf4aa301 [1], and along
with the UUID dbb8e3e6-5886-4ba6-8795-1319f52a966b, for the Hierarchical
Data Extension for _DSD [5].

Definitions of the terms "device properties", "property sets", "property
subsets", and the process for requesting they be included in the common
database of device properties are documented independently [2].


2. Database Structure
---------------------

2.1. Directory Tree Representation
----------------------------------
The database is organized as a directory tree.  The topmost-level
directory of it is referred to as the database root.

The top-level subdirectories of the database root are assigned to
bus types, or other categories of devices, each using a uniform device
identification scheme.  They are referred to as "bus directories" and
their names reflect the name of the bus type in question.  For example,
the "pci" bus directory will contain the properties of PCI devices while
the "acpi" bus directory will contain properties of devices using ACPI
or PNP device IDs for identification.  The allowed names for bus
directories will be defined by the database maintainers as needed, in
order to maintain uniformity.

The subdirectories of each of bus directory are assigned to device
vendors.  They are referred to as "vendor directories" and their names
will be the bus-assigned Vendor ID (e.g., "INTC" for Intel under the
ACPI bus directory, or "ARMH" for ARM Ltd. under ACPI).  Each vendor
directory contains the property set definitions for that vendor's Device
IDs.

The names of subdirectories in each vendor directory are the Device IDs
of devices using the bus type in question, or belonging to the category
represented by the given bus directory.  Each subdirectory contains the
definitions of all revisions of the property set applicable to devices
using that particular Device ID for identification.  They are referred
to as "device directories".

A vendor directory may also contain subdirectories that are not device
directories, such as "common" or "shared", if necessary or useful.

Each device directory contains subdirectories whose names are treated
as strings representing the revisions of the property set defined in
it.  They are referred to as "revision directories".  The most recent
revision of the property set is defined in the revision directory whose
name represents the largest value, when compared.

Revision names may consist of groupings of ASCII digits separated by a
'.', or any numeric value commonly used in the C language.  Comparison
is from left to right, and values are compared numerically; any group
not present is assumed to be zero.  For example, '1.4' > '1.3.1',
'0x01040000' > '0x01030100', and '20160421' > '20160312'.  New revisions
must always be greater than any existing revisions; i.e., you cannot add
revision '1.3.1' if '1.4' already exists.

The rules regarding the creation of new revisions of a property set are
set in the section on immutability that follows.  At least one revision
directory must be present in each device directory.

Each property in a property set is represented by a file located in the
revision directory defining it.  The name of that file is the name of
the property represented by it.  It contains a list of property
attributes in a simple human-readable format, described in detail, and
with examples, in [3].

Property subsets of a given property set are represented by
subdirectories of the revision directory defining it.  Their names are
the keys identifying those property subsets.  They each contain files
representing properties in the given subset following the same
formalisms as property attributes, or subdirectories representing
further subsets.


2.2. Inheritance
----------------
To facilitate re-use of existing definitions of properties and property
subsets, the database is designed to allow new property sets to be built
on top of existing ones and to inherit property items (i.e., properties
or property subsets) from them.

The property set whose property items are inherited is referred to as a
base set.  The property set inheriting property items is referred to as
a derived set.

A property set may be derived from multiple base sets.

In order to inherit properties from some base sets, the revision
directory defining the derived set will contain a list of pointers to
the base sets the current derived set is based on, and must retain the
ordering given in the property set definition.  This ensures that the
semantics used in the derivation are preserved -- that is, that "A is
derived from B and C" is different from "A is derived from C and B".
Each of these stored pointers is the path from the database root to the
revision directory containing the base set in question.  How these
pointers are stored and how they represent the path are implementation
defined.

As a rule, a derived set contains all of the properties from all base
sets along with the properties defined in it directly. 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.  For example, if property set C is derived from set A
first, and then set B, and both sets A and B contain a property called
"maximum", then C would use the property definition from A; "maximum"
from B would be discarded.

Direct definitions of properties in the derived set cannot override
any properties inherited from the base sets.  Such property definitions
will be considered an error.  That is, if property set B derives from
set A, and A has a definition of property "my-property", B cannot also
contain another definition for "my-property".

In general, inheritance should be limited to individual vendor
directories.  Cross-vendor inheritance of property sets, although
technically possible, would require an agreement between the involved
vendors for each revision.

A single vendor, however, may define property sets for the sole purpose
of inheritance by other property sets belonging to that vendor.  In that
case, it is required to locate the definitions of those property sets in
a separate subdirectory of the vendor directory, using a name such as
"common" or "shared".  We refer to such property sets as "abstract"
property sets, as they are not associated with a particular device ID.
In the same manner as regular property set definitions, each abstract
set is represented by a directory.  The name of that directory should
reflect the purpose of the "abstract" property set and its structure
must follow the format of revision directories as previously described.

For clarity, the directories containing the definitions of the
"abstract" property sets may be located in different parent directories.
For example, the "shared" subdirectory of a vendor directory may contain
subdirectories like "pci", "acpi", "usb", etc. (reflecting the bus type
names) that would contain subdirectories defining "abstract" property
sets (applicable to devices on those bus types).


3. Content License
------------------
By submitting a property set description and allowing it to be included
in the database, the copyright owner of the description is implicitly
allowing that content to re-distributed under the terms of the BSD
2-clause license [4].  The terms of the license are very simple:

    Copyright (c) <YEAR>, <OWNER>
    All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:

    1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

    2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
    COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
    POSSIBILITY OF SUCH DAMAGE.

For the purposes of the database, the <YEAR> above will be the year
when the property set is submitted, and <OWNER> will be the vendor
specified in the property set definition.


4. Immutability of Registered Property Set Definitions
------------------------------------------------------
All property set definitions, once registered and in the database, are
essentially immutable.  It is not possible to remove existing content
from the database, and modifications are limited to a very specific set
of possible changes.  Section 8 of the Property Ruleset [2], provides
further details.


5. References
-------------
[1]
http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf

[2] See document entitled "_DSD Property Registration Ruleset"

[3] See document entitled "_DSD Formal Language Ruleset"

[4] https://opensource.org/licenses/BSD-2-Clause

[5]
http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.pdf


6. Contributors
---------------
In alphabetical order, by first name:

Al Stone <ahs3@redhat.com>
Charles Garcia-Tobin <charles.garcia-tobin@arm.com>
Darren Hart <darren.hart@intel.com>
David Woodhouse <david.woodhouse@intel.com>
Mark Doran <mark.doran@intel.com>
Rafael Wysocki <rafael.j.wysocki@intel.com>
Robert Gough <robert.gough@intel.com>

[RFC DSD v2 03/04] _DSD Formal Language Ruleset

[Al Stone]

_DSD Formal Language Ruleset
============================
Dated:	2016-07-25
Status:	DRAFT


Contents
--------
1. Purpose
2. Formalisms for Describing Property Sets
    2.1 Notes on Database Structure
    2.2 Formal Language for Property Sets
        2.2.1 Set Definition
        2.2.2 Preamble Definition
        2.2.3 Set Location
        2.2.4 Property Definitions
        2.2.5 Additional Syntactical and Semantic Rules
        2.2.6 A Brief and Incomplete Example
3. References
4. Contributors



1. Purpose
----------
This document specifies the formal language to be used for describing
property sets to be registered in the common database of device
properties [1].  This common database is to be used with the ACPI _DSD
(Device Specific Data) device configuration object along with the Device
Properties UUID, daffd814-6eba-4d8c-8a91-bc9bbf4aa301 [2].

Definitions of the terms "device properties", "property sets", "property
subsets", and the process for requesting they be included in the common
database of device properties are documented independently [3].


2. Formalisms for Describing Property Sets
------------------------------------------

2.1. Notes on Database Structure
--------------------------------
Given the database structure described in [1], the directory tree for
a database might look something like the following:

--- Path ----------------------------------            -- Entries --

+-- root						1
     |
     +-- bus ("acpi"|"pci"|"common")			1..n
          |
          +-- vendor directory ("YYDN")			1..n
             |
	     + Device ID ("YYDN0007"|...)		1..n
	        |
		+ revision ("0"|"1"|...)		1..n
                   |
		   + property attributes file		1..n
		   |
		   + property subset tree		1..n
		      |
		      + property attributes file	1..n
		      |
		      + property subset tree		1..n


This is just a quick overview of the possible internal structure.  There
will be only one root, but there are can be one to n subdirectories or
files of each and every flavor.  In parentheses, we can see what some of
the values might be, so that we might have a path that looks like this:

/acpi/YYDN/YYDN0007/0/instruction-cycles-per-fortnight

Again, this is just an example, provided to be more concrete about the
database and its content, and to show how a formal language can be
geared towards describing that content.


2.2. Formal Language for Property Sets
--------------------------------------
When someone asks to register a property set, what information must they
provide?  Informally, we need enough information to be able to place a
file in the database directory, and then stash a bit more information in
that file to describe a property and its possible values.


2.2.1. Set Definition
---------------------
On a more formal basis, we can use BNF to describe what we need:

    <set-definition> ::= <set-preamble> <set-location> <set-properties>

That is, each property set definition consists of a preamble, some
location information, and property definitions.


2.2.2. Preamble Definition
--------------------------
The preamble provides an identifying name for the set, defines what type
of set we have, lists any other sets this one may be derived from, and
who approved the registration; optionally, we can include who submitted
it, and who reviewed it, solely for historical records:

    <set-preamble> ::= <set-name> <set-type> [ <parent-sets> ]
		       <acks> [ <submitters> ] [ <reviewers> ]

    <set-name> ::= "property-set" ":" <name> <EOL>

    <set-type> ::= "set-type" ":" <type-name> <EOL>
    <type-name> ::= "abstract" | "subset" | "definition"

    <parent-sets> ::= "derived-from" ":" <set-list>
    <set-list> ::= <full-path-to-parent> { <EOL> <full-path-to-parent> } <EOL>

    <acks> ::= <acked-by> | <acked-by> <acks>
    <acked-by> ::= "acked-by" ":" <person> <EOL>

    <person> ::= <first-name> <last-name> "<" <email-address> ">"

    <submitters> ::= <submitted-by> | <submitted-by> <submitters>
    <submitted-by> ::= "submitted-by" ":" <person> <EOL>

    <reviewers> ::= <reviewed-by> | <reviewed-by> <reviewers>
    <reviewed-by> ::= "reviewed-by" ":" <person> <EOL>

A <name> may not include an <EOL>, commas (",") or slashes ("/").

A property set can be "abstract", a "subset", or a "definition."  A
definition has no ambiguity: we know precisely where to put the
information in the database, what the property is, and what type it is.
A subset is a collection of property definitions for a single device.
An abstract set could be located in any number of places in the database
directory tree and is only present in order to provide properties other
definitions can re-use.

The <submitters>, if not provided, will be gleaned from the email the
property set was sent in (the From: header, see [3] for details on the
submission process).  The <reviewers> will be gleaned from emails sent
in response to a submission on the dsd@acpica.org mailing list; the line
"Reviewed-by: Name <email@address>" will be the indicator to add such a
line to the property set definition.  The <acks> are similar in that (1)
there must be an email on the mailing list with "Acked-by: Name
<email@address>", but (2) the name used will be checked againt the list
of database maintainers and must be present there before it is
considered valid.

There may be multiple <derived-from> lines; <acks>, <submitters> and
<reviewers> can be multiple lines as well.


2.2.3. Set Location
-------------------
Location information tells us where in the database we need to place the
device properties being defined in this set:

    <set-location> ::= <abstract-set-location> | <full-set-location>
    <abstract-set-location> ::= <vendor> [ <bus> ] [ <device-id> ] <revision>
    <full-set-location> ::= <vendor> <bus> <device-id> <revision>

    <vendor> ::= "vendor" ":" <name> <EOL>

    <bus> ::= "bus" ":" <name> [ "," "shared" ] <EOL>

    <device-id> ::= "device-id" ":" <identifier> <EOL>

    <revision> ::= "revision" ":" <revision-string> <EOL>

    <revision-string> ::= <integral-value> { '.' <integral-value> }
    <integral-value> ::= any C integer string

These can be assembled into a path in the database:

    /bus-name/vendor-name/device-id-identifier/revision-string

Unless this is an abstract property set for other sets to inherit from,
all parts of the path must be provided.  For an abstract set, bus and
vendor are the only required parts.

An <identifier> is the string used by the OS reading a property set to
connect a device to a device driver (e.g., PNP0010, or ACPI0007).


2.2.4. Property Definitions
---------------------------
A stanza must be provided to describe each individual property that is
an element of a property set:

    <set-properties> ::= <property-definition> |
			 <property-definition> <set-properties>

    <property-definition> ::= <property-name> <property-type>
			      [ <property-usage> ]
			      [ <property-values> ]
			      [ <property-description> ]
			      [ <property-example> ]
			      [ <property-dependency> ]

    <property-name> ::= "property" ":" <name> <EOL>

    <property-type> ::= "type" ":" <type-name> <EOL>
    <type-name> ::= "integer" | "string" | "reference" | "package"

    <property-usage> ::= "usage" ":" "required" | "optional" <EOL>

    <property-values> ::= "values" ":" <value-list>
    <value-list> ::= <value-constraint> | <value-constraint> <value-list>
    <value-constraint> ::= <string-value> | <integer-value> |
			   <reference-value> | <subpackage-value>
    <string-value> ::= "token" ":" <string> <EOL>
                       "description" ":" <string> <EOL>
    <integer-value> ::= "integer" ":" <range-list> <EOL>
                        "description" ":" <string> <EOL>
    <range-list> ::= <range> { "," <range> }
    <range> ::= <integer> ".." <integer> | <integer>
    <reference-value> ::= "reference" ":" <ACPI-name> <EOL>
                          "description" ":" <string> <EOL>
    <subpackage-value> ::= "subpackage" ":" <subpackage-definition> <EOL>
                           "description" ":" <string> <EOL>
    <subpackage-definition> ::= "{" <field-type> { "," <field-type> } "}"
    <field-type> ::= "integer" | "reference" | "string" |
		     <subpackage-definition>

    <property-description> ::= "description" ":" <free-form-text>

    <property-example> ::= "example" ":" <free-form-text>

    <free-form-text> ::= <any-text> <EOL> { " " <any-text> <EOL> } <EOL>

    <property-dependency> ::= "requires" ":" <property-name-list>
    <property-name-list> ::= <name> { "," <name> }

A <string> starts with the first non-blank character and continues to
the <EOL>; any white space between the last non-blank and the <EOL> will
be removed.


2.2.5. Additional Syntactical and Semantic Rules
------------------------------------------------
Comments start anywhere in a line of text, using the "#", and continue
to the end of the line ("<EOL>").

Most lines consist of a keyword, followed by a ":", followed by text
providing a value, followed by an <EOL>.  The only exceptions are
descriptions and examples that may have several lines of text, with each
continuation line starting with a " ".  The first line that is either an
empty line or starts with something other than a " " terminates the
block of text.

Lines may generally appear in almost any order, within some constraints:

    -- A <set-name> marks the beginning of a property set and all lines
       after it, until the next <set-name>, will be part of that set.
       So, a <set-type> will always define the type of the prior
       <set-name> in the file.

    -- Similarly, a <property-name> marks the beginning of a property
       definition and all lines after it until the next <property-name>,
       will be part of that definition.  So, a <property-type> will
       always define the type of the prior <property-name> in the file.

    -- Set location information always defines the location of the
       previous <set-name> in the file, and applies identically to all
       property definitions provided in the set.

    -- Property values, if given, must follow the order given in the
       BNF: "values:<EOL>" followed by one or more sets of "token:
       <string><EOL> description: <string><EOL>", or the equivalent
       "integer: <range><EOL> description: <string> <EOL>".  This is the
       only rigorous ordering defined.

In general, white space and blank lines are ignored and irrelevant.  The
text for descriptions and examples is the only time it is relevant, and
then only to indicate the continuation of the text.

If a property has a <property-dependency>, each <property-name> must be
a name being defined in the current property set, or a parent set the
property set is derived from.

If a property does not have a <property-usage> explicitly stated, it is
assumed to be "optional."  However, if <property-usage> indicates the
property is "required," and the property also has a
<property-dependency>, any dependencies also become "required."

If a property set is derived from other sets, the full path to the
parent sets must be provided.

Properties in derived sets cannot override definitions in sets they
have inherited from.  If property set A defines a property "some-name",
and property set B is derived from A, then B cannot also contain a
property "some-name", and will be considered in error.

As noted in [1], revision strings consist of groupings of ASCII digits
separated by a '.', or any numeric value commonly used in the C
language.  Comparison is from left to right, and values are compared
numerically; any group not present is assumed to be zero.  For example,
revision '1.4' > '1.3.1', '0x01040000' > '0x01030100', and '20160421' >
'20160312'.  New revisions must always be greater than any existing
revisions; i.e., you cannot add revision '1.3.1' if '1.4' already
exists.



2.2.6. A Brief and Incomplete Example
-------------------------------------
property-set:	NIC Device Properties
set-type:	definition
bus:		pci
vendor:		YYDN
device-id:	YYDN1001
revision:	0
derived-from:	/pci/YYDN/YYDN1000/25

property:	phy-mode
type:		string
description:
	Defines the PHY mode to be used for this device.
values:
	token:		na
	description:	none available
	token:		mii
	description	media independent interface (MII)
	token:		gmii
	description	gigabit MII
	token:		sgmii
	description	serial gigabit MII
example:
	Package (2) { "phy-mode", "gmii" }

property:	phy-channel
type:		integer
values:
	integer:	0..255
	description:	hex value of the PHY channel number
description:
	If present, defines the PHY channel number (in hex) to be used
	by this device.
example:
	Package (2) { "phy-channel", 3 }

submitted-by:	N. Bonaparte <nb@waterloo.be>
acked-by:	A. Wellesley <duke@wellington.co.uk>


3. References
-------------
[1] See document entitled "_DSD Property Database Ruleset"

[2]
http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf

[3] See document entitled "_DSD Property Registration Ruleset"


4. Contributors
---------------
In alphabetical order, by first name:

Al Stone <ahs3@redhat.com>
Charles Garcia-Tobin <charles.garcia-tobin@arm.com>
Darren Hart <darren.hart@intel.com>
David Woodhouse <david.woodhouse@intel.com>
Mark Doran <mark.doran@intel.com>
Rafael Wysocki <rafael.j.wysocki@intel.com>
Robert Gough <robert.gough@intel.com>

[RFC DSD v2 04/04] Informal ChangeLog

[Al Stone]

===== v0.0.11 ==========================================================

Parser/Tools:
=============
-- Updated the tools to reflect the documentation changes below

Documentation:
==============
-- [Robert Gough] db doc:
>>> Section 2.1, I believe the top level directories should not be vendors,
>>> but bus types. The next level would then be vendors, based on the
>>> bus-assigned Vendor ID. For example, bus types would include ACPI, PCI,
>>> USB, etc. Subdirectories would then be bus-specific. So for example,
>>> Intel would own properties under ACPI/INTC and PCI/0x8086. This would
>>> provide an unambiguous mechanism for determining ownership of property
>>> definition.
	-- changed in database_rules.txt

-- [Robert Gough] db doc:
>>> In section 2.2, I believe the requirement for "00-base-sets" as well as
>>> the '/' character should be removed from this doc and included in the
>>> 0003-formal-language document, but I haven't gotten there yet.
	-- changed in database_rules.txt
	-- removed the mention of 00-base-sets as an implementation
	   detail; there's no real need for us to specify that level
	   of info to be used by the tools.

-- Explain clearly that "derives-from: B, C" implies an order of use for
>> common names -- e.g., that B/foo takes precedence over C/foo, which will
>> be ignored.
	-- changed in database_rules.txt

-- Consensus: overriding a property definition is not allowed.
	-- stated explicitly in database_rules.txt
	-- stated explicitly in formal_language.txt

-- [Robert Gough] db doc:
>>> Furthermore, I'd like to suggest that using a different scheme for
>>> versioning may be more useful. It may make sense for a given property
>>> set to map to a specification which uses versioning beyond simple
>>> integers, and it may be preferable to have those versions match the
>>> property set versions; so something like 1.3.5 or 0x01030500, for a
>>> major.minor.secondary.tertiary scheme, or something like this <solicit
>>> discussion...>. Also, to go along with this, in section 4 I would
>>> recommend stating that any "new revision" must be greater than any
>>> previously defined revision- such that one cannot create version 1.3.1
>>> after version 1.4 has been defined.
	-- relaxed the definition of a revision string to be any C
	   integer string (0x0, 007, 0b01000010) -- for example,
	   20150419, 0x01030500, 1.5.3.1, 12
	-- added proper text to database_rules.txt
	-- added proper text to formal_language.txt

-- Consensus: amendments to the text on making changes need to say:
>>
>> (1) *No* changes to an accepted property set is too strict.
>>
>> (2) Changes to a property set are only allowed in new revisions.
>>
>> (3) Changes to an accepted property set are allowed if either:
>>
>>     (a) The change is an obvious typographical error, or,
>>
>>     (b) The change is an erratum, meant to correct the property set
>>         so that it accurately reflects shipping firmware, or,
>>
>>     (c) The change is to an existing data validation rule to make it
>>         stricter, which ensures we maintain backwards compatibility.
>>         The change cannot not change the types of values, or allow
>>         for a broader range of values.
	-- added the text above to process_rules.txt
	-- added pointer to the text above in process_rules.txt to
	   database_rules.txt
	-- minor rewrites, but content remains the same

[RFC DSD v2 00/04] How to Use the ACPI _DSD Device Properties UUIDs

[Al Stone]

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@redhat.com>
    Charles Garcia-Tobin <charles.garcia-tobin@arm.com>
    Darren Hart <darren.hart@intel.com>
    David Woodhouse <david.woodhouse@intel.com>
    Mark Doran <mark.doran@intel.com>
    Rafael Wysocki <rafael.j.wysocki@intel.com>
    Robert Gough <robert.gough@intel.com>
    (...my apologies if anyone has not been mentioned...)

References:
[0]
http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
[1]
http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.pdf


-- 
ciao,
al
-----------------------------------
Al Stone
Software Engineer
Red Hat, Inc.
ahs3@redhat.com
-----------------------------------