diff options
Diffstat (limited to 'Documentation/firmware-guide/acpi/DSD-properties-rules.rst')
| -rw-r--r-- | Documentation/firmware-guide/acpi/DSD-properties-rules.rst | 103 |
1 files changed, 103 insertions, 0 deletions
diff --git a/Documentation/firmware-guide/acpi/DSD-properties-rules.rst b/Documentation/firmware-guide/acpi/DSD-properties-rules.rst new file mode 100644 index 000000000..70442bc25 --- /dev/null +++ b/Documentation/firmware-guide/acpi/DSD-properties-rules.rst @@ -0,0 +1,103 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================== +_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 +section titled "Well-Known _DSD UUIDs and Data Structure Formats" sub-section +"Device Properties UUID" in _DSD (Device Specific Data) Implementation Guide +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 +section titled "Well-Known _DSD UUIDs and Data Structure Formats" sub-section +"Hierarchical Data Extension UUID" in _DSD (Device Specific Data) +Implementation Guide document [1]_. + +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] https://github.com/UEFI/DSD-Guide |