Last week at the ASWG conference call I took the action of defining some
ground rules for _DSD submissions. I have drafted some up here. I¹d be
grateful to know your thoughts.
The following provides rules for the process of submitting _DSD
properties. This process must be followed by vendors wishing to see their
drivers supported by OS vendors that support ACPI.
What properties can be described by _DSD
_DSD stands for device specific data, it is an object in ACPI that may be
associated with a device to describe specific device properties that are
not covered by other mechanisms in the ACPI specification. An example may
be a mac address, or phy for an networking device.
What properties must not be described by _DSD
_DSD must only be used to describe properties that are specific to a
device, rather than properties of the system as whole. i.e. Generic
properties that are required by generic kernel frameworks must not be
described with _DSD.
_DSD must not be used to describe properties that are already covered in
the ACPI specification.
For a system described with ACPI, it must not a requirement that any of
the following areas need and OS to evaluate _DSD in order to work:
- Support dynamic device configurations (hot add/removal)
- Support hardware abstraction through control methods
- power management
- thermal management
- RAS interfaces
_DSD must not be used to describe properties that are specific to an
operating system. For example properties with OS names in the key
would not allowed.
Submitting a binding
<Insert previous mails from Al Stone on the dsd too and dsd(a)acpica.org>
Becoming a reviewer
Anybody who is member of the dsd(a)acpica.org can be a reviewer.
Becoming a maintainer
_DSD maintainership is a meritocracy. The process is:
1. You submit a request dsd(a)acpica.org to become maintainer
2. Existing maintainers take a view on teh merit of the request based
on the track record of the person making the request in:
2.1 OS verndors. Eg FreeBSD, RH, or Windows may propose a maintainer
2.2 Existing FW representation technologies: ie person is a known
ACPI contributor or Device Tree contributor or maintainer
<< Other stuff to eventually include >>
Dsd tool stuff from Al, Rules on what properties look like from Rafael
-- 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.
ARM Limited, Registered office 110 Fulbourn Road, Cambridge CB1 9NJ, Registered in England & Wales, Company No: 2557590
ARM Holdings plc, Registered office 110 Fulbourn Road, Cambridge CB1 9NJ, Registered in England & Wales, Company No: 2548782
This topic has been under discussion for the last several months and it
looks like an agreement on how the database should be organized and so
on is within reach.
Appended is a draft document specifying the _DSD property database rules
which is intended to be a starting point for discussion. However, there
are a few things related to it worth mentioning upfront.
First of all, during earlier discussions there was a controversy on
whether or not to require property sets submitted for registration to be
tied to specific device IDs (with the possible exception of property
sets created for the sole purpose of inheritance as described in the
document below). The eventual universal agreement here was that making
that requirement was unavoidable and that the vendors who controlled
those device IDs would also need to be allowed to control the property
sets they wanted to use along with them.
In addition to that, everyone involved seemed to agree that use cases in
which common (that is, shared between multiple vendors) properties would
be useful in principle should be addressed by defining a suitable
mechanism in a specification of some sort (that may be the ACPI
specification or a different one more suitable for the given use case,
like the PCI spec might be a better place to address use cases related
to PCI devices), as that would require the vendors in question to
collaborate in a more formal fashion.
With that, please review the appended document and let me know if you
have any concerns about it. Also please let me know if you think that
some things should be taken into account differently. As stated above,
it is intended as a starting point for a discussion, so let's have one. :-)
Common _DSD Property Database Rules (Draft)
This document specifies the rules regarding the content, operation 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.
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 .
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 by this document.
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
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 .
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
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 holds property sets, not
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
Section 8.2 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 .
In particular, since _DSD properties are intended to be used in
addition to, and not instead of, the existing mechanisms defined by
the ACPI specification, 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 will be given in .]
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
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
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(a)acpica.org
(public mailing list) and (optionally) to the maintainers of the common
device properties database.
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
avoid putting invalid content into the database (that's critical in the
face of Section 9).
Submitted property sets can be reviewed by all of the subscribers of the
dsd(a)acpica.org mailing list and the reviewers' comments can only be
into consideration by the database maintainers if they are sent to that
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 between 1 and 2 weeks inclusive) 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. Database Structure
8.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 (eg. when
the first property set for the given vendor). Each of them
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
device identification scheme. They are referred to as "bus
and their names should reflect the name of the bus type in
For example, the "pci" bus directory will contain the
properties of PCI
devices while the "acpi" bus directory will contain properties
using ACPI or PNP device IDs for identification. A vendor
contain subdirectories that are not bus directories, such as
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
represented by the given bus directory). Each of them contains the
definitions of all revisions of the property set applicable to
using that particular Device ID for identification. They are
to as "device directories".
Each device directory contains subdirectories whose names are
decimal integers representing revisions of the property set
it. They are referred to as "revision directories". The most
revision of the property set is defined in the revision
name represents the greatest number (the rules regarding the
of new revisions of a property set are set in Section 9). 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
the property represented by it. It contains a list of property
attributes in a simple YAML format where spaces are used for
and tabulators are used for separating attributes from their
Currently, only one attribute is mandatory:
type: <property data type specification>
and the following attributes are optional:
Property subsets of a given property set are represented by
subdirectories of the revision directory defining it. Their
the keys identifying those property subsets. They each contain
representing properties in the given subset following the above
or subdirectories representing their own subsets.
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 (ie. 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
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
under the name "00-base-sets" containing a list of pointers to
sets the current derived set is based on, one per line. Each of
pointers is the path from the database root to the revision
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
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
the base sets.
In general, inheritance should be limited to individual vendor
directories. Cross-vendor inheritance of property sets, although
technically possible, each time would require an agreement between
the involved vendors.
A single vendor, however, may define property sets for the sole
of inheritance by other property sets belonging to that
vendor. In that
case, it is required to locate the definitions of those
in a separate subdirectory of the vendor directory, such as
"shared". As for the "regular" property set definitions, each of
those "abstract" property sets is represented by a directory.
of that directory should reflect the purpose of the "abstract"
set and its structure must follow the format of revision
described in Section 8.1.
For clarity, the directories containing the definitions of the
"abstract" property sets may be located in different parent
For example, the "shared" subdirectory of a vendor directory
subdirectories like "pci", "acpi", "usb" etc. (reflecting the
names) that will contain subdirectories defining "abstract"
sets (applicable to devices on those bus types).
9. Immutability of Registered Property Set Definitions
All property set definitions in the database, once registered, are
It is not possible to remove existing content from the database or
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 create a new revision of the property set in question and put it
into a new revision directory as described in Section 8.1.
Moreover, when creating a new revision of a property set, it is
redefine property keys (that is, associate them with different data
or give them different meaning). New revisions can only add
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
and define a new property with a new key as a replacement for it.
If there are multiple revisions of a property set in the database,
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
Operating Systems are required to use properties from the most recent
revision of a property set they are aware of. However, if those
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.
On 12/11/15, 9:22 AM, "DSD on behalf of Charles Garcia-Tobin" <dsd-bounces(a)acpica.org on behalf of charles.garcia-tobin(a)arm.com> wrote:
>Thanks for sending this out. A lot of work has gone into this.
>I have some comments below.
Hi Charles. Apologies for the delay. I wanted to comment on the Device ID requirement specifically, inline below, and will respond to the other comments separately.
>On 08/12/2015 23:19, "Rafael J. Wysocki" <rafael.j.wysocki(a)intel.com>
>> 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
>> Section 8.2 below), there must be at least one Device ID
>> with it. That can be a PNP or ACPI device ID, a device ID that
>> 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.
>So here I have concern. My understanding per ACPI spec is that you¹d use
>_HID, _CID and _CLS for this method. I am wondering if this text is here
>to allow binding driver using device tree¹s ³compatible" string. I find
>this worrying because:
The language above was chosen to ensure we comply with the ACPI specification and requirements for a device ID.
PRP0001, as a separate topic, was proposed to address the compatible style binding in a way that met those same requirements.
>1. Above we state how properties are going to be assigned to one Device
One "Device ID", not each physical instantiation of a device (or each model/part number). Properties, in general, are useful because they can describe multiple variants of a given type of device without requiring a new Device ID for each and every solitary change.
>2. We don¹t want to do generic properties, instead if a generic property
>was found we should promote creation of that to the ACPI spec.
I suppose that line can be interpreted in a number of ways. While we argued against defining "Ethernet_MAC" in the absence of a Device ID to which it pertained, I would expect something like a Foo Networks line of Ethernet NICs to potentially all work from a single FOOXXXX ID with a defined set of properties with which to parameterize the OS driver.
>Yet the ³compatible² if used in this way would be an example of a generic
>property, in as much as it applies to many devices. The PRP00001 kind of
>hides this, but actually promotes the very behaviours we were trying to
>avoid in creating these rules. In particular we only want to use DSD for
>properties that are not covered by the spec in any other way. Using
>compatible would just encourage folk to pull in whole DTs which in turn
>could pull in properties that do overlap with ACPI.
I share the objection to pulling in entire DTs containing conflicting properties. We have attempted to address this through language in the document (3.3 immediately below) about specific things which should not be included in properties. It's also probably worth noting that the most problematic examples wouldn't actually work anyway, which is a far better deterrent than the language in 3.3 :-)
As to something like PRP0001+compatible. The goal for this has always been to enable the use of drivers for leaf-node devices like sensors on non-enumerable busses, gpio connected things, etc, which already exist today and for which there has been unanimous preference voiced (Kernel Summit 2014, from various architecture representatives) to not generate hundreds of ACPI Ids, but to rather make them available in a firmware implementation agnostic way. This is what drove the new device_properties API within the Linux kernel.
All that said, PRP0001 is a separate issue from the database. At most, I would expect to see an entry for PRP0001 with a single entry "compatible=<matchterm>" in the database, with a reference to known documentation for the matchterm sources, such as the Linux DT documentation, with caveats for use as described above. This is not intended to document best practice, but instead to be a practical approach to enabling that will result in more consistent usage via a prescribed path than if we were to ignore this reality and leave everyone to fend for themselves.
I'll respond to the organization topic separately.
Intel Open Source Technology Center