1.. SPDX-License-Identifier: GPL-2.0 2 3================================== 4_DSD Device Properties Usage Rules 5================================== 6 7Properties, Property Sets and Property Subsets 8============================================== 9 10The _DSD (Device Specific Data) configuration object, introduced in ACPI 5.1, 11allows any type of device configuration data to be provided via the ACPI 12namespace. In principle, the format of the data may be arbitrary, but it has to 13be identified by a UUID which must be recognized by the driver processing the 14_DSD output. However, there are generic UUIDs defined for _DSD recognized by 15the ACPI subsystem in the Linux kernel which automatically processes the data 16packages associated with them and makes those data available to device drivers 17as "device properties". 18 19A device property is a data item consisting of a string key and a value (of a 20specific type) associated with it. 21 22In the ACPI _DSD context it is an element of the sub-package following the 23generic Device Properties UUID in the _DSD return package as specified in the 24Device Properties UUID definition document [1]_. 25 26It also may be regarded as the definition of a key and the associated data type 27that can be returned by _DSD in the Device Properties UUID sub-package for a 28given device. 29 30A property set is a collection of properties applicable to a hardware entity 31like a device. In the ACPI _DSD context it is the set of all properties that 32can be returned in the Device Properties UUID sub-package for the device in 33question. 34 35Property subsets are nested collections of properties. Each of them is 36associated with an additional key (name) allowing the subset to be referred 37to as a whole (and to be treated as a separate entity). The canonical 38representation of property subsets is via the mechanism specified in the 39Hierarchical Properties Extension UUID definition document [2]_. 40 41Property sets may be hierarchical. That is, a property set may contain 42multiple property subsets that each may contain property subsets of its 43own and so on. 44 45General Validity Rule for Property Sets 46======================================= 47 48Valid property sets must follow the guidance given by the Device Properties UUID 49definition document [1]. 50 51_DSD properties are intended to be used in addition to, and not instead of, the 52existing mechanisms defined by the ACPI specification. Therefore, as a rule, 53they should only be used if the ACPI specification does not make direct 54provisions for handling the underlying use case. It generally is invalid to 55return property sets which do not follow that rule from _DSD in data packages 56associated with the Device Properties UUID. 57 58Additional Considerations 59------------------------- 60 61There are cases in which, even if the general rule given above is followed in 62principle, the property set may still not be regarded as a valid one. 63 64For example, that applies to device properties which may cause kernel code 65(either a device driver or a library/subsystem) to access hardware in a way 66possibly leading to a conflict with AML methods in the ACPI namespace. In 67particular, that may happen if the kernel code uses device properties to 68manipulate hardware normally controlled by ACPI methods related to power 69management, like _PSx and _DSW (for device objects) or _ON and _OFF (for power 70resource objects), or by ACPI device disabling/enabling methods, like _DIS and 71_SRS. 72 73In all cases in which kernel code may do something that will confuse AML as a 74result of using device properties, the device properties in question are not 75suitable for the ACPI environment and consequently they cannot belong to a valid 76property set. 77 78Property Sets and Device Tree Bindings 79====================================== 80 81It often is useful to make _DSD return property sets that follow Device Tree 82bindings. 83 84In those cases, however, the above validity considerations must be taken into 85account in the first place and returning invalid property sets from _DSD must be 86avoided. For this reason, it may not be possible to make _DSD return a property 87set following the given DT binding literally and completely. Still, for the 88sake of code re-use, it may make sense to provide as much of the configuration 89data as possible in the form of device properties and complement that with an 90ACPI-specific mechanism suitable for the use case at hand. 91 92In any case, property sets following DT bindings literally should not be 93expected to automatically work in the ACPI environment regardless of their 94contents. 95 96References 97========== 98 99.. [1] https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf 100.. [2] https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf 101