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