On Wed, 2016-11-30 at 02:52 +0100, Rafael J. Wysocki wrote: > From: Rafael J. Wysocki <rafael.j.wysocki@xxxxxxxxx> > > Following some discussions during the Kernel Summit and LPC, document > what can be returned from ACPI _DSD as device properties and when it > is valid to use the special PRP0001 device ID. > > Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@xxxxxxxxx> > --- > > Here's my follow-up to the discussions we had during the KS and LPC. > > Please let me know if that's sufficient or it needs to be extended > somehow. > > Thanks, > Rafael That's nice one and explains basically what we discussed at KS/LPC! Acked-by: Andy Shevchenko <andriy.shevchenko@xxxxxxxxxxxxxxx> > > --- > Documentation/acpi/DSD-properties-rules.txt | 97 > ++++++++++++++++++++++++++++ > Documentation/acpi/enumeration.txt | 9 ++ > 2 files changed, 106 insertions(+) > > Index: linux-pm/Documentation/acpi/enumeration.txt > =================================================================== > --- linux-pm.orig/Documentation/acpi/enumeration.txt > +++ linux-pm/Documentation/acpi/enumeration.txt > @@ -415,3 +415,12 @@ the "compatible" property in the _DSD or > ancestors provides a _DSD with a valid "compatible" property. Such > device > objects are then simply regarded as additional "blocks" providing > hierarchical > configuration information to the driver of the composite ancestor > device. > + > +However, PRP0001 can only be returned from either _HID or _CID of a > device > +object if all of the properties returned by the _DSD associated with > it (either > +the _DSD of the device object itself or the _DSD of its ancestor in > the > +"composite device" case described above) can be used in the ACPI > environment. > +Otherwise, the _DSD itself is regarded as invalid and therefore the > "compatible" > +property returned by it is meaningless. > + > +Refer to DSD-properties-rules.txt for more information. > Index: linux-pm/Documentation/acpi/DSD-properties-rules.txt > =================================================================== > --- /dev/null > +++ linux-pm/Documentation/acpi/DSD-properties-rules.txt > @@ -0,0 +1,97 @@ > +_DSD Device Properties Usage Rules > +---------------------------------- > + > +Properties, Property Sets and Property Subsets > +---------------------------------------------- > + > +The _DSD (Device Specific Data) configuration object, introduced in > ACPI 5.1, > +allows any type of device configuration data to be provided via the > ACPI > +namespace. In principle, the format of the data may be arbitrary, > but it has to > +be identified by a UUID which must be recognized by the driver > processing the > +_DSD output. However, there are generic UUIDs defined for _DSD > recognized by > +the ACPI subsystem in the Linux kernel which automatically processes > the data > +packages associated with them and makes those data available to > device drivers > +as "device properties". > + > +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 > +generic 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. > + > +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. > + > +General Validity Rule for Property Sets > +--------------------------------------- > + > +Valid property sets 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. It generally is > invalid to > +return property sets which do not follow that rule from _DSD in data > packages > +associated with the Device Properties UUID. > + > +Additional Considerations > +------------------------- > + > +There are cases in which, even if the general rule given above is > followed in > +principle, the property set may still not be regarded as a valid one. > + > +For example, that applies to device properties which may cause kernel > code > +(either a device driver or a library/subsystem) to access hardware in > a way > +possibly leading to a conflict with AML methods in the ACPI > namespace. In > +particular, that may happen if the kernel code uses device properties > to > +manipulate hardware normally controlled by ACPI methods related to > power > +management, like _PSx and _DSW (for device objects) or _ON and _OFF > (for power > +resource objects), or by ACPI device disabling/enabling methods, like > _DIS and > +_SRS. > + > +In all cases in which kernel code may do something that will confuse > AML as a > +result of using device properties, the device properties in question > are not > +suitable for the ACPI environment and consequently they cannot belong > to a valid > +property set. > + > +Property Sets and Device Tree Bindings > +-------------------------------------- > + > +It often is useful to make _DSD return property sets that follow > Device Tree > +bindings. > + > +In those cases, however, the above validity considerations must be > taken into > +account in the first place and returning invalid property sets from > _DSD must be > +avoided. For this reason, it may not be possible to make _DSD return > a property > +set following the given DT binding literally and completely. Still, > for the > +sake of code re-use, it may make sense to provide as much of the > configuration > +data as possible in the form of device properties and complement that > with an > +ACPI-specific mechanism suitable for the use case at hand. > + > +In any case, property sets following DT bindings literally should not > be > +expected to automatically work in the ACPI environment regardless of > their > +contents. > + > +References > +---------- > + > +[1] http://www.uefi.org/sites/default/files/resources/_DSD-device-pro > perties-UUID.pdf > +[2] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchic > al-data-extension-UUID-v1.1.pdf > -- Andy Shevchenko <andriy.shevchenko@xxxxxxxxxxxxxxx> Intel Finland Oy -- To unsubscribe from this list: send the line "unsubscribe linux-acpi" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
