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

[RFC DSD 00/03] 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.

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 in July or 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>
    Rafael Wysocki <rjw.rjwysocki.net>
    (apologies if we're missing someone that should be on this list...)

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 01/03] _DSD Property Registration Ruleset

[Al Stone]

_DSD Property Registration Ruleset
==================================
Dated:	2016-06-14
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 immutable. It is not possible to remove existing content from the
database or to modify any of it in place.  It only is possible to add
new content.

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 or remove them from it.  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 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>
Rafael Wysocki <rjw.rjwysocki.net>

[RFC DSD 02/03] _DSD Property Database Ruleset

[Al Stone]

_DSD Property Database Ruleset
==============================
Dated:	2016-06-14
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].

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 device
vendors.  They are referred to as "vendor directories" and their names
are chosen by the vendors in question (e.g., when registering the first
property set for the given vendor).  Each of them contains property set
definitions for that vendor's Device IDs.

Each vendor directory should contain subdirectories assigned to various
bus types or other categories of devices each using a uniform device
identification scheme.  They are referred to as "bus directories" and
their names should 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.  A vendor
directory may contain subdirectories that are not bus directories, such
as "common" or "shared", if necessary or useful.

The names of subdirectories in each bus directory are Device IDs of
devices based on the bus type in question, or belonging to the category
represented by the given bus directory.  Each of them 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".

Each device directory contains subdirectories whose names are positive
decimal integers representing 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 greatest number (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 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 has to contain a special text file
under the name "00-base-sets" containing a list of pointers to the base
sets the current derived set is based on, one per line.  Each of these
pointers is the path from the database root to the revision directory
containing the base set in question, where the "slash" character ‘/’ is
used as the path separator.

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
"00-base-sets" containing it.  Moreover, direct definitions of
properties in the derived set override any properties inherited from the
base sets.

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
immutable. It is not possible to remove existing content from the
database or to modify any of it in place.  It only is possible to add
new content.

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 and put it
into a new revision directory as described in above.

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 or remove them from it.  A property set will
be considered deprecated if and only if the key no longer appears in
the most recent revision.


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


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>
Rafael Wysocki <rjw.rjwysocki.net>


--
To unsubscribe from this list: send the line "unsubscribe linux-acpi" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC DSD 03/03] _DSD Formal Language Ruleset

[Al Stone]

_DSD Formal Language Ruleset
============================
Dated:	2016-06-14
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
     |
     +-- vendor directory ("Yoyodyne, Inc.")		1..n
          |
	  + bus ("acpi"|"pci"|"common")			1..n
             |
	     + Device ID ("ACPI0007"|...)		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:

/Yoyodyne, Inc./acpi/ACPI0007/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" ":" <integer> <EOL>

These can be assembled into a path in the database:

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

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, vendor and
revision 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.


2.2.6. A Brief and Incomplete Example
-------------------------------------
property-set:	NIC Device Properties
set-type:	definition
vendor:		Yoyodyne Inc.
bus:		pci
device-id:	YYDN1001
revision:	0
derived-from:	/Yoyodyne Inc./pci/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>
Rafael Wysocki <rjw.rjwysocki.net>

Re: [RFC DSD 01/03] _DSD Property Registration Ruleset

[Hart, Darren]

Thanks Al,

On 6/28/16, 1:07 PM, "Al Stone" <ahs3@redhat.com> wrote:

…

>8. Immutability of Registered Property Set Definitions
>------------------------------------------------------
>All property set definitions, once registered and in the database [2],
>are immutable. It is not possible to remove existing content from the
>database or to modify any of it in place.  It only is possible to add
>new content.
>
>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 or remove them from it.  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 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.

The wording “…or remove them from it” is problematic. In order to ensure backward compatibility, we need to ensure that new revisions do not remove required properties from previous revisions.

The goal is for an older OS/driver that only knows about revision 1 to continue to function with revision 2 by using all the required fields, and ignoring the additional fields added by later revisions.

I’d recommend we strike “ or remove them from it” from section 8.

-- 
Darren Hart
Intel Open Source Technology Center

Re: [RFC DSD 02/03] _DSD Property Database Ruleset

[Charles Garcia-Tobin]

Hi Al

Thanks a lot for putting this together. I only had one very minor comment
below.

On 28/06/2016 21:08, "Al Stone" <ahs3@redhat.com> wrote:

>_DSD Property Database Ruleset
>==============================
>Dated: 2016-06-14
>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].
>
>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 device
>vendors.  They are referred to as "vendor directories" and their names
>are chosen by the vendors in question (e.g., when registering the first
>property set for the given vendor).  Each of them contains property set
>definitions for that vendor's Device IDs.
>
>Each vendor directory should contain subdirectories assigned to various
>bus types or other categories of devices each using a uniform device
>identification scheme.  They are referred to as "bus directories" and
>their names should 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.  A vendor
>directory may contain subdirectories that are not bus directories, such
>as "common" or "shared", if necessary or useful.
>
>The names of subdirectories in each bus directory are Device IDs of
>devices based on the bus type in question, or belonging to the category
>represented by the given bus directory.  Each of them 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".
>
>Each device directory contains subdirectories whose names are positive
>decimal integers representing 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 greatest number (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 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.

I think it’d be nice to either insert or make reference here to the
example given in [3] section 2.1

Cheers

Charles


>
>
>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 has to contain a special text file
>under the name "00-base-sets" containing a list of pointers to the base
>sets the current derived set is based on, one per line.  Each of these
>pointers is the path from the database root to the revision directory
>containing the base set in question, where the "slash" character ‘/’ is
>used as the path separator.
>
>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
>"00-base-sets" containing it.  Moreover, direct definitions of
>properties in the derived set override any properties inherited from the
>base sets.
>
>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
>immutable. It is not possible to remove existing content from the
>database or to modify any of it in place.  It only is possible to add
>new content.
>
>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 and put it
>into a new revision directory as described in above.
>
>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 or remove them from it.  A property set will
>be considered deprecated if and only if the key no longer appears in
>the most recent revision.
>
>
>5. References
>-------------
>[1]
>http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-U
>UID.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
>
>
>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>
>Rafael Wysocki <rjw.rjwysocki.net>
>
>


IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.

--
To unsubscribe from this list: send the line "unsubscribe linux-acpi" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC DSD 01/03] _DSD Property Registration Ruleset

