Rules for what you can and can't do with _DSD
by Charles Garcia-Tobin
Hi all
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.
Cheers
Charles
Introduction
============
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
6 years, 8 months
_DSD property database rules
by Rafael J. Wysocki
Hi Everyone,
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. :-)
Thanks,
Rafael
---
Common _DSD Property Database Rules (Draft)
1. Purpose
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 [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 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
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 [2].
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 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
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 [1].
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 [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(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
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 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
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 etc.
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 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
name of
the property represented by it. It contains a list of property
attributes in a simple YAML format where spaces are used for
indentation
and tabulators are used for separating attributes from their
values.
Currently, only one attribute is mandatory:
type: <property data type specification>
and the following attributes are optional:
description: <text>
example: <text>
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 above
format
or subdirectories representing their own subsets.
8.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 (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
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, each time would require an agreement between
the involved vendors.
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, such as
"common" or
"shared". As for the "regular" property set definitions, each of
those "abstract" property sets 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
described in Section 8.1.
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 will contain subdirectories defining "abstract"
property
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
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 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
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 in the database,
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.
References
[1]
http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-...
[2]
http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-...
6 years, 8 months
Re: [DSD] _DSD property database rules
by Hart, Darren
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:
>Hi Rafael
>
>Thanks for sending this out. A lot of work has gone into this.
>I have some comments below.
>
>Cheers
>
>Charles
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>
>wrote:
...
>> 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.
>
>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.
Thanks!
--
Darren Hart
Intel Open Source Technology Center
6 years, 8 months
Re: [DSD] _DSD property database rules
by Charles Garcia-Tobin
Hi
I originally objected because I would hope that OSs that use the reverse
solidus U+005C for path separation would also adopt this database. So
wanted clearer language, as maybe they are forced into making a
distinction between slashes more often. But honestly it¹s not important,
happy to drop it.
Cheers
Charles
On 13/01/2016 17:01, "Woodhouse, David" <david.woodhouse(a)intel.com> wrote:
>On Wed, 2016-01-13 at 16:42 +0000, Charles Garcia-Tobin wrote:
>> 2. nit: s/slash/forward slash/
>
>I for one would tend to frown upon that one. The solidus U+002F is
>known as a slash; the term "forward slash" is a retronym which I
>understand (although it makes my teeth grind) when we're trying to
>dictate URLs aurally to a computer-illiterate public, but which doesn't
>seem to have much place in a technical document.
>
>--
>David Woodhouse Open Source Technology Centre
>David.Woodhouse(a)intel.com Intel Corporation
>
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.
6 years, 8 months