ACPI / property: Document usage rules for _DSD properties
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@intel.com> Reviewed-by: Mika Westerberg <mika.westerberg@linux.intel.com> Acked-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com> Reviwed-by: Mark Brown <broonie@kernel.org>
This commit is contained in:
parent
99db5ff7fe
commit
ee39222d45
97
Documentation/acpi/DSD-properties-rules.txt
Normal file
97
Documentation/acpi/DSD-properties-rules.txt
Normal file
|
@ -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-properties-UUID.pdf
|
||||
[2] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf
|
|
@ -415,3 +415,12 @@ the "compatible" property in the _DSD or a _CID as long as one of their
|
|||
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.
|
||||
|
|
Loading…
Reference in a new issue