[Charles Garcia-Tobin]

Hi Al

Thanks for posting this! One other minor comment is that given section 8
repeats and expands the content of "_DSD Property Database Ruleset"
section 4, maybe to make life easier, you should strike the latter and put
a reference in there to this section?

Cheers

Charles


On 29/06/2016 00:08, "Hart, Darren" <darren.hart@intel.com> wrote:

>Thanks Al,
>
>On 6/28/16, 1:07 PM, "Al Stone" <ahs3@redhat.com> wrote:
>
>…
>
>>8. Immutability of Registered Property Set Definitions
>>------------------------------------------------------
>>All property set definitions, once registered and in the database [2],
>>are immutable. It is not possible to remove existing content from the
>>database or to modify any of it in place.  It only is possible to add
>>new content.
>>
>>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 or remove them from it.  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 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.
>
>The wording “…or remove them from it” is problematic. In order to ensure
>backward compatibility, we need to ensure that new revisions do not
>remove required properties from previous revisions.
>
>The goal is for an older OS/driver that only knows about revision 1 to
>continue to function with revision 2 by using all the required fields,
>and ignoring the additional fields added by later revisions.
>
>I’d recommend we strike “ or remove them from it” from section 8.
>
>--
>Darren Hart
>Intel Open Source Technology Center
>


IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.

--
To unsubscribe from this list: send the line "unsubscribe linux-acpi" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC DSD 01/03] _DSD Property Registration Ruleset

[Al Stone]

On 06/29/2016 03:53 AM, Charles Garcia-Tobin wrote:
> Hi Al
> 
> Thanks for posting this! One other minor comment is that given section 8
> repeats and expands the content of "_DSD Property Database Ruleset"
> section 4, maybe to make life easier, you should strike the latter and put
> a reference in there to this section?

Ah.  Good point.  No sense in duplicating code, so to speak.

> Cheers
> 
> Charles
> 
> 
> On 29/06/2016 00:08, "Hart, Darren" <darren.hart@intel.com> wrote:
> 
>> Thanks Al,
>>
>> On 6/28/16, 1:07 PM, "Al Stone" <ahs3@redhat.com> wrote:
>>
>> …
>>
>>> 8. Immutability of Registered Property Set Definitions
>>> ------------------------------------------------------
>>> All property set definitions, once registered and in the database [2],
>>> are immutable. It is not possible to remove existing content from the
>>> database or to modify any of it in place.  It only is possible to add
>>> new content.
>>>
[snip...]

-- 
ciao,
al
-----------------------------------
Al Stone
Software Engineer
Red Hat, Inc.
ahs3@redhat.com
-----------------------------------
--
To unsubscribe from this list: send the line "unsubscribe linux-acpi" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC DSD 02/03] _DSD Property Database Ruleset

[Al Stone]

On 06/29/2016 03:19 AM, Charles Garcia-Tobin wrote:
> 
> Hi Al
> 
> Thanks a lot for putting this together. I only had one very minor comment
> below.
> 
> On 28/06/2016 21:08, "Al Stone" <ahs3@redhat.com> wrote:
> 
>> _DSD Property Database Ruleset
>> ==============================
>> Dated: 2016-06-14
>> Status:        DRAFT
[snip...]

>>
>> 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 in
>> [3].

Good idea.  How about changing the sentence above to "...described in
detail, 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.
> 
> I think it’d be nice to either insert or make reference here to the
> example given in [3] section 2.1
> 
> Cheers
> 
> Charles

-- 
ciao,
al
-----------------------------------
Al Stone
Software Engineer
Red Hat, Inc.
ahs3@redhat.com
-----------------------------------
--
To unsubscribe from this list: send the line "unsubscribe linux-acpi" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC DSD 02/03] _DSD Property Database Ruleset

[Charles Garcia-Tobin]

On 29/06/2016 17:29, "Al Stone" <ahs3@redhat.com> wrote:

>On 06/29/2016 03:19 AM, Charles Garcia-Tobin wrote:
>>
>> Hi Al
>>
>> Thanks a lot for putting this together. I only had one very minor
>>comment
>> below.
>>
>> On 28/06/2016 21:08, "Al Stone" <ahs3@redhat.com> wrote:
>>
>>> _DSD Property Database Ruleset
>>> ==============================
>>> Dated: 2016-06-14
>>> Status:        DRAFT
>[snip...]
>
>>>
>>> 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 in
>>> [3].
>
>Good idea.  How about changing the sentence above to "...described in
>detail, with examples, in [3]"?

Works for me.

Cheers

Charles

>
>>> 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.
>>
>> I think it’d be nice to either insert or make reference here to the
>> example given in [3] section 2.1
>>
>> Cheers
>>
>> Charles
>
>--
>ciao,
>al
>-----------------------------------
>Al Stone
>Software Engineer
>Red Hat, Inc.
>ahs3@redhat.com
>-----------------------------------
>


IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.

--
To unsubscribe from this list: send the line "unsubscribe linux-acpi" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html