ACPI / property: Document usage rules for _DSD properties

_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

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.